Randomness & Distributions

Relevant source files

The following files were used as context for generating this wiki page:

• deep_causality_rand/README.md
• deep_causality_rand/CHANGELOG.md
• openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md
• openspec/changes/archive/spec-kit-old/002-replace-rng-currently/plan.md
• openspec/changes/archive/spec-kit-old/002-replace-rng-currently/tasks.md
• AGENTS.md

The deep_causality_rand crate provides custom statistics tools and distributions designed specifically for the DeepCausality project. Its primary purpose is to provide a minimalistic, auditable, and dependency-free implementation of random number generation (RNG) and statistical distributions that can operate in environments where standard libraries or common external crates like rand might be unavailable or undesirable.

This module is essential for the deep_causality_uncertain crate, supporting first-order types for uncertain programming. It prioritizes cross-compilation capability, zero unsafe code, and zero macros in the main implementation to ensure high maintainability and security across exotic hardware targets.

Sources: deep_causality_rand/README.md:16-35, AGENTS.md:118-118, openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md:58-62

Architecture and Design Principles

The architecture of the randomness module is built around strict technical constraints to ensure portability and security. It is structured to follow the standard DeepCausality crate layout, with dedicated subfolders for errors, traits, and types.

Core Constraints

The implementation adheres to three "Zero" principles:

• Zero External Dependencies: By default, it relies only on the Rust std library and the internal deep_causality_num crate.
• Zero Unsafe Code: No unsafe blocks are permitted in the library code.
• Zero Macros: Generic traits and types are used instead of macros to improve code reviewability and maintenance, though macros are permitted sparingly for generating test cases.

Sources: deep_causality_rand/README.md:31-35, openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md:10-15, AGENTS.md:175-179

Component Relationship

The following diagram illustrates the relationship between the RNG module and the broader project.

Pseudo-Random Number Generation (PRNG)

The crate implements a default pseudo-random number generator using the SipHash13 algorithm. This choice provides a portable, general-purpose PRNG that relies on std::collections::hash_map::RandomState for seeding.

RNG Implementation Types

Type	Description	Dependency
SipHash13Rng	Default PRNG used for general-purpose randomness and testing.	std only
OsRandomRng	OS-backed RNG enabled via feature flag for stronger randomness.	getrandom crate
ChaCha20Rng	Cryptographically secure PRNG implementation.	Internal
Xoshiro256	Reference implementation used for testing and development.	Internal

Sources: deep_causality_rand/README.md:46-60, deep_causality_rand/CHANGELOG.md:17-21, openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md:83-85

OS-Random Integration

For applications requiring cryptographically secure or hardware-backed random numbers, the crate provides an os-random feature flag. This flag enables the getrandom crate, which interfaces with operating system entropy sources.

Error Handling

The module utilizes a custom error enumeration, RngError, to manage failure states across different RNG implementations. This is particularly important when interfacing with external OS entropy sources which may fail.

RngError Variants

• OsRandomGenerator(String): Wraps error messages returned from the getrandom crate when the OS generator fails.
• FeatureScoreError(String): (Contextual to algorithms) Used when calculations involving distributions or random selection result in NaN or Infinity.

Sources: openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md:89-92, openspec/changes/archive/spec-kit-old/006-mrmr-feature-score/spec.md:50-52

Implementation Details

The module defines a core Rng trait that specifies the interface for generating various types of random data.

Key Functional Requirements

• FR-009: The Rng trait and all its depending traits must be implemented within the deep_causality_rand crate.
• FR-010: A default PRNG must be provided using SipHash13.
• Trait Design: Traits are implemented with generic types from deep_causality_num (e.g., the custom Float type) to avoid macro dependency.

Sources: deep_causality_rand/README.md:73-77, openspec/changes/archive/spec-kit-old/002-replace-rng-currently/002-replace-rng-currently.md:82-85

Data Flow for Generation

Summary

The Randomness & Distributions system provides the foundational entropy required for causal reasoning under uncertainty. By implementing a native, macro-free, and safe Rust RNG, the project ensures that its most critical probabilistic computations remain auditable and portable across all deployment targets, from standard servers to custom hardware without a full C library.