HydroRoll-Team / HydroRoll-Team/OneRoll

Execute semicolon-separated Programs across Rust, Python, and CLI

Open
#38 0 comments 0 reactions 0 assignees View on GitHub
area:cli-tui area:engine area:language 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

- #7

## What to build

Move semicolon execution onto the accepted typed Engine and RFC-0003 ProgramResult without regressing compatibility `roll()` or `run()`.

## Frozen contract

- Strict `Engine.roll` accepts exactly one Instruction and returns `InstructionResult`; `Engine.run` accepts source text and returns `ProgramResult`.
- Top-level instructions are source ordered and share one request-wide RollNode/TraceNode pool, RNG, immutable environment, deadline/token, and budget.
- Each InstructionResult has a unique activation ID, frame-local index, byte span, canonical text, typed value, scalar projection, trace root, and nested executions.
- Repeat iterations, selected branches, and function bodies remain under their activating instruction instead of flattening into top-level history.
- Program comment is decoded text or null in strict v2; metadata records compatibility mode and replay descriptor.
- Any instruction failure atomically returns one structured exception/error envelope and no completed prefix.
- Module-level `roll`/`run` retain v1 dictionaries through adapters over the same Engine.

## Acceptance criteria

- [ ] `Engine.run("1d6; 2d6 # encounter")` returns two ordered typed instructions plus Program metadata.
- [ ] `Engine.roll` rejects separators and returns one typed InstructionResult.
- [ ] Rust, installed Python objects, `to_dict()`, and CLI JSON validate against RFC-0003 and agree on ordering and IDs.
- [ ] Nested indices, spans, trace roots, values, and read-only collections satisfy graph invariants.
- [ ] All instructions share one RFC-0002 ExecutionContext and counter set.
- [ ] Empty instructions and mid-Program failures return structured atomic errors.
- [ ] Compatibility `roll()` and `run()` retain legacy dictionaries through Engine adapters.

## Blocked by

- #7 human acceptance
- #4 human acceptance
- #5 human acceptance
- #39

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with the typed Engine.run and Engine.roll entry points and read the RFC-0002 ExecutionContext and RFC-0003 ProgramResult contracts. Trace the Rust implementation, installed Python objects, to_dict(), and CLI JSON paths. Done means semicolon-separated programs, atomic errors, shared execution state, nested metadata, and compatibility adapters agree across all surfaces.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
backend, cli
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.