feat(collections): add immutable list builder core

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,662 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,666 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 seventeen bounded
+repair, three P1 parity repairs, P1 portability revalidation, and eighteen bounded
 P2 API slices are complete: 41 physical modules, 90 production dependency
-edges, and 12,662 tests across 37 executables.*
+edges, and 12,666 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,662 passing tests
+- The full native baseline is a warning-free build with 12,666 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
@@ -70,6 +70,10 @@ Historical session detail belongs in git history and `plan.sqlite3`.
   integer values. It also supports signed left and arithmetic right shifts,
   plus minimal byte-vector conversion with signed/unsigned and little/big-endian
   options.
+- `ImmutableList<T>` provides `CreateBuilder()` and `ToBuilder()` with core
+  mutable operations and independent `ToImmutable()` snapshots. The current
+  vector backend copies source/snapshot contents rather than claiming .NET's
+  tree-backed O(1) conversion characteristics.
 - 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.
@@ -78,7 +82,7 @@ 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,759 completed tickets. Ticket #1737 records the completed P0 split, tickets
+1,760 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
@@ -91,8 +95,9 @@ database also records #1752 for its `IComparer<T>` sorting overloads, #1753
 for its equality-based item mutations, #1754 for its equality-based range
 queries, #1755 for its comparer-aware binary search, #1756 for its default
 range sort, #1757 for `BigInteger` bitwise operators, #1758 for signed
-`BigInteger` shifts, and #1759 for byte-vector conversion; it is git-ignored
-and is not part of a fresh clone.
+`BigInteger` shifts, #1759 for byte-vector conversion, and #1760 for the
+`ImmutableList<T>` Builder core; it is git-ignored and is not part of a fresh
+clone.
 
 ## P0 completion: restore Collections isolation
 
@@ -235,11 +240,11 @@ full-list/range order and invalid range validation.
 All currently planned P1 work is complete. Choose one consumer-driven P2
 slice, create a ticket, and keep the changes isolated:
 
-1. **`ImmutableList<T>` builder support.** Treat `ToBuilder`/`Builder` as a
-   separately scoped API design, not an opportunistic extension of the
-   vector-backed immutable-list methods.
-2. **Other documented partial surfaces.** Examples include fuller UTF-7
+1. **Other documented partial surfaces.** Examples include fuller UTF-7
    behavior and wider debugger/process/XML surfaces.
+2. **Advanced `ImmutableList<T>::Builder` operations by consumer need.**
+   Query, sorting, and copy overloads remain explicitly deferred; retain the
+   vector-backed snapshot semantics if a focused consumer requires one.
 3. **Doxygen warning baseline.** Establish a reproducible warning count, then
    keep touched public APIs from increasing it; do not do a mass comment-only
    rewrite.

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,662 passing tests across 37 test executables**.
+with **12,666 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,662 tests. |
+| Linux/GCC | Current full component build and all 12,666 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,662 tests across 36
+The verified 2026-07-25 `All` baseline contains 12,666 tests across 36
 component executables and one integration executable.
 
 ## Boundary validation and CI

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

@@ -26,12 +26,11 @@ using SharpRuntime::intcs;
  *
  * Covers the core mutation/lookup surface (Add/AddRange/Insert/InsertRange/SetItem/Replace/
  * Remove/RemoveAll/RemoveAt/RemoveRange(int,int)/Sort/Reverse/Contains/IndexOf/LastIndexOf/
- * BinarySearch).
+ * BinarySearch) and the core mutable Builder workflow.
  * Deliberately deferred relative to real .NET's ImmutableList<T> (a much larger surface backed
- * by an AVL tree, not a flat vector): ToBuilder/Builder. This is a real gap, not incorrect
- * behavior for the surface that does exist -- left undone here rather than expanded ad hoc in a
- * single audit pass; a full port would need an AVL/red-black backing structure to match .NET's
- * O(log n) persistent-update complexity (this port's vector-copy approach is O(n) per mutation).
+ * by an AVL tree, not a flat vector): advanced Builder query, sorting, and copy operations. The
+ * implemented Builder makes independent vector-backed immutable snapshots, so it does not claim
+ * the .NET tree implementation's O(1) ToBuilder or near-O(1) ToImmutable characteristics.
  *
  * @tparam T The type of elements stored in the list.
  */
@@ -63,6 +62,128 @@ class ImmutableList {
     }
 
 public:
+    /**
+     * @brief Mutable staging collection for building an ImmutableList snapshot.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.Builder. It uses the current
+     * vector-backed representation, so ToImmutable copies the current contents
+     * and later Builder changes cannot mutate an already returned list.
+     */
+    class Builder {
+        std::vector<T> data_;
+
+        void requireIndexInRange(intcs index) const {
+            if (index < 0 || index >= static_cast<intcs>(data_.size())) {
+                throw System::ArgumentOutOfRangeException(
+                    "index", "Index was out of range. Must be non-negative and less than the size of the collection.");
+            }
+        }
+
+        void requireValidRange(intcs index, intcs count) const {
+            if (index < 0 || index > static_cast<intcs>(data_.size())) {
+                throw System::ArgumentOutOfRangeException(
+                    "index", "Index was out of range. Must be non-negative and less than or equal to the size of the collection.");
+            }
+            if (count < 0 || index > static_cast<intcs>(data_.size()) - count) {
+                throw System::ArgumentOutOfRangeException(
+                    "count", "Count must refer to a location within the collection.");
+            }
+        }
+
+    public:
+        /** @brief Creates an empty Builder. Prefer ImmutableList<T>::CreateBuilder(). */
+        Builder() = default;
+
+        /** @brief Creates a Builder initialized from the supplied vector. */
+        explicit Builder(const std::vector<T>& items) : data_(items) {}
+
+        /** @brief Gets the number of elements in this Builder. */
+        [[nodiscard]] intcs getCountProperty() const { return static_cast<intcs>(data_.size()); }
+
+        /** @brief Gets a mutable reference to an element after range validation. */
+        T& operator[](intcs index) {
+            requireIndexInRange(index);
+            return data_[static_cast<size_t>(index)];
+        }
+
+        /** @brief Gets a const reference to an element after range validation. */
+        const T& operator[](intcs index) const {
+            requireIndexInRange(index);
+            return data_[static_cast<size_t>(index)];
+        }
+
+        /** @brief Appends an item to this Builder. */
+        void Add(const T& item) { data_.push_back(item); }
+
+        /** @brief Appends all items in @p items to this Builder. */
+        void AddRange(const std::vector<T>& items) {
+            data_.insert(data_.end(), items.begin(), items.end());
+        }
+
+        /** @brief Inserts an item at @p index. */
+        void Insert(intcs index, const T& item) {
+            if (index < 0 || index > static_cast<intcs>(data_.size())) {
+                throw System::ArgumentOutOfRangeException("index");
+            }
+            data_.insert(data_.begin() + index, item);
+        }
+
+        /** @brief Inserts all @p items at @p index. */
+        void InsertRange(intcs index, const std::vector<T>& items) {
+            if (index < 0 || index > static_cast<intcs>(data_.size())) {
+                throw System::ArgumentOutOfRangeException("index");
+            }
+            data_.insert(data_.begin() + index, items.begin(), items.end());
+        }
+
+        /** @brief Replaces the element at @p index. */
+        void SetItem(intcs index, const T& item) {
+            requireIndexInRange(index);
+            data_[static_cast<size_t>(index)] = item;
+        }
+
+        /** @brief Removes the first matching item and reports whether one was removed. */
+        bool Remove(const T& item) {
+            const auto found = std::find(data_.begin(), data_.end(), item);
+            if (found == data_.end()) {
+                return false;
+            }
+            data_.erase(found);
+            return true;
+        }
+
+        /** @brief Removes the element at @p index. */
+        void RemoveAt(intcs index) {
+            requireIndexInRange(index);
+            data_.erase(data_.begin() + index);
+        }
+
+        /** @brief Removes @p count elements starting at @p index. */
+        void RemoveRange(intcs index, intcs count) {
+            requireValidRange(index, count);
+            data_.erase(data_.begin() + index, data_.begin() + index + count);
+        }
+
+        /** @brief Removes all elements from this Builder. */
+        void Clear() { data_.clear(); }
+
+        /** @brief Determines whether this Builder contains @p item. */
+        [[nodiscard]] bool Contains(const T& item) const {
+            return std::find(data_.begin(), data_.end(), item) != data_.end();
+        }
+
+        /** @brief Returns the first index of @p item, or -1 if it is absent. */
+        [[nodiscard]] intcs IndexOf(const T& item) const {
+            const auto found = std::find(data_.begin(), data_.end(), item);
+            return found == data_.end() ? -1 : static_cast<intcs>(found - data_.begin());
+        }
+
+        /** @brief Returns an immutable snapshot unaffected by later Builder mutations. */
+        [[nodiscard]] ImmutableList<T> ToImmutable() const {
+            return ImmutableList<T>(std::make_shared<std::vector<T>>(data_));
+        }
+    };
+
     /** @brief Default-constructs an empty ImmutableList. */
     ImmutableList() : data_(std::make_shared<std::vector<T>>()) {}
 
@@ -74,6 +195,13 @@ class ImmutableList {
      */
     static ImmutableList<T> Empty() { return ImmutableList<T>(); }
 
+    /**
+     * @brief Creates an empty mutable Builder.
+     *
+     * C++ counterpart of .NET ImmutableList.CreateBuilder<T>().
+     */
+    [[nodiscard]] static Builder CreateBuilder() { return Builder(); }
+
     /**
      * @brief Creates an ImmutableList from an initializer list.
      *
@@ -96,6 +224,14 @@ class ImmutableList {
         return ImmutableList<T>(std::make_shared<std::vector<T>>(items));
     }
 
+    /**
+     * @brief Creates a mutable Builder with a copy of this list's contents.
+     *
+     * C++ counterpart of .NET ImmutableList<T>.ToBuilder(). The vector-backed
+     * representation copies contents so the source remains immutable.
+     */
+    [[nodiscard]] Builder ToBuilder() const { return Builder(*data_); }
+
     /**
      * @brief Gets the number of elements in the list.
      *

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

@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) Robert Vokac and contributors
+// Portions based on .NET runtime API (MIT License, Copyright .NET Foundation and Contributors)
+#include <gtest/gtest.h>
+
+#include <vector>
+
+#include "System/ArgumentOutOfRangeException.hpp"
+#include "System/Collections/Immutable/ImmutableList.hpp"
+
+using System::Collections::Immutable::ImmutableList;
+
+TEST(ImmutableListBuilderTest, ToBuilderMutatesWorkingCopyWithoutChangingSource) {
+    const auto source = ImmutableList<int>::Create({1, 2, 4});
+    auto builder = source.ToBuilder();
+
+    builder.Insert(2, 3);
+    builder[0] = 10;
+    builder.Add(5);
+
+    const auto snapshot = builder.ToImmutable();
+    EXPECT_EQ(source.getCountProperty(), 3);
+    EXPECT_EQ(source[0], 1);
+    EXPECT_EQ(source[2], 4);
+    EXPECT_EQ(snapshot.getCountProperty(), 5);
+    EXPECT_EQ(snapshot[0], 10);
+    EXPECT_EQ(snapshot[1], 2);
+    EXPECT_EQ(snapshot[2], 3);
+    EXPECT_EQ(snapshot[4], 5);
+}
+
+TEST(ImmutableListBuilderTest, SnapshotsRemainImmutableAfterFurtherBuilderMutations) {
+    auto builder = ImmutableList<int>::CreateBuilder();
+    builder.AddRange({1, 2});
+
+    const auto first = builder.ToImmutable();
+    builder.SetItem(0, 10);
+    builder.Add(3);
+    const auto second = builder.ToImmutable();
+
+    EXPECT_EQ(first.getCountProperty(), 2);
+    EXPECT_EQ(first[0], 1);
+    EXPECT_EQ(first[1], 2);
+    EXPECT_EQ(second.getCountProperty(), 3);
+    EXPECT_EQ(second[0], 10);
+    EXPECT_EQ(second[2], 3);
+}
+
+TEST(ImmutableListBuilderTest, RangeMutationsAndQueriesFollowMutableListSemantics) {
+    auto builder = ImmutableList<int>::CreateBuilder();
+    builder.AddRange({1, 4});
+    builder.InsertRange(1, {2, 3});
+    EXPECT_TRUE(builder.Contains(3));
+    EXPECT_EQ(builder.IndexOf(3), 2);
+    EXPECT_TRUE(builder.Remove(2));
+    EXPECT_FALSE(builder.Remove(99));
+    builder.RemoveRange(1, 2);
+
+    const auto result = builder.ToImmutable();
+    ASSERT_EQ(result.getCountProperty(), 1);
+    EXPECT_EQ(result[0], 1);
+}
+
+TEST(ImmutableListBuilderTest, ValidatesIndexesAndRangesAndClearCreatesEmptySnapshot) {
+    auto builder = ImmutableList<int>::CreateBuilder();
+    builder.Add(1);
+
+    EXPECT_THROW(builder[-1], System::ArgumentOutOfRangeException);
+    EXPECT_THROW(builder.Insert(2, 3), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(builder.RemoveAt(1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(builder.RemoveRange(1, 1), System::ArgumentOutOfRangeException);
+    EXPECT_THROW(builder.RemoveRange(0, -1), System::ArgumentOutOfRangeException);
+
+    builder.Clear();
+    EXPECT_TRUE(builder.ToImmutable().getIsEmptyProperty());
+}