refactor(FenwickTree): extract PrefixSumCore, correct the layout wording, harden the test attribute

Review round 6:

- Extract the descending prefix walk into a single private PrefixSumCore, now
  shared by PrefixSum, RangeSumCore, and the indexer getter. The bit-strip was
  written three times across two methods; centralizing it removes the drift risk.
  RangeSumCore becomes the obvious PrefixSumCore(end) - PrefixSumCore(start).
- Correct the "single n-element array" wording in the XML summary, the API
  reference and the README: the 1-based layout means the backing array holds
  n + 1 elements with index 0 unused. The substantive claim (one flat array, no
  per-node object overhead) is unchanged.
- MemoryIntensiveFactAttribute now rejects a non-positive requiredMegabytes with
  ArgumentOutOfRangeException — a non-positive threshold is meaningless and would
  silently force the test to run everywhere, the exact behaviour the attribute
  exists to prevent — and states the no-overflow intent with checked arithmetic.
- Tag the memory-intensive regression with [Trait("Category", "MemoryIntensive")]
  so CI can segregate it (a serial job, or --filter "Category!=MemoryIntensive")
  without it having to be opted out of by default.

Verified: full suite 4420 passed / 0 failed; trait exclusion drops exactly that
one test (4419); the memory gate still reports Skipped under
DOTNET_GCHeapHardLimit=0x10000000.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: marius-bughiu

README.md

@@ -88,7 +88,7 @@ The mutable sets (`CeleritySet`, `SwissSet`, `RobinHoodSet`, `HashCachingSet`, `
 
 **Prefix sums**
 
-- `FenwickTree<T>` — a **Binary Indexed Tree** over a fixed-length numeric sequence (`where T : struct, INumber<T>`): **point update** and **prefix / range sum** both in `O(log n)`, in one `n`-element array with no per-node overhead. The prefix-sum structure the BCL lacks — running aggregates, rank / order-statistics counters, cumulative-frequency tables — where a plain array is `O(n)` per query (recompute the slice) *or* `O(n)` per update (fix the suffix). Wins precisely when updates and partial-sum queries interleave.
+- `FenwickTree<T>` — a **Binary Indexed Tree** over a fixed-length numeric sequence (`where T : struct, INumber<T>`): **point update** and **prefix / range sum** both in `O(log n)`, in one flat array with no per-node overhead. The prefix-sum structure the BCL lacks — running aggregates, rank / order-statistics counters, cumulative-frequency tables — where a plain array is `O(n)` per query (recompute the slice) *or* `O(n)` per update (fix the suffix). Wins precisely when updates and partial-sum queries interleave.
 
 **Probabilistic & bit-level**
 

docs/api/collections.md

@@ -3660,7 +3660,7 @@ public sealed class FenwickTree<T> : IReadOnlyCollection<T>
     where T : struct, INumber<T>
 ```
 
-A **Fenwick tree** (Binary Indexed Tree) is a fixed-length, array-backed sequence of numeric values that answers **prefix sums** — and therefore arbitrary **range sums** — and applies **point updates** in `O(log n)` each, over a single `n`-element array with no per-node object overhead. It is generic over `System.Numerics.INumber<T>`, so it works for `int`, `long`, `uint`, `ulong`, `double`, `decimal`, and any other value type with generic-math addition and subtraction.
+A **Fenwick tree** (Binary Indexed Tree) is a fixed-length, array-backed sequence of numeric values that answers **prefix sums** — and therefore arbitrary **range sums** — and applies **point updates** in `O(log n)` each, over a single flat array of `n + 1` elements (index `0` is unused by the 1-based layout), with no per-node object overhead. It is generic over `System.Numerics.INumber<T>`, so it works for `int`, `long`, `uint`, `ulong`, `double`, `decimal`, and any other value type with generic-math addition and subtraction.
 
 The BCL ships nothing for the **interleaved point-update + prefix-sum-query** workload, and a plain `T[]` forces a losing tradeoff: keep the raw values and every prefix / range query is `O(n)` (sum a slice); precompute a running-total array and queries are `O(1)` but every point update is `O(n)` (fix the whole suffix). A Fenwick tree gives **both** in `O(log n)`.
 

src/Celerity.Tests/Collections/FenwickTreeTests.cs

@@ -432,7 +432,10 @@ public void Enumerator_NonGeneric_ShouldYieldValues()
     // beyond the ~30 cells the ascent touches (the runtime zeroes lazily), so it completes in ~17 ms. Where
     // that headroom genuinely is not available (a memory-capped container or runner), MemoryIntensiveFact
     // reports the test skipped rather than running it, so it can never turn the build red on resource grounds.
+    // The Category trait lets CI segregate this if it ever needs to — e.g. `--filter "Category!=MemoryIntensive"`
+    // to exclude it, or a dedicated serial job to run it away from the parallel suite.
     [MemoryIntensiveFact(1024)]
+    [Trait("Category", "MemoryIntensive")]
     public void Add_ShouldNotOverflowIndex_WhenTreeExceedsTwoToThe30()
     {
         const int length = 1 << 30; // 2^30 one-byte cells + the reserved 1-based slot ≈ 1 GiB

src/Celerity.Tests/MemoryIntensiveFactAttribute.cs

@@ -19,14 +19,26 @@ public sealed class MemoryIntensiveFactAttribute : FactAttribute
     /// <summary>
     /// Marks a test as requiring <paramref name="requiredMegabytes"/> of allocatable memory.
     /// </summary>
-    /// <param name="requiredMegabytes">The size of the allocation the test makes, in MiB.</param>
+    /// <param name="requiredMegabytes">The size of the allocation the test makes, in MiB. Must be positive.</param>
+    /// <exception cref="ArgumentOutOfRangeException"><paramref name="requiredMegabytes"/> is not positive.</exception>
     public MemoryIntensiveFactAttribute(int requiredMegabytes)
     {
-        long required = (long)requiredMegabytes * 1024 * 1024;
+        // A non-positive requirement would make the threshold meaningless and silently force the test to run
+        // everywhere — exactly the behaviour this attribute exists to prevent. The argument is a compile-time
+        // constant, so this fails the first time the test is discovered rather than at run time.
+        if (requiredMegabytes <= 0)
+        {
+            throw new ArgumentOutOfRangeException(nameof(requiredMegabytes), requiredMegabytes,
+                "The required size must be positive.");
+        }
+
+        // Widening before the multiply already rules out overflow for every permitted argument; `checked`
+        // states that intent rather than relying on the reader to re-derive it.
+        long required = checked((long)requiredMegabytes * 1024 * 1024);
         long available = GC.GetGCMemoryInfo().TotalAvailableMemoryBytes;
 
         // A non-positive reading means "unknown" — run the test rather than skip on missing information.
-        if (available > 0 && available < required * RequiredHeadroomFactor)
+        if (available > 0 && available < checked(required * RequiredHeadroomFactor))
         {
             Skip = $"Needs ~{requiredMegabytes} MiB of allocatable memory " +
                    $"(with {RequiredHeadroomFactor}x headroom); this environment reports " +

src/Celerity/Collections/FenwickTree.cs

@@ -6,7 +6,8 @@ namespace Celerity.Collections;
 /// <summary>
 /// A <b>Fenwick tree</b> (Binary Indexed Tree): a fixed-length, array-backed sequence of numeric values that
 /// answers <b>prefix sums</b> (and therefore arbitrary range sums) and applies <b>point updates</b> in
-/// <c>O(log n)</c> each, over a single <c>n</c>-element array with no per-node object overhead.
+/// <c>O(log n)</c> each, over a single flat array — <c>n + 1</c> elements, the slot at index <c>0</c> being
+/// unused by the 1-based layout — with no per-node object overhead.
 /// </summary>
 /// <typeparam name="T">
 /// The numeric element type. Constrained to <see cref="INumber{TSelf}"/>, so it works for <see cref="int"/>,
@@ -193,11 +194,7 @@ public T PrefixSum(int endExclusive)
             throw new ArgumentOutOfRangeException(nameof(endExclusive), endExclusive,
                 "endExclusive must be in the range [0, Count].");
 
-        T sum = T.Zero;
-        for (int k = endExclusive; k > 0; k -= k & -k)
-            sum += _tree[k];
-
-        return sum;
+        return PrefixSumCore(endExclusive);
     }
 
     /// <summary>
@@ -266,18 +263,22 @@ private void AddCore(int index, T delta)
         _version++;
     }
 
-    // Range sum without validation: PrefixSum(endExclusive) - PrefixSum(start), collapsed to two walks.
-    private T RangeSumCore(int start, int endExclusive)
+    // The prefix walk, without validation — the single place the descending bit-strip is written, shared by
+    // PrefixSum, RangeSumCore, and the indexer getter. Unlike the ascending walks this one only ever clears
+    // the lowest set bit, so it strictly decreases and cannot overflow.
+    private T PrefixSumCore(int endExclusive)
     {
         T sum = T.Zero;
         for (int k = endExclusive; k > 0; k -= k & -k)
             sum += _tree[k];
-        for (int k = start; k > 0; k -= k & -k)
-            sum -= _tree[k];
 
         return sum;
     }
 
+    // Range sum without validation.
+    private T RangeSumCore(int start, int endExclusive) =>
+        PrefixSumCore(endExclusive) - PrefixSumCore(start);
+
     private static void ThrowIfSourceTooLong(int count, string paramName)
     {
         if (count > MaxLength)