Skip to content

docs: harden RollPart spec from design review #114#115

Merged
edloidas merged 1 commit into
masterfrom
docs/harden-rollpart-spec-114
May 10, 2026
Merged

docs: harden RollPart spec from design review #114#115
edloidas merged 1 commit into
masterfrom
docs/harden-rollpart-spec-114

Conversation

@edloidas
Copy link
Copy Markdown
Owner

Landed the 10 spec corrections to .claude/docs/STAGE3.md §5 from the design review of #84. Docs-only — no source or test changes. On merge, #84 is unblocked.

  • Added total: number to literal and variable so result.parts.total === result.total holds for trivial expressions.
  • Added the grouped variant — keeps user-typed (...) distinct in the part tree and preserves the 1:1 AST↔RollPart mapping (16 variants).
  • Replaced opaque modifier: string with ModifierSpec[] mirroring flattenModifierChain; chains like 4d6kh3kl1 round-trip per-spec.
  • Preserved threshold conditions on reroll (condition), explode (threshold?), successCount (threshold + failThreshold?), and critThreshold (successThresholds[] + failThresholds[]).
  • Added count: number to dice — symmetric with fateDice, eliminates the "derive from rolls.length" footgun under keep/drop.
  • Pinned successCount.total = successes − failures as an invariant regardless of empty-pool or wrapping arithmetic.
  • Pinned group.keptIndices semantics — 0-based, indexes parts[] in author-written order, pre-sort, omitted on bare groups, written by evalGroupModifier onto the inner group part; dropped sub-rolls retain their full RollPart including versus.degree.
  • Documented DieResult reference sharing between part-tree rolls[] and result.rolls[] — no deep-clone.
  • Added the RollPartType = RollPart['type'] alias for exhaustive switches.
  • Added per-branch construction notes for evalDice, evalModifier, evalGroupModifier, evalGroup, evalVersus, evalSuccessCount, and evalCritThreshold; rejected the partsStack alternative and the optional parts? field in prose.

Closes #114

Drafted with AI assistance

Spec corrections to STAGE3.md §5 (RollPart shape):

`literal` / `variable` carry `total: number`
`grouped` variant added — preserves user-typed `(...)` distinct in the part tree
`modifier` redesigned with `ModifierSpec[]` mirroring `flattenModifierChain`
Conditions on threshold modifiers preserved — `condition` on `reroll`, `threshold?` on `explode`, `threshold` + `failThreshold?` on `successCount`, `successThresholds[]` + `failThresholds[]` on `critThreshold`
`dice` carries `count: number` — symmetric with `fateDice`
`successCount.total = successes - failures` invariant pinned
`group.keptIndices` semantics pinned — 0-based, pre-sort, omitted on bare groups, dropped sub-rolls retain full RollPart
`DieResult` reference sharing documented — no deep-clone
`RollPartType = RollPart['type']` alias added
Per-branch construction notes for `evalVersus`, `evalSuccessCount`, `evalGroupModifier`

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@edloidas edloidas merged commit 3c001ac into master May 10, 2026
10 checks passed
@edloidas edloidas deleted the docs/harden-rollpart-spec-114 branch May 10, 2026 10:53
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: harden RollPart spec from design review

1 participant