feat(collections): add immutable list comparison sort

Author: robertvokac

CLAUDE.md

@@ -9,7 +9,7 @@
 ## Non-negotiable rules
 
 1. **Zero errors, zero warnings** before any commit. `cmake --build build --parallel 4` must be clean.
-2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,630 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
+2. **No test-count regression.** `scripts/run_component_tests.sh build` must show no failures. The verified baseline is 12,632 tests across 36 component executables and one integration executable; this floor should be raised as new tests are added and lowered only with an explicit, documented reason.
 3. **Push only to `feature/work`.** Never push to `develop` or `master`, and never create tags, without explicit per-action user approval.
 4. **SPDX header on every project source/header** — `// SPDX-License-Identifier: MIT` + copyright + .NET attribution. Vendored sources retain their upstream headers; Markdown uses an HTML SPDX comment where one is present.
 5. **Property naming:** always `getXxxProperty()` / `setXxxProperty()`. Exception: indexers

NEXT.md

@@ -4,9 +4,9 @@
 # NEXT.md
 
 *Last verified: 2026-07-25. Branch: `feature/work`. The P0 component-boundary
-repair, three P1 parity repairs, P1 portability revalidation, and seven bounded
+repair, three P1 parity repairs, P1 portability revalidation, and eight bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,630 tests across 37 executables.*
+edges, and 12,632 tests across 37 executables.*
 
 This is the cold-start handoff for the next working session. Keep it focused
 on verified facts, remaining bounded work, and commands needed to resume.
@@ -28,7 +28,7 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - The ten-job selective consumer matrix, including a direct
   `Collections.Blocking` consumer, is green. Text.Json retains its target
   absence and negative include-leakage assertions.
-- The full native baseline is a warning-free build with 12,630 passing tests
+- The full native baseline is a warning-free build with 12,632 passing tests
   across 36 component executables and one integration executable.
 - `TaskT<TResult>::ContinueWith` now supports both action and result-producing
   callbacks. It runs inline on completion; `NotOn*` and `OnlyOn*` filter the
@@ -43,6 +43,9 @@ Historical session detail belongs in git history and `plan.sqlite3`.
 - `ImmutableList<T>` supports all three `CopyTo` overloads using a fixed-size
   `std::vector` destination. Its bounds checks distinguish invalid source
   ranges from an undersized destination and avoid signed-overflow-prone sums.
+- `ImmutableList<T>::Sort(Comparison<T>)` returns an independently backed
+  custom-ordered result using the established signed comparison delegate and
+  rejects an empty delegate.
 - MinGW-w64 GCC 14-win32/CMake 3.31.6 and Emscripten 5.0.7/CMake 3.31.6 both
   compile the post-modular `All` graph and selective `Text.Json` libraries.
   This is compile-only evidence: cross tests were deliberately disabled.
@@ -51,15 +54,16 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   ASan/LSan ownership scenarios, including 100 continuation teardowns, pass.
 
 The local `plan.sqlite3` snapshot contains 16,201 classified `task` rows and
-1,749 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,750 completed tickets. Ticket #1737 records the completed P0 split, tickets
 #1738/#1739 the MemoryStream and generic-continuation repairs, ticket #1740 the
 XML whitespace repair, #1741 the completed cross-build revalidation and
 `WebProxy` portability fix, #1742 focused sanitizer evidence, and #1743 the
 `ImmutableList<T>` predicate-query slice. Ticket #1744 records seekable
 `BinaryReader::PeekChar`, #1745 `ImmutableList<T>::Sort`/`Reverse`, and #1746
 `ImmutableList<T>::GetRange`, #1747 `ImmutableList<T>::ConvertAll`, #1748 the
-UTF-8 `BinaryReader` batch-character APIs, and #1749 `ImmutableList<T>`
-copying. The database is git-ignored and is not part of a fresh clone.
+UTF-8 `BinaryReader` batch-character APIs, #1749 `ImmutableList<T>` copying,
+and #1750 its custom comparison sort. The database is git-ignored and is not
+part of a fresh clone.
 
 ## P0 completion: restore Collections isolation
 
@@ -176,13 +180,20 @@ They preserve order and source immutability, allow valid empty end ranges,
 and distinguish invalid indices/ranges from an undersized destination. Five
 regressions cover each overload, boundary behavior, and validation.
 
+## P2 completion: `ImmutableList<T>::Sort(Comparison<T>)`
+
+`Sort` now accepts the project's signed `Comparison<T>` delegate convention:
+negative is before, zero equivalent, positive after. It returns an
+independently backed result and rejects an empty delegate with
+`ArgumentNullException`; two regressions cover custom ordering and validation.
+
 ## Recommended next bounded tasks
 
 All currently planned P1 work is complete. Choose one consumer-driven P2
 slice, create a ticket, and keep the changes isolated:
 
 1. **`ImmutableList<T>` breadth.** Select one real consumer-needed group from
-   builder support or comparer overloads.
+   builder support, range operations, or remaining comparer overloads.
 2. **Other documented partial surfaces.** Examples include `BigInteger`
    bitwise operations, fuller UTF-7 behavior, and wider debugger/process/XML
    surfaces.

README.md

@@ -7,7 +7,7 @@ collector, or the complete .NET platform.
 
 The repository currently builds as 41 independently selectable CMake
 components. The verified Linux baseline on 2026-07-25 is a warning-free build
-with **12,630 passing tests across 37 test executables**.
+with **12,632 passing tests across 37 test executables**.
 
 ## What is included
 
@@ -181,7 +181,7 @@ Other platform evidence is narrower:
 
 | Platform/toolchain | Verified scope |
 |---|---|
-| Linux/GCC | Current full component build and all 12,630 tests. |
+| Linux/GCC | Current full component build and all 12,632 tests. |
 | Windows/MinGW | MinGW-w64 GCC 14-win32/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. GoogleTest was not cross-built and repository CI remains Ubuntu-only. |
 | Emscripten | Emscripten 5.0.7/CMake 3.31.6 compiled the post-component `All` and selective `Text.Json` library graphs under ticket #1741. Tests were not cross-built or run, and some runtime APIs deliberately throw `PlatformNotSupportedException`. |
 | macOS/Apple Clang | Real downstream Xcode 15.4 builds drove portability fixes on 2026-07-20; this repository has no macOS job or recorded full standalone test baseline. |

docs/CMakeComponents.md

@@ -131,7 +131,7 @@ are named `SharpRuntimeTests_<Component>`; genuinely cross-module scenarios
 are in `SharpRuntimeIntegrationTests`. CTest also discovers every individual
 GoogleTest case.
 
-The verified 2026-07-25 `All` baseline contains 12,630 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,632 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

modules/collections/include/System/Collections/Immutable/ImmutableList.hpp

@@ -26,8 +26,7 @@ using SharpRuntime::intcs;
  * Remove/RemoveAll/RemoveAt/RemoveRange(int,int)/Sort/Reverse/Contains/IndexOf/LastIndexOf/
  * BinarySearch).
  * Deliberately deferred relative to real .NET's ImmutableList<T> (a much larger surface backed
- * by an AVL tree, not a flat vector): range and custom-comparer Sort/Reverse overloads,
- * ToBuilder/Builder,
+ * by an AVL tree, not a flat vector): range Sort/Reverse overloads, ToBuilder/Builder,
  * RemoveRange(IEnumerable<T>), and every
  * IEqualityComparer<T>/IComparer<T>-taking overload of Remove/RemoveRange/Replace/IndexOf/
  * LastIndexOf/BinarySearch (this port always uses T::operator== / operator< instead). These are
@@ -373,8 +372,8 @@ class ImmutableList {
     /**
      * @brief Returns a new list with all elements sorted using T::operator<.
      *
-     * C++ counterpart of .NET ImmutableList<T>.Sort(). Range and custom-comparer
-     * overloads remain deliberately unimplemented.
+     * C++ counterpart of .NET ImmutableList<T>.Sort(). Range overloads remain
+     * deliberately unimplemented.
      * @return A sorted immutable list; the source list is unchanged.
      */
     [[nodiscard]] ImmutableList<T> Sort() const {
@@ -383,6 +382,29 @@ class ImmutableList {
         return ImmutableList<T>(std::move(values));
     }
 
+    /**
+     * @brief Returns a new list sorted by a custom comparison delegate.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.Sort(Comparison<T>). The comparison follows
+     * the established project convention: negative means before, zero equivalent, and positive
+     * means after.
+     * @param comparison The comparison delegate.
+     * @return A sorted immutable list; the source list is unchanged.
+     * @throws System::ArgumentNullException if @p comparison is empty.
+     */
+    [[nodiscard]] ImmutableList<T> Sort(std::function<intcs(const T&, const T&)> comparison) const {
+        if (!comparison) {
+            throw System::ArgumentNullException("comparison");
+        }
+
+        auto values = std::make_shared<std::vector<T>>(*data_);
+        std::sort(values->begin(), values->end(),
+                  [&comparison](const T& left, const T& right) {
+                      return comparison(left, right) < 0;
+                  });
+        return ImmutableList<T>(std::move(values));
+    }
+
     /**
      * @brief Returns a new list whose elements are in reverse order.
      *

modules/collections/tests/System/Collections/ImmutableListOrderingTests.cpp

@@ -3,6 +3,9 @@
 // Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
 #include <gtest/gtest.h>
 
+#include <functional>
+
+#include "System/ArgumentNullException.hpp"
 #include "System/Collections/Immutable/ImmutableList.hpp"
 
 using System::Collections::Immutable::ImmutableList;
@@ -44,3 +47,24 @@ TEST(ImmutableListOrderingTests, SortAndReverseHandleEmptyAndSingletonLists) {
     ASSERT_EQ(single.Reverse().getCountProperty(), 1);
     EXPECT_EQ(single.Reverse()[0], 42);
 }
+
+TEST(ImmutableListOrderingTests, SortWithCustomComparisonReturnsIndependentOrder) {
+    const auto source = ImmutableList<int>::Create({4, 1, 3, 2});
+    const auto sorted = source.Sort([](const int& left, const int& right) {
+        return right - left;
+    });
+
+    EXPECT_EQ(source[0], 4);
+    EXPECT_EQ(source[1], 1);
+    EXPECT_EQ(sorted[0], 4);
+    EXPECT_EQ(sorted[1], 3);
+    EXPECT_EQ(sorted[2], 2);
+    EXPECT_EQ(sorted[3], 1);
+}
+
+TEST(ImmutableListOrderingTests, SortWithEmptyComparisonThrowsArgumentNullException) {
+    const auto source = ImmutableList<int>::Create({1});
+    const std::function<SharpRuntime::intcs(const int&, const int&)> comparison;
+
+    EXPECT_THROW(source.Sort(comparison), System::ArgumentNullException);
+}

plan.md

@@ -1,7 +1,7 @@
 # Sharp Runtime plan
 
 *Last verified: 2026-07-25 — 41 physical components, 90 direct production
-dependency edges, a clean native build, 12,630 passing tests across 37
+dependency edges, a clean native build, 12,632 passing tests across 37
 executables, and a green ten-job selective matrix.*
 
 Sharp Runtime is in a consumer-driven expansion phase. The original type
@@ -32,7 +32,7 @@ was never created. Neither file should be linked as current documentation.
 ### Code and validation
 
 - Native Linux/GCC build: zero errors and zero warnings.
-- Tests: 12,630 passing across 36 component binaries plus one integration
+- Tests: 12,632 passing across 36 component binaries plus one integration
   binary.
 - Component graph: 41 physical modules and 90 direct production edges.
 - Boundary validator: no cycles, duplicate public include paths, orphan
@@ -52,7 +52,7 @@ The 2026-07-25 local snapshot contains:
 | Table | State |
 |---|---|
 | `task` | 16,201 rows: 1,082 `ported`, 140 `ignore`, 14,979 legacy `ignored`; no unclassified or `tobedecided` rows |
-| `ticket` | 1,749 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
+| `ticket` | 1,750 rows, all `done`; no `todo`, `doing`, `blocked`, or `needs_user` rows |
 
 Because `plan.sqlite3` is git-ignored, these counts describe the maintainer
 snapshot, not data shipped in a fresh clone.
@@ -107,6 +107,9 @@ assertion without an explicit architecture decision.
 - Added all three `ImmutableList<T>::CopyTo` overloads under ticket #1749,
   using checked fixed-size `std::vector` destinations, including source range
   and destination offset handling without signed-overflow-prone bounds checks.
+- Added `ImmutableList<T>::Sort(Comparison<T>)` under ticket #1750. It follows
+  the established signed comparison-delegate convention, rejects an empty
+  delegate, and returns an independently backed sorted list.
 - Added consumer-driven coverage across core, collections, IO, networking,
   threading/tasks, text/JSON, XML, numerics, globalization, and cryptographic
   hashing/random APIs.
@@ -167,7 +170,7 @@ The first consumer-driven ports after modularization added:
 - XML schema exception types.
 
 The verified test baseline grew from 12,494 at the modularization checkpoint
-to 12,630.
+to 12,632.
 
 ## Candidate roadmap
 
@@ -177,9 +180,9 @@ acceptance criteria and a validation command before changing code.
 ### P2 — Consumer-driven API breadth
 
 1. **Continue a bounded `ImmutableList<T>` slice.**
-   Its documented omissions include builder support and comparer overloads.
-   Do not attempt the entire surface in one change; select methods required by
-   a real consumer and port them against the .NET reference.
+   Its documented omissions include builder support plus range and remaining
+   comparer overloads. Do not attempt the entire surface in one change; select
+   methods required by a real consumer and port them against the .NET reference.
 
 2. **Extend `BinaryReader` only from a concrete consumer need.**
    `ReadChar`, `ReadChars`, `Read(char[])`, `ReadDecimal`, and seekable