roll-parser 3.0.0-beta.0 → 3.1.0

package/src/parser/ast.ts

@@ -13,92 +13,182 @@ import type { ComparePoint } from '../types.js';
  * original notation string. The parser sets both on every node it produces;
  * they are typed optional so hand-constructed ASTs (tests, programmatic
  * consumers) remain valid without positions.
+ *
+ * `notation.slice(start, end)` recovers the source text of any parsed node,
+ * which is how the CLI underlines the failing sub-expression.
+ *
+ * @category AST
  */
 export type NodeSpan = {
-  start?: number;
-  end?: number;
+  readonly start?: number;
+  readonly end?: number;
 };
 
 /**
- * Numeric literal node.
+ * Numeric literal node — an integer or decimal written directly in the
+ * notation (`3`, `2.5`). Leaf node.
+ *
+ * Decimals are accepted and carried through arithmetic exactly as written;
+ * only dice counts and sides are required to resolve to integers.
+ *
+ * @category AST
  */
 export type LiteralNode = NodeSpan & {
-  type: 'Literal';
-  value: number;
+  readonly type: 'Literal';
+  readonly value: number;
 };
 
 /**
- * Dice roll node.
- * Count and sides can be expressions to support computed dice like (1+1)d(3*2).
+ * Dice roll node (`NdX`, `dX`, `d%`).
+ *
+ * `count` and `sides` are full sub-expressions, not numbers, which is what
+ * makes computed dice like `(1+1)d(3*2)` and `(1d4)d6` expressible. Both are
+ * evaluated first and must resolve to integers; `d%` desugars to a `sides`
+ * literal of `100`, and an omitted count to a `count` literal of `1`.
+ *
+ * Dice rolled by the `count`/`sides` sub-expressions are meta-expression dice
+ * — they land in `RollResult.rolls` tagged `'meta'` and belong to no pool.
+ *
+ * @category AST
  */
 export type DiceNode = NodeSpan & {
-  type: 'Dice';
-  count: ASTNode;
-  sides: ASTNode;
+  readonly type: 'Dice';
+  readonly count: ASTNode;
+  readonly sides: ASTNode;
 };
 
 /**
  * Fate/Fudge dice node (`dF`).
  * Each die produces a result in {-1, 0, +1}. No configurable sides.
+ *
+ * Fate dice carry `sides: 0` as a sentinel in their `DieResult`, so the
+ * default `critical`/`fumble` rule never fires — it is guarded on `sides > 1`,
+ * which also stops a `+1` face from reading as a fumbled 1. An explicit
+ * threshold still applies: `4dFcs>0` and `4dFcf=-1` set the flags, while the
+ * bare `cs`/`cf` forms are rejected at parse time.
+ *
+ * @category AST
  */
 export type FateDiceNode = NodeSpan & {
-  type: 'FateDice';
-  count: ASTNode;
+  readonly type: 'FateDice';
+  readonly count: ASTNode;
 };
 
 /**
- * Binary operation node.
+ * Binary operation node — the arithmetic backbone of an expression.
+ *
+ * | Operator | Meaning | Precedence | Associativity |
+ * |----------|---------|-----------:|---------------|
+ * | `+` `-` | add, subtract | 10 | left |
+ * | `*` `/` `%` | multiply, divide, modulo | 20 | left |
+ * | `**` | power (also spelled `^`) | 30 | right |
+ *
+ * Dice bind tighter than all of them (40), and postfix modifiers sit at 35,
+ * so `2d6+3` is `(2d6)+3` and `4d6kh3*2` is `(4d6kh3)*2`. The `vs` operator
+ * binds loosest of all (2) and has its own {@link VersusNode}.
+ *
+ * `/` and `%` throw `DIVISION_BY_ZERO` / `MODULO_BY_ZERO` on a zero right
+ * side; any operator producing a non-finite total throws `NON_FINITE_RESULT`.
+ * Division is not rounded — wrap it in `floor()` if you need an integer.
+ *
+ * @category AST
  */
 export type BinaryOpNode = NodeSpan & {
-  type: 'BinaryOp';
-  operator: '+' | '-' | '*' | '/' | '%' | '**';
-  left: ASTNode;
-  right: ASTNode;
+  readonly type: 'BinaryOp';
+  readonly operator: '+' | '-' | '*' | '/' | '%' | '**';
+  readonly left: ASTNode;
+  readonly right: ASTNode;
 };
 
 /**
- * Unary operation node.
+ * Unary operation node — prefix negation, the only unary operator.
+ *
+ * Binding power 25 sits between multiplication and power, so `-1d4` is
+ * `-(1d4)` (negate the roll) rather than `(-1)d4`, while `-2**2` is `-(2**2)`.
+ *
+ * @category AST
  */
 export type UnaryOpNode = NodeSpan & {
-  type: 'UnaryOp';
-  operator: '-';
-  operand: ASTNode;
+  readonly type: 'UnaryOp';
+  readonly operator: '-';
+  readonly operand: ASTNode;
 };
 
 /**
- * Keep/drop modifier node.
+ * Keep/drop modifier node (`khN`, `klN`, `dhN`, `dlN`, and the `kN`
+ * shorthand for `khN`).
+ *
  * Wraps a dice expression with keep highest/lowest or drop highest/lowest.
- */
-export type ModifierNode = NodeSpan & {
-  type: 'Modifier';
-  modifier: 'keep' | 'drop';
-  selector: 'highest' | 'lowest';
-  count: ASTNode;
-  target: ASTNode;
+ * An omitted count defaults to 1, so `4d6kh` is `4d6kh1`. `count` is a full
+ * sub-expression, so `4d6kh(1d2)` is legal — and its dice are drawn *before*
+ * the pool.
+ *
+ * Chained modifiers (`4d6kh3dl1`) do not nest: the evaluator flattens the
+ * chain and applies each spec independently to the same pool, unioning the
+ * dropped sets, which is the Roll20 rule.
+ *
+ * @category AST
+ */
+export type KeepDropNode = NodeSpan & {
+  readonly type: 'KeepDrop';
+  readonly kind: 'keep' | 'drop';
+  readonly selector: 'highest' | 'lowest';
+  readonly count: ASTNode;
+  readonly target: ASTNode;
 };
 
 /**
  * Exploding dice node (`!`, `!!`, `!p`, `!>Y`).
  * Wraps a dice expression with a standard, compounding, or penetrating
  * explosion. An absent `threshold` means "explode on the die's maximum face".
+ *
+ * Thresholds accept any comparator. In notation like `1d10!=10` (the
+ * Storyteller "10-again" rule) the `!` is the explode marker and `=10` the
+ * equality threshold — there is no `!=` comparator. Per-die explosion count
+ * is capped by `EvaluationOptions.maxExplodeIterations`.
+ *
+ * @category AST
  */
 export type ExplodeNode = NodeSpan & {
-  type: 'Explode';
-  variant: 'standard' | 'compound' | 'penetrating';
-  threshold?: ComparePoint;
-  target: ASTNode;
+  readonly type: 'Explode';
+  readonly variant: 'standard' | 'compound' | 'penetrating';
+  readonly threshold?: ComparePoint;
+  readonly target: ASTNode;
 };
 
 /**
  * Reroll node (`r<COND>`, `ro<COND>`).
  * Re-rolls dice that match a comparison condition. `once: true` for `ro`
  * keeps the second result regardless of match; `once: false` for `r`
- * re-rolls recursively until the condition no longer matches.
+ * re-rolls recursively until the condition no longer matches, bounded by
+ * `EvaluationOptions.maxRerollIterations`.
+ *
+ * @category AST
  */
 export type RerollNode = NodeSpan & {
-  type: 'Reroll';
-  once: boolean;
-  condition: ComparePoint;
+  readonly type: 'Reroll';
+  readonly once: boolean;
+  readonly condition: ComparePoint;
+  readonly target: ASTNode;
+};
+
+/**
+ * Per-die clamp node (`minN`, `maxN`).
+ * `4d6min2` raises every die below 2 to 2; `4d6max5` lowers every die above
+ * 5 to 5. The clamp rewrites `DieResult.result` (preserving the raw face in
+ * `initialResult`) and re-sums the pool; `critical`/`fumble` keep reflecting
+ * the natural face. The bound is a full sub-expression (`4d6min(1d2)`),
+ * drawn *after* the pool like other threshold arguments.
+ *
+ * Chained bounds nest and apply left to right: `4d6min2max5` clamps into
+ * [2, 5].
+ *
+ * @category AST
+ */
+export type DieBoundNode = NodeSpan & {
+  type: 'DieBound';
+  bound: 'min' | 'max';
+  value: ASTNode;
   target: ASTNode;
 };
 
@@ -110,12 +200,14 @@ export type RerollNode = NodeSpan & {
  * `SuccessCountNode` may not be wrapped by any postfix modifier, binary
  * operator, unary operator, versus operand, or function argument. The
  * `failThreshold` accepts any `CompareOp`; bare `fN` defaults to `operator: '='`.
+ *
+ * @category AST
  */
 export type SuccessCountNode = NodeSpan & {
-  type: 'SuccessCount';
-  target: ASTNode;
-  threshold: ComparePoint;
-  failThreshold?: ComparePoint;
+  readonly type: 'SuccessCount';
+  readonly target: ASTNode;
+  readonly threshold: ComparePoint;
+  readonly failThreshold?: ComparePoint;
 };
 
 /**
@@ -127,11 +219,13 @@ export type SuccessCountNode = NodeSpan & {
  * roll side. Lowest-precedence operator — chaining (`a vs b vs c`) is
  * rejected at parse time; nesting via parens (`a vs (b vs c)`) is rejected
  * at evaluation time.
+ *
+ * @category AST
  */
 export type VersusNode = NodeSpan & {
-  type: 'Versus';
-  roll: ASTNode;
-  dc: ASTNode;
+  readonly type: 'Versus';
+  readonly roll: ASTNode;
+  readonly dc: ASTNode;
 };
 
 /**
@@ -141,11 +235,16 @@ export type VersusNode = NodeSpan & {
  * variadic functions `max`, `min` (minimum 2 args). Arity is validated at
  * parse time against a static table; by the time the evaluator sees a
  * `FunctionCallNode`, `args.length` is guaranteed to match the function.
+ *
+ * `max`/`min` are variadic with no upper bound, so `max(1d20, 1d20, 1d20)`
+ * is a valid three-way advantage roll.
+ *
+ * @category AST
  */
 export type FunctionCallNode = NodeSpan & {
-  type: 'FunctionCall';
-  name: string;
-  args: ASTNode[];
+  readonly type: 'FunctionCall';
+  readonly name: string;
+  readonly args: readonly ASTNode[];
 };
 
 /**
@@ -155,10 +254,12 @@ export type FunctionCallNode = NodeSpan & {
  * `RollResult.expression` and `RollResult.rendered` round-trip through
  * `parse` without losing precedence information. Semantically transparent:
  * evaluation returns the inner expression's value unchanged.
+ *
+ * @category AST
  */
 export type GroupedNode = NodeSpan & {
-  type: 'Grouped';
-  expression: ASTNode;
+  readonly type: 'Grouped';
+  readonly expression: ASTNode;
 };
 
 /**
@@ -169,10 +270,15 @@ export type GroupedNode = NodeSpan & {
  * lexer preserves case in the `AT` token's `value`, distinct from other
  * identifier tokens which lowercase. Leaf node — no LED, never wraps a
  * sub-expression.
+ *
+ * A name missing from `context` throws `UNDEFINED_VARIABLE` unless
+ * `onMissingVariable: 'zero'` is set.
+ *
+ * @category AST
  */
 export type VariableNode = NodeSpan & {
-  type: 'Variable';
-  name: string;
+  readonly type: 'Variable';
+  readonly name: string;
 };
 
 /**
@@ -183,10 +289,12 @@ export type VariableNode = NodeSpan & {
  * with the sub-roll count. `expressions.length === 1` is a passthrough
  * (flat-pool when wrapped by keep/drop); `expressions.length >= 2` treats
  * each sub-roll's subtotal as a compound die for keep/drop selection.
+ *
+ * @category AST
  */
 export type GroupNode = NodeSpan & {
-  type: 'Group';
-  expressions: ASTNode[];
+  readonly type: 'Group';
+  readonly expressions: readonly ASTNode[];
 };
 
 /**
@@ -197,41 +305,91 @@ export type GroupNode = NodeSpan & {
  * `successes`/`failures`, or any die-level flag (`kept`/`dropped`/
  * `critical`/`fumble`). Dropped dice retain their `dropped` flag and
  * appear in sorted position alongside kept dice.
+ *
+ * `s` and `sa` both mean ascending; `sd` is descending.
+ *
+ * @category AST
  */
 export type SortNode = NodeSpan & {
-  type: 'Sort';
-  order: 'ascending' | 'descending';
-  target: ASTNode;
+  readonly type: 'Sort';
+  readonly order: 'ascending' | 'descending';
+  readonly target: ASTNode;
 };
 
 /**
- * Sentinel for bare `cs` / `cf` without a ComparePoint. Resolved to
- * `result === sides` (for critical) or `result === 1` (for fumble) at
- * evaluation time, using each die's own `sides`.
+ * Sentinel for bare `cs` / `cf` without a ComparePoint. Resolved at
+ * evaluation time against each die's own `sides` and its natural face
+ * (`initialResult ?? result`): critical when that face equals `sides`,
+ * fumble when it equals 1.
+ *
+ * @category AST
  */
 export type CritThreshold = ComparePoint | 'default';
 
 /**
  * Critical threshold modifier node (`cs`, `cf`).
  *
- * Overrides the default `critical`/`fumble` flag logic for the dice
- * produced by `target`. Bare `cs`/`cf` uses the `'default'` sentinel
+ * Overrides the default `critical`/`fumble` flag logic for `target`'s dice
+ * pool — including dice an enclosing `!` or `r` adds to it afterwards, which
+ * `target` never produced. Bare `cs`/`cf` uses the `'default'` sentinel
  * (max face / 1). Custom thresholds accept any ComparePoint. Chaining
  * collapses into a single node — `1d20cs=20cs=1cf>18` has two success
  * and one fail threshold. Display-only: does not change `total`,
  * explosion triggers, or success counting. `cs` and `cf` are independent
  * overrides — a side with no explicit thresholds keeps the default rule
  * (the evaluator substitutes the `'default'` sentinel at apply time).
+ *
+ * @category AST
  */
 export type CritThresholdNode = NodeSpan & {
-  type: 'CritThreshold';
-  successThresholds: CritThreshold[];
-  failThresholds: CritThreshold[];
-  target: ASTNode;
+  readonly type: 'CritThreshold';
+  readonly successThresholds: readonly CritThreshold[];
+  readonly failThresholds: readonly CritThreshold[];
+  readonly target: ASTNode;
 };
 
 /**
- * Union type of all AST nodes.
+ * Discriminated union of all 17 AST node types — what {@link parse} returns
+ * and what {@link evaluate} consumes.
+ *
+ * Narrow it either by switching on `node.type` (PascalCase discriminants, as
+ * opposed to the camelCase ones on {@link RollPart}) or with the exported
+ * type guards: {@link isLiteral}, {@link isDice}, {@link isFateDice},
+ * {@link isBinaryOp}, {@link isUnaryOp}, {@link isKeepDrop},
+ * {@link isExplode}, {@link isReroll}, {@link isDieBound},
+ * {@link isSuccessCount}, {@link isVersus}, {@link isFunctionCall},
+ * {@link isGrouped}, {@link isVariable}, {@link isGroup}, {@link isSort},
+ * {@link isCritThreshold}.
+ *
+ * Nodes are plain data with no methods, so they are structurally clonable and
+ * safe to cache. Every parser-produced node carries a {@link NodeSpan}.
+ *
+ * @example A guard-based walker — count the dice an expression can roll
+ * ```typescript
+ * import {
+ *   type ASTNode, isBinaryOp, isDice, isFateDice, isGroup, isGrouped,
+ *   isFunctionCall, isLiteral, isUnaryOp, isVersus, parse,
+ * } from 'roll-parser';
+ *
+ * function countPools(node: ASTNode): number {
+ *   if (isDice(node) || isFateDice(node)) return 1;
+ *   if (isLiteral(node)) return 0;
+ *   if (isBinaryOp(node)) return countPools(node.left) + countPools(node.right);
+ *   if (isUnaryOp(node)) return countPools(node.operand);
+ *   if (isGrouped(node)) return countPools(node.expression);
+ *   if (isVersus(node)) return countPools(node.roll) + countPools(node.dc);
+ *   if (isGroup(node)) return node.expressions.reduce((n, e) => n + countPools(e), 0);
+ *   if (isFunctionCall(node)) return node.args.reduce((n, a) => n + countPools(a), 0);
+ *   // Every remaining variant is a postfix modifier wrapping `target`.
+ *   return 'target' in node ? countPools(node.target) : 0;
+ * }
+ *
+ * countPools(parse('2d6+3')); // 1
+ * countPools(parse('{2d20kh1+5, 3d8!}kh1')); // 2
+ * countPools(parse('1+2')); // 0
+ * ```
+ *
+ * @category AST
  */
 export type ASTNode =
   | LiteralNode
@@ -239,9 +397,10 @@ export type ASTNode =
   | FateDiceNode
   | BinaryOpNode
   | UnaryOpNode
-  | ModifierNode
+  | KeepDropNode
   | ExplodeNode
   | RerollNode
+  | DieBoundNode
   | SuccessCountNode
   | VersusNode
   | FunctionCallNode
@@ -252,377 +411,205 @@ export type ASTNode =
   | CritThresholdNode;
 
 /**
- * Type guard for LiteralNode.
+ * Narrows an {@link ASTNode} to a numeric literal (`3`, `2.5`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link LiteralNode}
+ *
+ * @category AST
  */
 export function isLiteral(node: ASTNode): node is LiteralNode {
   return node.type === 'Literal';
 }
 
 /**
- * Type guard for DiceNode.
+ * Narrows an {@link ASTNode} to a dice pool (`2d6`, `d%`, `(1d4)d6`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link DiceNode}
+ *
+ * @category AST
  */
 export function isDice(node: ASTNode): node is DiceNode {
   return node.type === 'Dice';
 }
 
 /**
- * Type guard for FateDiceNode.
+ * Narrows an {@link ASTNode} to a Fate/Fudge pool (`4dF`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link FateDiceNode}
+ *
+ * @category AST
  */
 export function isFateDice(node: ASTNode): node is FateDiceNode {
   return node.type === 'FateDice';
 }
 
 /**
- * Type guard for BinaryOpNode.
+ * Narrows an {@link ASTNode} to an arithmetic operation (`+ - * / % **`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link BinaryOpNode}
+ *
+ * @category AST
  */
 export function isBinaryOp(node: ASTNode): node is BinaryOpNode {
   return node.type === 'BinaryOp';
 }
 
 /**
- * Type guard for UnaryOpNode.
+ * Narrows an {@link ASTNode} to a prefix negation (`-1d4`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link UnaryOpNode}
+ *
+ * @category AST
  */
 export function isUnaryOp(node: ASTNode): node is UnaryOpNode {
   return node.type === 'UnaryOp';
 }
 
 /**
- * Type guard for ModifierNode.
+ * Narrows an {@link ASTNode} to a keep/drop modifier (`kh`, `kl`, `dh`, `dl`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link KeepDropNode}
+ *
+ * @category AST
  */
-export function isModifier(node: ASTNode): node is ModifierNode {
-  return node.type === 'Modifier';
+export function isKeepDrop(node: ASTNode): node is KeepDropNode {
+  return node.type === 'KeepDrop';
 }
 
 /**
- * Type guard for ExplodeNode.
+ * Narrows an {@link ASTNode} to an explosion (`!`, `!!`, `!p`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link ExplodeNode}
+ *
+ * @category AST
  */
 export function isExplode(node: ASTNode): node is ExplodeNode {
   return node.type === 'Explode';
 }
 
 /**
- * Type guard for RerollNode.
+ * Narrows an {@link ASTNode} to a reroll (`r`, `ro`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link RerollNode}
+ *
+ * @category AST
  */
 export function isReroll(node: ASTNode): node is RerollNode {
   return node.type === 'Reroll';
 }
 
 /**
- * Type guard for SuccessCountNode.
+ * Narrows an {@link ASTNode} to a success count (`>=6`, with optional `f1`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link SuccessCountNode}
+ *
+ * @category AST
  */
 export function isSuccessCount(node: ASTNode): node is SuccessCountNode {
   return node.type === 'SuccessCount';
 }
 
 /**
- * Type guard for VersusNode.
+ * Narrows an {@link ASTNode} to a PF2e degree-of-success check (`vs`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link VersusNode}
+ *
+ * @category AST
  */
 export function isVersus(node: ASTNode): node is VersusNode {
   return node.type === 'Versus';
 }
 
 /**
- * Type guard for FunctionCallNode.
+ * Narrows an {@link ASTNode} to a math function call (`floor`, `max`, …).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link FunctionCallNode}
+ *
+ * @category AST
  */
 export function isFunctionCall(node: ASTNode): node is FunctionCallNode {
   return node.type === 'FunctionCall';
 }
 
 /**
- * Type guard for GroupedNode.
+ * Narrows an {@link ASTNode} to a parenthesized group (`(1d6+2)`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link GroupedNode}
+ *
+ * @category AST
  */
 export function isGrouped(node: ASTNode): node is GroupedNode {
   return node.type === 'Grouped';
 }
 
 /**
- * Type guard for VariableNode.
+ * Narrows an {@link ASTNode} to a variable reference (`@str`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link VariableNode}
+ *
+ * @category AST
  */
 export function isVariable(node: ASTNode): node is VariableNode {
   return node.type === 'Variable';
 }
 
 /**
- * Type guard for GroupNode.
+ * Narrows an {@link ASTNode} to a braced grouped roll (`{1d8, 1d10}`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link GroupNode}
+ *
+ * @category AST
  */
 export function isGroup(node: ASTNode): node is GroupNode {
   return node.type === 'Group';
 }
 
 /**
- * Type guard for SortNode.
+ * Narrows an {@link ASTNode} to a sort modifier (`s`, `sa`, `sd`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link SortNode}
+ *
+ * @category AST
  */
 export function isSort(node: ASTNode): node is SortNode {
   return node.type === 'Sort';
 }
 
 /**
- * Type guard for CritThresholdNode.
+ * Narrows an {@link ASTNode} to a crit-threshold override (`cs`, `cf`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link CritThresholdNode}
+ *
+ * @category AST
  */
 export function isCritThreshold(node: ASTNode): node is CritThresholdNode {
   return node.type === 'CritThreshold';
 }
 
 /**
- * Wrapper kinds that `unwrapTransparent` can peel.
- *
- * "Transparent" is relative to the question being asked. `Modifier`/`Sort`/
- * `CritThreshold` are transparent for "what is the underlying operand?" when
- * deciding whether to reject a `Group` target — they preserve `containsDicePool`'s
- * answer for whatever they wrap. They are NOT transparent for "is this a
- * `SuccessCount`?" or "is this a `Versus`?", because the parsers that build
- * those wrappers already reject `SuccessCount`/`Versus` operands upstream.
- */
-export type TransparentWrapperKind = 'Grouped' | 'Modifier' | 'Sort' | 'CritThreshold';
-
-/**
- * Walks `node` while its `.type` is in `kinds`, returning the first descendant
- * that is not one of the listed wrappers. Each caller picks the subset that
- * matches its rejection semantics — see `TransparentWrapperKind` for guidance.
- *
- * Used by parser reject helpers to look past wrappers when deciding whether
- * an operand violates a rule (e.g., `Group` cannot be the target of `cs`/`cf`,
- * even when wrapped in `Modifier` like `{1d6}kh1cs>5`).
- */
-export function unwrapTransparent(
-  node: ASTNode,
-  kinds: readonly TransparentWrapperKind[],
-): ASTNode {
-  let current = node;
-  while (true) {
-    switch (current.type) {
-      case 'Grouped':
-        if (!kinds.includes('Grouped')) return current;
-        current = current.expression;
-        break;
-      case 'Modifier':
-        if (!kinds.includes('Modifier')) return current;
-        current = current.target;
-        break;
-      case 'Sort':
-        if (!kinds.includes('Sort')) return current;
-        current = current.target;
-        break;
-      case 'CritThreshold':
-        if (!kinds.includes('CritThreshold')) return current;
-        current = current.target;
-        break;
-      default:
-        return current;
-    }
-  }
-}
-
-/**
- * Returns `true` only when `node`'s direct result is a dice pool —
- * `Dice`, `FateDice`, or a chained pool modifier (`Modifier` / `Explode` /
- * `Reroll`). Does NOT recurse through arithmetic wrappers (`BinaryOp`,
- * `UnaryOp`, `FunctionCall`), so `(1d6+5)` and `floor(1d6/2)` are rejected.
- *
- * Used by the parser to reject postfix pool-modifier targets (kh/kl/dh/dl,
- * !/!!/!p, r/ro) that wrap a non-pool expression. Operating on the inner
- * dice pool would silently drop the surrounding arithmetic.
- */
-export function containsDicePool(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'Dice':
-    case 'FateDice':
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-      return true;
-    case 'Sort':
-    case 'CritThreshold':
-      return containsDicePool(node.target);
-    case 'Grouped':
-      return containsDicePool(node.expression);
-    case 'Group':
-      // ? Multi-sub-roll groups (`{a, b, c}kh1`) always accept: keep/drop
-      //   operates on subtotals, which are "compound dice" by definition —
-      //   even a literal-only `{3, 5, 7}kh1` is valid. Single-sub-roll
-      //   groups are the user's explicit opt-in to flat-pool semantics, so
-      //   we deep-walk through arithmetic that a raw `(1d6+5)kh1` would
-      //   reject. This is the `{}` escape hatch per Stage 3 spec.
-      return node.expressions.length >= 2 || node.expressions.some(deepContainsDicePool);
-    default:
-      return false;
-  }
-}
-
-/**
- * Deeper variant of `containsDicePool` that recurses through arithmetic and
- * function wrappers. Used from the `Group` case above (ordinary parenthesized
- * arithmetic `(1d6+5)kh1` must still reject, so the shallow `containsDicePool`
- * handles those directly) and from the Sort parser guard (sort accepts
- * `(1d6+2d8)s` per Stage 3 spec).
- */
-export function deepContainsDicePool(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'Dice':
-    case 'FateDice':
-      return true;
-    case 'BinaryOp':
-      return deepContainsDicePool(node.left) || deepContainsDicePool(node.right);
-    case 'UnaryOp':
-      return deepContainsDicePool(node.operand);
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-    case 'SuccessCount':
-    case 'Sort':
-    case 'CritThreshold':
-      return deepContainsDicePool(node.target);
-    case 'Versus':
-      return deepContainsDicePool(node.roll) || deepContainsDicePool(node.dc);
-    case 'FunctionCall':
-      return node.args.some(deepContainsDicePool);
-    case 'Grouped':
-      return deepContainsDicePool(node.expression);
-    case 'Group':
-      return node.expressions.length >= 2 || node.expressions.some(deepContainsDicePool);
-    default:
-      return false;
-  }
-}
-
-/**
- * Returns `true` if the pool this node resolves to is (or wraps) a `FateDice`
- * pool. Walks through chained pool modifiers (`Modifier` / `Explode` /
- * `Reroll`) but not arithmetic wrappers — callers should run
- * `containsDicePool` first to reject those.
- *
- * Used by the parser to reject `!`, `!!`, `!p` applied to Fate pools
- * (`4dF!`, `(4dF)kh2!`, etc.). Fate explosion semantics are undefined, so
- * parse-time rejection is preferred over a silent evaluator no-op.
- *
- * Inside a `Group`, recursion uses `deepContainsFatePool` to mirror
- * `containsDicePool`'s deep walk through the same case — otherwise
- * `{4dF+1d6}cf` slips past the bare-Fate guard and the default fumble
- * check (`result === 1`) flips `+1` faces into fumbles.
- */
-export function containsFatePool(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'FateDice':
-      return true;
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-    case 'Sort':
-    case 'CritThreshold':
-      return containsFatePool(node.target);
-    case 'Grouped':
-      return containsFatePool(node.expression);
-    case 'Group':
-      return node.expressions.some(deepContainsFatePool);
-    default:
-      return false;
-  }
-}
-
-/**
- * Deeper variant of `containsFatePool` that recurses through arithmetic and
- * function wrappers. Mirrors `deepContainsDicePool`. Used from
- * `containsFatePool`'s `Group` case so single-sub-roll groups containing
- * arithmetic-wrapped Fate (`{4dF+1d6}cf`) still trip the bare-Fate guard.
- *
- * Outside a `Group`, ordinary parenthesized arithmetic (`(4dF+1d6)cf`) is
- * already rejected upstream by shallow `containsDicePool`, so this helper
- * intentionally stays Group-internal.
- */
-export function deepContainsFatePool(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'FateDice':
-      return true;
-    case 'BinaryOp':
-      return deepContainsFatePool(node.left) || deepContainsFatePool(node.right);
-    case 'UnaryOp':
-      return deepContainsFatePool(node.operand);
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-    case 'SuccessCount':
-    case 'Sort':
-    case 'CritThreshold':
-      return deepContainsFatePool(node.target);
-    case 'Versus':
-      return deepContainsFatePool(node.roll) || deepContainsFatePool(node.dc);
-    case 'FunctionCall':
-      return node.args.some(deepContainsFatePool);
-    case 'Grouped':
-      return deepContainsFatePool(node.expression);
-    case 'Group':
-      return node.expressions.some(deepContainsFatePool);
-    default:
-      return false;
-  }
-}
-
-/**
- * Deep-walks a node to find any descendant `Group` with two or more
- * sub-expressions. Used by `rejectGroupTarget`'s single-sub-roll
- * passthrough so a multi-sub Group buried under arithmetic
- * (`{{1d6,2d8}+0}cs>5`), function calls (`{abs({1d6,2d8})}cs>5`), or any
- * other non-transparent wrapper still rejects with the same error code.
- *
- * Without this walk, the unwrap inside `rejectGroupTarget` only peels
- * `Grouped`/`Modifier`/`Sort`/`CritThreshold` — a multi-sub Group cloaked
- * in a `BinaryOp`/`UnaryOp`/`FunctionCall` revives issue #97.
- */
-export function containsMultiSubGroup(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'Group':
-      return node.expressions.length >= 2 || node.expressions.some(containsMultiSubGroup);
-    case 'BinaryOp':
-      return containsMultiSubGroup(node.left) || containsMultiSubGroup(node.right);
-    case 'UnaryOp':
-      return containsMultiSubGroup(node.operand);
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-    case 'SuccessCount':
-    case 'Sort':
-    case 'CritThreshold':
-      return containsMultiSubGroup(node.target);
-    case 'Versus':
-      return containsMultiSubGroup(node.roll) || containsMultiSubGroup(node.dc);
-    case 'FunctionCall':
-      return node.args.some(containsMultiSubGroup);
-    case 'Grouped':
-      return containsMultiSubGroup(node.expression);
-    default:
-      return false;
-  }
-}
-
-/**
- * Deep-walks a node to find any descendant `Versus`. Used by
- * `rejectVersusTarget`'s single-sub-roll Group passthrough so a buried
- * Versus (`{1+(1d20 vs 15)}cs>18`, `{abs(1d20 vs 15)}cs>18`,
- * `{-(1d20 vs 15)}kh1`) still rejects with `NESTED_VERSUS` instead of
- * silently dropping `versusMetadata` at the modifier consumer site.
- */
-export function containsVersus(node: ASTNode): boolean {
-  switch (node.type) {
-    case 'Versus':
-      return true;
-    case 'BinaryOp':
-      return containsVersus(node.left) || containsVersus(node.right);
-    case 'UnaryOp':
-      return containsVersus(node.operand);
-    case 'Modifier':
-    case 'Explode':
-    case 'Reroll':
-    case 'SuccessCount':
-    case 'Sort':
-    case 'CritThreshold':
-      return containsVersus(node.target);
-    case 'FunctionCall':
-      return node.args.some(containsVersus);
-    case 'Grouped':
-      return containsVersus(node.expression);
-    case 'Group':
-      return node.expressions.some(containsVersus);
-    default:
-      return false;
-  }
+ * Narrows an {@link ASTNode} to a per-die clamp (`min2`, `max5`).
+ *
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link DieBoundNode}
+ *
+ * @category AST
+ */
+export function isDieBound(node: ASTNode): node is DieBoundNode {
+  return node.type === 'DieBound';
 }