roll-parser 2.3.2 → 3.0.0-beta.0

package/src/evaluator/evaluator.ts

@@ -0,0 +1,1552 @@
+/**
+ * AST evaluator - transforms parsed AST into roll results.
+ *
+ * @module evaluator/evaluator
+ */
+
+import type { RollParserErrorCode } from '../errors.js';
+import { RollParserError } from '../errors.js';
+import type {
+  ASTNode,
+  BinaryOpNode,
+  CritThreshold,
+  CritThresholdNode,
+  DiceNode,
+  ExplodeNode,
+  FateDiceNode,
+  FunctionCallNode,
+  GroupedNode,
+  GroupNode,
+  LiteralNode,
+  ModifierNode,
+  RerollNode,
+  SortNode,
+  SuccessCountNode,
+  UnaryOpNode,
+  VariableNode,
+  VersusNode,
+} from '../parser/ast.js';
+import { isModifier } from '../parser/ast.js';
+import type { RNG } from '../rng/types.js';
+import type {
+  ComparePoint,
+  DieResult,
+  EvaluateOptions,
+  ResolvedComparePoint,
+  RollPart,
+  RollResult,
+} from '../types.js';
+import { DegreeOfSuccess } from '../types.js';
+import { applyCritThresholds, type ResolvedCritThreshold } from './modifiers/crit-threshold.js';
+import {
+  applyCompoundExplode,
+  applyPenetratingExplode,
+  applyStandardExplode,
+  buildShouldExplode,
+  DEFAULT_MAX_EXPLODE_ITERATIONS,
+} from './modifiers/explode.js';
+import {
+  applyDropHighest,
+  applyDropLowest,
+  applyKeepHighest,
+  applyKeepLowest,
+  markAllKept,
+  sumKeptDice,
+} from './modifiers/keep-drop.js';
+import {
+  applyRecursiveReroll,
+  applyRerollOnce,
+  DEFAULT_MAX_REROLL_ITERATIONS,
+} from './modifiers/reroll.js';
+import { sortDice } from './modifiers/sort.js';
+import { countSuccesses } from './modifiers/success-count.js';
+
+/**
+ * Error thrown during AST evaluation.
+ */
+export class EvaluatorError extends RollParserError {
+  readonly nodeType: string | undefined;
+  /**
+   * Source span of the tightest AST node that was being evaluated when the
+   * error was thrown — stamped by `evalNode` on the way up, so the innermost
+   * node wins. `undefined` when the AST was built without parser spans.
+   */
+  start: number | undefined;
+  end: number | undefined;
+
+  constructor(message: string, code: RollParserErrorCode, nodeType?: string) {
+    super(message, code);
+    this.name = 'EvaluatorError';
+    this.nodeType = nodeType ?? undefined;
+    this.start = undefined;
+    this.end = undefined;
+  }
+}
+
+/** Default maximum total dice allowed per evaluation. */
+export const DEFAULT_MAX_DICE = 10_000;
+
+export { DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS };
+
+/**
+ * Per-evaluation shared environment (created once, shared across all branches).
+ *
+ * Exported for use by modifier implementations under `./modifiers/*`. Not part
+ * of the public library API.
+ */
+export type EvalEnv = {
+  readonly maxDice: number;
+  readonly maxExplodeIterations: number;
+  readonly maxRerollIterations: number;
+  totalDiceRolled: number;
+  /**
+   * Set to `true` by `evalSuccessCount`. Propagates through the shared env
+   * so `evaluate()` can include `successes`/`failures` fields even when no
+   * die was tagged (impossible threshold).
+   */
+  hasSuccessCount: boolean;
+  /**
+   * `true` while the evaluator is inside a `VersusNode`'s roll or DC
+   * sub-evaluation. `evalVersus` rejects nesting via this flag — catches
+   * paren-nested versus (`1d20 vs (5 vs 3)`) that slip past the parser's
+   * left-chain check.
+   */
+  insideVersus: boolean;
+  /**
+   * User-supplied variable map for `@name` / `@{name}` references. Always
+   * defined — `evaluate()` defaults to an empty object so lookups can be
+   * branch-free on presence.
+   */
+  readonly context: Readonly<Record<string, number>>;
+  /**
+   * Behavior when a referenced variable is missing from `context`. Always
+   * defined — `evaluate()` defaults to `'throw'`.
+   */
+  readonly onMissingVariable: 'throw' | 'zero';
+};
+
+/**
+ * Per-branch mutable accumulator for tracking rolls and output during recursion.
+ *
+ * @internal exported for targeted `mergeMetaRolls` tests only; not a public API.
+ */
+export type EvalContext = {
+  rolls: DieResult[];
+  expressionParts: string[];
+  renderedParts: string[];
+  /**
+   * Populated by `evalVersus` with the resolved degree and natural value.
+   * `evaluate()` reads this from the top-level ctx to surface `degree` and
+   * `natural` on the final `RollResult`. Only populated when `vs` is the
+   * root of the expression.
+   */
+  versusMetadata?: {
+    degree: DegreeOfSuccess;
+    natural: number | undefined;
+    dcTotal: number;
+  };
+};
+
+/**
+ * Flattened representation of a keep/drop modifier for chain evaluation.
+ * Superset of the public `ModifierSpec` (adds the notation `code`).
+ */
+type ModifierSpec = {
+  modifier: 'keep' | 'drop';
+  selector: 'highest' | 'lowest';
+  count: number;
+  code: string;
+};
+
+/**
+ * Every branch returns its numeric total AND the `RollPart` it contributes
+ * to the structured breakdown — TypeScript exhaustiveness guarantees no
+ * branch can forget to produce a part.
+ */
+type EvalResult = {
+  total: number;
+  part: RollPart;
+};
+
+/**
+ * Copies an AST node's source span onto a part (spread into the literal).
+ * Empty when the AST was built without parser spans.
+ */
+function partSpan(node: ASTNode): { start?: number; end?: number } {
+  if (node.start === undefined || node.end === undefined) return {};
+  return { start: node.start, end: node.end };
+}
+
+/** Maps internal modifier specs to the public `RollPart` spec shape. */
+function toPublicSpecs(
+  specs: ModifierSpec[],
+): { kind: 'keep' | 'drop'; selector: 'highest' | 'lowest'; count: number }[] {
+  return specs.map((spec) => ({ kind: spec.modifier, selector: spec.selector, count: spec.count }));
+}
+
+/**
+ * Creates a new die result with critical/fumble detection.
+ */
+function createDieResult(sides: number, result: number): DieResult {
+  // ? `sides > 1` guards both flags — a d1 always rolls 1, so it is neither
+  //   an exceptional max (critical) nor an exceptional min (fumble).
+  return {
+    sides,
+    result,
+    modifiers: [],
+    critical: result === sides && sides > 1,
+    fumble: result === 1 && sides > 1,
+  };
+}
+
+/**
+ * Creates a Fate/Fudge die result. Uses `sides = 0` as a sentinel — Fate dice
+ * have no max-face concept, so `critical` and `fumble` are always `false`.
+ */
+function createFateDieResult(result: number): DieResult {
+  return {
+    sides: 0,
+    result,
+    modifiers: [],
+    critical: false,
+    fumble: false,
+  };
+}
+
+/**
+ * Renders dice results for display. Marker priority: dropped wins over
+ * success/failure (dropped dice are never counted), success wins over
+ * failure (a die cannot be both). Example: `[~~1~~, **6**, __1__, 3]`.
+ *
+ * Dice tagged `'meta'` (rolled to compute sub-expression parameters such as
+ * count/sides/threshold) are hidden from the rendered output — they exist in
+ * `RollResult.rolls` for audit, not for display.
+ */
+function renderDice(dice: DieResult[]): string {
+  const parts = dice
+    .filter((die) => !die.modifiers.includes('meta'))
+    .map((die) => {
+      if (die.modifiers.includes('dropped')) {
+        return `~~${die.result}~~`;
+      }
+      if (die.modifiers.includes('success')) {
+        return `**${die.result}**`;
+      }
+      if (die.modifiers.includes('failure')) {
+        return `__${die.result}__`;
+      }
+      return String(die.result);
+    });
+  return `[${parts.join(', ')}]`;
+}
+
+/**
+ * Forwards rolls from a throwaway sub-expression context into the parent
+ * audit trail, tagging them as `'meta'` + `'dropped'`. Meta dice are dice
+ * rolled to compute parameters (dice count, sides, threshold, modifier
+ * count) — they consume RNG and count against `maxDice`, so they must be
+ * inspectable. Tagging them `'dropped'` keeps totals correct via
+ * `sumKeptDice`; `'meta'` lets renderers hide them and lets callers
+ * distinguish them from ordinary pool dice.
+ *
+ * `'success'`/`'failure'` tags are stripped here as defense-in-depth against
+ * a SuccessCount leaking into a meta sub-expression (parser rejects all such
+ * wrappings; this strip ensures a future parse regression cannot leak tags
+ * into the top-level `successes`/`failures` scan).
+ */
+/** @internal exported for targeted defense-in-depth tests only. */
+export function mergeMetaRolls(parent: EvalContext, source: EvalContext): void {
+  for (const die of source.rolls) {
+    parent.rolls.push({
+      ...die,
+      modifiers: [
+        ...die.modifiers.filter(
+          (m) => m !== 'kept' && m !== 'dropped' && m !== 'success' && m !== 'failure',
+        ),
+        'meta',
+        'dropped',
+      ],
+    });
+  }
+}
+
+/**
+ * Evaluates an AST node, returning its total and `RollPart` while updating
+ * the context.
+ *
+ * Errors bubbling up get the source span of the tightest node that was being
+ * evaluated — the innermost `evalNode` frame stamps first, outer frames leave
+ * an already-stamped error untouched.
+ */
+function evalNode(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  try {
+    return evalNodeInner(node, rng, ctx, env);
+  } catch (error) {
+    if (error instanceof EvaluatorError && error.start === undefined && node.start !== undefined) {
+      error.start = node.start;
+      error.end = node.end;
+    }
+    throw error;
+  }
+}
+
+function evalNodeInner(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  switch (node.type) {
+    case 'Literal':
+      return evalLiteral(node, ctx);
+
+    case 'Dice':
+      return evalDice(node, rng, ctx, env);
+
+    case 'FateDice':
+      return evalFateDice(node, rng, ctx, env);
+
+    case 'BinaryOp':
+      return evalBinaryOp(node, rng, ctx, env);
+
+    case 'UnaryOp':
+      return evalUnaryOp(node, rng, ctx, env);
+
+    case 'Modifier':
+      return evalModifier(node, rng, ctx, env);
+
+    case 'Explode':
+      return evalExplode(node, rng, ctx, env);
+
+    case 'Reroll':
+      return evalReroll(node, rng, ctx, env);
+
+    case 'SuccessCount':
+      return evalSuccessCount(node, rng, ctx, env);
+
+    case 'Versus':
+      return evalVersus(node, rng, ctx, env);
+
+    case 'FunctionCall':
+      return evalFunctionCall(node, rng, ctx, env);
+
+    case 'Grouped':
+      return evalGrouped(node, rng, ctx, env);
+
+    case 'Group':
+      return evalGroup(node, rng, ctx, env);
+
+    case 'Sort':
+      return evalSort(node, rng, ctx, env);
+
+    case 'CritThreshold':
+      return evalCritThreshold(node, rng, ctx, env);
+
+    case 'Variable':
+      return evalVariable(node, ctx, env);
+
+    default: {
+      const exhaustive: never = node;
+      throw new EvaluatorError(
+        `Unknown node type: ${(exhaustive as ASTNode).type}`,
+        'UNKNOWN_NODE_TYPE',
+        (exhaustive as ASTNode).type,
+      );
+    }
+  }
+}
+
+function evalLiteral(node: LiteralNode, ctx: EvalContext): EvalResult {
+  const { value } = node;
+  ctx.expressionParts.push(String(value));
+  ctx.renderedParts.push(String(value));
+  return { total: value, part: { type: 'literal', value, total: value, ...partSpan(node) } };
+}
+
+/**
+ * Re-derives whether a variable name needs braces in its rendered form.
+ *
+ * The lexer accepts `@name` (bare) or `@{name with spaces}` (braced) but
+ * strips the braces from the captured value. To round-trip through `rendered`
+ * we re-derive bracedness from the name shape — anything outside the bare
+ * identifier grammar implies the user wrote braces (or would need them).
+ */
+function variableNeedsBraces(name: string): boolean {
+  return !/^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+
+/**
+ * Looks up a variable in `env.context` and resolves missing keys per
+ * `env.onMissingVariable`. The resolved scalar is the variable's value;
+ * `expression` shows the resolved number (mirrors how literals render),
+ * while `rendered` keeps the original `@name` (or `@{name}`) annotated with
+ * the resolved value in brackets so readers can attribute the number.
+ */
+function evalVariable(node: VariableNode, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const present = Object.hasOwn(env.context, node.name);
+  if (!present) {
+    if (env.onMissingVariable === 'throw') {
+      throw new EvaluatorError(
+        `Undefined variable: ${node.name}`,
+        'UNDEFINED_VARIABLE',
+        'Variable',
+      );
+    }
+    const display = variableNeedsBraces(node.name) ? `@{${node.name}}` : `@${node.name}`;
+    ctx.expressionParts.push('0');
+    ctx.renderedParts.push(`${display}[0]`);
+    return {
+      total: 0,
+      part: { type: 'variable', name: node.name, value: 0, total: 0, ...partSpan(node) },
+    };
+  }
+
+  const value = env.context[node.name] as number;
+  if (!Number.isFinite(value)) {
+    throw new EvaluatorError(
+      `Invalid variable value: ${node.name} = ${value}`,
+      'INVALID_VARIABLE_VALUE',
+      'Variable',
+    );
+  }
+  const display = variableNeedsBraces(node.name) ? `@{${node.name}}` : `@${node.name}`;
+  ctx.expressionParts.push(String(value));
+  ctx.renderedParts.push(`${display}[${value}]`);
+  return {
+    total: value,
+    part: { type: 'variable', name: node.name, value, total: value, ...partSpan(node) },
+  };
+}
+
+/**
+ * RNG draw order: `count` expression → `sides` expression → pool dice
+ * (one `nextInt` per die, left-to-right). Meta-expressions on `count`/`sides`
+ * (e.g. `(1+1)d(3*2)`) draw before the pool. For modifier-argument
+ * meta-expressions like `4d6kh(1d2)`, `flattenModifierChain` draws the
+ * modifier args first, then `evalModifier` calls `evalDice` for the base
+ * pool. See `.claude/rules/rng.md` for the full draw-order spec.
+ */
+function evalDice(node: DiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const countCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const count = evalNode(node.count, rng, countCtx, env).total;
+  mergeMetaRolls(ctx, countCtx);
+
+  const sidesCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const sides = evalNode(node.sides, rng, sidesCtx, env).total;
+  mergeMetaRolls(ctx, sidesCtx);
+
+  if (!Number.isInteger(count) || count < 0) {
+    throw new EvaluatorError(`Invalid dice count: ${count}`, 'INVALID_DICE_COUNT', 'Dice');
+  }
+  if (!Number.isInteger(sides) || sides < 1) {
+    throw new EvaluatorError(`Invalid dice sides: ${sides}`, 'INVALID_DICE_SIDES', 'Dice');
+  }
+
+  if (env.totalDiceRolled + count > env.maxDice) {
+    throw new EvaluatorError(
+      `Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`,
+      'DICE_LIMIT_EXCEEDED',
+      'Dice',
+    );
+  }
+  env.totalDiceRolled += count;
+
+  const dice: DieResult[] = [];
+  for (let i = 0; i < count; i++) {
+    const result = rng.nextInt(1, sides);
+    dice.push(createDieResult(sides, result));
+  }
+
+  const markedDice = markAllKept(dice);
+  ctx.rolls.push(...markedDice);
+
+  const total = sumKeptDice(markedDice);
+  const notation = `${count}d${sides}`;
+
+  ctx.expressionParts.push(notation);
+  ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
+
+  return {
+    total,
+    part: { type: 'dice', count, sides, rolls: markedDice, total, ...partSpan(node) },
+  };
+}
+
+function evalFateDice(node: FateDiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const countCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const count = evalNode(node.count, rng, countCtx, env).total;
+  mergeMetaRolls(ctx, countCtx);
+
+  if (!Number.isInteger(count) || count < 0) {
+    throw new EvaluatorError(`Invalid dice count: ${count}`, 'INVALID_DICE_COUNT', 'FateDice');
+  }
+
+  if (env.totalDiceRolled + count > env.maxDice) {
+    throw new EvaluatorError(
+      `Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`,
+      'DICE_LIMIT_EXCEEDED',
+      'FateDice',
+    );
+  }
+  env.totalDiceRolled += count;
+
+  const dice: DieResult[] = [];
+  for (let i = 0; i < count; i++) {
+    const result = rng.nextInt(-1, 1);
+    dice.push(createFateDieResult(result));
+  }
+
+  const markedDice = markAllKept(dice);
+  ctx.rolls.push(...markedDice);
+
+  const total = sumKeptDice(markedDice);
+  const notation = `${count}dF`;
+
+  ctx.expressionParts.push(notation);
+  ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
+
+  return {
+    total,
+    part: { type: 'fateDice', count, rolls: markedDice, total, ...partSpan(node) },
+  };
+}
+
+/**
+ * Propagates `versusMetadata` onto a parent so `degree`/`natural` survive
+ * wrappers like `floor(...)`, `(vs) + 0`, or `-(vs)`. Throws `NESTED_VERSUS`
+ * if the parent already carries metadata — two versus results cannot occupy
+ * the same `RollResult`. No-op when `metadata` is `undefined`.
+ *
+ * Use this directly when the caller has already pushed (or transformed) `rolls`
+ * itself — e.g. `evalSort`, `evalCritThreshold`, `evalGroupModifier`. For the
+ * default case where the child's raw rolls flow up unchanged, use
+ * `mergeContext` instead.
+ */
+function propagateMetadata(parent: EvalContext, metadata: EvalContext['versusMetadata']): void {
+  if (!metadata) return;
+  if (parent.versusMetadata) {
+    throw new EvaluatorError(
+      'Multiple versus operators in the same expression',
+      'NESTED_VERSUS',
+      'Versus',
+    );
+  }
+  parent.versusMetadata = metadata;
+}
+
+/**
+ * Merges a child sub-context back into its parent. Copies `rolls` and
+ * delegates `versusMetadata` propagation to `propagateMetadata`.
+ *
+ * Does not merge `expressionParts` / `renderedParts` — each wrapper formats
+ * those with its own operator/function syntax.
+ */
+function mergeContext(parent: EvalContext, child: EvalContext): void {
+  parent.rolls.push(...child.rolls);
+  propagateMetadata(parent, child.versusMetadata);
+}
+
+function evalBinaryOp(node: BinaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const leftCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const rightCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+
+  const left = evalNode(node.left, rng, leftCtx, env);
+  const right = evalNode(node.right, rng, rightCtx, env);
+
+  mergeContext(ctx, leftCtx);
+  mergeContext(ctx, rightCtx);
+
+  const leftExpr = leftCtx.expressionParts.join('');
+  const rightExpr = rightCtx.expressionParts.join('');
+  const leftRendered = leftCtx.renderedParts.join('');
+  const rightRendered = rightCtx.renderedParts.join('');
+
+  ctx.expressionParts.push(`${leftExpr} ${node.operator} ${rightExpr}`);
+  ctx.renderedParts.push(`${leftRendered} ${node.operator} ${rightRendered}`);
+
+  const total = applyBinaryOperator(node.operator, left.total, right.total);
+
+  return {
+    total,
+    part: {
+      type: 'binaryOp',
+      operator: node.operator,
+      left: left.part,
+      right: right.part,
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+function applyBinaryOperator(
+  operator: BinaryOpNode['operator'],
+  left: number,
+  right: number,
+): number {
+  switch (operator) {
+    case '+':
+      return left + right;
+    case '-':
+      return left - right;
+    case '*':
+      return left * right;
+    case '/':
+      if (right === 0) {
+        throw new EvaluatorError('Division by zero', 'DIVISION_BY_ZERO', 'BinaryOp');
+      }
+      return left / right;
+    case '%':
+      if (right === 0) {
+        throw new EvaluatorError('Modulo by zero', 'MODULO_BY_ZERO', 'BinaryOp');
+      }
+      return left % right;
+    case '**':
+      return left ** right;
+    default: {
+      const exhaustive: never = operator;
+      throw new EvaluatorError(`Unknown operator: ${exhaustive}`, 'UNKNOWN_OPERATOR', 'BinaryOp');
+    }
+  }
+}
+
+function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const innerCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const inner = evalNode(node.operand, rng, innerCtx, env);
+
+  mergeContext(ctx, innerCtx);
+
+  const innerExpr = innerCtx.expressionParts.join('');
+  const innerRendered = innerCtx.renderedParts.join('');
+
+  ctx.expressionParts.push(`-${innerExpr}`);
+  ctx.renderedParts.push(`-${innerRendered}`);
+
+  const total = -inner.total;
+
+  return {
+    total,
+    part: { type: 'unaryOp', operator: '-', operand: inner.part, total, ...partSpan(node) },
+  };
+}
+
+function evalGrouped(node: GroupedNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const innerCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const inner = evalNode(node.expression, rng, innerCtx, env);
+
+  mergeContext(ctx, innerCtx);
+
+  ctx.expressionParts.push(`(${innerCtx.expressionParts.join('')})`);
+  ctx.renderedParts.push(`(${innerCtx.renderedParts.join('')})`);
+
+  return {
+    total: inner.total,
+    part: { type: 'grouped', inner: inner.part, total: inner.total, ...partSpan(node) },
+  };
+}
+
+/**
+ * Evaluates a grouped roll `{expr1, expr2, ...}`.
+ *
+ * Each sub-expression is evaluated in an isolated context, then its rolls
+ * and `versusMetadata` propagate up via `mergeContext`. Sub-roll subtotals
+ * sum to the group's total. When the group is the base target of a
+ * keep/drop modifier with `expressions.length >= 2`, `evalModifier`
+ * intercepts first and never calls this function — dual semantics
+ * (flat-pool vs sub-roll) are decided there.
+ */
+function evalGroup(node: GroupNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const subExprs: string[] = [];
+  const subRendered: string[] = [];
+  const subParts: RollPart[] = [];
+  let total = 0;
+
+  for (const expr of node.expressions) {
+    const subCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const sub = evalNode(expr, rng, subCtx, env);
+    mergeContext(ctx, subCtx);
+    subExprs.push(subCtx.expressionParts.join(''));
+    subRendered.push(subCtx.renderedParts.join(''));
+    subParts.push(sub.part);
+    total += sub.total;
+  }
+
+  ctx.expressionParts.push(`{${subExprs.join(', ')}}`);
+  ctx.renderedParts.push(`{${subRendered.join(', ')}}`);
+
+  // ? No `keptIndices` — bare groups (and single-sub passthroughs) perform
+  //   no sub-roll selection; only `evalGroupModifier` sets it.
+  return { total, part: { type: 'group', parts: subParts, total, ...partSpan(node) } };
+}
+
+function evalFunctionCall(
+  node: FunctionCallNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): EvalResult {
+  const argCtxs: EvalContext[] = [];
+  const argResults: EvalResult[] = [];
+
+  for (const arg of node.args) {
+    const argCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    argResults.push(evalNode(arg, rng, argCtx, env));
+    argCtxs.push(argCtx);
+  }
+
+  for (const argCtx of argCtxs) {
+    mergeContext(ctx, argCtx);
+  }
+
+  const argExprs = argCtxs.map((c) => c.expressionParts.join(''));
+  const argRendereds = argCtxs.map((c) => c.renderedParts.join(''));
+
+  ctx.expressionParts.push(`${node.name}(${argExprs.join(', ')})`);
+  ctx.renderedParts.push(`${node.name}(${argRendereds.join(', ')})`);
+
+  const total = applyFunction(
+    node.name,
+    argResults.map((r) => r.total),
+  );
+
+  return {
+    total,
+    part: {
+      type: 'functionCall',
+      name: node.name,
+      args: argResults.map((r) => r.part),
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+function applyFunction(name: string, values: number[]): number {
+  switch (name) {
+    case 'floor':
+      return Math.floor(requireUnaryArg(name, values));
+    case 'ceil':
+      return Math.ceil(requireUnaryArg(name, values));
+    case 'round':
+      // ? Delegates to `Math.round`, which rounds half-values toward +∞
+      //   (IEEE-754 half-up). So `round(2.5) === 3` but `round(-2.5) === -2`,
+      //   not `-3`. Users needing symmetric rounding must compose via `floor`.
+      return Math.round(requireUnaryArg(name, values));
+    case 'abs':
+      return Math.abs(requireUnaryArg(name, values));
+    case 'max':
+      return Math.max(...values);
+    case 'min':
+      return Math.min(...values);
+    default:
+      throw new EvaluatorError(`Unknown function: ${name}`, 'UNKNOWN_FUNCTION', 'FunctionCall');
+  }
+}
+
+function requireUnaryArg(name: string, values: number[]): number {
+  const [x] = values;
+  if (x === undefined) {
+    // ? Unreachable: parser validates arity before evaluation. Defensive for
+    // `noNonNullAssertion`.
+    throw new EvaluatorError(
+      `Function '${name}' requires an argument`,
+      'UNKNOWN_FUNCTION',
+      'FunctionCall',
+    );
+  }
+  return x;
+}
+
+/**
+ * Walks a nested ModifierNode chain, collecting specs outermost-first,
+ * then reverses to notation order (innermost-first).
+ */
+function flattenModifierChain(
+  node: ModifierNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): { specs: ModifierSpec[]; baseTarget: ASTNode } {
+  const specs: ModifierSpec[] = [];
+  let current: ASTNode = node;
+
+  while (isModifier(current)) {
+    const countCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const modCount = evalNode(current.count, rng, countCtx, env).total;
+    mergeMetaRolls(ctx, countCtx);
+
+    if (!Number.isInteger(modCount) || modCount < 0) {
+      throw new EvaluatorError(
+        `Invalid modifier count: ${modCount}`,
+        'INVALID_MODIFIER_COUNT',
+        'Modifier',
+      );
+    }
+
+    const code =
+      current.modifier === 'keep'
+        ? current.selector === 'highest'
+          ? 'kh'
+          : 'kl'
+        : current.selector === 'highest'
+          ? 'dh'
+          : 'dl';
+
+    specs.push({ modifier: current.modifier, selector: current.selector, count: modCount, code });
+    current = current.target;
+  }
+
+  specs.reverse();
+  return { specs, baseTarget: current };
+}
+
+/**
+ * Applies a single modifier spec to a dice pool.
+ */
+function applyModifierSpec(dice: DieResult[], spec: ModifierSpec): DieResult[] {
+  if (spec.modifier === 'keep') {
+    return spec.selector === 'highest'
+      ? applyKeepHighest(dice, spec.count)
+      : applyKeepLowest(dice, spec.count);
+  }
+  return spec.selector === 'highest'
+    ? applyDropHighest(dice, spec.count)
+    : applyDropLowest(dice, spec.count);
+}
+
+/**
+ * Applies each modifier independently to the full dice pool
+ * and merges drop sets via union. A die is dropped if ANY modifier dropped it.
+ *
+ * Mutates each die's flags in place — the same `DieResult` objects are
+ * shared between `RollResult.rolls` and the `RollPart` tree. The per-spec
+ * appliers still work on copies internally (each spec must see the
+ * unmodified pool), only the merged outcome is written back.
+ */
+function mergeDropSets(baseDice: DieResult[], specs: ModifierSpec[]): DieResult[] {
+  const droppedIndices = new Set<number>();
+
+  for (const spec of specs) {
+    const result = applyModifierSpec(baseDice, spec);
+    for (let i = 0; i < result.length; i++) {
+      if (result[i]?.modifiers.includes('dropped')) {
+        droppedIndices.add(i);
+      }
+    }
+  }
+
+  baseDice.forEach((die, index) => {
+    die.modifiers = droppedIndices.has(index)
+      ? [...die.modifiers.filter((m) => m !== 'kept' && m !== 'dropped'), 'dropped']
+      : [...die.modifiers.filter((m) => m !== 'dropped' && m !== 'kept'), 'kept'];
+  });
+
+  return baseDice;
+}
+
+/**
+ * Builds the notation string for an explode modifier, e.g. `!`, `!!>=3`, `!p>5`.
+ */
+function formatExplodeCode(
+  variant: ExplodeNode['variant'],
+  threshold: ComparePoint | undefined,
+  thresholdValue: number | undefined,
+): string {
+  const marker = variant === 'standard' ? '!' : variant === 'compound' ? '!!' : '!p';
+  if (threshold == null || thresholdValue == null) return marker;
+  return `${marker}${threshold.operator}${thresholdValue}`;
+}
+
+function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+  const targetExpr = targetCtx.expressionParts.join('');
+
+  let thresholdValue: number | undefined;
+  if (node.threshold != null) {
+    const thresholdCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    thresholdValue = evalNode(node.threshold.value, rng, thresholdCtx, env).total;
+    mergeMetaRolls(ctx, thresholdCtx);
+  }
+
+  const code = formatExplodeCode(node.variant, node.threshold, thresholdValue);
+
+  const buildPart = (total: number): RollPart => {
+    const part: RollPart = {
+      type: 'explode',
+      variant: node.variant,
+      target: target.part,
+      total,
+      ...partSpan(node),
+    };
+    if (node.threshold != null && thresholdValue !== undefined) {
+      part.threshold = { operator: node.threshold.operator, value: thresholdValue };
+    }
+    return part;
+  };
+
+  // No-op when the target produced no dice (e.g., `(1+2)!`).
+  if (targetCtx.rolls.length === 0) {
+    ctx.expressionParts.push(`${targetExpr}${code}`);
+    ctx.renderedParts.push(`${targetExpr}${code}`);
+    return { total: target.total, part: buildPart(target.total) };
+  }
+
+  const shouldExplode = buildShouldExplode(node.threshold?.operator, thresholdValue);
+
+  const expanded =
+    node.variant === 'standard'
+      ? applyStandardExplode(targetCtx.rolls, shouldExplode, rng, env)
+      : node.variant === 'compound'
+        ? applyCompoundExplode(targetCtx.rolls, shouldExplode, rng, env)
+        : applyPenetratingExplode(targetCtx.rolls, shouldExplode, rng, env);
+
+  ctx.rolls.push(...expanded);
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  // ? Include the explode code in rendered output so readers can attribute
+  //   the extra dice. Modifier rendering (kh/dl) skips its code because
+  //   dropped dice are visible; explosion-origin is otherwise invisible.
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(expanded)}`);
+
+  const total = sumKeptDice(expanded);
+  return { total, part: buildPart(total) };
+}
+
+function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+  const targetExpr = targetCtx.expressionParts.join('');
+
+  const thresholdCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const thresholdValue = evalNode(node.condition.value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
+
+  const code = `${node.once ? 'ro' : 'r'}${node.condition.operator}${thresholdValue}`;
+  const condition: ResolvedComparePoint = {
+    operator: node.condition.operator,
+    value: thresholdValue,
+  };
+
+  // No-op when the target produced no dice (e.g., `(1+2)r<5`).
+  if (targetCtx.rolls.length === 0) {
+    ctx.expressionParts.push(`${targetExpr}${code}`);
+    ctx.renderedParts.push(`${targetExpr}${code}`);
+    const total = sumKeptDice(targetCtx.rolls);
+    return {
+      total,
+      part: {
+        type: 'reroll',
+        once: node.once,
+        condition,
+        target: target.part,
+        total,
+        ...partSpan(node),
+      },
+    };
+  }
+
+  const pool = node.once
+    ? applyRerollOnce(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env)
+    : applyRecursiveReroll(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env);
+
+  ctx.rolls.push(...pool);
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(pool)}`);
+
+  const total = sumKeptDice(pool);
+  return {
+    total,
+    part: {
+      type: 'reroll',
+      once: node.once,
+      condition,
+      target: target.part,
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+/**
+ * Evaluates a sort modifier. Purely visual — sorts the dice produced by
+ * `node.target` in ascending or descending order of `result` without
+ * changing the total or any die-level flag. Dropped dice participate in
+ * the sort alongside kept dice, preserving their `'dropped'` marker.
+ *
+ * Rendering mirrors `evalExplode` / `evalModifier`: emits
+ * `<targetExpr><code>[<sortedDice>]`, replacing any inline dice brackets
+ * the target itself rendered. Multi-sub-roll Group targets (`{4d6, 3d6}s`)
+ * are rejected at parse time with `INVALID_SORT_TARGET` until hierarchical
+ * per-sub-roll sorting (Stage 3 spec §3 "Group interaction") is implemented.
+ */
+function evalSort(node: SortNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+
+  const sortedRolls = sortDice(targetCtx.rolls, node.order);
+
+  ctx.rolls.push(...sortedRolls);
+  propagateMetadata(ctx, targetCtx.versusMetadata);
+
+  const code = node.order === 'ascending' ? 's' : 'sd';
+  const targetExpr = targetCtx.expressionParts.join('');
+
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(sortedRolls)}`);
+
+  return {
+    total: target.total,
+    part: {
+      type: 'sort',
+      order: node.order,
+      target: target.part,
+      total: target.total,
+      ...partSpan(node),
+    },
+  };
+}
+
+/**
+ * Evaluates a critical/fumble threshold modifier. Pure post-processing:
+ * evaluates the target in an isolated context, resolves each threshold's
+ * ComparePoint value (including meta-expressions, which consume RNG draws
+ * AFTER the target pool), then overrides `critical`/`fumble` flags on the
+ * produced dice in place.
+ *
+ * Independent overrides (Roll20 semantics): `cs` thresholds replace only the
+ * crit criteria and `cf` thresholds replace only the fumble criteria. When a
+ * side has no explicit threshold, the `'default'` rule applies — so
+ * `1d20cf<3` keeps the default nat-20 crit. Bare `cs`/`cf` uses the
+ * `'default'` sentinel resolved per-die to `result === sides` or
+ * `result === 1`.
+ *
+ * Renders `<targetExpr><codes>[<dice>]`, mirroring `evalSort`/`evalExplode`.
+ */
+function evalCritThreshold(
+  node: CritThresholdNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): EvalResult {
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+
+  const successResolved = node.successThresholds.map((t) => resolveCritThreshold(t, rng, ctx, env));
+  const failResolved = node.failThresholds.map((t) => resolveCritThreshold(t, rng, ctx, env));
+
+  // Independent overrides: a side with no explicit threshold falls back to
+  // the default rule instead of being wiped by the other side's override.
+  const successApplied: ResolvedCritThreshold[] =
+    successResolved.length > 0 ? successResolved : ['default'];
+  const failApplied: ResolvedCritThreshold[] = failResolved.length > 0 ? failResolved : ['default'];
+
+  applyCritThresholds(targetCtx.rolls, successApplied, failApplied);
+
+  ctx.rolls.push(...targetCtx.rolls);
+  propagateMetadata(ctx, targetCtx.versusMetadata);
+
+  const targetExpr = targetCtx.expressionParts.join('');
+  const codes = [
+    ...successResolved.map((t) => (t === 'default' ? 'cs' : `cs${t.operator}${t.value}`)),
+    ...failResolved.map((t) => (t === 'default' ? 'cf' : `cf${t.operator}${t.value}`)),
+  ].join('');
+
+  ctx.expressionParts.push(`${targetExpr}${codes}`);
+  ctx.renderedParts.push(`${targetExpr}${codes}${renderDice(targetCtx.rolls)}`);
+
+  return {
+    total: target.total,
+    part: {
+      type: 'critThreshold',
+      successThresholds: successResolved,
+      failThresholds: failResolved,
+      target: target.part,
+      total: target.total,
+      ...partSpan(node),
+    },
+  };
+}
+
+function resolveCritThreshold(
+  threshold: CritThreshold,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): ResolvedCritThreshold {
+  if (threshold === 'default') return 'default';
+  const thresholdCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const resolved = evalNode(threshold.value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
+  if (!Number.isFinite(resolved)) {
+    throw new EvaluatorError(
+      `Invalid crit threshold: ${resolved}`,
+      'INVALID_THRESHOLD',
+      'CritThreshold',
+    );
+  }
+  return { operator: threshold.operator, value: resolved };
+}
+
+function evalModifier(node: ModifierNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const { specs, baseTarget } = flattenModifierChain(node, rng, ctx, env);
+
+  // Multi-sub-roll group: keep/drop operates on sub-roll subtotals as if
+  // each subtotal were a compound die. Single-sub-roll groups fall through
+  // to the flat-pool path below — `evalGroup` evaluates the inner expression
+  // into `targetCtx.rolls`, and `mergeDropSets` selects individual dice.
+  if (baseTarget.type === 'Group' && baseTarget.expressions.length >= 2) {
+    return evalGroupModifier(node, baseTarget, specs, rng, ctx, env);
+  }
+
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(baseTarget, rng, targetCtx, env);
+
+  const mergedDice = mergeDropSets(targetCtx.rolls, specs);
+
+  ctx.rolls.push(...mergedDice);
+
+  const total = sumKeptDice(mergedDice);
+
+  const targetExpr = targetCtx.expressionParts.join('');
+  const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join('');
+
+  ctx.expressionParts.push(`${targetExpr}${modifierCodes}`);
+  ctx.renderedParts.push(`${targetExpr}${renderDice(mergedDice)}`);
+
+  return {
+    total,
+    part: {
+      type: 'modifier',
+      specs: toPublicSpecs(specs),
+      target: target.part,
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+/**
+ * Strips per-die markdown markers from an already-rendered sub-roll string.
+ * Used when a whole group sub-roll is dropped: the outer `~~...~~` wrap
+ * supersedes inner success (`**`), failure (`__`), and dropped (`~~`)
+ * markers, and leaving them in place would nest strikethroughs or show
+ * success highlights inside a dropped span.
+ */
+function stripInnerMarkers(rendered: string): string {
+  return rendered
+    .replace(/\*\*(-?\d+)\*\*/g, '$1')
+    .replace(/__(-?\d+)__/g, '$1')
+    .replace(/~~(-?\d+)~~/g, '$1');
+}
+
+/**
+ * Evaluates a keep/drop modifier chain whose base target is a multi
+ * sub-roll group. Each sub-roll is evaluated in isolation so its subtotal
+ * and dice are captured separately. Synthetic dice — one per sub-roll,
+ * `result = subtotal` — feed `mergeDropSets` to pick kept/dropped indices.
+ * Dropped sub-rolls' inner dice are re-flagged `'dropped'` so `sumKeptDice`
+ * on the propagated rolls still agrees with the group total, and the
+ * rendered form wraps them in strikethrough `~~...~~`.
+ */
+function evalGroupModifier(
+  node: ModifierNode,
+  group: GroupNode,
+  specs: ModifierSpec[],
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): EvalResult {
+  type SubRoll = {
+    subtotal: number;
+    part: RollPart;
+    rolls: DieResult[];
+    expr: string;
+    rendered: string;
+    versusMetadata: EvalContext['versusMetadata'];
+  };
+
+  const subRolls: SubRoll[] = group.expressions.map((expr) => {
+    const subCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const sub = evalNode(expr, rng, subCtx, env);
+    return {
+      subtotal: sub.total,
+      part: sub.part,
+      rolls: subCtx.rolls,
+      expr: subCtx.expressionParts.join(''),
+      rendered: subCtx.renderedParts.join(''),
+      versusMetadata: subCtx.versusMetadata,
+    };
+  });
+
+  // ? Synthetic dice carry `sides = 0` as a sentinel — they're never
+  //   surfaced in `ctx.rolls`, only used as input to `mergeDropSets`. Any
+  //   `critical`/`fumble` flags would be meaningless for a subtotal.
+  const syntheticDice: DieResult[] = subRolls.map((sub) => ({
+    sides: 0,
+    result: sub.subtotal,
+    modifiers: [],
+    critical: false,
+    fumble: false,
+  }));
+
+  const mergedSynthetic = mergeDropSets(syntheticDice, specs);
+
+  const outerRendered: string[] = [];
+  const keptIndices: number[] = [];
+  let total = 0;
+
+  for (let i = 0; i < subRolls.length; i++) {
+    const sub = subRolls[i] as SubRoll;
+    const synth = mergedSynthetic[i] as DieResult;
+    const isDropped = synth.modifiers.includes('dropped');
+
+    if (isDropped) {
+      // Flag every inner die dropped so propagated rolls match the total.
+      // Keep existing `'kept'` stripped — the sub-roll didn't contribute,
+      // so its die-level kept annotation no longer applies. `'success'` /
+      // `'failure'` are stripped too: the top-level successes/failures scan
+      // must not count dice from a sub-roll that was dropped. Mutated in
+      // place — the same objects live in the sub-roll's RollPart.
+      for (const die of sub.rolls) {
+        die.modifiers = [
+          ...die.modifiers.filter(
+            (m) => m !== 'kept' && m !== 'dropped' && m !== 'success' && m !== 'failure',
+          ),
+          'dropped',
+        ];
+      }
+      ctx.rolls.push(...sub.rolls);
+      outerRendered.push(`~~${stripInnerMarkers(sub.rendered)}~~`);
+    } else {
+      keptIndices.push(i);
+      ctx.rolls.push(...sub.rolls);
+      outerRendered.push(sub.rendered);
+      total += sub.subtotal;
+    }
+
+    // Propagate Versus metadata only from kept sub-rolls — `RollResult.degree`
+    // must reflect dice that contributed to `RollResult.total`. Two kept
+    // versus sub-rolls still collide here via the `NESTED_VERSUS` guard
+    // inside `propagateMetadata`.
+    if (!isDropped) {
+      propagateMetadata(ctx, sub.versusMetadata);
+    }
+  }
+
+  const subExprStrs = subRolls.map((s) => s.expr);
+  const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join('');
+
+  ctx.expressionParts.push(`{${subExprStrs.join(', ')}}${modifierCodes}`);
+  // ? Mirror `evalModifier`'s flat-pool rendering: modifier codes live in
+  //   `expressionParts` only — the per-sub strikethrough already signals
+  //   which sub-rolls were kept vs dropped.
+  ctx.renderedParts.push(`{${outerRendered.join(', ')}}`);
+
+  // ? `keptIndices` lives on the inner `group` part (it describes sub-roll
+  //   selection), even though the outer modifier evaluation computed it —
+  //   the accepted model leak from STAGE3.md §5. Dropped sub-rolls keep
+  //   their complete parts; consumers filter by `keptIndices`.
+  const groupPart: RollPart = {
+    type: 'group',
+    parts: subRolls.map((s) => s.part),
+    keptIndices,
+    total,
+    ...partSpan(group),
+  };
+
+  return {
+    total,
+    part: {
+      type: 'modifier',
+      specs: toPublicSpecs(specs),
+      target: groupPart,
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+function resolveThreshold(
+  value: ASTNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+  role: 'threshold' | 'fail threshold',
+): number {
+  const thresholdCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const resolved = evalNode(value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
+
+  if (!Number.isFinite(resolved)) {
+    throw new EvaluatorError(`Invalid ${role}: ${resolved}`, 'INVALID_THRESHOLD', 'SuccessCount');
+  }
+
+  return resolved;
+}
+
+function evalSuccessCount(
+  node: SuccessCountNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): EvalResult {
+  // ? Flag tracks syntactic presence of success-count notation, not pool size —
+  //   set before any early return so empty pools still populate successes/failures.
+  env.hasSuccessCount = true;
+
+  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const target = evalNode(node.target, rng, targetCtx, env);
+  const targetExpr = targetCtx.expressionParts.join('');
+
+  const thresholdValue = resolveThreshold(node.threshold.value, rng, ctx, env, 'threshold');
+  const failValue =
+    node.failThreshold != null
+      ? resolveThreshold(node.failThreshold.value, rng, ctx, env, 'fail threshold')
+      : undefined;
+
+  const code = `${node.threshold.operator}${thresholdValue}${
+    failValue != null ? `f${failValue}` : ''
+  }`;
+
+  const buildPart = (total: number, successes: number, failures: number): RollPart => {
+    const part: RollPart = {
+      type: 'successCount',
+      threshold: { operator: node.threshold.operator, value: thresholdValue },
+      target: target.part,
+      successes,
+      failures,
+      total,
+      ...partSpan(node),
+    };
+    if (failValue != null && node.failThreshold != null) {
+      part.failThreshold = { operator: node.failThreshold.operator, value: failValue };
+    }
+    return part;
+  };
+
+  // No-op when the target produced no dice in its pool (`0d6>=4`).
+  // `containsDicePool` should already reject dice-less targets at parse
+  // time, but guard defensively. `targetValue` is 0 for an empty pool, so
+  // the `total === successes - failures` invariant holds.
+  if (targetCtx.rolls.length === 0) {
+    ctx.expressionParts.push(`${targetExpr}${code}`);
+    ctx.renderedParts.push(`${targetExpr}${code}`);
+    return { total: target.total, part: buildPart(target.total, 0, 0) };
+  }
+
+  const result = countSuccesses(
+    targetCtx.rolls,
+    { operator: node.threshold.operator, value: thresholdValue },
+    failValue != null && node.failThreshold != null
+      ? { operator: node.failThreshold.operator, value: failValue }
+      : undefined,
+  );
+
+  ctx.rolls.push(...targetCtx.rolls);
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
+
+  return {
+    total: result.total,
+    part: buildPart(result.total, result.successes, result.failures),
+  };
+}
+
+/**
+ * Extracts the "natural" d20 value from a roll-side dice pool. Returns the
+ * single value when exactly one primary kept d20 is present; otherwise
+ * `undefined`.
+ *
+ * Excludes dropped (`kh`/`kl`/`dh`/`dl`/`r`/`ro`) dice — these aren't the
+ * final kept result. Explosion continuation dice (appended by standard/
+ * penetrating explode, tagged `'exploded'` with no `initialResult`) are not
+ * primaries either — `1d20! vs DC` keeps the natural from the original d20.
+ * Compound explode accumulates into the original die and sets
+ * `initialResult`, so it stays a primary and the raw first face is used.
+ * Multiple primary kept d20s (e.g., `1d20+1d20`) yield `undefined` so no
+ * ambiguous upgrade/downgrade is applied.
+ */
+function extractNatural(rolls: DieResult[]): number | undefined {
+  // Rerolled intermediates are always stamped `['rerolled', 'dropped']`
+  // (see `modifiers/reroll.ts`), so filtering by `'dropped'` covers them.
+  const primaries = rolls.filter(
+    (d) =>
+      d.sides === 20 &&
+      !d.modifiers.includes('dropped') &&
+      !(d.modifiers.includes('exploded') && d.initialResult === undefined),
+  );
+  if (primaries.length !== 1) return undefined;
+  const die = primaries[0];
+  return die?.initialResult ?? die?.result;
+}
+
+/**
+ * PF2e degree of success: compares `total` to `dc` at three thresholds and
+ * applies natural 20 upgrade / natural 1 downgrade with clamping.
+ */
+function calculateDegree(total: number, dc: number, natural: number | undefined): DegreeOfSuccess {
+  let degree: DegreeOfSuccess;
+  if (total >= dc + 10) degree = DegreeOfSuccess.CriticalSuccess;
+  else if (total >= dc) degree = DegreeOfSuccess.Success;
+  else if (total > dc - 10) degree = DegreeOfSuccess.Failure;
+  else degree = DegreeOfSuccess.CriticalFailure;
+
+  if (natural === 20 && degree < DegreeOfSuccess.CriticalSuccess) degree++;
+  if (natural === 1 && degree > DegreeOfSuccess.CriticalFailure) degree--;
+
+  return degree;
+}
+
+function degreeLabel(degree: DegreeOfSuccess): string {
+  switch (degree) {
+    case DegreeOfSuccess.CriticalFailure:
+      return 'Critical Failure';
+    case DegreeOfSuccess.Failure:
+      return 'Failure';
+    case DegreeOfSuccess.Success:
+      return 'Success';
+    case DegreeOfSuccess.CriticalSuccess:
+      return 'Critical Success';
+  }
+}
+
+function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  if (env.insideVersus) {
+    throw new EvaluatorError('Cannot nest versus operators', 'NESTED_VERSUS', 'Versus');
+  }
+
+  env.insideVersus = true;
+  try {
+    const rollCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const rollResult = evalNode(node.roll, rng, rollCtx, env);
+    // ? Extract natural from rollCtx directly — the roll-side pool is isolated
+    //   here, so no index slicing on the merged parent pool is needed.
+    const natural = extractNatural(rollCtx.rolls);
+
+    const dcCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const dcResult = evalNode(node.dc, rng, dcCtx, env);
+
+    const degree = calculateDegree(rollResult.total, dcResult.total, natural);
+
+    ctx.rolls.push(...rollCtx.rolls, ...dcCtx.rolls);
+
+    const rollExpr = rollCtx.expressionParts.join('');
+    const dcExpr = dcCtx.expressionParts.join('');
+    const rollRendered = rollCtx.renderedParts.join('');
+    const dcRendered = dcCtx.renderedParts.join('');
+
+    ctx.expressionParts.push(`${rollExpr} vs ${dcExpr}`);
+    ctx.renderedParts.push(`${rollRendered} vs ${dcRendered}`);
+    ctx.versusMetadata = { degree, natural, dcTotal: dcResult.total };
+
+    return {
+      total: rollResult.total,
+      part: {
+        type: 'versus',
+        roll: rollResult.part,
+        dc: dcResult.part,
+        degree,
+        total: rollResult.total,
+        ...partSpan(node),
+      },
+    };
+  } finally {
+    env.insideVersus = false;
+  }
+}
+
+/**
+ * Evaluates a parsed AST and returns the roll result.
+ *
+ * @param ast - The parsed AST node
+ * @param rng - Random number generator to use for dice rolls
+ * @param options - Optional evaluation options
+ * @returns Complete roll result with total and metadata
+ *
+ * @example
+ * ```typescript
+ * const ast = parse('2d6+3');
+ * const rng = new SeededRNG('test');
+ * const result = evaluate(ast, rng);
+ * console.log(result.total); // Sum of dice plus 3
+ * ```
+ */
+export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}): RollResult {
+  const maxDice =
+    options.maxDice != null && Number.isFinite(options.maxDice) && options.maxDice > 0
+      ? Math.floor(options.maxDice)
+      : DEFAULT_MAX_DICE;
+
+  const maxExplodeIterations =
+    options.maxExplodeIterations != null &&
+    Number.isFinite(options.maxExplodeIterations) &&
+    options.maxExplodeIterations >= 0
+      ? Math.floor(options.maxExplodeIterations)
+      : DEFAULT_MAX_EXPLODE_ITERATIONS;
+
+  const maxRerollIterations =
+    options.maxRerollIterations != null &&
+    Number.isFinite(options.maxRerollIterations) &&
+    options.maxRerollIterations >= 0
+      ? Math.floor(options.maxRerollIterations)
+      : DEFAULT_MAX_REROLL_ITERATIONS;
+
+  const context = options.context ?? {};
+  const onMissingVariable = options.onMissingVariable ?? 'throw';
+
+  const env: EvalEnv = {
+    maxDice,
+    maxExplodeIterations,
+    maxRerollIterations,
+    totalDiceRolled: 0,
+    hasSuccessCount: false,
+    insideVersus: false,
+    context,
+    onMissingVariable,
+  };
+  const ctx: EvalContext = {
+    rolls: [],
+    expressionParts: [],
+    renderedParts: [],
+  };
+
+  const { total, part } = evalNode(ast, rng, ctx, env);
+
+  if (!Number.isFinite(total)) {
+    throw new EvaluatorError(
+      `Result is not a finite number: ${total}`,
+      'NON_FINITE_RESULT',
+      ast.type,
+    );
+  }
+
+  const expression = ctx.expressionParts.join('');
+  // ? Versus replaces the numeric total with the degree label in the rendered
+  //   form; `RollResult.total` remains the numeric roll total.
+  const trailing = ctx.versusMetadata ? degreeLabel(ctx.versusMetadata.degree) : String(total);
+  const rendered = `${ctx.renderedParts.join('')} = ${trailing}`;
+
+  const result: RollResult = {
+    total,
+    notation: options.notation ?? expression,
+    expression,
+    rendered,
+    rolls: ctx.rolls,
+    parts: part,
+  };
+
+  if (env.hasSuccessCount) {
+    let successes = 0;
+    let failures = 0;
+    for (const die of ctx.rolls) {
+      if (die.modifiers.includes('success')) successes += 1;
+      else if (die.modifiers.includes('failure')) failures += 1;
+    }
+    result.successes = successes;
+    result.failures = failures;
+  }
+
+  if (ctx.versusMetadata) {
+    result.degree = ctx.versusMetadata.degree;
+    if (ctx.versusMetadata.natural !== undefined) {
+      result.natural = ctx.versusMetadata.natural;
+    }
+  }
+
+  return result;
+}