HydroRoll-Team / HydroRoll-Team/OneRoll
Inject unbiased randomness with deterministic seed support
- 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