HydroRoll-Team / HydroRoll-Team/OneRoll
Consolidate parse, validate, roll, and run under a typed Engine API
- Dominant language
- Python
- Stars
- 3
- Forks
- 1
- Avg merge
- 3d 4h
- Merged PRs (30d)
- 2
Description
## Parent
- #5
## What to build
Implement the immutable Python-first Engine surface in `docs/rfcs/0004-target-api.pyi` over one Rust execution path and the RFC-0003 result/error vocabulary.
## Frozen API
- `Engine(*, resource_policy=None, compatibility_mode="strict_v2")` is frozen, shareable, and stores no variables, seed, RNG cursor, deadline, token, or counters.
- Exact methods are `parse(source)`, `validate(source, *, variables=None)`, `roll(expression, *, variables=None, seed=None, cancellation=None, timeout=None)`, `run(program, ...)`, and `run_batch(program, samples, ...)`.
- Each call creates a fresh RFC-0002 context. `roll` accepts one Instruction; `run` accepts source text for a complete Program.
- Parsed and validated objects are immutable introspection results, not executable/precompiled inputs.
- Variables are copied into bounded Rust-owned scalar/sequence values; seed and timeout forms follow RFC-0002/0004.
- Engine methods return frozen Rust-backed RFC-0003 classes with read-only tuples/maps and detached `to_dict()` copies.
- Compatibility helpers delegate to Engine and keep existing v1 dictionary shapes throughout 2.x.
## Acceptance criteria
- [ ] Runtime classes and signatures match `0004-target-api.pyi` and `0004-api-contract.json` exactly.
- [ ] Engine is safely reusable across threads and equal independent calls are scheduling-invariant.
- [ ] Source, variables, policy, compatibility mode, seed, cancellation, and timeout reach one request context.
- [ ] Parse/validate cannot initialize randomness or retain caller-owned variables.
- [ ] Rust serialization, installed Python results, and CLI JSON pass the same RFC-0003 corpus.
- [ ] Runtime exports and installed type declarations have exact parity tests.
- [ ] Every v1 entry point delegates to Engine and has the RFC-0004 migration path.
## Blocked by
- #5 human acceptance
- #4 human acceptance
- #38
- #39
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with docs/rfcs/0004-target-api.pyi and 0004-api-contract.json, then read the RFC-0002 context and RFC-0003 result/error vocabulary. Trace the existing v1 entry points and Rust execution path before implementing the Engine surface. Done means the runtime, installed declarations, Rust serialization, CLI JSON, and compatibility helpers satisfy the listed parity, delegation, reuse, and corpus criteria.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, rust
- Domain
- api, backend-api-design, devtools
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 25/100