refactor(Trie): align with the IReadOnlyDictionary<TKey, TValue?> convention, drop LINQ

- Implement IReadOnlyDictionary<string, TValue?> (was TValue), matching CelerityDictionary
  and the rest of the dictionary surface: public getters stay non-null (TValue), the nullable
  interface indexer is provided explicitly, and TryGetValue / Values / GetEnumerator now carry
  the TValue? annotation. Resolves the README "all dictionaries implement ...TValue?" tension.
- Replace the two LINQ Select usages (GetKeysWithPrefix, Values) — the only LINQ in
  src/Celerity/Collections — with plain iterator helpers (EnumerateKeys / EnumerateValues),
  keeping the eager version snapshot.
- Update docs/README to IReadOnlyDictionary<string, TValue?>.

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

Author: marius-bughiu

README.md

@@ -83,7 +83,7 @@ The mutable sets (`CeleritySet`, `SwissSet`, `RobinHoodSet`, `HashCachingSet`, `
 
 **Prefix trees**
 
-- `Trie<TValue>` — ordered **prefix tree** mapping string keys to values. `GetByPrefix` lists every entry whose key starts with a prefix in `O(prefix + matches)`, and `TryGetLongestPrefix` finds the longest stored key that is a prefix of a query in `O(query)`. The trie the BCL lacks — autocomplete, longest-prefix routing, and ordered (ascending-ordinal) iteration, where a `Dictionary<string, TValue>` has no prefix index and must scan every key and run `StartsWith`. Exact `Add` / `TryGetValue` favour a `Dictionary` (one hash vs a character walk); the trie earns its place on the prefix operations. Implements `IReadOnlyDictionary<string, TValue>`.
+- `Trie<TValue>` — ordered **prefix tree** mapping string keys to values. `GetByPrefix` lists every entry whose key starts with a prefix in `O(prefix + matches)`, and `TryGetLongestPrefix` finds the longest stored key that is a prefix of a query in `O(query)`. The trie the BCL lacks — autocomplete, longest-prefix routing, and ordered (ascending-ordinal) iteration, where a `Dictionary<string, TValue>` has no prefix index and must scan every key and run `StartsWith`. Exact `Add` / `TryGetValue` favour a `Dictionary` (one hash vs a character walk); the trie earns its place on the prefix operations. Implements `IReadOnlyDictionary<string, TValue?>`.
 
 **Probabilistic & bit-level**
 
@@ -514,7 +514,7 @@ Each type buys a different tradeoff. Find your workload below; if it isn't here,
 | **Double-ended queue** — add/remove at both ends (bounded FIFO queue, sliding window, work-stealing / undo buffer) or a queue needing random access by position | `Deque<T>` | Growable double-ended queue backed by a **circular buffer**: `O(1)` amortized `PushFront` / `PushBack` / `PopFront` / `PopBack` / peek and `O(1)` random access by index. The BCL has no deque — `Queue<T>` is FIFO-only, `Stack<T>` LIFO-only, and `LinkedList<T>` (the only O(1)-both-ends type) allocates a node per element. A warm bounded churn reuses the buffer with wrap-around so it **allocates nothing**, and enumeration walks contiguous memory. For a strict FIFO queue that never pushes front / pops back, BCL `Queue<T>` is already a circular buffer and is simpler. |
 | **Incremental connectivity / connected components** — union equivalence classes and ask whether two elements are in the same group (Kruskal MST, clustering, image segmentation, undirected cycle detection, "are these accounts linked?") | `DisjointSet<T>` | Union-find with **union by size** + **path halving**: near-`O(1)` amortized `Union` / `Find` / `Connected`, `O(α(n)) ≤ 4`. Runs a stream of merges + connectivity queries in near-linear total time, where the BCL substitutes are super-linear — a `Dictionary<T, HashSet<T>>` set-merge is `O(n²)` to coalesce `n` singletons, and a per-query BFS/DFS is `O(V+E)` every query. Grows only by merging (no un-union); it is not an `ISet<T>` — for element membership with add/remove/set-algebra use `CeleritySet` or `HashSet<T>`. |
 | **Priority queue whose priorities change** — a best-so-far frontier you relax (Dijkstra / Prim / A\*), or an event scheduler that reschedules / cancels pending items | `IndexedPriorityQueue<TElement, TPriority, THasher>` | Addressable binary min-heap with an element→slot index: `Update` (decrease-/increase-key) and `Remove` an arbitrary element in `O(log n)`, `Contains` / `TryGetPriority` in `O(1)`. The BCL `PriorityQueue<,>` can do none of these — its only substitute is lazy deletion, which grows the heap by one entry per update. Each element is a key (appears once); custom `IComparer<TPriority>` for a max-heap. For plain enqueue/dequeue with duplicate elements, the BCL `PriorityQueue<,>` is simpler. |
-| **Prefix / autocomplete / longest-prefix** over string keys — list everything under a prefix, find the most specific stored key that prefixes a query, or iterate keys in order (typeahead, route/dispatch tables, tokenizer / dictionary matching, namespace listing) | `Trie<TValue>` | Ordered prefix tree: `GetByPrefix` yields every entry under a prefix in `O(prefix + matches)` and in ascending key order, `TryGetLongestPrefix` finds the longest stored prefix of a query in `O(query)`, and enumeration is sorted for free — none of which a `Dictionary<string, TValue>` can do without an `O(n)` scan + `StartsWith`. For **pure exact-key** `Add` / `TryGetValue` / `Remove` a `Dictionary` (one hash vs a per-character walk) is faster; the trie earns its place only when you use the prefix operations. Implements `IReadOnlyDictionary<string, TValue>`; not thread-safe. |
+| **Prefix / autocomplete / longest-prefix** over string keys — list everything under a prefix, find the most specific stored key that prefixes a query, or iterate keys in order (typeahead, route/dispatch tables, tokenizer / dictionary matching, namespace listing) | `Trie<TValue>` | Ordered prefix tree: `GetByPrefix` yields every entry under a prefix in `O(prefix + matches)` and in ascending key order, `TryGetLongestPrefix` finds the longest stored prefix of a query in `O(query)`, and enumeration is sorted for free — none of which a `Dictionary<string, TValue>` can do without an `O(n)` scan + `StartsWith`. For **pure exact-key** `Add` / `TryGetValue` / `Remove` a `Dictionary` (one hash vs a per-character walk) is faster; the trie earns its place only when you use the prefix operations. Implements `IReadOnlyDictionary<string, TValue?>`; not thread-safe. |
 | Need a stable iteration order or multi-threaded access | BCL `Dictionary<,>`, `ConcurrentDictionary<,>` | Celerity is single-threaded and iteration order is unspecified. |
 
 **Celerity is not the right answer when** you need concurrent access (use `ConcurrentDictionary<,>` or your own lock — Celerity is single-threaded), the mutable `IDictionary<,>` interface, or a guaranteed iteration order (Celerity exposes `IReadOnlyDictionary<,>` only and does not promise order across versions).

docs/api/collections.md

@@ -3428,10 +3428,10 @@ Console.WriteLine(string.Join(", ", final.OrderBy(kv => kv.Key).Select(kv => $"{
 
 ## Trie<TValue>
 
-An ordered **prefix tree** (trie) mapping `string` keys to values. Every key is stored as a path of characters from a shared root, so keys sharing a prefix share that prefix's nodes. Implements `IReadOnlyDictionary<string, TValue>`.
+An ordered **prefix tree** (trie) mapping `string` keys to values. Every key is stored as a path of characters from a shared root, so keys sharing a prefix share that prefix's nodes. Implements `IReadOnlyDictionary<string, TValue?>`.
 
 ```csharp
-public sealed class Trie<TValue> : IReadOnlyDictionary<string, TValue>
+public sealed class Trie<TValue> : IReadOnlyDictionary<string, TValue?>
 ```
 
 The BCL ships no trie. `Dictionary<string, TValue>` answers an exact-key lookup in `O(1)` but has **no efficient prefix operation**: listing every key that starts with a prefix, or finding the longest stored key that is a prefix of a query, both force an `O(n)` scan of the whole dictionary plus a `StartsWith` per key. A trie answers those directly from its structure.

src/Celerity/Collections/Trie.cs

@@ -48,7 +48,7 @@ namespace Celerity.Collections;
 /// thread-safe; concurrent callers must synchronize externally.
 /// </para>
 /// </remarks>
-public sealed class Trie<TValue> : IReadOnlyDictionary<string, TValue>
+public sealed class Trie<TValue> : IReadOnlyDictionary<string, TValue?>
 {
     // A trie node. The root carries no incoming edge; every other node is reached by exactly one edge
     // character from its parent. Child edges are held in two parallel arrays kept sorted ascending by
@@ -243,7 +243,7 @@ public bool ContainsKey(string key)
     /// </param>
     /// <returns><c>true</c> if the key was found; otherwise <c>false</c>.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="key"/> is <c>null</c>.</exception>
-    public bool TryGetValue(string key, out TValue value)
+    public bool TryGetValue(string key, out TValue? value)
     {
         ArgumentNullException.ThrowIfNull(key);
         Node? node = FindNode(key);
@@ -252,7 +252,7 @@ public bool TryGetValue(string key, out TValue value)
             value = node.Value;
             return true;
         }
-        value = default!;
+        value = default;
         return false;
     }
 
@@ -359,7 +359,7 @@ public bool ContainsPrefix(string prefix)
     /// <param name="prefix">The prefix to match.</param>
     /// <returns>A lazily evaluated sequence of the matching entries in ascending key order.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="prefix"/> is <c>null</c>.</exception>
-    public IEnumerable<KeyValuePair<string, TValue>> GetByPrefix(string prefix)
+    public IEnumerable<KeyValuePair<string, TValue?>> GetByPrefix(string prefix)
     {
         ArgumentNullException.ThrowIfNull(prefix);
         Node? node = FindNode(prefix);
@@ -377,7 +377,12 @@ public IEnumerable<KeyValuePair<string, TValue>> GetByPrefix(string prefix)
     /// <param name="prefix">The prefix to match.</param>
     /// <returns>A lazily evaluated sequence of the matching keys in ascending order.</returns>
     /// <exception cref="ArgumentNullException"><paramref name="prefix"/> is <c>null</c>.</exception>
-    public IEnumerable<string> GetKeysWithPrefix(string prefix) => GetByPrefix(prefix).Select(pair => pair.Key);
+    public IEnumerable<string> GetKeysWithPrefix(string prefix)
+    {
+        ArgumentNullException.ThrowIfNull(prefix);
+        Node? node = FindNode(prefix);
+        return EnumerateKeys(node, prefix, _version);
+    }
 
     /// <summary>
     /// Finds the longest stored key that is a prefix of <paramref name="query"/> (a stored key equal to
@@ -441,18 +446,23 @@ public bool TryGetLongestPrefix(string query, out string? key, out TValue? value
     public IEnumerable<string> Keys => GetKeysWithPrefix(string.Empty);
 
     /// <summary>Gets the values ordered by their keys' ascending ordinal order.</summary>
-    public IEnumerable<TValue> Values => Enumerate(_root, string.Empty, _version).Select(pair => pair.Value);
+    public IEnumerable<TValue?> Values => EnumerateValues(_root, string.Empty, _version);
 
     /// <summary>
     /// Returns an enumerator that yields every entry in ascending ordinal key order. Enumeration allocates a
     /// small traversal stack; if the trie is modified during enumeration,
     /// <see cref="IEnumerator.MoveNext"/> throws <see cref="InvalidOperationException"/>.
     /// </summary>
     /// <returns>An enumerator over the trie's entries in ascending key order.</returns>
-    public IEnumerator<KeyValuePair<string, TValue>> GetEnumerator() => Enumerate(_root, string.Empty, _version).GetEnumerator();
+    public IEnumerator<KeyValuePair<string, TValue?>> GetEnumerator() => Enumerate(_root, string.Empty, _version).GetEnumerator();
 
     IEnumerator IEnumerable.GetEnumerator() => GetEnumerator();
 
+    // IReadOnlyDictionary<string, TValue?> indexer: the public indexer getter returns the non-null TValue for a
+    // nicer caller experience, so the interface's nullable-value getter is provided explicitly, matching the
+    // rest of the Celerity dictionary surface (e.g. CelerityDictionary).
+    TValue? IReadOnlyDictionary<string, TValue?>.this[string key] => this[key];
+
     // ---- internal machinery ----------------------------------------------------------------------
 
     // Walks the key from the root and returns the node it ends on, or null if the path breaks.
@@ -508,7 +518,7 @@ private bool TryInsert(string key, TValue value, bool overwrite)
     // and after each yield, so it surfaces on the very first MoveNext (BCL-style), not one item late. A null
     // `start` (a missing prefix) yields nothing but still runs the version check, so the empty result carries
     // the same invalidation contract as a non-empty one.
-    private IEnumerable<KeyValuePair<string, TValue>> Enumerate(Node? start, string startKey, int expectedVersion)
+    private IEnumerable<KeyValuePair<string, TValue?>> Enumerate(Node? start, string startKey, int expectedVersion)
     {
         if (expectedVersion != _version)
             ThrowModified();
@@ -518,7 +528,7 @@ private IEnumerable<KeyValuePair<string, TValue>> Enumerate(Node? start, string
 
         if (start.HasValue)
         {
-            yield return new KeyValuePair<string, TValue>(startKey, start.Value);
+            yield return new KeyValuePair<string, TValue?>(startKey, start.Value);
             if (expectedVersion != _version)
                 ThrowModified();
         }
@@ -539,7 +549,7 @@ private IEnumerable<KeyValuePair<string, TValue>> Enumerate(Node? start, string
                 sb.Append(node.ChildChars[ci]); // sb now holds the path to `child`
                 if (child.HasValue)
                 {
-                    yield return new KeyValuePair<string, TValue>(sb.ToString(), child.Value);
+                    yield return new KeyValuePair<string, TValue?>(sb.ToString(), child.Value);
                     if (expectedVersion != _version)
                         ThrowModified();
                 }
@@ -553,6 +563,21 @@ private IEnumerable<KeyValuePair<string, TValue>> Enumerate(Node? start, string
         }
     }
 
+    // Key- and value-only projections of Enumerate, as plain iterator blocks rather than LINQ, so the library
+    // keeps its no-LINQ / allocation-conscious stance. Each snapshots the version through Enumerate exactly as
+    // the pair walk does.
+    private IEnumerable<string> EnumerateKeys(Node? start, string startKey, int expectedVersion)
+    {
+        foreach (KeyValuePair<string, TValue?> pair in Enumerate(start, startKey, expectedVersion))
+            yield return pair.Key;
+    }
+
+    private IEnumerable<TValue?> EnumerateValues(Node? start, string startKey, int expectedVersion)
+    {
+        foreach (KeyValuePair<string, TValue?> pair in Enumerate(start, startKey, expectedVersion))
+            yield return pair.Value;
+    }
+
     private static void ThrowModified() =>
         throw new InvalidOperationException("Collection was modified; enumeration operation may not execute.");
 }