HydroRoll-Team / HydroRoll-Team/OneRoll

Reconsider v2 surface syntax for non-code hosts and LLM tool-call recall

Open
#51 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
3
Forks
1
Avg merge
3d 4h
Merged PRs (30d)
2

Description

## Context

RFC-0001 (v2.0) intentionally moved OneRoll from a flat-precedence roller to a
typed, bounded dice program language. The grammar accepted in
`docs/rfcs/0001-v2-target.pest` favors dense prefix/operator notation for
control flow and validators, for example:

```
(1 + 2)i:[>2]{10}
repeat(2; 1d6)
f[>3]
```

This works well as a machine-checked grammar and keeps parsing/execution
bounded, but it was designed and reviewed as a language-internal contract
(pest grammar, Pratt precedence, RFC acceptance criteria) rather than against
concrete end-user input surfaces. I want to raise a usability concern before
v2 syntax freezes further downstream (#29 migration diagnostics, #20 docs
rebuild) make this harder to revisit.

I maintain [astrbot_plugin_oneroll](https://github.com/Xero-Team/astrbot_plugin_oneroll),
which bridges OneRoll into AstrBot for QQ/IM deployment. Building and
supporting that integration surfaced two concrete problems with the current
surface syntax that aren't visible when the grammar is only exercised through
Rust tests, the CLI, or the Python SDK.

## Problem 1: non-code chat platforms have no affordance for this notation

`i:[>2]{10}`, `f[>3]`, and similar validator/bracket-prefixed forms assume a
reading context with syntax highlighting, monospace rendering, and users who
already parse symbolic grammars for a living. QQ, and IM platforms generally,
give none of that:

- Messages render in a proportional font with no token coloring, so `i:[>2]{10}`
and visually similar-but-wrong strings (e.g. mismatched brackets, stray `:`)
are hard to eyeball-diff for non-programmer users.
- The actual OneRoll user base for a TRPG bot skews toward players and GMs,
not developers. Existing, widely deployed dice notations in this exact
ecosystem (OliviaDice/OneDice's `AdB(kq)C(pb)DaE` family, documented at
https://github.com/OlivOS-Team/onedice/blob/main/inputdescribe.md, and the
broader `kh`/`kl`/`dh`/`dl` convention used by Roll20/FoundryVTT/Rollem)
already trained this audience on suffix-letter mnemonics attached directly
to the dice term, not on standalone prefix operators with bracket-delimited
predicates and block bodies.
- v1 compatibility shims (`r`, `ro`, `R`, `a`, `c` per #29) partially cover
this, but v2's *canonical* strict-mode forms are the ones users will
eventually see in error messages, docs, and migration diagnostics.

## Problem 2: bracket/prefix density hurts LLM tool-call recall

A growing share of OneRoll's likely integration surface is LLM agents/bots
that generate dice expressions from natural-language player input (e.g. "let
me roll with advantage, reroll ones") rather than a human typing raw syntax.
In practice this means the *generation-side* recall/precision of the model
matters as much as human readability:

- Symbol-dense, non-standard-order syntax (`i:[>2]{10}` vs. an `if`/`then`
shape) is objectively less represented in pretraining corpora than
natural-language-adjacent keyword forms or the extremely common `kh`/`kl`
dice-notation family. This increases the chance an LLM hallucinates a
plausible-but-invalid variant (wrong bracket type, missing `:`, wrong block
count) when asked to emit OneRoll v2 syntax directly.
- Because a failed parse currently discards the whole instruction atomically
(per #38/#26), a single malformed conditional in a longer semicolon-joined
Program can fail the entire batch, which is a worse failure mode for
agent-generated input than for hand-typed input.

## What I'd like considered

Not proposing a specific grammar change yet — raising this for discussion
before it's frozen further. Options that came up while comparing against
OneDice and natural-language-style conditionals:

- Offer a documented, canonical *alternate surface form* for `conditional`
closer to `if then { .. } else { .. }`, either as sugar that
desugars to the existing pest rule, or as the primary documented form with
`i:[...]{}{}` demoted to a compact/compatibility alias.
- Align keep/drop/filter-style option letters more closely with the
`kh`/`kl`/`dh`/`dl` convention already used by OneDice in this space, rather than introducing new single-letter mnemonics
(`k`, `d`, `f`, `c`, `r` alone) where an existing convention covers the same
operation.
- If a keyword-based surface form is out of scope for v2.0, consider whether
RFC-0001's "Design provenance" section should explicitly record *why*
prefix/bracket density was chosen over keyword forms, so downstream
integrators (bot plugin authors, agent-tool-schema authors) have a citable
rationale instead of re-litigating this per integration.

## Non-goals

- Not asking to change v2's typed Value/Trace/Validator execution semantics —
this is purely about surface syntax/notation.
- Not asking to drop the existing compact grammar; compatibility and the
pest-checked canonical form can coexist with an alternate documented
surface syntax the way v1 compatibility forms already coexist with v2
canonical forms (#29).

## Context links

- Integration this was found through: https://github.com/Xero-Team/astrbot_plugin_oneroll
- Comparable existing notation: https://github.com/OlivOS-Team/onedice/blob/main/inputdescribe.md
- Related: #7 (RFC-0001 acceptance), #29 (v1→v2 migration diagnostics), #20 (docs IA rebuild)

Contributor guide

No contributing guide indexed for this repository

Research direction

Read docs/rfcs/0001-v2-target.pest and RFC-0001's design provenance, then compare the syntax concerns with migration issue #29 and the documentation rebuild in #20. Evaluate the cited alternate forms and integrations; done means the project has a decided syntax direction or documented rationale before v2 freezes.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, rust
Domain
compilers, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.