HydroRoll-Team / HydroRoll-Team/OneRoll
Map domain errors to a typed Python exception hierarchy
- 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