roll-parser 3.0.0-alpha.0 → 3.0.0-beta.0

package/src/parser/parser.ts

@@ -4,26 +4,41 @@
  * @module parser/parser
  */
 
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
-import { lex } from '../lexer/lexer';
-import { type Token, TokenType } from '../lexer/tokens';
-import type { CompareOp, ComparePoint } from '../types';
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import { lex } from '../lexer/lexer.js';
+import { type Token, TokenType } from '../lexer/tokens.js';
+import type { CompareOp, ComparePoint } from '../types.js';
 import type {
   ASTNode,
   BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
   DiceNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
+  GroupedNode,
+  GroupNode,
   LiteralNode,
   ModifierNode,
   RerollNode,
+  SortNode,
   SuccessCountNode,
   UnaryOpNode,
+  VariableNode,
   VersusNode,
-} from './ast';
-import { containsDice, isSuccessCount } from './ast';
+} from './ast.js';
+import {
+  containsDicePool,
+  containsFatePool,
+  containsMultiSubGroup,
+  containsVersus,
+  deepContainsDicePool,
+  isCritThreshold,
+  isSuccessCount,
+  unwrapTransparent,
+} from './ast.js';
 
 /**
  * Error thrown when the parser encounters invalid syntax.
@@ -57,6 +72,10 @@ const BP = {
   // Versus (left-associative, lowest precedence — `1d20+10 vs 25+10` = `(1d20+10) vs (25+10)`)
   VS_LEFT: 2,
   VS_RIGHT: 3,
+  // Comparison operators used as the success-count LED. Must be below
+  // ADD/MUL so `XdY+N>T` parses as `(XdY+N)>T` and fails the pool-target
+  // guard with a clear error, instead of the `>` stealing `N` from the `+`.
+  COMPARE: 8,
   // Addition/subtraction (left-associative)
   ADD_LEFT: 10,
   ADD_RIGHT: 11,
@@ -75,6 +94,24 @@ const BP = {
   DICE_RIGHT: 41,
 } as const;
 
+/**
+ * Maximum expression nesting depth. Far beyond any human-authored notation —
+ * exists so adversarial input like 20,000 nested parens throws a typed
+ * `ParseError` instead of an uncaught `RangeError` stack overflow (which
+ * would also break the `isRollParserError` contract). Bounding parse depth
+ * also bounds AST depth, protecting the recursive AST walkers and evaluator.
+ */
+const MAX_PARSE_DEPTH = 128;
+
+/** Human-readable symbols for tokens named in `expect()` error messages. */
+const TOKEN_DISPLAY: Partial<Record<TokenType, string>> = {
+  [TokenType.LPAREN]: `'('`,
+  [TokenType.RPAREN]: `')'`,
+  [TokenType.LBRACE]: `'{'`,
+  [TokenType.RBRACE]: `'}'`,
+  [TokenType.COMMA]: `','`,
+};
+
 /**
  * Arity table for math functions. `min` and `max` are inclusive.
  * `POSITIVE_INFINITY` means unbounded (variadic).
@@ -97,6 +134,7 @@ const FUNCTION_ARITY: Record<string, { min: number; max: number }> = {
 export class Parser {
   private readonly tokens: Token[];
   private pos = 0;
+  private depth = 0;
 
   constructor(tokens: Token[]) {
     this.tokens = tokens;
@@ -130,19 +168,33 @@ export class Parser {
    * Parse an expression with minimum binding power.
    */
   private parseExpression(minBp: number): ASTNode {
-    let left = this.parseNud();
+    this.depth += 1;
+    if (this.depth > MAX_PARSE_DEPTH) {
+      throw new ParseError(
+        `Expression nesting exceeds the maximum depth of ${MAX_PARSE_DEPTH}`,
+        'MAX_DEPTH_EXCEEDED',
+        this.peek().position,
+        this.peek(),
+      );
+    }
 
-    while (this.hasTokens()) {
-      const token = this.peek();
-      const leftBp = this.getLeftBp(token);
+    try {
+      let left = this.parseNud();
 
-      if (leftBp < minBp) break;
+      while (this.hasTokens()) {
+        const token = this.peek();
+        const leftBp = this.getLeftBp(token);
 
-      this.advance();
-      left = this.parseLed(left, token);
-    }
+        if (leftBp < minBp) break;
 
-    return left;
+        this.advance();
+        left = this.parseLed(left, token);
+      }
+
+      return left;
+    } finally {
+      this.depth -= 1;
+    }
   }
 
   /**
@@ -157,23 +209,29 @@ export class Parser {
         return this.parseLiteral(token);
 
       case TokenType.MINUS:
-        return this.parseUnaryMinus();
+        return this.parseUnaryMinus(token);
 
       case TokenType.DICE:
-        return this.parsePrefixDice();
+        return this.parsePrefixDice(token);
 
       case TokenType.DICE_PERCENT:
-        return this.parsePrefixDicePercent();
+        return this.parsePrefixDicePercent(token);
 
       case TokenType.DICE_FATE:
-        return this.parsePrefixFateDice();
+        return this.parsePrefixFateDice(token);
 
       case TokenType.LPAREN:
-        return this.parseGrouped();
+        return this.parseGrouped(token);
+
+      case TokenType.LBRACE:
+        return this.parseGroup(token);
 
       case TokenType.FUNCTION:
         return this.parseFunctionCall(token);
 
+      case TokenType.AT:
+        return this.parseVariable(token);
+
       case TokenType.EOF:
         throw new ParseError('Unexpected end of input', 'UNEXPECTED_END', token.position);
 
@@ -194,13 +252,13 @@ export class Parser {
   private parseLed(left: ASTNode, token: Token): ASTNode {
     switch (token.type) {
       case TokenType.DICE:
-        return this.parseInfixDice(left);
+        return this.parseInfixDice(left, token);
 
       case TokenType.DICE_PERCENT:
-        return this.parseInfixDicePercent(left);
+        return this.parseInfixDicePercent(left, token);
 
       case TokenType.DICE_FATE:
-        return this.parseInfixFateDice(left);
+        return this.parseInfixFateDice(left, token);
 
       case TokenType.PLUS:
       case TokenType.MINUS:
@@ -225,6 +283,14 @@ export class Parser {
       case TokenType.REROLL_ONCE:
         return this.parseReroll(left, token);
 
+      case TokenType.SORT_ASC:
+      case TokenType.SORT_DESC:
+        return this.parseSort(left, token);
+
+      case TokenType.CRIT_SUCCESS:
+      case TokenType.CRIT_FAIL:
+        return this.parseCritThreshold(left, token);
+
       case TokenType.GREATER:
       case TokenType.GREATER_EQUAL:
       case TokenType.LESS:
@@ -247,82 +313,152 @@ export class Parser {
 
   // * Node parsers
 
+  /**
+   * Zero-width span for synthetic nodes (implicit counts, `d%` sides) that
+   * have no source text of their own — anchored at the governing token.
+   */
+  private static syntheticLiteral(value: number, token: Token): LiteralNode {
+    return { type: 'Literal', value, start: token.position, end: token.position };
+  }
+
   private parseLiteral(token: Token): LiteralNode {
     return {
       type: 'Literal',
       value: Number.parseFloat(token.value),
+      start: token.position,
+      end: token.end,
     };
   }
 
-  private parseUnaryMinus(): UnaryOpNode {
+  private parseUnaryMinus(token: Token): UnaryOpNode {
     const operand = this.parseExpression(BP.UNARY);
+    this.rejectSuccessCountTarget(operand, token);
     return {
       type: 'UnaryOp',
       operator: '-',
       operand,
+      start: token.position,
+      end: operand.end ?? token.end,
     };
   }
 
-  private parsePrefixDice(): DiceNode {
+  private parsePrefixDice(token: Token): DiceNode {
     // d20 → Dice(1, 20)
     const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
     return {
       type: 'Dice',
-      count: { type: 'Literal', value: 1 },
+      count: Parser.syntheticLiteral(1, token),
       sides,
+      start: token.position,
+      end: sides.end ?? token.end,
     };
   }
 
-  private parseInfixDice(left: ASTNode): DiceNode {
+  private parseInfixDice(left: ASTNode, token: Token): DiceNode {
     // 4d6 → Dice(4, 6)
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     const sides = this.parseExpression(BP.DICE_RIGHT);
+    this.rejectSuccessCountTarget(sides, token);
+    this.rejectVersusTarget(sides, token);
     return {
       type: 'Dice',
       count: left,
       sides,
+      start: left.start ?? token.position,
+      end: sides.end ?? token.end,
     };
   }
 
-  private parsePrefixDicePercent(): DiceNode {
+  private parsePrefixDicePercent(token: Token): DiceNode {
     // d% → Dice(1, 100)
     return {
       type: 'Dice',
-      count: { type: 'Literal', value: 1 },
-      sides: { type: 'Literal', value: 100 },
+      count: Parser.syntheticLiteral(1, token),
+      sides: Parser.syntheticLiteral(100, token),
+      start: token.position,
+      end: token.end,
     };
   }
 
-  private parseInfixDicePercent(left: ASTNode): DiceNode {
+  private parseInfixDicePercent(left: ASTNode, token: Token): DiceNode {
     // 2d% → Dice(2, 100)
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     return {
       type: 'Dice',
       count: left,
-      sides: { type: 'Literal', value: 100 },
+      sides: Parser.syntheticLiteral(100, token),
+      start: left.start ?? token.position,
+      end: token.end,
     };
   }
 
-  private parsePrefixFateDice(): FateDiceNode {
+  private parsePrefixFateDice(token: Token): FateDiceNode {
     // dF → FateDice(1)
     return {
       type: 'FateDice',
-      count: { type: 'Literal', value: 1 },
+      count: Parser.syntheticLiteral(1, token),
+      start: token.position,
+      end: token.end,
     };
   }
 
-  private parseInfixFateDice(left: ASTNode): FateDiceNode {
+  private parseInfixFateDice(left: ASTNode, token: Token): FateDiceNode {
     // 4dF → FateDice(4). Unlike parseInfixDice, there is no sides sub-parse,
     // so modifiers (`kh`, `dl`, …) naturally bind at the outer Pratt loop
     // without BP competition against a right-operand.
+    this.rejectSuccessCountTarget(left, token);
+    this.rejectVersusTarget(left, token);
+    this.rejectBareDiceChain(left, token);
     return {
       type: 'FateDice',
       count: left,
+      start: left.start ?? token.position,
+      end: token.end,
     };
   }
 
-  private parseGrouped(): ASTNode {
-    const expr = this.parseExpression(0);
-    this.expect(TokenType.RPAREN);
-    return expr;
+  private parseGrouped(token: Token): GroupedNode {
+    const expression = this.parseExpression(0);
+    const close = this.expect(TokenType.RPAREN);
+    return { type: 'Grouped', expression, start: token.position, end: close.end };
+  }
+
+  private parseGroup(startToken: Token): GroupNode {
+    // ? `LBRACE`/`RBRACE`/`COMMA` all have `getLeftBp === -1`, so inner
+    //   `parseExpression(0)` calls terminate at the first `,` or `}` without
+    //   competing with modifier/arithmetic BPs.
+    if (this.peek().type === TokenType.RBRACE) {
+      throw new ParseError('Empty group', 'UNEXPECTED_TOKEN', startToken.position, startToken);
+    }
+
+    const expressions: ASTNode[] = [this.parseExpression(0)];
+    while (this.peek().type === TokenType.COMMA) {
+      this.advance();
+      expressions.push(this.parseExpression(0));
+    }
+
+    if (this.peek().type !== TokenType.RBRACE) {
+      const unterminated = this.peek();
+      throw new ParseError(
+        `Unterminated group: expected '}' or ','`,
+        'EXPECTED_TOKEN',
+        unterminated.position,
+        unterminated,
+      );
+    }
+    const close = this.advance();
+
+    return { type: 'Group', expressions, start: startToken.position, end: close.end };
+  }
+
+  private parseVariable(token: Token): VariableNode {
+    return { type: 'Variable', name: token.value, start: token.position, end: token.end };
   }
 
   private parseFunctionCall(token: Token): FunctionCallNode {
@@ -333,14 +469,18 @@ export class Parser {
 
     const args: ASTNode[] = [];
     if (this.peek().type !== TokenType.RPAREN) {
-      args.push(this.parseExpression(0));
+      const first = this.parseExpression(0);
+      this.rejectSuccessCountTarget(first, token);
+      args.push(first);
       while (this.peek().type === TokenType.COMMA) {
         this.advance();
-        args.push(this.parseExpression(0));
+        const next = this.parseExpression(0);
+        this.rejectSuccessCountTarget(next, token);
+        args.push(next);
       }
     }
 
-    this.expect(TokenType.RPAREN);
+    const close = this.expect(TokenType.RPAREN);
 
     const arity = FUNCTION_ARITY[token.value];
     if (arity === undefined) {
@@ -370,24 +510,69 @@ export class Parser {
       );
     }
 
-    return { type: 'FunctionCall', name: token.value, args };
+    return {
+      type: 'FunctionCall',
+      name: token.value,
+      args,
+      start: token.position,
+      end: close.end,
+    };
   }
 
   private parseBinaryOp(left: ASTNode, token: Token): BinaryOpNode {
+    this.rejectSuccessCountTarget(left, token);
+
     const operator = this.getOperatorSymbol(token);
     const rightBp = this.getRightBp(token);
     const right = this.parseExpression(rightBp);
 
+    this.rejectSuccessCountTarget(right, token);
+
     return {
       type: 'BinaryOp',
       operator,
       left,
       right,
+      start: left.start ?? token.position,
+      end: right.end ?? token.end,
     };
   }
 
+  /**
+   * Rejects a dice token whose count operand is itself a bare (unparenthesized)
+   * dice expression. `4d6d1` would otherwise silently parse as `(4d6)d1` —
+   * roll 4d6, then use the result as a count of d1 dice — which is almost
+   * never intended: every major dice dialect reads `4d6d1` as "drop lowest 1".
+   * Both meanings stay reachable through explicit forms: `4d6dl1` to drop,
+   * `(4d6)d1` for nested dice.
+   */
+  private rejectBareDiceChain(left: ASTNode, token: Token): void {
+    switch (left.type) {
+      case 'Dice':
+      case 'FateDice':
+      case 'Explode':
+      case 'Reroll':
+      case 'Modifier':
+      case 'Sort':
+      case 'CritThreshold':
+        throw new ParseError(
+          `Ambiguous dice chain: use 'dl'/'dh' to drop dice (4d6dl1) or parentheses for nested dice ((4d6)d1)`,
+          'AMBIGUOUS_DICE_CHAIN',
+          token.position,
+          token,
+        );
+      default:
+        return;
+    }
+  }
+
   private rejectSuccessCountTarget(target: ASTNode, token: Token): void {
-    if (isSuccessCount(target)) {
+    // ? Narrow unwrap: only `Grouped`. A `SuccessCount` cannot live inside
+    //   `Modifier`/`Sort`/`CritThreshold` because each of those parsers calls
+    //   this same reject on their target before constructing the wrapper —
+    //   so widening the set here would never match.
+    const node = unwrapTransparent(target, ['Grouped']);
+    if (isSuccessCount(node)) {
       throw new ParseError(
         `Cannot apply modifier after success counting`,
         'INVALID_SUCCESS_COUNT_TARGET',
@@ -397,8 +582,102 @@ export class Parser {
     }
   }
 
+  /**
+   * Rejects `GroupNode` (or a wrapper-cloaked group) as the target of `token`.
+   * Explode, reroll, and crit-threshold wrap bare dice pools only — a group
+   * is a container of sub-expressions, so these modifiers have no defined
+   * semantics. Walks `Grouped`/`Modifier`/`Sort`/`CritThreshold` so wrappers
+   * cannot smuggle a group past the check (`{1d6}kh1cs>5`, `({1d6})!`,
+   * `{1d6}scs>5` all reject the same as `{1d6}!`/`{1d6}cs>5`).
+   *
+   * `singleSubRollPasses` opts the caller into the Stage 3 single-sub-roll
+   * passthrough rule (STAGE3.md "Group Semantics: Single vs Multi Sub-Roll"):
+   * a `Group` with one expression is the user's explicit flat-pool escape
+   * hatch and is equivalent to its unwrapped form. Currently only
+   * `parseCritThreshold` opts in — explode/reroll keep the strict reject so
+   * existing notation contracts don't shift.
+   */
+  private rejectGroupTarget(
+    target: ASTNode,
+    token: Token,
+    action: string,
+    code: RollParserErrorCode,
+    singleSubRollPasses = false,
+  ): void {
+    const node = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    if (node.type !== 'Group') return;
+    if (singleSubRollPasses && node.expressions.length === 1) {
+      // ! Deep-walk the inner sub-expression — `unwrapTransparent` only peels
+      //   `Grouped`/`Modifier`/`Sort`/`CritThreshold`, so a multi-sub Group
+      //   buried under arithmetic (`{{1d6,2d8}+0}cs>5`), function calls
+      //   (`{abs({1d6,2d8})}cs>5`), or unary ops would otherwise revive the
+      //   exact dropped-die-flag bug from #97.
+      const inner = node.expressions[0];
+      if (inner != null && containsMultiSubGroup(inner)) {
+        throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+      }
+      return;
+    }
+    throw new ParseError(`Cannot ${action} a group`, code, token.position, token);
+  }
+
+  private rejectVersusTarget(target: ASTNode, token: Token): void {
+    // ? Versus produces a PF2e degree outcome — a terminal scalar, not a
+    //   valid input to dice count/sides/thresholds. Symmetric with
+    //   `rejectSuccessCountTarget`; wrappers like `floor(vs)+0` still
+    //   propagate `versusMetadata` via `mergeContext`, so this only blocks
+    //   `mergeMetaRolls` sites where metadata would silently vanish.
+    // ? Narrow unwrap: only `Grouped`. `Modifier`/`Sort`/`CritThreshold`
+    //   cannot wrap a `Versus` because `containsDicePool` does not recurse
+    //   into `Versus`, so each of those parsers rejects the wrap upstream.
+    const node = unwrapTransparent(target, ['Grouped']);
+    if (node.type === 'Versus') {
+      throw new ParseError(
+        `Versus cannot be used as a meta-expression`,
+        'NESTED_VERSUS',
+        token.position,
+        token,
+      );
+    }
+    // ! Single-sub-roll `Group` passthrough is the new sibling route —
+    //   `containsDicePool` recurses into Group's single sub-expression via
+    //   `deepContainsDicePool`, which traverses Versus's `roll`/`dc`. Deep
+    //   walk for any descendant Versus so `{1d20 vs 15}cs>18`,
+    //   `{1+(1d20 vs 15)}cs>18`, and `4d6>={abs(1d20 vs 15)}` reject too.
+    if (node.type === 'Group' && node.expressions.length === 1) {
+      const inner = node.expressions[0];
+      if (inner != null && containsVersus(inner)) {
+        throw new ParseError(
+          `Versus cannot be used as a meta-expression`,
+          'NESTED_VERSUS',
+          token.position,
+          token,
+        );
+      }
+    }
+  }
+
   private parseModifier(target: ASTNode, token: Token): ModifierNode {
     this.rejectSuccessCountTarget(target, token);
+    // ! Mirror `parseSort`/`parseCritThreshold` — keep/drop applied to a
+    //   Versus target silently drops `degree`/`natural` metadata. Pre-existing
+    //   for `(1d20 vs 15)kh1` (caught upstream by `containsDicePool` with a
+    //   different error code), but the single-sub-roll Group passthrough makes
+    //   `{1d20 vs 15}kh1` reachable past `containsDicePool` (Group's deep
+    //   walk recurses into Versus's roll/dc), so the explicit reject is the
+    //   only thing that closes the metadata-drop hole.
+    this.rejectVersusTarget(target, token);
+
+    // Keep/drop modifiers need a dice pool to select from. Wrapping arithmetic
+    // (e.g. `(1d6+5)kh1`, `4d6+2kh3`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Keep/drop modifiers require a dice pool target`,
+        'INVALID_MODIFIER_TARGET',
+        token.position,
+        token,
+      );
+    }
 
     const modifier =
       token.type === TokenType.KEEP_HIGH || token.type === TokenType.KEEP_LOW ? 'keep' : 'drop';
@@ -410,10 +689,15 @@ export class Parser {
 
     // Default to 1 when no explicit count follows the modifier (e.g., 4d6kh → 4d6kh1)
     const nextToken = this.peek().type;
-    const count: ASTNode =
-      nextToken === TokenType.NUMBER || nextToken === TokenType.LPAREN
-        ? this.parseExpression(BP.DICE_LEFT)
-        : { type: 'Literal', value: 1 };
+    const hasExplicitCount =
+      nextToken === TokenType.NUMBER ||
+      nextToken === TokenType.LPAREN ||
+      nextToken === TokenType.AT;
+    const count: ASTNode = hasExplicitCount
+      ? this.parseExpression(BP.DICE_LEFT)
+      : Parser.syntheticLiteral(1, token);
+    this.rejectSuccessCountTarget(count, token);
+    this.rejectVersusTarget(count, token);
 
     return {
       type: 'Modifier',
@@ -421,12 +705,42 @@ export class Parser {
       selector,
       count,
       target,
+      start: target.start ?? token.position,
+      end: hasExplicitCount ? (count.end ?? token.end) : token.end,
     };
   }
 
   private parseExplode(target: ASTNode, token: Token): ExplodeNode {
     this.rejectSuccessCountTarget(target, token);
 
+    // Groups have no explode semantics — reject outright. Must come before
+    // `containsDicePool`, which recurses into `Group` and would otherwise
+    // let `{4d6}!` slip through.
+    this.rejectGroupTarget(target, token, 'explode', 'INVALID_EXPLODE_TARGET');
+
+    // Explode needs a dice pool to explode on. Wrapping arithmetic (e.g.
+    // `(1d6+5)!`, `floor(1d6/2)!`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Explode modifier requires a dice pool target`,
+        'INVALID_EXPLODE_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // Fate dice (sides = 0) cannot explode — the symmetric -1/0/+1 range has
+    // no natural "max" trigger, so semantics are undefined. Reject at parse
+    // time rather than silently no-op in the evaluator.
+    if (containsFatePool(target)) {
+      throw new ParseError(
+        `Fate dice cannot explode`,
+        'INVALID_EXPLODE_TARGET',
+        token.position,
+        token,
+      );
+    }
+
     // ? Reject nested explodes (e.g., `1d6!!!`) — a second explode token atop
     //   an ExplodeNode has no meaningful semantics and is rejected per spec.
     if (target.type === 'Explode') {
@@ -445,9 +759,16 @@ export class Parser {
           ? 'compound'
           : 'penetrating';
 
-    const node: ExplodeNode = { type: 'Explode', variant, target };
+    const node: ExplodeNode = {
+      type: 'Explode',
+      variant,
+      target,
+      start: target.start ?? token.position,
+      end: token.end,
+    };
     if (this.isComparePointAhead()) {
       node.threshold = this.parseComparePoint();
+      node.end = node.threshold.value.end ?? token.end;
     }
     return node;
   }
@@ -455,6 +776,21 @@ export class Parser {
   private parseReroll(target: ASTNode, token: Token): RerollNode {
     this.rejectSuccessCountTarget(target, token);
 
+    // Groups have no reroll semantics — reject outright. Must come before
+    // `containsDicePool`, which recurses into `Group`.
+    this.rejectGroupTarget(target, token, 'reroll', 'INVALID_REROLL_TARGET');
+
+    // Reroll needs a dice pool to inspect. Wrapping arithmetic (e.g.
+    // `(1d6+5)r<3`, `floor(1d6/2)ro<3`) would silently drop user math.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Reroll modifier requires a dice pool target`,
+        'INVALID_REROLL_TARGET',
+        token.position,
+        token,
+      );
+    }
+
     // A reroll token must be followed by a comparison — bare `r` / `ro` is invalid.
     if (!this.isComparePointAhead()) {
       throw new ParseError(
@@ -468,18 +804,153 @@ export class Parser {
     const once = token.type === TokenType.REROLL_ONCE;
     const condition = this.parseComparePoint();
 
-    return { type: 'Reroll', once, condition, target };
+    return {
+      type: 'Reroll',
+      once,
+      condition,
+      target,
+      start: target.start ?? token.position,
+      end: condition.value.end ?? token.end,
+    };
+  }
+
+  private parseSort(target: ASTNode, token: Token): SortNode {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+
+    // Sort is purely visual but still needs a dice pool to reorder —
+    // `5s`, `(1+2)s`, or `floor(5)s` have no dice to touch. Uses the deep
+    // guard so arithmetic-wrapped pools like `(1d6+2d8)s` are accepted per
+    // Stage 3 spec, while pure literals/arithmetic reject.
+    if (!deepContainsDicePool(target)) {
+      throw new ParseError(
+        `Sort modifier requires a dice pool target`,
+        'INVALID_SORT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // ! Multi-sub-roll groups (`{a, b}s`, `({a, b})s`) need hierarchical
+    //   sort per Stage 3 spec §3 (sort dice within each sub-roll, then sort
+    //   sub-rolls by total) — `evalSort` only flat-sorts, so accepting the
+    //   syntax would silently ship non-spec behaviour. Reject at parse time
+    //   until the deferred Stage 4 implementation lands. Single-sub Groups
+    //   keep passing through (the unwrap returns a `Group` with one
+    //   expression, which is the user's flat-pool escape hatch).
+    const base = unwrapTransparent(target, ['Grouped', 'Modifier', 'Sort', 'CritThreshold']);
+    if (base.type === 'Group' && base.expressions.length >= 2) {
+      throw new ParseError(
+        `Sort modifier does not yet support multi-sub-roll groups`,
+        'INVALID_SORT_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const order: SortNode['order'] = token.type === TokenType.SORT_ASC ? 'ascending' : 'descending';
+
+    // ? Chained sorts (`4d6ss`, `4d6sasd`) are allowed — sort is idempotent
+    //   when repeated in the same direction; a later `sd` after `s` just
+    //   overrides the order since both pass over the same pool.
+    return {
+      type: 'Sort',
+      order,
+      target,
+      start: target.start ?? token.position,
+      end: token.end,
+    };
+  }
+
+  private parseCritThreshold(target: ASTNode, token: Token): CritThresholdNode {
+    this.rejectSuccessCountTarget(target, token);
+    this.rejectVersusTarget(target, token);
+
+    // Multi-sub-roll groups have no crit-threshold semantics per Stage 3 spec
+    // — a group there is a container of sub-roll subtotals, not a dice pool,
+    // and applying cs/cf would override `critical`/`fumble` on dropped
+    // sub-roll dice. Single-sub-roll groups pass through under the documented
+    // flat-pool rule (`{1d20}kh1cs>18` ≡ `(1d20)kh1cs>18`). Must run before
+    // `containsDicePool`, which recurses into `Group`.
+    this.rejectGroupTarget(
+      target,
+      token,
+      'apply crit threshold to',
+      'INVALID_CRIT_THRESHOLD_TARGET',
+      true,
+    );
+
+    // Shallow dice-pool check (bare dice only) — rejects `(1d6+2d8)cs>5`,
+    // `5cs`, `(1+2)cs`, `floor(5)cs`. Matches explode/reroll behavior.
+    // Note: if `target` already is a `CritThresholdNode`, `containsDicePool`
+    // recurses into its `target`, so chained `cs`/`cf` naturally pass.
+    if (!containsDicePool(target)) {
+      throw new ParseError(
+        `Crit threshold modifier requires a dice pool target`,
+        'INVALID_CRIT_THRESHOLD_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    // Bare `cs`/`cf` resolve to a per-die default that assumes max-side / 1
+    // semantics — incompatible with Fate dice (`{-1, 0, +1}`), where the bare
+    // fumble check would flip the best face (`+1`) into a fumble. Custom
+    // thresholds with explicit ComparePoints remain accepted. Mirrors the
+    // Fate-explosion rejection above.
+    if (!this.isComparePointAhead() && containsFatePool(target)) {
+      throw new ParseError(
+        `Bare cs/cf cannot apply to Fate dice`,
+        'INVALID_CRIT_THRESHOLD_TARGET',
+        token.position,
+        token,
+      );
+    }
+
+    const threshold: CritThreshold = this.isComparePointAhead()
+      ? this.parseComparePoint()
+      : 'default';
+    const end = threshold === 'default' ? token.end : (threshold.value.end ?? token.end);
+
+    // ? Unwrap parens so `(1d20cs>19)cs=1` chains into the inner node. Without
+    //   unwrapping, the outer `cs` would create a second CritThresholdNode
+    //   wrapping the Grouped — the collapse-into-single-node design decision
+    //   from STAGE3.md §"CritThreshold Collects Multiple Thresholds" would
+    //   be subtly broken for any user who parenthesizes the chain.
+    let chainTarget: ASTNode = target;
+    while (chainTarget.type === 'Grouped') {
+      chainTarget = chainTarget.expression;
+    }
+    if (isCritThreshold(chainTarget)) {
+      if (token.type === TokenType.CRIT_SUCCESS) {
+        chainTarget.successThresholds.push(threshold);
+      } else {
+        chainTarget.failThresholds.push(threshold);
+      }
+      chainTarget.end = end;
+      return chainTarget;
+    }
+
+    return {
+      type: 'CritThreshold',
+      successThresholds: token.type === TokenType.CRIT_SUCCESS ? [threshold] : [],
+      failThresholds: token.type === TokenType.CRIT_FAIL ? [threshold] : [],
+      target,
+      start: target.start ?? token.position,
+      end,
+    };
   }
 
   private parseSuccessCount(target: ASTNode, token: Token): SuccessCountNode {
     // Success counting is terminal: chaining (`>=5>=3`) has no semantics.
     this.rejectSuccessCountTarget(target, token);
 
-    // Reject non-dice targets like `1>=3` or `(1+2)>=3`. Success counting
-    // operates on a dice pool; a sum has no pool to count.
-    if (!containsDice(target)) {
+    // Reject non-pool targets like `1>=3`, `(1+2)>=3`, `(1d6*2)>=10`, or
+    // `(1d20 vs 15)>=1`. Success counting operates on a raw dice pool; any
+    // arithmetic or composition wrapping would be silently ignored.
+    if (!containsDicePool(target)) {
       throw new ParseError(
-        `Success counting requires a dice expression`,
+        `Success counting requires a dice pool target`,
         'INVALID_SUCCESS_COUNT_TARGET',
         token.position,
         token,
@@ -487,33 +958,60 @@ export class Parser {
     }
 
     const operator = this.getCompareOp(token);
+    // ? Threshold binding: `BP.DICE_LEFT` — see `parseComparePoint` JSDoc.
     const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
     const node: SuccessCountNode = {
       type: 'SuccessCount',
       target,
       threshold: { operator, value },
+      start: target.start ?? token.position,
+      end: value.end ?? token.end,
     };
 
     if (this.peek().type === TokenType.FAIL) {
       this.advance();
-      const failValue = this.parseExpression(BP.DICE_LEFT);
-      node.failThreshold = { operator: '=', value: failValue };
+      if (this.isComparePointAhead()) {
+        node.failThreshold = this.parseComparePoint();
+      } else {
+        // ? Same threshold binding as above (BP.DICE_LEFT).
+        const failValue = this.parseExpression(BP.DICE_LEFT);
+        this.rejectSuccessCountTarget(failValue, token);
+        this.rejectVersusTarget(failValue, token);
+        node.failThreshold = { operator: '=', value: failValue };
+      }
+      node.end = node.failThreshold.value.end ?? node.end ?? token.end;
     }
 
     return node;
   }
 
   private parseVersus(left: ASTNode, token: Token): VersusNode {
+    this.rejectSuccessCountTarget(left, token);
+
     // ? Chained `a vs b vs c` has no semantics — a degree is a scalar, not a
-    //   comparable. Parens (`a vs (b vs c)`) slip past this check and are
-    //   caught by the evaluator via `EvalEnv.insideVersus`.
-    if (left.type === 'Versus') {
+    //   comparable. Unwrap `Grouped` so `(a vs b) vs c` rejects at parse
+    //   time like the bare form; paren-nested DC (`a vs (b vs c)`) is still
+    //   caught by the evaluator via `mergeContext`.
+    let leftChain: ASTNode = left;
+    while (leftChain.type === 'Grouped') {
+      leftChain = leftChain.expression;
+    }
+    if (leftChain.type === 'Versus') {
       throw new ParseError('Cannot chain versus operators', 'NESTED_VERSUS', token.position, token);
     }
 
     const dc = this.parseExpression(BP.VS_RIGHT);
+    this.rejectSuccessCountTarget(dc, token);
 
-    return { type: 'Versus', roll: left, dc };
+    return {
+      type: 'Versus',
+      roll: left,
+      dc,
+      start: left.start ?? token.position,
+      end: dc.end ?? token.end,
+    };
   }
 
   // * Compare point utilities
@@ -536,6 +1034,13 @@ export class Parser {
    * Parses a comparison operator followed by a value expression.
    * Called by modifier parsers (explode, reroll, success counting).
    *
+   * The threshold value is parsed at `BP.DICE_LEFT`, which binds tighter than
+   * arithmetic. This keeps the comparison bound to the dice pool on the left
+   * rather than letting arithmetic to the right be consumed into the
+   * threshold. As a consequence, `1d6>=5+2` parses as `(1d6>=5)+2` with
+   * threshold `5` — not `7`. Computed thresholds require parens:
+   * `1d6>=(5+2)`. Same binding applies to `parseSuccessCount` below.
+   *
    * @returns A ComparePoint with the operator and value AST node
    * @throws {ParseError} If the next token is not a comparison operator
    */
@@ -546,6 +1051,8 @@ export class Parser {
     this.advance();
 
     const value = this.parseExpression(BP.DICE_LEFT);
+    this.rejectSuccessCountTarget(value, token);
+    this.rejectVersusTarget(value, token);
 
     return { operator, value };
   }
@@ -624,20 +1131,33 @@ export class Parser {
       case TokenType.EXPLODE_PENETRATING:
       case TokenType.REROLL:
       case TokenType.REROLL_ONCE:
+      case TokenType.SORT_ASC:
+      case TokenType.SORT_DESC:
+      case TokenType.CRIT_SUCCESS:
+      case TokenType.CRIT_FAIL:
+        return BP.MODIFIER;
       // Comparison operators act as LED-dispatched success-count modifiers
-      // at the Pratt level. Inside `parseComparePoint` (called manually by
-      // explode/reroll) they are consumed directly and this BP is bypassed.
+      // at the Pratt level. Sit below ADD/MUL so arithmetic on a dice pool
+      // completes before success counting wraps it — `5d6+2>4` parses as
+      // `(5d6+2)>4` and then cleanly fails the pool-target guard, rather
+      // than the `>` stealing `2` from the `+`. Inside `parseComparePoint`
+      // (called manually by explode/reroll) this BP is bypassed.
       case TokenType.GREATER:
       case TokenType.GREATER_EQUAL:
       case TokenType.LESS:
       case TokenType.LESS_EQUAL:
       case TokenType.EQUAL:
-        return BP.MODIFIER;
+        return BP.COMPARE;
       case TokenType.RPAREN:
       case TokenType.EOF:
       // Punctuation and keywords that terminate expressions
       case TokenType.COMMA:
       case TokenType.FUNCTION:
+      // Group boundaries: `}` closes the current group (consumed inside
+      // `parseGroup`), and a stray `{` after a complete expression is an
+      // error. Both terminate the outer Pratt loop at -1.
+      case TokenType.LBRACE:
+      case TokenType.RBRACE:
         return -1;
       default:
         return 0;
@@ -665,7 +1185,9 @@ export class Parser {
   }
 
   private peek(): Token {
-    return this.tokens[this.pos] ?? { type: TokenType.EOF, value: '', position: this.pos };
+    return (
+      this.tokens[this.pos] ?? { type: TokenType.EOF, value: '', position: this.pos, end: this.pos }
+    );
   }
 
   private advance(): Token {
@@ -677,9 +1199,10 @@ export class Parser {
   private expect(type: TokenType): Token {
     const token = this.peek();
     if (token.type !== type) {
-      const expected = TokenType[type];
+      const expected = TOKEN_DISPLAY[type] ?? TokenType[type];
+      const got = token.type === TokenType.EOF ? 'end of input' : `'${token.value}'`;
       throw new ParseError(
-        `Expected ${expected} but got '${token.value}'`,
+        `Expected ${expected} but got ${got}`,
         'EXPECTED_TOKEN',
         token.position,
         token,