# Capability: statistical-distributions

## ADDED Requirements

### Location

- REQ-DIST-001: All distribution functions live in `@suaveplan/random` under `src/distributions/`.

### Continuous distributions

- REQ-DIST-010: Exports `normal(mu?: number, sigma?: number, rng?: Rng): () => number` — Gaussian via Box-Muller. Defaults `mu=0, sigma=1`.
- REQ-DIST-011: Exports `logNormal(mu?: number, sigma?: number, rng?: Rng): () => number` — `exp(normal(mu, sigma))`.
- REQ-DIST-012: Exports `exponential(lambda: number, rng?: Rng): () => number`. Throws if `lambda <= 0`.
- REQ-DIST-013: Exports `gamma(k: number, theta?: number, rng?: Rng): () => number` — Marsaglia-Tsang for k≥1, Ahrens-Dieter for k<1. Default `theta=1`.
- REQ-DIST-014: Exports `beta(alpha: number, betaParam: number, rng?: Rng): () => number` — ratio of two Gamma samples.
- REQ-DIST-015: Exports `pareto(alpha: number, rng?: Rng): () => number`. Throws if `alpha <= 0`.
- REQ-DIST-016: Exports `weibull(k: number, a?: number, b?: number, rng?: Rng): () => number`. Defaults `a=0, b=1`.
- REQ-DIST-017: Exports `cauchy(a?: number, b?: number, rng?: Rng): () => number`. Defaults `a=0, b=1`.
- REQ-DIST-018: Exports `logistic(a?: number, b?: number, rng?: Rng): () => number`. Defaults `a=0, b=1`.

### Discrete distributions

- REQ-DIST-020: Exports `bernoulli(p: number, rng?: Rng): () => 0 | 1`. Throws if `p` outside `[0, 1]`.
- REQ-DIST-021: Exports `geometric(p: number, rng?: Rng): () => number`. Throws if `p` outside `(0, 1]`.
- REQ-DIST-022: Exports `binomial(n: number, p: number, rng?: Rng): () => number`. Throws if `n < 0` or `p` outside `[0, 1]`.
- REQ-DIST-023: Exports `poisson(lambda: number, rng?: Rng): () => number` — Knuth for λ≤30, rejection method above. Throws if `lambda <= 0`.

### Unified dispatcher

- REQ-DIST-030: Exports `DistributionConfig` — discriminated union: `{ type: 'normal'; mu?: number; sigma?: number } | { type: 'exponential'; lambda: number } | ...` (one member per distribution).
- REQ-DIST-031: Exports `createSampler(config: DistributionConfig, rng?: Rng): () => number` — dispatches to the appropriate distribution factory.
- REQ-DIST-032: Exports `sample(config: DistributionConfig, rng?: Rng): number` — one-shot convenience: `createSampler(config, rng)()`.
- REQ-DIST-033: `DistributionConfig` is a plain JSON-serialisable type. `rng` is always passed externally, never embedded in config.
- REQ-DIST-034: `createSampler` throws `RandomError("RANDOM.DISTRIBUTION.UNKNOWN_TYPE")` for unrecognised `type` values (runtime guard for JS consumers without TypeScript).

### Quality

- REQ-DIST-040: fast-check: for each distribution, generate 10k samples and verify mean/variance are within 5% of theoretical values at standard parameters.
- REQ-DIST-041: `DistributionConfig` round-trips through `JSON.parse(JSON.stringify(config))` without loss for all distribution types.