HydroRoll-Team / HydroRoll-Team/OneRoll
Run bounded batch rolls in Rust and release the GIL
- Dominant language
- Python
- Stars
- 3
- Forks
- 1
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 2
Description
## Parent
- #5
## What to build
Implement RFC-0004's detached, deterministic, atomic Rust batch path and concurrency contract.
## Frozen contract
- `run_batch(program, samples, ...)` requires a positive sample count, crosses the Python/Rust boundary once, and parses/validates once.
- V2.0 evaluates sequentially in increasing sample-index order. There is no `workers` parameter or core progress callback.
- One request budget, cancellation token, timeout, and counter set covers the complete batch; any failure discards all completed children.
- The root seed is accepted/generated once. Sample `i` uses SHA-256 of `b"OneRoll batch seed v1\0"`, the 32-byte root seed, and `uint64_le(i)`.
- Success returns RFC-0003 `BatchResult`; failure includes the root batch descriptor and failing sample index.
- Python-owned inputs are copied before Rust-only parsing/evaluation; CPU work releases the GIL and reacquires it only for result/exception creation.
- Detached code never accesses a Python object or callback. Another thread can call the one-shot `CancellationToken.cancel()`.
## Random foundation
The request stream, seed normalization, unbiased bounded sampler, entropy handling, replay descriptor, and raw-word accounting from #18 are delivered in `79a3793`. This issue owns batch derivation and final batch evidence; it no longer waits for the #18 roll-up issue to close.
## Acceptance criteria
- [ ] Batch evaluation crosses the binding once and has no per-sample Python loop.
- [ ] All-zero root seed vectors match RFC-0004 for sample indices 0 and 1.
- [ ] Shared-budget, stable failure-index, timeout, cancellation, and atomic-discard tests pass.
- [ ] Two independent calls on one Engine can make progress concurrently under ordinary CPython.
- [ ] The GIL is released only around Rust-owned work, with cancellation callable from another Python thread.
- [ ] Benchmarks compare the Rust batch path with the compatibility Python loop.
- [ ] Real outputs and failures validate against the RFC-0003 batch corpus.
## Blocked by
- #19
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the frozen RFC-0004 contract and the run_batch entry point, then review the random foundation delivered in 79a3793 and the blocker in #19. Use the acceptance criteria to validate single-boundary execution, deterministic sample derivation, shared budgets, cancellation, GIL behavior, benchmarks, and RFC-0003 batch outputs.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, rust
- Domain
- api, backend, performance
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100