suaveplan/openspec/archive/2026-04-19-enterprise-random-family/proposal.md

Change: enterprise-random-family

Why

Randomness is used in 15+ places across the genesis and games codebases with five different hand-rolled PRNG algorithms (Mulberry32, SFC32, LCG, Park-Miller, xorshift128+) and direct Math.random() calls in game logic. There is no canonical seeded PRNG with offset/fork/checkpoint support, no statistical distribution library, and no unified string/ID generation surface. @suaveplan/types defines the Rng interface but no implementations ship. This change delivers the full randomness stack in three focused packages.

What Changes

New packages (3)

• @suaveplan/pseudo-random — deterministic seeded PRNG implementations conforming to @suaveplan/types's Rng interface. Algorithms: Mulberry32 (32-bit, ultra-light), SFC32 (128-bit, high-quality), Xoshiro256++ (256-bit, supports jump), CounterRng (hash-based, O(1) seek to any position). Extended SeededRng interface adds skip(n), at(offset), fork(id), checkpoint(), restore(state). Seed normalization via splitmix64 mixing (not djb2/FNV-1a). Fisher-Yates shuffle, weighted choice, and distribution helpers all accept an rng? parameter. Zero dependency on crypto.getRandomValues.

• @suaveplan/random — high-level random utilities backed by a CSPRNG default. Provides: pluggable global source (getDefaultRng/setDefaultRng), cryptoRng() factory (WebCrypto-backed Rng), string/ID generation (randomString with 8 character-set presets, randomUUID v4+v7, randomULID, randomNanoid), collection operations (shuffle, sample, choice, weightedChoice, weightedSample), object/record operations (randomKey, randomValue, randomEntry, randomSubset), game primitives (coin, dice, roll), and statistical distributions (Normal, LogNormal, Exponential, Gamma, Beta, Pareto, Weibull, Cauchy, Logistic, Bernoulli, Geometric, Binomial, Poisson) plus a unified createSampler(config: DistributionConfig, rng?) dispatcher for data-driven/serializable distribution selection. All functions accept optional rng?: Rng.

• @suaveplan/noise — spatial field functions for procedural generation. Perlin (2D/3D), Simplex (2D/3D/4D), Value noise (2D/3D), Worley/cell noise (2D/3D), Fractional Brownian Motion (fBm) compositor, and Blue noise sampler. All seeded. These are deterministic field functions, not PRNGs — they belong in a separate package from @suaveplan/pseudo-random.

Modified Capabilities

• @suaveplan/geo (future) — will receive a random subpath (@suaveplan/geo/random) exposing randomPosition, randomPoint, randomPolygon, randomLineString with bbox constraints. Not in scope for this change; noted for coordination.

Capabilities

New Capabilities

• seeded-prng: SeededRng interface + Mulberry32, SFC32, Xoshiro256++, CounterRng implementations with offset/fork/checkpoint. Consolidates hand-rolled PRNGs from bingo, baccarat, rummy, minesweeper, fruit-machine.
• random-utilities: CSPRNG-backed general utilities — strings, IDs, collections, objects, game primitives, all injectable.
• statistical-distributions: Full d3-random-equivalent distribution suite with DistributionConfig tagged-union for serializable dispatch.
• noise-functions: Spatial/procedural noise field functions (Perlin, Simplex, Value, Worley, fBm, Blue noise).

Modified Capabilities

None — no existing genesis specs exist for these capabilities yet.

Impact

• Dependency order: pseudo-random (no workspace deps) → random (depends on @suaveplan/types, @suaveplan/error) → noise (independent, @suaveplan/error only)
• @suaveplan/pseudo-random and @suaveplan/random are parallel-shippable — noise has no dependency on either
• Consolidates 5 hand-rolled PRNGs across games codebase — migration path: replace with Mulberry32Rng or Sfc32Rng from @suaveplan/pseudo-random
• @suaveplan/testing seededRng — currently ships its own Mulberry32. After @suaveplan/pseudo-random ships, @suaveplan/testing can re-export from there (but must not add a workspace dep — the testing rule holds; the existing inline implementation stays)
• @suaveplan/crypto ByteSource — crypto's byte-level injection type is distinct from Rng in @suaveplan/types and is not affected by this change
• Non-goals: Cryptographic PRNGs (ChaCha20-DRBG, Fortuna) — those belong in @suaveplan/crypto-sodium/crypto-browser. Gaussian Process regression, Monte Carlo methods — future @suaveplan/stats. Geo random geometry — deferred to @suaveplan/geo.