feat(core): add pluggable IRandom facade over NRandom with weighted selection

Introduce a random-number facade in SquidStd.Core (SquidStd.Core.Rng) that
exposes multiple PRNG algorithms and gameplay helpers behind a SquidStd-owned
interface, so consumers never depend on the underlying NRandom types.

- feat(core): add IRandom abstraction (ints/longs/doubles, ranges, gaussian,
  NextBool with probability, NextBytes, Pick, Fisher-Yates Shuffle)
- feat(core): add RandomFactory with Shared (thread-safe) and seeded/algorithm
  Create overloads; RandomAlgorithmType selects xoshiro256**/xoshiro128**/pcg32/
  splitmix64/mersenne-twister/chacha
- feat(core): add NRandomAdapter wrapping NRandom generators; add NRandom 2.0.2
  package reference (non-cryptographic; crypto stays on CryptoUtils)
- feat(core): add IWeightedList/WeightedList for O(log n) weighted selection
  (loot/spawn tables) on cumulative weights over IRandom
- feat(game): add DiceExpression.Roll(IRandom) overload to roll from an injected
  reproducible source alongside the ambient BuiltInRng roll
- test: cover all algorithms (reproducibility, ranges, gaussian mean, bool
  extremes, shuffle multiset, pick), weighted distribution, and injected dice rolls

Author: tgiachi

src/SquidStd.Core/Interfaces/Rng/IRandom.cs

@@ -0,0 +1,55 @@
+namespace SquidStd.Core.Interfaces.Rng;
+
+/// <summary>
+/// A source of non-cryptographic pseudo-random values. Obtain instances from
+/// <see cref="SquidStd.Core.Rng.RandomFactory" />; instances created with a fixed seed produce
+/// reproducible sequences.
+/// </summary>
+public interface IRandom
+{
+    /// <summary>Returns a random 32-bit integer across the full range (may be negative).</summary>
+    int NextInt();
+
+    /// <summary>Returns a random integer in <c>[0, maxExclusive)</c>.</summary>
+    /// <param name="maxExclusive">Exclusive upper bound; must be positive.</param>
+    int NextInt(int maxExclusive);
+
+    /// <summary>Returns a random integer in <c>[minInclusive, maxExclusive)</c>.</summary>
+    /// <param name="minInclusive">Inclusive lower bound.</param>
+    /// <param name="maxExclusive">Exclusive upper bound; must exceed <paramref name="minInclusive" />.</param>
+    int NextInt(int minInclusive, int maxExclusive);
+
+    /// <summary>Returns a random 64-bit integer.</summary>
+    long NextLong();
+
+    /// <summary>Returns a random double in <c>[0, 1)</c>.</summary>
+    double NextDouble();
+
+    /// <summary>Returns a random double in <c>[minInclusive, maxExclusive)</c>.</summary>
+    /// <param name="minInclusive">Inclusive lower bound.</param>
+    /// <param name="maxExclusive">Exclusive upper bound.</param>
+    double NextDouble(double minInclusive, double maxExclusive);
+
+    /// <summary>Returns a normally-distributed random double.</summary>
+    /// <param name="mean">The distribution mean.</param>
+    /// <param name="standardDeviation">The distribution standard deviation.</param>
+    double NextGaussian(double mean = 0, double standardDeviation = 1);
+
+    /// <summary>Returns <c>true</c> with the given probability.</summary>
+    /// <param name="probability">Chance of <c>true</c> in <c>[0, 1]</c>; defaults to 0.5.</param>
+    bool NextBool(double probability = 0.5);
+
+    /// <summary>Fills the buffer with random bytes.</summary>
+    /// <param name="buffer">The buffer to fill.</param>
+    void NextBytes(Span<byte> buffer);
+
+    /// <summary>Returns a uniformly-chosen element from a non-empty list.</summary>
+    /// <typeparam name="T">The element type.</typeparam>
+    /// <param name="items">The list to pick from; must be non-empty.</param>
+    T Pick<T>(IReadOnlyList<T> items);
+
+    /// <summary>Shuffles the list in place using the Fisher–Yates algorithm.</summary>
+    /// <typeparam name="T">The element type.</typeparam>
+    /// <param name="items">The list to shuffle.</param>
+    void Shuffle<T>(IList<T> items);
+}

src/SquidStd.Core/Interfaces/Rng/IWeightedList.cs

@@ -0,0 +1,25 @@
+namespace SquidStd.Core.Interfaces.Rng;
+
+/// <summary>
+/// A mutable collection of items with associated positive weights, supporting weighted random
+/// selection — useful for loot tables, spawn tables, and similar gameplay data.
+/// </summary>
+/// <typeparam name="T">The element type.</typeparam>
+public interface IWeightedList<T>
+{
+    /// <summary>The number of items in the list.</summary>
+    int Count { get; }
+
+    /// <summary>The sum of all item weights.</summary>
+    double TotalWeight { get; }
+
+    /// <summary>Adds an item with the given weight.</summary>
+    /// <param name="item">The item to add.</param>
+    /// <param name="weight">The selection weight; must be positive.</param>
+    void Add(T item, double weight);
+
+    /// <summary>Selects an item at random, with probability proportional to its weight.</summary>
+    /// <param name="random">The random source to draw from.</param>
+    /// <returns>The selected item.</returns>
+    T Next(IRandom random);
+}

src/SquidStd.Core/Rng/NRandomAdapter.cs

@@ -0,0 +1,95 @@
+using SquidStd.Core.Interfaces.Rng;
+
+namespace SquidStd.Core.Rng;
+
+/// <summary>
+/// Adapts an <see cref="NRandom.IRandom" /> generator to the SquidStd <see cref="IRandom" /> surface,
+/// keeping consumer code independent of the underlying NRandom types.
+/// </summary>
+internal sealed class NRandomAdapter : IRandom
+{
+    private readonly NRandom.IRandom _inner;
+
+    public NRandomAdapter(NRandom.IRandom inner)
+    {
+        _inner = inner;
+    }
+
+    public int NextInt()
+    {
+        return NRandom.RandomEx.NextInt(_inner);
+    }
+
+    public int NextInt(int maxExclusive)
+    {
+        return NRandom.RandomEx.NextInt(_inner, maxExclusive);
+    }
+
+    public int NextInt(int minInclusive, int maxExclusive)
+    {
+        return NRandom.RandomEx.NextInt(_inner, minInclusive, maxExclusive);
+    }
+
+    public long NextLong()
+    {
+        return NRandom.RandomEx.NextLong(_inner);
+    }
+
+    public double NextDouble()
+    {
+        return NRandom.RandomEx.NextDouble(_inner);
+    }
+
+    public double NextDouble(double minInclusive, double maxExclusive)
+    {
+        return NRandom.RandomEx.NextDouble(_inner, minInclusive, maxExclusive);
+    }
+
+    public double NextGaussian(double mean = 0, double standardDeviation = 1)
+    {
+        return mean + (standardDeviation * NRandom.RandomEx.NextDoubleGaussian(_inner));
+    }
+
+    public bool NextBool(double probability = 0.5)
+    {
+        if (probability <= 0)
+        {
+            return false;
+        }
+
+        if (probability >= 1)
+        {
+            return true;
+        }
+
+        return NRandom.RandomEx.NextDouble(_inner) < probability;
+    }
+
+    public void NextBytes(Span<byte> buffer)
+    {
+        NRandom.RandomEx.NextBytes(_inner, buffer);
+    }
+
+    public T Pick<T>(IReadOnlyList<T> items)
+    {
+        ArgumentNullException.ThrowIfNull(items);
+
+        if (items.Count == 0)
+        {
+            throw new ArgumentException("Cannot pick from an empty collection.", nameof(items));
+        }
+
+        return items[NRandom.RandomEx.NextInt(_inner, items.Count)];
+    }
+
+    public void Shuffle<T>(IList<T> items)
+    {
+        ArgumentNullException.ThrowIfNull(items);
+
+        for (var i = items.Count - 1; i > 0; i--)
+        {
+            var j = NRandom.RandomEx.NextInt(_inner, i + 1);
+            (items[i], items[j]) = (items[j], items[i]);
+        }
+    }
+}

src/SquidStd.Core/Rng/RandomFactory.cs

@@ -0,0 +1,65 @@
+using SquidStd.Core.Interfaces.Rng;
+using SquidStd.Core.Types;
+
+namespace SquidStd.Core.Rng;
+
+/// <summary>
+/// Entry point for obtaining <see cref="IRandom" /> instances. Consumers depend only on this factory
+/// and <see cref="IRandom" />, never on the underlying NRandom generators.
+/// </summary>
+public static class RandomFactory
+{
+    private const int ChaChaRounds = 20;
+
+    /// <summary>A shared, thread-safe random source seeded non-deterministically.</summary>
+    public static IRandom Shared { get; } = new NRandomAdapter(NRandom.RandomEx.Shared);
+
+    /// <summary>Creates a random source using the default algorithm and a non-deterministic seed.</summary>
+    /// <returns>A new, non-thread-safe random source.</returns>
+    public static IRandom Create()
+    {
+        return new NRandomAdapter(NRandom.RandomEx.Create());
+    }
+
+    /// <summary>Creates a reproducible random source using the default algorithm and the given seed.</summary>
+    /// <param name="seed">The seed for reproducible sequences.</param>
+    /// <returns>A new, non-thread-safe random source.</returns>
+    public static IRandom Create(uint seed)
+    {
+        return Create(RandomAlgorithmType.Xoshiro256, seed);
+    }
+
+    /// <summary>Creates a random source using the given algorithm and a non-deterministic seed.</summary>
+    /// <param name="algorithm">The pseudo-random algorithm to use.</param>
+    /// <returns>A new, non-thread-safe random source.</returns>
+    public static IRandom Create(RandomAlgorithmType algorithm)
+    {
+        return new NRandomAdapter(NewGenerator(algorithm));
+    }
+
+    /// <summary>Creates a reproducible random source using the given algorithm and seed.</summary>
+    /// <param name="algorithm">The pseudo-random algorithm to use.</param>
+    /// <param name="seed">The seed for reproducible sequences.</param>
+    /// <returns>A new, non-thread-safe random source.</returns>
+    public static IRandom Create(RandomAlgorithmType algorithm, uint seed)
+    {
+        var generator = NewGenerator(algorithm);
+        generator.InitState(seed);
+
+        return new NRandomAdapter(generator);
+    }
+
+    private static NRandom.IRandom NewGenerator(RandomAlgorithmType algorithm)
+    {
+        return algorithm switch
+        {
+            RandomAlgorithmType.Xoshiro256 => new NRandom.Xoshiro256StarStarRandom(),
+            RandomAlgorithmType.Xoshiro128 => new NRandom.Xoshiro128StarStarRandom(),
+            RandomAlgorithmType.Pcg32 => new NRandom.Pcg32Random(),
+            RandomAlgorithmType.SplitMix64 => new NRandom.SplitMix64Random(),
+            RandomAlgorithmType.MersenneTwister => new NRandom.MersenneTwisterRandom(),
+            RandomAlgorithmType.ChaCha => new NRandom.ChaChaRandom(ChaChaRounds),
+            _ => throw new ArgumentOutOfRangeException(nameof(algorithm), algorithm, null),
+        };
+    }
+}

src/SquidStd.Core/Rng/WeightedList.cs

@@ -0,0 +1,56 @@
+using SquidStd.Core.Interfaces.Rng;
+
+namespace SquidStd.Core.Rng;
+
+/// <summary>
+/// A weighted collection backed by cumulative weights, selecting items in <c>O(log n)</c> via
+/// binary search. Weights must be positive; selection probability is proportional to weight.
+/// </summary>
+/// <typeparam name="T">The element type.</typeparam>
+public sealed class WeightedList<T> : IWeightedList<T>
+{
+    private readonly List<T> _items = [];
+    private readonly List<double> _cumulative = [];
+    private double _total;
+
+    public int Count => _items.Count;
+
+    public double TotalWeight => _total;
+
+    public void Add(T item, double weight)
+    {
+        if (weight <= 0 || double.IsNaN(weight) || double.IsInfinity(weight))
+        {
+            throw new ArgumentOutOfRangeException(nameof(weight), weight, "Weight must be a positive, finite number.");
+        }
+
+        _total += weight;
+        _items.Add(item);
+        _cumulative.Add(_total);
+    }
+
+    public T Next(IRandom random)
+    {
+        ArgumentNullException.ThrowIfNull(random);
+
+        if (_items.Count == 0)
+        {
+            throw new InvalidOperationException("The weighted list is empty.");
+        }
+
+        var roll = random.NextDouble() * _total;
+        var index = _cumulative.BinarySearch(roll);
+
+        if (index < 0)
+        {
+            index = ~index;
+        }
+
+        if (index >= _items.Count)
+        {
+            index = _items.Count - 1;
+        }
+
+        return _items[index];
+    }
+}

src/SquidStd.Core/SquidStd.Core.csproj

@@ -10,6 +10,7 @@
 
     <ItemGroup>
         <PackageReference Include="DryIoc.dll" Version="5.4.3"/>
+        <PackageReference Include="NRandom" Version="2.0.2"/>
         <PackageReference Include="Serilog" Version="4.3.1"/>
         <PackageReference Update="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.301">
             <PrivateAssets>all</PrivateAssets>

src/SquidStd.Core/Types/RandomAlgorithmType.cs

@@ -0,0 +1,27 @@
+namespace SquidStd.Core.Types;
+
+/// <summary>
+/// Selects the pseudo-random algorithm backing an <see cref="Interfaces.Rng.IRandom" /> instance.
+/// All options are non-cryptographic; use <see cref="Utils.CryptoUtils" /> or
+/// <see cref="System.Security.Cryptography.RandomNumberGenerator" /> for security-sensitive randomness.
+/// </summary>
+public enum RandomAlgorithmType
+{
+    /// <summary>xoshiro256** — fast, high-quality general-purpose default.</summary>
+    Xoshiro256,
+
+    /// <summary>xoshiro128** — 32-bit oriented variant.</summary>
+    Xoshiro128,
+
+    /// <summary>PCG32 (PCG-XSH-RR) — compact state with strong statistical quality.</summary>
+    Pcg32,
+
+    /// <summary>SplitMix64 — minimal state, well suited to seeding other generators.</summary>
+    SplitMix64,
+
+    /// <summary>Mersenne Twister (MT19937) — very long period, classic choice.</summary>
+    MersenneTwister,
+
+    /// <summary>ChaCha (20 rounds) — highest statistical quality of the set, but slower.</summary>
+    ChaCha,
+}

src/SquidStd.Game/Dice/DiceExpression.cs

@@ -1,4 +1,5 @@
 using System.Globalization;
+using SquidStd.Core.Interfaces.Rng;
 using SquidStd.Core.Utils;
 
 namespace SquidStd.Game.Dice;
@@ -27,9 +28,32 @@ public readonly record struct DiceExpression(int Count, int Sides, int Modifier)
 
     /// <summary>Rolls the expression, returning a random total in <c>[Min, Max]</c>.</summary>
     /// <returns>The rolled total, or <see cref="Modifier" /> for a pure constant.</returns>
+    /// <remarks>Uses the ambient <see cref="BuiltInRng" />; for an injected source use <see cref="Roll(IRandom)" />.</remarks>
     public int Roll()
         => IsConstant ? Modifier : RandomUtils.Dice(Count, Sides, Modifier);
 
+    /// <summary>Rolls the expression using the supplied random source, returning a total in <c>[Min, Max]</c>.</summary>
+    /// <param name="random">The random source to draw from.</param>
+    /// <returns>The rolled total, or <see cref="Modifier" /> for a pure constant.</returns>
+    public int Roll(IRandom random)
+    {
+        ArgumentNullException.ThrowIfNull(random);
+
+        if (IsConstant)
+        {
+            return Modifier;
+        }
+
+        var total = Modifier;
+
+        for (var i = 0; i < Count; i++)
+        {
+            total += random.NextInt(1, Sides + 1);
+        }
+
+        return total;
+    }
+
     /// <summary>
     /// Parses dice notation such as <c>2d4+1</c>, <c>d6</c>, <c>5</c>, or the wrapped form
     /// <c>dice(2d4+1)</c>. Whitespace is ignored and the <c>d</c> separator is case-insensitive.