roll-parser 3.0.0-beta.0 → 3.1.0

package/dist/parser/ast.d.ts

@@ -11,84 +11,173 @@ 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;
 };
 /**
@@ -99,12 +188,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;
 };
 /**
  * Versus node (`<roll> vs <dc>`) — PF2e Degrees of Success.
@@ -115,11 +206,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;
 };
 /**
  * Math function call node (`floor(expr)`, `max(a, b, ...)`, etc.).
@@ -128,11 +221,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[];
 };
 /**
  * Parenthesized group node (`(<expr>)`).
@@ -141,10 +239,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;
 };
 /**
  * Variable reference node (`@name` or `@{name with spaces}`).
@@ -154,10 +254,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;
 };
 /**
  * Grouped-roll node (`{expr}`, `{expr1, expr2, ...}`).
@@ -167,10 +272,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[];
 };
 /**
  * Sort modifier node (`s`, `sa`, `sd`).
@@ -180,189 +287,241 @@ 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 | DiceNode | FateDiceNode | BinaryOpNode | UnaryOpNode | ModifierNode | ExplodeNode | RerollNode | SuccessCountNode | VersusNode | FunctionCallNode | GroupedNode | VariableNode | GroupNode | SortNode | CritThresholdNode;
+export type ASTNode = LiteralNode | DiceNode | FateDiceNode | BinaryOpNode | UnaryOpNode | KeepDropNode | ExplodeNode | RerollNode | DieBoundNode | SuccessCountNode | VersusNode | FunctionCallNode | GroupedNode | VariableNode | GroupNode | SortNode | 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 declare function isLiteral(node: ASTNode): node is LiteralNode;
 /**
- * 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 declare function isDice(node: ASTNode): node is DiceNode;
 /**
- * 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 declare function isFateDice(node: ASTNode): node is FateDiceNode;
 /**
- * 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 declare function isBinaryOp(node: ASTNode): node is BinaryOpNode;
 /**
- * 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 declare function isUnaryOp(node: ASTNode): node is UnaryOpNode;
 /**
- * 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 declare function isModifier(node: ASTNode): node is ModifierNode;
+export declare function isKeepDrop(node: ASTNode): node is KeepDropNode;
 /**
- * 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 declare function isExplode(node: ASTNode): node is ExplodeNode;
 /**
- * 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 declare function isReroll(node: ASTNode): node is RerollNode;
 /**
- * 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 declare function isSuccessCount(node: ASTNode): node is SuccessCountNode;
 /**
- * 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 declare function isVersus(node: ASTNode): node is VersusNode;
 /**
- * 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 declare function isFunctionCall(node: ASTNode): node is FunctionCallNode;
 /**
- * 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 declare function isGrouped(node: ASTNode): node is GroupedNode;
 /**
- * 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 declare function isVariable(node: ASTNode): node is VariableNode;
 /**
- * Type guard for GroupNode.
- */
-export declare function isGroup(node: ASTNode): node is GroupNode;
-/**
- * Type guard for SortNode.
- */
-export declare function isSort(node: ASTNode): node is SortNode;
-/**
- * Type guard for CritThresholdNode.
- */
-export declare function isCritThreshold(node: ASTNode): node is CritThresholdNode;
-/**
- * Wrapper kinds that `unwrapTransparent` can peel.
+ * Narrows an {@link ASTNode} to a braced grouped roll (`{1d8, 1d10}`).
  *
- * "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.
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link GroupNode}
  *
- * 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`).
+ * @category AST
  */
-export declare function unwrapTransparent(node: ASTNode, kinds: readonly TransparentWrapperKind[]): ASTNode;
+export declare function isGroup(node: ASTNode): node is GroupNode;
 /**
- * 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.
+ * Narrows an {@link ASTNode} to a sort modifier (`s`, `sa`, `sd`).
  *
- * 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 declare function containsDicePool(node: ASTNode): boolean;
-/**
- * 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).
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link SortNode}
+ *
+ * @category AST
  */
-export declare function deepContainsDicePool(node: ASTNode): boolean;
+export declare function isSort(node: ASTNode): node is SortNode;
 /**
- * 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.
+ * Narrows an {@link ASTNode} to a crit-threshold override (`cs`, `cf`).
  *
- * 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.
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link CritThresholdNode}
  *
- * 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.
+ * @category AST
  */
-export declare function containsFatePool(node: ASTNode): boolean;
+export declare function isCritThreshold(node: ASTNode): node is CritThresholdNode;
 /**
- * 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.
+ * Narrows an {@link ASTNode} to a per-die clamp (`min2`, `max5`).
  *
- * Outside a `Group`, ordinary parenthesized arithmetic (`(4dF+1d6)cf`) is
- * already rejected upstream by shallow `containsDicePool`, so this helper
- * intentionally stays Group-internal.
- */
-export declare function deepContainsFatePool(node: ASTNode): boolean;
-/**
- * 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.
+ * @param node - Any AST node
+ * @returns `true` when `node` is a {@link DieBoundNode}
  *
- * 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 declare function containsMultiSubGroup(node: ASTNode): boolean;
-/**
- * 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.
+ * @category AST
  */
-export declare function containsVersus(node: ASTNode): boolean;
+export declare function isDieBound(node: ASTNode): node is DieBoundNode;
 //# sourceMappingURL=ast.d.ts.map