HydroRoll-Team / HydroRoll-Team/OneRoll

Run bounded batch rolls in Rust and release the GIL

Open
#22 0 comments 0 reactions 0 assignees View on GitHub
area:engine area:python blocked priority:p1 type:feature workflow:afk
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.