42 lines
4.5 KiB
Markdown
42 lines
4.5 KiB
Markdown
# 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`.
|