docs(BTree): stop conflating a null key with default(TKey)

Comparer<T>.Default orders null before every non-null value, which is what
makes a null key or element legal here — but that says nothing about
default(TKey) for a value type: default(int) is 0, and sorts after every
negative key like any other. The B-trees have no out-of-band default slot at
all, unlike the hash-based family, so default(TKey) is simply an ordinary key.

Reworded in the BTreeDictionary / BTreeSet / DefaultComparer XML remarks and
in both places in docs/api/collections.md, and renamed the two tests whose
names claimed default(TKey) sorts first (the assertions were already correct:
0 lands between -5 and 5).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: marius-bughiu

docs/api/collections.md

@@ -3781,7 +3781,7 @@ There is no capacity or load-factor parameter — a B-tree grows one node at a t
 | `Enumerator GetEnumerator()` | Struct enumerator over the entries in ascending key order. The traversal path is held in an inline buffer, so a `foreach` allocates nothing. |
 | `void CopyTo(KeyValuePair<TKey, TValue?>[] array, int arrayIndex)` | Copy every entry in key order. |
 
-Unlike `SortedDictionary`, a **`null` (or `default`) key is legal** and sorts before every other key, matching how the rest of the family treats the out-of-band default key; a custom `TComparer` that rejects `null` overrides that. Adding, removing, and clearing invalidate active enumerators (`InvalidOperationException` from `MoveNext`); lookups, a rejected duplicate `TryAdd`, a `Remove` of an absent key, and an in-place value overwrite do not. Not thread-safe.
+Unlike `SortedDictionary`, a **`null` key is legal**: `Comparer<TKey>.Default` orders `null` before every non-`null` key (a custom `TComparer` that rejects `null` overrides that). There is no out-of-band `default(TKey)` slot as in the hash-based family — a value-type `default(TKey)` is an ordinary key that sorts wherever the comparer puts it, so `0` follows every negative `int` rather than coming first. Adding, removing, and clearing invalidate active enumerators (`InvalidOperationException` from `MoveNext`); lookups, a rejected duplicate `TryAdd`, a `Remove` of an absent key, and an in-place value overwrite do not. Not thread-safe.
 
 ### Usage example
 
@@ -3859,7 +3859,7 @@ As with the dictionary, there is no capacity or load factor. The `IEnumerable` o
 | `void CopyTo(T[] array, int arrayIndex)` | Copy every element in ascending order. |
 | `Enumerator GetEnumerator()` | Allocation-free struct enumerator in ascending order. |
 
-Membership is defined by `TComparer` — two elements are the same element when the comparer orders them equal. The set-algebra members materialize the right-hand side into a `HashSet<T>`, so they compare *that* side with `EqualityComparer<T>.Default` (matching the rest of the family). A custom comparer that treats two values as equal when `EqualityComparer<T>.Default` does not — a case-insensitive order, say — can therefore disagree with `SortedSet<T>` on those members alone. A `null` (or `default`) element is legal and sorts first. Not thread-safe.
+Membership is defined by `TComparer` — two elements are the same element when the comparer orders them equal. The set-algebra members materialize the right-hand side into a `HashSet<T>`, so they compare *that* side with `EqualityComparer<T>.Default` (matching the rest of the family). A custom comparer that treats two values as equal when `EqualityComparer<T>.Default` does not — a case-insensitive order, say — can therefore disagree with `SortedSet<T>` on those members alone. A `null` element is legal and `Comparer<T>.Default` orders it before every non-`null` one; a value-type `default(T)` is just an ordinary element, sorted wherever the comparer puts it. Not thread-safe.
 
 ### Usage example
 

src/Celerity.Tests/Collections/BTreeDictionaryTests.cs

@@ -396,8 +396,10 @@ public void AddAndRemove_ShouldStayConsistent_WhenInterleaved()
     // ---- the default / null key ---------------------------------------------
 
     [Fact]
-    public void Add_ShouldAcceptDefaultKey_AndSortItFirst()
+    public void Add_ShouldTreatDefaultKeyAsOrdinary_WhenKeyIsAValueType()
     {
+        // There is no out-of-band default-key slot here: default(int) is 0, an ordinary key that sorts
+        // between the negatives and the positives rather than first.
         var dict = new BTreeDictionary<int, string>();
         dict.Add(5, "five");
         dict.Add(0, "zero");
@@ -410,7 +412,7 @@ public void Add_ShouldAcceptDefaultKey_AndSortItFirst()
     }
 
     [Fact]
-    public void Add_ShouldAcceptNullKey_AndSortItFirst()
+    public void Add_ShouldAcceptNullKey_AndSortItBeforeEveryNonNullKey()
     {
         // Comparer<string>.Default orders null before every non-null key, so — unlike SortedDictionary —
         // a null key is a legal, well-ordered key here.

src/Celerity.Tests/Collections/BTreeSetTests.cs

@@ -246,7 +246,7 @@ public void AddAndRemove_ShouldStayConsistent_WhenInterleaved()
     }
 
     [Fact]
-    public void Add_ShouldAcceptNullElement_AndSortItFirst()
+    public void Add_ShouldAcceptNullElement_AndSortItBeforeEveryNonNullElement()
     {
         var set = new BTreeSet<string>();
         set.Add("b");

src/Celerity/Collections/BTreeDictionary.cs

@@ -75,10 +75,12 @@ public BTreeDictionary(IEnumerable<KeyValuePair<TKey, TValue>> source)
 /// <see cref="CelerityDictionary{TKey, TValue, THasher}"/> instead.
 /// </para>
 /// <para>
-/// Unlike <see cref="SortedDictionary{TKey, TValue}"/>, a <c>null</c> (or <c>default</c>) key is legal and
-/// sorts before every other key, matching how the rest of the family treats the out-of-band default key;
-/// a custom <typeparamref name="TComparer"/> that rejects <c>null</c> overrides that. This type is not
-/// thread-safe; concurrent callers must synchronize externally.
+/// Unlike <see cref="SortedDictionary{TKey, TValue}"/>, a <c>null</c> key is legal:
+/// <see cref="Comparer{T}.Default"/> orders <c>null</c> before every non-<c>null</c> key (a custom
+/// <typeparamref name="TComparer"/> that rejects <c>null</c> overrides that). There is no out-of-band
+/// <c>default(TKey)</c> slot as in the hash-based family — a value-type <c>default(TKey)</c> is an ordinary
+/// key that sorts wherever the comparer puts it, so <c>0</c> follows every negative <see cref="int"/> rather
+/// than coming first. This type is not thread-safe; concurrent callers must synchronize externally.
 /// </para>
 /// </remarks>
 public class BTreeDictionary<TKey, TValue, TComparer>

src/Celerity/Collections/BTreeSet.cs

@@ -67,9 +67,11 @@ public BTreeSet(IEnumerable<T> source)
 /// <see cref="EqualityComparer{T}.Default"/>, matching the rest of the family. A custom comparer that treats
 /// two values as equal when <see cref="EqualityComparer{T}.Default"/> does not — a case-insensitive order,
 /// say — can therefore disagree with <see cref="SortedSet{T}"/> on those members alone. Like the rest of the family, <see cref="Add"/> throws
-/// on a duplicate — use <see cref="TryAdd"/> when the element may already be present. A <c>null</c> (or
-/// <c>default</c>) element is legal and sorts first. This type is not thread-safe; concurrent callers must
-/// synchronize externally.
+/// on a duplicate — use <see cref="TryAdd"/> when the element may already be present. A <c>null</c> element is
+/// legal and <see cref="Comparer{T}.Default"/> orders it before every non-<c>null</c> one; there is no
+/// out-of-band <c>default(T)</c> slot as in the hash-based family, so a value-type <c>default(T)</c> is an
+/// ordinary element that sorts wherever the comparer puts it (<c>0</c> follows every negative
+/// <see cref="int"/>). This type is not thread-safe; concurrent callers must synchronize externally.
 /// </para>
 /// </remarks>
 public class BTreeSet<T, TComparer> : ISet<T>, IReadOnlySet<T>

src/Celerity/Collections/DefaultComparer.cs

@@ -29,7 +29,9 @@ namespace Celerity.Collections;
 /// </code>
 /// <para>
 /// A <c>null</c> argument is not rejected: <see cref="Comparer{T}.Default"/> orders <c>null</c> before every
-/// non-<c>null</c> value, which is what makes <c>default(TKey)</c> a legal key in the ordered collections.
+/// non-<c>null</c> value, which is what makes a <c>null</c> key or element legal in the ordered collections.
+/// That says nothing about <c>default(T)</c> for a value type — <c>default(int)</c> is simply <c>0</c>, and
+/// sorts after every negative value like any other key.
 /// </para>
 /// </remarks>
 public readonly struct DefaultComparer<T> : IComparer<T>