HydroRoll-Team / HydroRoll-Team/OneRoll

Inject unbiased randomness with deterministic seed support

Open
#18 2 comments 0 reactions 0 assignees View on GitHub
area:engine area:python blocked breaking-change priority:p1 type:feature workflow:afk
Dominant language
Python
Stars
3
Forks
1
Avg merge
3d 4h
Merged PRs (30d)
2

Description

## Parent

- #6

## What to build

Implement RFC-0002's injectable `oneroll-chacha12-v1` random source with unbiased bounded sampling, OS-backed default entropy, stable seed conversion, and replay metadata.

## Frozen contract

- One request owns one deterministic ChaCha12 stream; Python's `random` module and client-side seeding are not used.
- Python/CLI seeds accept unsigned 64-bit integers or canonical 64-digit hexadecimal input and normalize to one 32-byte seed.
- Bounded numeric and list selection use rejection sampling rather than modulo reduction.
- Draw order is source deterministic and every raw word is charged and reported through RFC-0003 metadata.
- Unseeded requests acquire all 32 bytes from the operating system or fail with `random.entropy_unavailable`.

## Foundation delivered

Commit `79a3793` provides the shared Rust primitive:

- ChaCha12 request streams, u64/hex/byte seed normalization, and OS entropy without fallback.
- Rejection-sampled `uniform_below`, exact `rng_words` charging, and replay descriptors.
- Numeric-dice migration plus RFC raw-word, d6, d20, weighted-choice, retry, failure, and equal-preimage tests.
- Remote Quality, V1 Conformance, and Docs workflows are green.

The remaining work is integration on final public surfaces, not a second random implementation.

## Acceptance criteria

- [x] Implemented numeric faces use the accepted unbiased range API.
- [x] RFC-0002 raw-word, d6, d20, normalization, rejection, and entropy vectors pass in Rust.
- [x] Seed validation and entropy failures have stable codes and atomic Rust behavior.
- [x] Random-word counters and replay descriptors remain exact after rejection and evaluation failure.
- [ ] Weighted-list sources in #40 use the same unbiased primitive.
- [ ] Final Python Engine and CLI seed/replay surfaces in #19 pass installed-Python vectors.
- [ ] Batch sub-seeds and failure descriptors in #22 match RFC-0004.
- [ ] Same source, variables, policy, and seed replay across supported targets.

## Integration dependencies

- #12
- #39
- #19
- #22
- #40

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reviewing the shared Rust primitive from commit 79a3793 and the integration dependencies in #19, #22, and #40. Then inspect the final Python Engine and CLI surfaces, weighted-list sources, and batch handling; run the installed-Python vectors and verify unbiased selection, seed/replay behavior, counters, and failure descriptors across supported targets.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
backend, cli, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.