Feature/readonly collections and adapters

[kasyanovandrii]

Problem: Equality Contract Violation in Dictionary and HashSet Comparers

The original DictionaryEqualityComparer, ReadOnlyDictionaryEqualityComparer, and HashSetEqualityComparer violated the
fundamental .NET equality contract:

▎ If Equals(x, y) == true then GetHashCode(x) == GetHashCode(y)

Equals was order-independent (TryGetValue / SetEquals) but GetHashCode was order-dependent (OrderBy + sequential
HashCode.Add). Two logically equal collections in different insertion order would produce different hash codes,
causing incorrect behavior in Dictionary, HashSet, and any equality-based data structure.

---

Changes

DictionaryEqualityComparer<K,V> and ReadOnlyDictionaryEqualityComparer<K,V>

Equals — unchanged, uses TryGetValue (order-independent).

GetHashCode — was OrderBy(key) + sequential HashCode.Add (order-dependent, inconsistent with Equals). Now uses
commutative SUM of HashCode.Combine(key, value) (order-independent, consistent with Equals).

HashSetEqualityComparer

Equals — unchanged, uses SetEquals (order-independent).

GetHashCode — was OrderBy + sequential HashCode.Add (order-dependent, inconsistent with Equals). Now uses commutative
SUM of element hash codes (order-independent, consistent with Equals).

New: [DictionaryEquality(sequential: true)]

Opt-in key-sorted comparison mode where both Equals and GetHashCode use OrderBy(key) — consistent with each other and
deterministic regardless of Dictionary<K,V> internal iteration order:

[DictionaryEquality(sequential: true)]
public Dictionary<string, int>? Entries { get; set; }

Backed by two new comparers:

• OrderedDictionaryEqualityComparer<K,V> — for IDictionary<K,V>
• OrderedReadOnlyDictionaryEqualityComparer<K,V> — for IReadOnlyDictionary<K,V>

Both use OrderBy(key) with a sort comparer that guarantees strict total order: prefers IComparer if available,
falls back to a hash-code tiebreaker to handle cases where Comparer.Default returns 0 for distinct keys (e.g.
culture-sensitive string.CompareTo treating "" and "\x02" as equal).

Nested collections and multidimensional arrays (unchanged)

The generator composes comparers automatically for nested collection types. These were not affected by the bug.
Examples of what the generator produces:

• Dict<K, List> → ReadOnlyDictionaryEqualityComparer<K, SequenceEqualityComparer> — outer unordered, inner
  ordered
• List<Dict<K,V>> → SequenceEqualityComparer<ReadOnlyDictionaryEqualityComparer<K,V>> — outer ordered, inner unordered
• Dict<K, Dict<K2, List>> → three-level nesting with correct semantics per level
• int[,] / T[,,] → MultiDimensionalArrayEqualityComparer — row-major order, no LINQ allocations

SequenceEqualityComparer and MultiDimensionalArrayEqualityComparer were always consistent (both order-dependent,
matching their respective Equals semantics) and are unchanged.

---

Property-Based Tests (FsCheck.Xunit.v3)

• Migrated from FsCheck.Xunit (xUnit v2 only, previously excluded from compilation) to FsCheck.Xunit.v3 (xUnit v3
  compatible)
• All property test files rewritten from v2 API (value.ToProperty()) to v3 API (Prop.ToProperty(value))
• Added Arbitraries class with custom generators for HashSet (not auto-derived in FsCheck v3)
• Property tests now run as part of the normal test suite (238 tests total, 0 failures)