[CmdPal] Phase 7b: parallel + off-lock search scoring (same settled order)

Throughput and render-unblocking for the main-list search scoring, with the
final settled result order kept byte-identical to phase 7a.

- Shrink the TopLevelCommands lock scope in MainListPage.UpdateSearchTextCore.
  Sources are now snapshotted under the lock, the heavy scoring/sort runs OFF
  the lock, and the lock is re-acquired only to publish the finished results.
  The swap is atomic and supersede-safe via the existing cancellation-token
  guard, so a newer keystroke always wins and a stale snapshot is dropped.
- Parallelize the dominant apps scoring pass via FilterListWithScoresParallel.
  Contiguous partitions are scored on separate threads and concatenated in
  partition order, producing a pre-sort buffer identical to the serial path;
  the same Array.Sort then yields a byte-identical ordered result. Commands
  and fallbacks stay serial. RecentCommandsManager.Index is pre-warmed
  single-threaded (PrewarmIndex) before the parallel loop because its lazy
  dictionary build is not thread-safe.
- Drop the redundant second commands.Where(IsFallback) pass by reusing the
  specialFallbacks list already built in the prefilter loop.
- Add a committed output-equivalence MSTest (ScoringParallelEquivalenceTests)
  asserting the parallel path matches a sequential reference item-for-item and
  score-for-score across full-catalog, extend, retype-rebuild, commands, and
  determinism cases. Extend the throughput harness with a serial-vs-parallel
  before/after measurement.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: michaeljolley

src/modules/cmdpal/Microsoft.CmdPal.Common/Helpers/InternalListHelpers.cs

@@ -60,6 +60,90 @@ public static RoScored<T>[] FilterListWithScores<T>(
         }
     }
 
+    // Minimum item count before the parallel path is worth its partitioning/merge overhead.
+    // Below this the serial path wins, so commands (hundreds) and small app sets stay serial.
+    private const int ParallelScoringThreshold = 512;
+
+    /// <summary>
+    /// Order-preserving parallel variant of <see cref="FilterListWithScores{T}"/>. Partitions the
+    /// input into contiguous index ranges, scores each range on a separate thread, then
+    /// concatenates the per-partition matched items back in partition order. This produces a
+    /// pre-sort buffer BYTE-IDENTICAL to the serial path (matched items in original enumeration
+    /// order), so the subsequent <see cref="Array.Sort(Array, int, int, IComparer)"/> - which is
+    /// deterministic for a given input - yields the exact same ordered result. The scoring
+    /// function must be pure over each item (each item is scored by exactly one thread, so any
+    /// per-item cached state is never touched concurrently). Falls back to the serial path for
+    /// small inputs where partitioning would not pay off.
+    /// </summary>
+    public static RoScored<T>[] FilterListWithScoresParallel<T>(
+        IReadOnlyList<T>? items,
+        in FuzzyQuery query,
+        in ScoringFunction<T> scoreFunction)
+    {
+        if (items is null || items.Count == 0)
+        {
+            return [];
+        }
+
+        var count = items.Count;
+        var partitions = Math.Min(Environment.ProcessorCount, Math.Max(1, count / ParallelScoringThreshold));
+
+        if (count < ParallelScoringThreshold || partitions <= 1)
+        {
+            return FilterListWithScores(items, query, scoreFunction);
+        }
+
+        // Copy the by-ref parameters into locals so they can be captured by the parallel body.
+        // FuzzyQuery is an immutable value read concurrently (never mutated), so sharing one copy
+        // across threads is safe.
+        var q = query;
+        var fn = scoreFunction;
+        var source = items;
+
+        var partitionResults = new List<RoScored<T>>[partitions];
+
+        System.Threading.Tasks.Parallel.For(0, partitions, p =>
+        {
+            var start = (int)((long)p * count / partitions);
+            var end = (int)((long)(p + 1) * count / partitions);
+
+            var local = new List<RoScored<T>>(end - start);
+            for (var i = start; i < end; i++)
+            {
+                var item = source[i];
+                var score = fn(in q, item);
+                if (score > 0)
+                {
+                    local.Add(new RoScored<T>(item, score));
+                }
+            }
+
+            partitionResults[p] = local;
+        });
+
+        var total = 0;
+        for (var p = 0; p < partitions; p++)
+        {
+            total += partitionResults[p].Count;
+        }
+
+        // Concatenate partitions in order. Contiguous ranges merged in partition order reproduce
+        // the exact original enumeration order of the matched items, matching the serial buffer.
+        var buffer = GC.AllocateUninitializedArray<RoScored<T>>(total);
+        var pos = 0;
+        for (var p = 0; p < partitions; p++)
+        {
+            var list = partitionResults[p];
+            for (var j = 0; j < list.Count; j++)
+            {
+                buffer[pos++] = list[j];
+            }
+        }
+
+        Array.Sort(buffer, 0, total, default(RoScoredDescendingComparer<T>));
+        return buffer;
+    }
+
     private static void GrowBuffer<T>(ref RoScored<T>[] buffer, int count)
     {
         var newBuffer = ArrayPool<RoScored<T>>.Shared.Rent(buffer.Length * 2);

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/Commands/MainListPage.cs

@@ -500,6 +500,19 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
         }
 
         var commands = _tlcManager.TopLevelCommands;
+
+        // Materialized inputs captured under the lock so the heavy scoring below can run OFF the
+        // lock. Scoring no longer converts directly into blocked settle/render time, because
+        // GetItems() takes the SAME lock and now only contends with the short snapshot/publish
+        // sections rather than the whole multi-thousand-item scoring pass.
+        IReadOnlyList<IListItem> itemsSource;
+        IReadOnlyList<IListItem> appsSource;
+        IReadOnlyList<IListItem> fallbackSource;
+        IListItem[] globalFallbackSources;
+        bool includeAppsSnapshot;
+        bool tookFullCatalog = false;
+
+        // ===== SNAPSHOT PHASE (under lock) =====
         lock (commands)
         {
             if (token.IsCancellationRequested)
@@ -553,52 +566,28 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
                 return;
             }
 
-            // If the new string doesn't start with the old string, then we can't
-            // re-use previous results. Reset _filteredItems, and keep er moving.
-            if (!newSearch.StartsWith(oldSearch, StringComparison.CurrentCultureIgnoreCase))
-            {
-                ClearResults();
-            }
-
-            // If the internal state has changed, reset _filteredItems to reset the list.
-            if (_filteredItemsIncludesApps != _includeApps)
-            {
-                ClearResults();
-            }
-
-            if (token.IsCancellationRequested)
-            {
-                return;
-            }
-
-            var newFilteredItems = Enumerable.Empty<IListItem>();
-            var newFallbacks = Enumerable.Empty<IListItem>();
-            var newApps = Enumerable.Empty<IListItem>();
-
-            if (_filteredItems is not null)
-            {
-                newFilteredItems = _filteredItems.Select(s => s.Item);
-            }
-
-            if (token.IsCancellationRequested)
-            {
-                return;
-            }
-
-            if (_filteredApps is not null)
-            {
-                newApps = _filteredApps.Select(s => s.Item);
-            }
-
-            if (token.IsCancellationRequested)
-            {
-                return;
-            }
-
-            if (_fallbackItems is not null)
-            {
-                newFallbacks = _fallbackItems.Select(s => s.Item);
-            }
+            includeAppsSnapshot = _includeApps;
+
+            // If the new string doesn't start with the old string we can't re-use previous
+            // results; likewise if the app-inclusion state changed. Either way we rebuild from the
+            // full catalog. On an extend (the new query starts with the old and app state is
+            // unchanged) we re-score only the previously matched subset, not the whole catalog.
+            var reset = !newSearch.StartsWith(oldSearch, StringComparison.CurrentCultureIgnoreCase)
+                || _filteredItemsIncludesApps != includeAppsSnapshot;
+
+            var prevFilteredItems = reset ? null : _filteredItems;
+            var prevApps = reset ? null : _filteredApps;
+            var prevFallbacks = reset ? null : _fallbackItems;
+
+            IEnumerable<IListItem> newFilteredItems = prevFilteredItems is not null
+                ? prevFilteredItems.Select(s => s.Item)
+                : Enumerable.Empty<IListItem>();
+            IEnumerable<IListItem> newApps = prevApps is not null
+                ? prevApps.Select(s => s.Item)
+                : Enumerable.Empty<IListItem>();
+            IEnumerable<IListItem> newFallbacks = prevFallbacks is not null
+                ? prevFallbacks.Select(s => s.Item)
+                : Enumerable.Empty<IListItem>();
 
             if (token.IsCancellationRequested)
             {
@@ -609,6 +598,7 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
             // with a list of all our commands & apps.
             if (!newFilteredItems.Any() && !newApps.Any())
             {
+                tookFullCatalog = true;
                 newFilteredItems = commands.Where(s => !s.IsFallback);
 
                 // Fallbacks are always included in the list, even if they
@@ -621,9 +611,7 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
                     return;
                 }
 
-                _filteredItemsIncludesApps = _includeApps;
-
-                if (_includeApps)
+                if (includeAppsSnapshot)
                 {
                     var allNewApps = AllAppsCommandProvider.Page.GetItems().Cast<AppListItem>().ToList();
 
@@ -646,49 +634,88 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
                 }
             }
 
-            var searchQuery = _fuzzyMatcherProvider.Current.PrecomputeQuery(SearchText);
+            // Materialize every source sequence while still under the lock. After this point the
+            // scoring passes never touch the live TopLevelCommands collection or the app provider,
+            // so they are free to run off the lock. globalFallbackSources reuses the specialFallbacks
+            // list already built above, dropping the redundant second commands.Where(...) pass.
+            itemsSource = MaterializeSource(newFilteredItems);
+            appsSource = MaterializeSource(newApps);
+            fallbackSource = MaterializeSource(newFallbacks);
+            globalFallbackSources = [.. specialFallbacks];
+        }
 
-            // Produce a list of everything that matches the current filter.
-            _filteredItems = InternalListHelpers.FilterListWithScores(newFilteredItems, searchQuery, _scoringFunction);
+        if (token.IsCancellationRequested)
+        {
+            return;
+        }
 
-            if (token.IsCancellationRequested)
-            {
-                return;
-            }
+        // ===== SCORING PHASE (OFF the lock) =====
+        // The dominant apps pass is parallelized; commands and fallbacks stay serial. All of this
+        // now runs without holding the TopLevelCommands lock, so it no longer blocks GetItems()/render.
+        var searchQuery = _fuzzyMatcherProvider.Current.PrecomputeQuery(SearchText);
 
-            // Snapshot the global fallbacks and query, but do NOT score them here. Their dynamic
-            // titles are updated asynchronously by the fallback update manager (BeginUpdate, above),
-            // which runs off the typing path. Scoring is deferred to the render path so late fallback
-            // resolutions fold in with fresh scores instead of a value frozen against a stale title.
-            _globalFallbackSources = commands.Where(s => s.IsFallback && configuredGlobalFallbackIds.Contains(s.Id)).ToArray();
-            _globalFallbackQuery = searchQuery;
+        var scoredFilteredItems = InternalListHelpers.FilterListWithScores(itemsSource, searchQuery, _scoringFunction);
+
+        if (token.IsCancellationRequested)
+        {
+            return;
+        }
+
+        var scoredFallbackItems = InternalListHelpers.FilterListWithScores(fallbackSource, searchQuery, _fallbackScoringFunction);
+
+        if (token.IsCancellationRequested)
+        {
+            return;
+        }
+
+        RoScored<IListItem>[]? scoredApps = null;
+        if (appsSource.Count > 0)
+        {
+            // Build the frecency lookup once, single-threaded, before the parallel pass reads it.
+            // The lazy dictionary build in RecentCommandsManager is not thread-safe.
+            _appStateService.State.RecentCommands.PrewarmIndex();
+
+            scoredApps = InternalListHelpers.FilterListWithScoresParallel(appsSource, searchQuery, _scoringFunction);
 
             if (token.IsCancellationRequested)
             {
                 return;
             }
+        }
 
-            _fallbackItems = InternalListHelpers.FilterListWithScores<IListItem>(newFallbacks ?? [], searchQuery, _fallbackScoringFunction);
+#if CMDPAL_FF_MAINPAGE_TIME_RAISE_ITEMS
+        var filterDoneTimestamp = stopwatch.ElapsedMilliseconds;
+#endif
 
+        // ===== PUBLISH PHASE (under lock): atomic swap, supersede-safe =====
+        lock (commands)
+        {
+            // A newer keystroke cancels this token before doing its own work, so a stale snapshot's
+            // finished results can never overwrite a newer query's. Skip the swap when superseded.
             if (token.IsCancellationRequested)
             {
                 return;
             }
 
-            // Produce a list of filtered apps with the appropriate limit
-            if (newApps.Any())
+            if (tookFullCatalog)
             {
-                _filteredApps = InternalListHelpers.FilterListWithScores(newApps, searchQuery, _scoringFunction);
-
-                if (token.IsCancellationRequested)
-                {
-                    return;
-                }
+                _filteredItemsIncludesApps = includeAppsSnapshot;
             }
 
-#if CMDPAL_FF_MAINPAGE_TIME_RAISE_ITEMS
-            var filterDoneTimestamp = stopwatch.ElapsedMilliseconds;
-#endif
+            _filteredItems = scoredFilteredItems;
+            _fallbackItems = scoredFallbackItems;
+
+            // Snapshot the global fallbacks and query, but do NOT score them here. Their dynamic
+            // titles are updated asynchronously by the fallback update manager (BeginUpdate, above),
+            // which runs off the typing path. Scoring is deferred to the render path so late fallback
+            // resolutions fold in with fresh scores instead of a value frozen against a stale title.
+            _globalFallbackSources = globalFallbackSources;
+            _globalFallbackQuery = searchQuery;
+
+            // Apps are only re-scored when there is an apps source (either the full catalog with
+            // apps included, or a retained subset on the extend path). When there is none, publish
+            // null so a rebuild clears any stale set - matching the previous ClearResults behavior.
+            _filteredApps = appsSource.Count > 0 ? scoredApps : null;
 
             // Queue a settled-search telemetry event. This measures the deterministic first-paint
             // results (commands + capped apps) and the latency to produce them, at this boundary -
@@ -727,6 +754,13 @@ private void UpdateSearchTextCore(string oldSearch, string newSearch, bool isUse
         }
     }
 
+    // Materializes a source sequence into a stable, indexable snapshot so the scoring passes can
+    // run off the TopLevelCommands lock. Sequences that are already an IReadOnlyList (our own
+    // freshly built lists and empty arrays) are used as-is; lazy LINQ over the live collection or
+    // over previous results is copied so later mutation of the source can't affect scoring.
+    private static IReadOnlyList<IListItem> MaterializeSource(IEnumerable<IListItem> items)
+        => items as IReadOnlyList<IListItem> ?? items.ToArray();
+
     private bool ActuallyLoading()
     {
         var allApps = AllAppsCommandProvider.Page;

src/modules/cmdpal/Microsoft.CmdPal.UI.ViewModels/RecentCommandsManager.cs

@@ -100,6 +100,15 @@ public RecentCommandsManager()
     {
     }
 
+    /// <summary>
+    /// Forces the lazy command-id lookup (<see cref="Index"/>) to be built now, on the calling
+    /// thread. The build itself is not thread-safe (it populates a shared dictionary field without
+    /// locking), so callers that are about to score items in parallel MUST call this once,
+    /// single-threaded, before the parallel loop. Once built, <see cref="GetCommandHistoryWeight(string)"/>
+    /// only performs concurrent dictionary reads, which are safe.
+    /// </summary>
+    public void PrewarmIndex() => _ = Index;
+
     public int GetCommandHistoryWeight(string commandId)
         => GetCommandHistoryWeight(commandId, DateTimeOffset.UtcNow);
 
@@ -177,4 +186,12 @@ public interface IRecentCommandsManager
     int GetCommandHistoryWeight(string commandId);
 
     RecentCommandsManager WithHistoryItem(string commandId);
+
+    /// <summary>
+    /// Builds any lazily-initialized internal state (e.g. the command-id lookup) on the calling
+    /// thread so that subsequent <see cref="GetCommandHistoryWeight(string)"/> calls are safe to
+    /// issue concurrently. Callers that score items in parallel must invoke this once, single-
+    /// threaded, before the parallel loop.
+    /// </summary>
+    void PrewarmIndex();
 }