Add Int32Murmur3Hasher

A higher-quality avalanche counterpart to Int32WangNaiveHasher, using the
canonical Murmur3 fmix32 finalizer. Struct hasher with AggressiveInlining
so calls devirtualize on the probe path through the struct-constrained
generic parameter.

Tests cover exact reference values (regenerated via Python against the
canonical algorithm), the 0 -> 0 identity, determinism, sign-bit
avalanche, a fixed-point sanity check, and a 1000-value distinctness
sweep.

Refs #24 in ISSUES.md. Closes the Int32Murmur3Hasher item on
milestone 1.1.0 in ROADMAP.md.

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

Author: marius-bughiu

CHANGELOG.md

@@ -6,6 +6,8 @@ All notable changes to Celerity are documented here. This project follows [Keep
 
 ### Added
 
+- `Int32Murmur3Hasher` in `Celerity.Hashing` — Murmur3 `fmix32` finalizer for `int` keys. Struct hasher, `AggressiveInlining`. Higher-quality avalanche counterpart to `Int32WangNaiveHasher`; use this when keys may be clustered or adversarial.
+- `Int32Murmur3HasherTests` — exact-value cases against the canonical Murmur3 fmix32 reference (including `0`, `1`, `-1`, `int.MinValue`, `int.MaxValue`), determinism, avalanche on the sign bit, a fixed-point sanity check guarding against the finalizer being bypassed, and a 1000-value distinctness sweep.
 - `UInt32Hasher` in `Celerity.Hashing` — Wang/Jenkins-style bit-mixer for `uint` keys. Struct hasher, `AggressiveInlining`. Counterpart to `Int32WangNaiveHasher`.
 - `UInt64Hasher` in `Celerity.Hashing` — Murmur3 `fmix64` finalizer for `ulong` keys. Struct hasher, `AggressiveInlining`. Counterpart to `Int64Murmur3Hasher`.
 - `UInt32HasherTests` and `UInt64HasherTests` — exact-value cases (including values crossing the sign bit), determinism, avalanche on the top bit, and a 1000-value distinctness sweep for the 64-bit mixer.

ROADMAP.md

@@ -49,7 +49,7 @@ The next release rounds out the `Celerity.Collections` package with missing coll
 
 ### Hashers
 
-- Add `Int32Murmur3Hasher`, `Int64WangHasher`, `GuidHasher`, `UInt32Hasher`, `UInt64Hasher`. (#24) — `UInt32Hasher` and `UInt64Hasher` `done`; the others still `planned`.
+- Add `Int32Murmur3Hasher`, `Int64WangHasher`, `GuidHasher`, `UInt32Hasher`, `UInt64Hasher`. (#24) — `Int32Murmur3Hasher`, `UInt32Hasher`, and `UInt64Hasher` `done`; `Int64WangHasher` and `GuidHasher` still `planned`.
 - Add `DefaultHasher<T>` fallback to `EqualityComparer<T>.Default.GetHashCode()`.
 
 ### Infrastructure

src/Celerity.Tests/Hashing/Int32Murmur3HasherTests.cs

@@ -0,0 +1,107 @@
+using Celerity.Hashing;
+
+namespace Celerity.Tests.Hashing;
+
+public class Int32Murmur3HasherTests
+{
+    private readonly Int32Murmur3Hasher _hasher = new Int32Murmur3Hasher();
+
+    // Reference values produced by the canonical MurmurHash3 fmix32 finalizer
+    // (k ^= k >> 16; k *= 0x85ebca6b; k ^= k >> 13; k *= 0xc2b2ae35; k ^= k >> 16).
+    // Exact values guard against accidental constant or shift edits.
+    [Theory]
+    [InlineData(0, 0)]
+    [InlineData(1, 1364076727)]             // 0x514E28B7
+    [InlineData(-1, -2114883783)]            // 0x81F16F39 (input 0xFFFFFFFF)
+    [InlineData(int.MinValue, 1832674720)]   // 0x6D3C65A0 (input 0x80000000)
+    [InlineData(int.MaxValue, -104067416)]   // 0xF9CC0EA8 (input 0x7FFFFFFF)
+    [InlineData(123456789, -1168058214)]     // 0xBA60D89A
+    public void Hash_ReturnsExpected(int input, int expected)
+    {
+        Assert.Equal(expected, _hasher.Hash(input));
+    }
+
+    [Fact]
+    public void Hash_Zero_ReturnsZero()
+    {
+        // Murmur3 fmix32 maps 0 -> 0 (each stage is a no-op on the zero state).
+        Assert.Equal(0, _hasher.Hash(0));
+    }
+
+    [Fact]
+    public void Hash_IsDeterministic()
+    {
+        int value = unchecked((int)0xDEADBEEF);
+        int result1 = _hasher.Hash(value);
+        int result2 = _hasher.Hash(value);
+        Assert.Equal(result1, result2);
+    }
+
+    [Fact]
+    public void Hash_DistinctInputs_ProduceDistinctResultsForSmallRange()
+    {
+        // fmix32 is a bijection on 32 bits, so a sequential sweep of 1000 inputs
+        // must produce 1000 distinct outputs. A collision here would indicate a
+        // broken mixer rather than an expected birthday-paradox event.
+        var seen = new HashSet<int>();
+        for (int i = 0; i < 1000; i++)
+        {
+            Assert.True(seen.Add(_hasher.Hash(i)),
+                $"Unexpected collision at input {i}.");
+        }
+    }
+
+    [Fact]
+    public void Hash_HighBit_InfluencesResult()
+    {
+        // Avalanche check: two inputs that differ only in the sign bit should
+        // produce very different 32-bit hashes. The naive Wang-style mixer only
+        // folds the top 16 bits into the bottom 16, so a single-bit flip in the
+        // MSB barely changes the low half of the output — Murmur3 fmix32 must
+        // do much better than that.
+        int low = _hasher.Hash(1);
+        int high = _hasher.Hash(unchecked((int)(1u | (1u << 31))));
+        Assert.NotEqual(low, high);
+    }
+
+    [Fact]
+    public void Hash_SequentialInputs_AreNotIdentity()
+    {
+        // A good mixer maps adjacent integers to distant hashes. Regression
+        // guard against accidentally returning the identity: hash(i) == i for
+        // many sequential i would indicate the finalizer was bypassed.
+        int identityMatches = 0;
+        for (int i = 0; i < 256; i++)
+        {
+            if (_hasher.Hash(i) == i)
+            {
+                identityMatches++;
+            }
+        }
+
+        // Only i = 0 is a fixed point of fmix32 in this range; anything more
+        // than that would indicate a broken implementation.
+        Assert.Equal(1, identityMatches);
+    }
+
+    [Fact]
+    public void Hash_DoesNotThrow()
+    {
+        int[] testValues =
+        {
+            0,
+            1,
+            -1,
+            int.MaxValue,
+            int.MinValue,
+            123456789,
+            -987654321,
+        };
+
+        foreach (int val in testValues)
+        {
+            var exception = Record.Exception(() => _hasher.Hash(val));
+            Assert.Null(exception);
+        }
+    }
+}

src/Celerity/Hashing/Int32Murmur3Hasher.cs

@@ -0,0 +1,47 @@
+using System.Runtime.CompilerServices;
+
+namespace Celerity.Hashing;
+
+/// <summary>
+/// A high-quality hash provider for <see cref="int"/> keys using the
+/// Murmur3 32-bit finalizer ("fmix32").
+/// </summary>
+/// <remarks>
+/// This is the same finalizer used in MurmurHash3 for 32-bit keys. Every input
+/// bit affects every output bit, giving excellent avalanche properties at the
+/// cost of a few more instructions than <see cref="Int32WangNaiveHasher"/>.
+/// Prefer this hasher when keys may be clustered or adversarial; prefer
+/// <see cref="Int32WangNaiveHasher"/> when keys are already well distributed
+/// and latency dominates.
+/// </remarks>
+public struct Int32Murmur3Hasher : IHashProvider<int>
+{
+    private const uint C1 = 0x85ebca6bU;
+    private const uint C2 = 0xc2b2ae35U;
+
+    /// <inheritdoc/>
+    [MethodImpl(MethodImplOptions.AggressiveInlining)]
+    public int Hash(int key)
+    {
+        // Reinterpret as unsigned so the shifts are logical, not arithmetic.
+        uint k = unchecked((uint)key);
+
+        // XOR with its shifted self.
+        k ^= k >> 16;
+
+        // Multiply by a large odd constant.
+        k *= C1;
+
+        // XOR again with its shifted self.
+        k ^= k >> 13;
+
+        // Multiply by another large odd constant.
+        k *= C2;
+
+        // Final XOR.
+        k ^= k >> 16;
+
+        // Reinterpret the 32-bit result as a signed integer.
+        return unchecked((int)k);
+    }
+}