Skip to main content

Crate arkhe_rand

Crate arkhe_rand 

Source
Expand description

BLAKE3-keyed PRNG with split() determinism — Lemire unbiased range + Fisher-Yates shuffle. Shell-side use (kernel/runtime forbids RNG for deterministic replay).

§Layer scope

arkhe-rand is an L3 Library tier crate per the ArkheForge layer model (L0 Kernel / L1 Runtime Primitives / L2 Runtime Services / L3 Library / L4-L6 Shell). The kernel and forge runtime forbid RNG entirely to preserve deterministic WAL replay; this crate is consumed only by shell-side code (BBS, examples, downstream applications).

§Cryptographic core

Each RngSource wraps a BLAKE3 XOF stream constructed via the KDF mode Hasher::new_derive_key("arkhe-rand stream").update(seed). The context string is a version-agnostic domain-separation tag: it scopes the stream away from other BLAKE3 uses of the same seed, and is held stable so stored seeds replay byte-identically.

XOF reader monotonic property is inherited from the blake3 crate spec (audited via supply-chain/audits.toml [[audits.blake3]]).

§API

§Cross-platform determinism

Byte-to-integer conversions use explicit little-endian (u32::from_le_bytes / u64::from_le_bytes) regardless of host endianness, and usize sampling routes through the u64 Lemire path on every pointer width, so the same seed yields identical values and identical stream consumption across targets. Enforcement: the golden-vector byte-compare in tests/golden_vector.rs, a CI self-grep that rejects native-endian conversion helpers under arkhe-rand/src/, and a host identity test asserting usize draws equal u64 draws bit-for-bit.

Structs§

RngSource
BLAKE3-keyed PRNG.

Enums§

RngError
Error returned by RngSource::from_os_entropy.

Traits§

RandInt
Integer types accepted by gen_range / gen_range_inclusive.

Functions§

gen_range
Sample a uniformly-random value from range ∈ [start, end).
gen_range_inclusive
Sample a uniformly-random value from range ∈ [start, end].
shuffle
In-place Fisher-Yates shuffle.