feat: establish production baseline and v2 specification

[HsiangNianian]

Summary

• harden the v1 engine with request budgets, checked arithmetic, deterministic randomness, conformance/property/fuzz gates, and one authoritative package version
• define executable RFC-0001 through RFC-0006 contracts for the v2 language, result model, Python API, verification, releases, and analysis
• separate distribution builds from approval-protected GitHub/PyPI publication using immutable candidate verification and Trusted Publishing OIDC

Validation

• 25 Rust tests; release-mode arithmetic/randomness/property suites: 2 / 8 / 5
• 87 installed-Python tests; rustfmt, Clippy, Ruff, strict mypy, strict Sphinx HTML and doctest
• targeted zizmor audit for build and release workflows
• PR Quality: https://github.com/HydroRoll-Team/OneRoll/actions/runs/30466065828
• V1 Conformance: https://github.com/HydroRoll-Team/OneRoll/actions/runs/30466065943
• Fuzz: https://github.com/HydroRoll-Team/OneRoll/actions/runs/30466065818
• Docs: https://github.com/HydroRoll-Team/OneRoll/actions/runs/30466056537
• 15 wheel/sdist jobs: https://github.com/HydroRoll-Team/OneRoll/actions/runs/30466073173

The artifact matrix uses Node 24 actions and the supported macos-15-intel runner; the final build log has no Node 20 or deprecation annotation.

Release boundary

This PR does not create a tag or public release. RFC acceptance and the M0/M1 publication choices remain explicit human decisions.

[sourcery-ai]

Sorry @HsiangNianian, your pull request is larger than the review limit of 150000 diff characters

[sourcery-ai]

Reviewer's Guide

Establishes a hardened execution model with resource budgets and deterministic randomness, extends the core dice engine to typed programs and batch execution, exposes a ResourcePolicy-aware Python API and CLI, and separates build-from-publish release workflows with machine-checked RFC contracts and tests.

File-Level Changes

Change	Details	Files
Introduce execution resource budgeting and deterministic request-scoped randomness to the Rust dice engine.	Add ResourcePolicy and ExecutionBudget types with named limits and nesting tracking. Replace ad-hoc rand usage in DiceCalculator with RequestRandom using ChaCha12, seed descriptors, and bounded uniform sampling. Charge work, generated values, collections, RNG words, output items, and bytes throughout evaluation and rolling paths, including new helper methods for aggregation and serialization. Implement RandomSeed utilities for integer/hex seeds and RandomDescriptor for replayable randomness metadata.	src/calculator.rs src/random.rs src/resource.rs src/errors.rs src/lib.rs
Extend the language from single expressions to programs with instruction frames, comments, and resource-aware parsing.	Add Program and ProgramResult types to represent ordered instruction sequences with shared comments. Refactor DiceParser to support parse_program and parse_expression_with_policy, enforcing source_bytes, parse_depth, ast_nodes, and parsed_instructions limits. Implement expression_ast_nodes and validate_ast_nodes to bound AST size and modifier nesting. Add program evaluation in DiceCalculator, including evaluate_program and evaluate_batch that share budgets across instructions or samples.	src/parser.rs src/types.rs src/calculator.rs src/lib.rs
Harden arithmetic and roll representation by moving to checked i64 operations and explicit error codes.	Change Expression::Number and DiceResult totals/rolls from i32 to i64, updating aggregations and modifier logic accordingly. Implement checked_sum helper and use i64::checked_add/checked_sub/checked_mul/checked_div/checked_pow across expression evaluation. Add DiceError variants for arithmetic overflow, divide-by-zero, and invalid exponents with stable codes, and propagate them through Python bindings. Adjust parser numeric parsing, Count modifier aggregation, and tests to reflect i64 semantics.	src/types.rs src/calculator.rs src/parser.rs src/errors.rs DEVELOPMENT_GUIDE.md
Expose ResourcePolicy, program execution, batching, and statistics through the Python extension, SDK, CLI, and TUI.	Introduce PyResourcePolicy pyclass with with_limit, limits, and hard_limits bridging to ResourcePolicy. Extend OneRoll Python class with optional policy constructor, run (program), roll_multiple (batch), roll_statistics, and roll_with_modifiers using DiceCalculator evaluate APIs. Add run_program free function and wire _core module to expose version, PyResourcePolicy, OneRoll, roll_dice, run_program, and roll_simple. Update CLI (main.py) to use OneRoll.run, add --limit and --show-limits options, print program results, and propagate policy to TUI; modify TUI to accept ResourcePolicy and use instance roller/statistics. Revise _core.pyi and oneroll/init.py to match the new API surface, including ResourcePolicy export and updated type signatures.	src/python_bindings.rs src/oneroll/_core.pyi src/oneroll/__init__.py src/oneroll/__main__.py src/oneroll/tui.py src/lib.rs
Rework documentation, RFCs, and Sphinx configuration to embed machine-checked grammars, result schemas, and release/analysis contracts.	Update README.md to describe v1 engine, v2 roadmap, resource limits, randomness protocol, and verification commands. Simplify docs/conf.py, align project metadata with Cargo.toml, and point links to the OneRoll repository and PyPI project. Add multiple RFC documents (0001–0006), associated JSON schemas/examples (result, conformance, analysis, capability matrix, distributions, API contract), and language/limits/quality/randomness/conformance/fuzzing/roadmap/releasing pages. Reference grammars and schemas via literalinclude in RFC and language docs, and ensure cross-references from index.rst.	README.md docs/source/conf.py docs/source/index.rst docs/source/language.rst docs/source/limits.rst docs/source/randomness.rst docs/source/fuzzing.rst docs/source/releasing.rst docs/source/roadmap.rst docs/source/conformance.rst docs/source/quality.rst docs/source/rfc-0001.rst docs/source/rfc-0002.rst docs/source/rfc-0003.rst docs/source/rfc-0004.rst docs/source/rfc-0005.rst docs/source/rfc-0006.rst docs/rfcs/0001-*.pest docs/rfcs/0003-*.json docs/rfcs/0004-*.pyi docs/rfcs/0004-*.json docs/rfcs/0005-*.json docs/rfcs/0006-*.json DEVELOPMENT_GUIDE.md
Split build and publish workflows, add quality/fuzz/conformance gates, and enforce immutable release candidates with Trusted Publishing.	Replace build.yml release job with a pure distribution build that uploads wheels/sdist artifacts and depends on quality.yml; pin actions to immutable SHAs and disable credential persistence on checkout. Create CHANGELOG-based manual publish workflow (changelog.yml) that verifies signed annotated tags, main ancestry, candidate build run identity, versions, and artifact policy via scripts/release_contract.py, then seals and publishes artifacts using GitHub Releases and pypa/gh-action-pypi-publish with OIDC. Add quality.yml to run Rust tests (including release-mode property/randomness suites), clippy, rustfmt, Ruff, mypy, Python unit tests, and Sphinx HTML builds. Introduce fuzz.yml and conformance.yml workflows to run cargo-fuzz campaigns and v1 corpus checks for both Rust and Python. Add test suites that assert workflow contracts, release contracts, documentation contracts, result schemas, RFC contracts, resource policies, evaluation budgets, fuzz gates, typing, and package version consistency.	.github/workflows/build.yml .github/workflows/changelog.yml .github/workflows/docs.yml .github/workflows/quality.yml .github/workflows/fuzz.yml .github/workflows/conformance.yml scripts/release_contract.py tests/test_release_workflow.py tests/test_quality_gate.py tests/test_documentation_contract.py tests/test_rfc_0004_contract.py tests/test_rfc_0005_contract.py tests/test_rfc_0006_contract.py
Add fuzz/property/conformance harnesses and regression corpora to harden parser and evaluator behavior under resource limits.	Introduce fuzz crate with parse_program and evaluate_program fuzz targets that use ResourcePolicy limits and seeded data headers; configure corpus seeds for empty instructions, deep parentheses, infinite explode/reroll, and arithmetic overflow. Add property_tests.rs with proptest-based suites covering dice range invariants, seeded replay equality, monotonicity of generated_value limits, UTF-8 parsing robustness, and bounded modifier combinations. Create conformance_tests.rs to enforce v1 corpus behavior, deterministic randomness vectors, seed normalization, result graph properties, and checked i64 arithmetic boundary behavior. Add Python tests mirroring evaluation budget behavior, resource policy boundaries, CLI/TUI smoke, batch semantics, v1 corpus, RFC contracts, and PEP 561 typing contracts.	fuzz/Cargo.toml fuzz/fuzz_targets/parse_program.rs fuzz/fuzz_targets/evaluate_program.rs fuzz/corpus/** src/property_tests.rs src/conformance_tests.rs tests/test_fuzz_gate.py tests/test_resource_policy.py tests/test_evaluation_budget.py tests/test_v1_conformance.py tests/test_checked_arithmetic.py tests/test_rfc_0002_contract.py tests/test_rfc_0005_contract.py tests/test_rfc_0006_contract.py tests/test_program.py tests/test_tui.py tests/test_typing_contract.py tests/test_package_version.py benchmarks/resource_limits.py
Align project metadata, dependencies, and ignore patterns with the new engine and tooling.	Update Cargo.toml description, documentation/homepage/repository URLs, crate-type to include rlib, and add getrandom, rand_chacha, rand_core, serde_json, and proptest dependencies. Update pyproject.toml keywords, URLs, dev dependencies (jsonschema, mypy, pyyaml), and maintainers to match OneRoll branding. Add build.rs to emit the pest grammar wrapper, mark py.typed in src/oneroll, and adjust .gitignore and uv.lock as needed. Add small benchmarks to exercise default resource limits and record measurement JSON.	Cargo.toml pyproject.toml build.rs src/oneroll/py.typed .gitignore uv.lock benchmarks/resource_limits.py

Possibly linked issues

• #RFC-0005: PR creates RFC-0005 schemas, examples, release-contract script, workflow changes, and tests that satisfy the verification/documentation/release RFC.
• #RFC-0001: PR implements RFC-0001’s language spec, checked pest grammar, and program execution, satisfying its acceptance criteria.
• #RFC-0002: PR introduces ResourcePolicy/ExecutionBudget, deterministic ChaCha12 RNG, seeded replay, limit errors, tests, and docs implementing RFC-0002.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[HsiangNianian]

@fu050409 Please review the final release head (ba41a48) as the required non-author Code Owner. This head includes the confirmed v1.3.5 version and release notes, plus a cache-safe version-contract gate discovered during release validation.

Local evidence on the final head: Release Contract passed; 25 Rust tests; release-mode arithmetic/randomness/property suites (2/8/5); Clippy, Ruff, strict mypy; 87 installed-Python tests; CLI version 1.3.5; and strict Sphinx HTML passed. Remote checks are rerunning, and auto-merge remains gated on both CI and your approval.

Please also record Accepted or requested changes on RFC-0003 (#4), RFC-0004 (#5), and RFC-0005 (#2). RFC-0001 (#7) can be accepted after #4 and #5. A PR approval satisfies the merge gate but does not by itself change the RFC issue state.

[fu050409]

@HsiangNianian Too many files to review, I see some checks failed to pass. Is this expected? I found it also failed on main branch so I am not sure if this situation is expected intentionally.

[HsiangNianian]

@HsiangNianian Too many files to review, I see some checks failed to pass. Is this expected? I found it also failed on main branch so I am not sure if this situation is expected intentionally.

got it, ill fix it and may require you review