A process-overridable, seedable pseudo-random number generator.

In production the wrapper falls through to Erlang's :rand. In tests, seed/1 pins a deterministic state in the calling process; subsequent calls walk the same byte-precise stream every run – so a flake-prone path (jittered backoff, a shuffled queue, an A/B tiebreaker) can be asserted exactly instead of retried.

Inheritance

The seed lives in Ambient.ProcessOverride, so any child process spawned by the test inherits it through:

• the implicit $callers chain (Task.async/1, Agent.start/1 – no setup needed), and
• explicit Ambient.Random.allow/1 for long-lived processes.

Note: each process draws from a fork of the seeded stream, not one shared advancing stream. A child inherits the owner's state as of the seed and advances its own private copy, so the owner and a freshly-spawned child (or two sibling tasks) that each draw will produce the same sequence. This keeps results deterministic per process; it does not interleave draws across processes into one global sequence.

Production

Ambient.Random.uniform(100)        # 1..100
Ambient.Random.shuffle(cards)
Ambient.Random.take_random(deck, 5)

Tests

Ambient.Random.seed(42)
x = Ambient.Random.uniform(100)    # same value every run
Ambient.Random.reset()

Cryptography

Seedable and unpredictable are opposites: a stream reproducible from a 64-bit integer cannot be credential-grade, and :exsss leaks its internal state to anyone who sees a handful of outputs. The split is therefore per-function:

• bytes/1 – credential-safe in production. With no seed in scope it is :crypto.strong_rand_bytes/1, and production builds don't compile the override machinery in (Ambient.ProcessOverride.enabled?/0), so no ambient context can downgrade it. Under seed/1, in a test build, it is deterministic and not safe.
• uniform/0,1, normal/2, shuffle/1, random/1, take_random/2 – :rand-backed, never credential-grade in any build. Don't hand-roll a token out of uniform(256).

Ambient.Credo.NoDirectRandom keeps direct :rand / Enum.shuffle calls from creeping back in.