Module rng 

Domain-separated Philox key derivation and the bounded-draw primitive.

Implemented by plan 02-04. Domain-separated Philox key derivation and the bounded-draw primitive.

The byte encoding is frozen by the contract: the key is a little-endian 64-bit truncation of a SHA-256 over a domain tag, the root seed, and a domain string drawn from a closed table; the counter carries the draw ordinal. Bounded draws use 64-bit multiply-shift. Modulo draws and next_f32 are forbidden — the first is biased and unauditable at the edges, the second has only 23 mantissa bits.

Every function here is STATELESS

No function in this module takes &mut self, and no mutable generator state crosses any boundary. Draw i is a pure function of (key, stream_id, ordinal), so worker count, thread scheduling and iteration order cannot change it (D-20). That is the whole reason this crate uses a counter-based generator instead of the rand_chacha stream .planning/research/STACK.md recommends: with a stateful stream, draw i depends on every draw before it, and worker-count independence becomes a discipline the implementation must maintain rather than a fact about its type.

Philox is a STATISTICAL generator, never a CSPRNG

Philox 4x32-10 is used here solely for sampling determinism. It is not cryptographic randomness: the key is derived from a caller-visible seed, the stream is seekable by construction, and nothing about it resists an adversary who knows the seed. Never reuse anything in this module for tokens, nonces, salts or key material.

The frozen byte encoding

Every byte-level decision below is contracted (rng_key_derivation, bounded_draw) and pinned by [rng_tests::rng_byte_encoding_golden_is_frozen], whose constants were derived from the contract text by an independent implementation rather than captured from a first run of this code:

Decision	Value
domain tag	b"apr-contrastive-v1\0" — 18 ASCII bytes plus one NUL terminator
root seed	u64::to_le_bytes, exactly 8 bytes
key truncation	digest bytes 0..8 as two LITTLE-ENDIAN u32 lanes; 8..32 discarded
counter	[ordinal as u32, (ordinal >> 32) as u32, stream_id, 0]
64-bit assembly	((lanes[1] as u64) << 32) | (lanes[0] as u64) — lane 0 is the LOW half
bounded draw	((x as u128 * n as u128) >> 64) as u64 — multiply-shift, never modulo

Modules

domains

The six frozen domain strings of protocol v1.

Structs

DomainKey

A Philox key derived from a (root_seed, domain) pair.

Functions

bounded

A uniform-ish draw in [0, n) by 64-bit multiply-shift.

derive_key

Derive a domain-separated Philox key.

draw

One Philox 4x32-10 output block at (key, stream_id, ordinal).