HydroRoll-Team / HydroRoll-Team/OneRoll

Map domain errors to a typed Python exception hierarchy

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

## Parents

- #4
- #5

## What to build

Expose RFC-0003 error fields through RFC-0004's Python hierarchy without a binding-specific payload.

## Frozen hierarchy

```text
OneRollError(ValueError)
+-- ParseError
+-- ValidationError
+-- EvaluationError
| +-- ResourceLimitError
| +-- RandomError
| +-- ArithmeticEvaluationError
+-- CancellationError
+-- DeadlineExceededError
```

## Frozen contract

- Every exception exposes `phase`, `code`, `message`, optional `span`, and the same meanings as Rust and CLI JSON.
- Resource exceptions expose `resource`, `used`, `requested`, and `limit` together.
- Replayable failures may expose `random`; batch failures expose the root descriptor and sample index; parse diagnostics may expose `expected`; migration diagnostics may expose `replacement`.
- `to_dict()` returns the schema `2.0` inner error object and never a partial ProgramResult or BatchResult.
- The subclass is ergonomic; portable clients branch on stable `code`. `OneRollError(ValueError)` preserves existing broad catches through 2.x.

## Acceptance criteria

- [ ] Python callers can catch every documented exception class independently.
- [ ] Convenience functions and Engine methods raise the same hierarchy and field vocabulary.
- [ ] Exception payloads validate against ordinary and batch RFC-0003 error examples.
- [ ] CLI and TUI render errors without parsing messages or leaking internal tracebacks.
- [ ] Pickling and string rendering preserve all machine-readable fields.
- [ ] Atomic failure is preserved through the binding boundary.

## Blocked by

- #12
- #5 human acceptance

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with RFC-0003 and RFC-0004, then trace the Python convenience functions, Engine methods, and binding boundary mentioned in the acceptance criteria. Compare ordinary and batch error examples and verify that the hierarchy, fields, serialization, CLI/TUI rendering, pickling, string output, and atomic failure meet the frozen contract once blockers #12 and #5 are resolved.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
api, backend-api-design
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.