HydroRoll-Team / HydroRoll-Team/OneRoll

Consolidate parse, validate, roll, and run under a typed Engine API

Open
#19 0 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

- #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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.