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

package/src/evaluator/evaluator.ts

@@ -4,32 +4,47 @@
  * @module evaluator/evaluator
  */
 
-import type { RollParserErrorCode } from '../errors';
-import { RollParserError } from '../errors';
+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';
-import { isModifier } from '../parser/ast';
-import type { RNG } from '../rng/types';
-import type { ComparePoint, DieResult, EvaluateOptions, RollResult } from '../types';
-import { DegreeOfSuccess } from '../types';
+} 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';
+} from './modifiers/explode.js';
 import {
   applyDropHighest,
   applyDropLowest,
@@ -37,24 +52,34 @@ import {
   applyKeepLowest,
   markAllKept,
   sumKeptDice,
-} from './modifiers/keep-drop';
+} from './modifiers/keep-drop.js';
 import {
   applyRecursiveReroll,
   applyRerollOnce,
   DEFAULT_MAX_REROLL_ITERATIONS,
-} from './modifiers/reroll';
-import { countSuccesses } from './modifiers/success-count';
+} 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;
   }
 }
 
@@ -87,12 +112,25 @@ export type EvalEnv = {
    * 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.
  */
-type EvalContext = {
+export type EvalContext = {
   rolls: DieResult[];
   expressionParts: string[];
   renderedParts: string[];
@@ -111,6 +149,7 @@ type EvalContext = {
 
 /**
  * Flattened representation of a keep/drop modifier for chain evaluation.
+ * Superset of the public `ModifierSpec` (adds the notation `code`).
  */
 type ModifierSpec = {
   modifier: 'keep' | 'drop';
@@ -119,16 +158,44 @@ type ModifierSpec = {
   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,
+    fumble: result === 1 && sides > 1,
   };
 }
 
@@ -150,30 +217,83 @@ function createFateDieResult(result: number): DieResult {
  * 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.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);
-  });
+  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(', ')}]`;
 }
 
 /**
- * Evaluates an AST node, returning value and updating context.
+ * 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): number {
+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.value, ctx);
+      return evalLiteral(node, ctx);
 
     case 'Dice':
       return evalDice(node, rng, ctx, env);
@@ -205,6 +325,21 @@ function evalNode(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): numb
     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(
@@ -216,25 +351,84 @@ function evalNode(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): numb
   }
 }
 
-function evalLiteral(value: number, ctx: EvalContext): number {
+function evalLiteral(node: LiteralNode, ctx: EvalContext): EvalResult {
+  const { value } = node;
   ctx.expressionParts.push(String(value));
   ctx.renderedParts.push(String(value));
-  return value;
+  return { total: value, part: { type: 'literal', value, total: value, ...partSpan(node) } };
 }
 
-function evalDice(node: DiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
-  const count = evalNode(
-    node.count,
-    rng,
-    { rolls: [], expressionParts: [], renderedParts: [] },
-    env,
-  );
-  const sides = evalNode(
-    node.sides,
-    rng,
-    { rolls: [], expressionParts: [], renderedParts: [] },
-    env,
-  );
+/**
+ * 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');
@@ -267,16 +461,16 @@ function evalDice(node: DiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): num
   ctx.expressionParts.push(notation);
   ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
 
-  return total;
+  return {
+    total,
+    part: { type: 'dice', count, sides, rolls: markedDice, total, ...partSpan(node) },
+  };
 }
 
-function evalFateDice(node: FateDiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
-  const count = evalNode(
-    node.count,
-    rng,
-    { rolls: [], expressionParts: [], renderedParts: [] },
-    env,
-  );
+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');
@@ -306,17 +500,56 @@ function evalFateDice(node: FateDiceNode, rng: RNG, ctx: EvalContext, env: EvalE
   ctx.expressionParts.push(notation);
   ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
 
-  return total;
+  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;
 }
 
-function evalBinaryOp(node: BinaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+/**
+ * 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);
 
-  ctx.rolls.push(...leftCtx.rolls, ...rightCtx.rolls);
+  mergeContext(ctx, leftCtx);
+  mergeContext(ctx, rightCtx);
 
   const leftExpr = leftCtx.expressionParts.join('');
   const rightExpr = rightCtx.expressionParts.join('');
@@ -326,7 +559,27 @@ function evalBinaryOp(node: BinaryOpNode, rng: RNG, ctx: EvalContext, env: EvalE
   ctx.expressionParts.push(`${leftExpr} ${node.operator} ${rightExpr}`);
   ctx.renderedParts.push(`${leftRendered} ${node.operator} ${rightRendered}`);
 
-  switch (node.operator) {
+  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 '-':
@@ -346,17 +599,17 @@ function evalBinaryOp(node: BinaryOpNode, rng: RNG, ctx: EvalContext, env: EvalE
     case '**':
       return left ** right;
     default: {
-      const exhaustive: never = node.operator;
+      const exhaustive: never = operator;
       throw new EvaluatorError(`Unknown operator: ${exhaustive}`, 'UNKNOWN_OPERATOR', 'BinaryOp');
     }
   }
 }
 
-function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
   const innerCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-  const value = evalNode(node.operand, rng, innerCtx, env);
+  const inner = evalNode(node.operand, rng, innerCtx, env);
 
-  ctx.rolls.push(...innerCtx.rolls);
+  mergeContext(ctx, innerCtx);
 
   const innerExpr = innerCtx.expressionParts.join('');
   const innerRendered = innerCtx.renderedParts.join('');
@@ -364,7 +617,61 @@ function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv
   ctx.expressionParts.push(`-${innerExpr}`);
   ctx.renderedParts.push(`-${innerRendered}`);
 
-  return -value;
+  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(
@@ -372,18 +679,18 @@ function evalFunctionCall(
   rng: RNG,
   ctx: EvalContext,
   env: EvalEnv,
-): number {
+): EvalResult {
   const argCtxs: EvalContext[] = [];
-  const values: number[] = [];
+  const argResults: EvalResult[] = [];
 
   for (const arg of node.args) {
     const argCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-    values.push(evalNode(arg, rng, argCtx, env));
+    argResults.push(evalNode(arg, rng, argCtx, env));
     argCtxs.push(argCtx);
   }
 
   for (const argCtx of argCtxs) {
-    ctx.rolls.push(...argCtx.rolls);
+    mergeContext(ctx, argCtx);
   }
 
   const argExprs = argCtxs.map((c) => c.expressionParts.join(''));
@@ -392,7 +699,21 @@ function evalFunctionCall(
   ctx.expressionParts.push(`${node.name}(${argExprs.join(', ')})`);
   ctx.renderedParts.push(`${node.name}(${argRendereds.join(', ')})`);
 
-  return applyFunction(node.name, values);
+  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 {
@@ -402,6 +723,9 @@ function applyFunction(name: string, values: number[]): number {
     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));
@@ -435,6 +759,7 @@ function requireUnaryArg(name: string, values: number[]): number {
 function flattenModifierChain(
   node: ModifierNode,
   rng: RNG,
+  ctx: EvalContext,
   env: EvalEnv,
 ): { specs: ModifierSpec[]; baseTarget: ASTNode } {
   const specs: ModifierSpec[] = [];
@@ -442,7 +767,8 @@ function flattenModifierChain(
 
   while (isModifier(current)) {
     const countCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-    const modCount = evalNode(current.count, rng, countCtx, env);
+    const modCount = evalNode(current.count, rng, countCtx, env).total;
+    mergeMetaRolls(ctx, countCtx);
 
     if (!Number.isInteger(modCount) || modCount < 0) {
       throw new EvaluatorError(
@@ -486,6 +812,11 @@ function applyModifierSpec(dice: DieResult[], spec: ModifierSpec): DieResult[] {
 /**
  * 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>();
@@ -499,12 +830,13 @@ function mergeDropSets(baseDice: DieResult[], specs: ModifierSpec[]): DieResult[
     }
   }
 
-  return baseDice.map((die, index) => ({
-    ...die,
-    modifiers: droppedIndices.has(index)
+  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'],
-  }));
+      : [...die.modifiers.filter((m) => m !== 'dropped' && m !== 'kept'), 'kept'];
+  });
+
+  return baseDice;
 }
 
 /**
@@ -520,24 +852,39 @@ function formatExplodeCode(
   return `${marker}${threshold.operator}${thresholdValue}`;
 }
 
-function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
   const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-  const targetValue = evalNode(node.target, rng, targetCtx, env);
+  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);
+    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 targetValue;
+    return { total: target.total, part: buildPart(target.total) };
   }
 
   const shouldExplode = buildShouldExplode(node.threshold?.operator, thresholdValue);
@@ -556,24 +903,41 @@ function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv
   //   dropped dice are visible; explosion-origin is otherwise invisible.
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(expanded)}`);
 
-  return sumKeptDice(expanded);
+  const total = sumKeptDice(expanded);
+  return { total, part: buildPart(total) };
 }
 
-function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
   const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-  evalNode(node.target, rng, targetCtx, env);
+  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);
+  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}`);
-    return sumKeptDice(targetCtx.rolls);
+    const total = sumKeptDice(targetCtx.rolls);
+    return {
+      total,
+      part: {
+        type: 'reroll',
+        once: node.once,
+        condition,
+        target: target.part,
+        total,
+        ...partSpan(node),
+      },
+    };
   }
 
   const pool = node.once
@@ -584,14 +948,153 @@ function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(pool)}`);
 
-  return sumKeptDice(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): number {
-  const { specs, baseTarget } = flattenModifierChain(node, rng, env);
+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: [] };
-  evalNode(baseTarget, rng, targetCtx, env);
+  const target = evalNode(baseTarget, rng, targetCtx, env);
 
   const mergedDice = mergeDropSets(targetCtx.rolls, specs);
 
@@ -605,17 +1108,169 @@ function evalModifier(node: ModifierNode, rng: RNG, ctx: EvalContext, env: EvalE
   ctx.expressionParts.push(`${targetExpr}${modifierCodes}`);
   ctx.renderedParts.push(`${targetExpr}${renderDice(mergedDice)}`);
 
-  return total;
+  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);
+  const resolved = evalNode(value, rng, thresholdCtx, env).total;
+  mergeMetaRolls(ctx, thresholdCtx);
 
   if (!Number.isFinite(resolved)) {
     throw new EvaluatorError(`Invalid ${role}: ${resolved}`, 'INVALID_THRESHOLD', 'SuccessCount');
@@ -629,27 +1284,49 @@ function evalSuccessCount(
   rng: RNG,
   ctx: EvalContext,
   env: EvalEnv,
-): number {
+): 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 targetValue = evalNode(node.target, rng, targetCtx, env);
+  const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join('');
 
-  const thresholdValue = resolveThreshold(node.threshold.value, rng, env, 'threshold');
+  const thresholdValue = resolveThreshold(node.threshold.value, rng, ctx, env, 'threshold');
   const failValue =
     node.failThreshold != null
-      ? resolveThreshold(node.failThreshold.value, rng, env, 'fail threshold')
+      ? resolveThreshold(node.failThreshold.value, rng, ctx, env, 'fail threshold')
       : undefined;
 
   const code = `${node.threshold.operator}${thresholdValue}${
     failValue != null ? `f${failValue}` : ''
   }`;
 
-  // No-op when the target produced no dice in its pool. `containsDice` should
-  // already reject this at parse time, but guard defensively.
+  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 targetValue;
+    return { total: target.total, part: buildPart(target.total, 0, 0) };
   }
 
   const result = countSuccesses(
@@ -660,28 +1337,42 @@ function evalSuccessCount(
       : undefined,
   );
 
-  env.hasSuccessCount = true;
-
   ctx.rolls.push(...targetCtx.rolls);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
 
-  return result.total;
+  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 kept d20 is present; otherwise `undefined`.
+ * single value when exactly one primary kept d20 is present; otherwise
+ * `undefined`.
  *
- * Excludes dropped (`kh`/`kl`/`dh`/`dl`) and rerolled (`r`/`ro`) dice — these
- * aren't the final kept result. Multiple kept d20s (e.g., `1d20+1d20`) yield
- * `undefined` so no ambiguous upgrade/downgrade is applied.
+ * 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 {
-  const keptD20s = rolls.filter(
-    (d) => d.sides === 20 && !d.modifiers.includes('dropped') && !d.modifiers.includes('rerolled'),
+  // 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),
   );
-  return keptD20s.length === 1 ? keptD20s[0]?.result : undefined;
+  if (primaries.length !== 1) return undefined;
+  const die = primaries[0];
+  return die?.initialResult ?? die?.result;
 }
 
 /**
@@ -714,7 +1405,7 @@ function degreeLabel(degree: DegreeOfSuccess): string {
   }
 }
 
-function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
   if (env.insideVersus) {
     throw new EvaluatorError('Cannot nest versus operators', 'NESTED_VERSUS', 'Versus');
   }
@@ -722,15 +1413,15 @@ function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   env.insideVersus = true;
   try {
     const rollCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-    const rollTotal = evalNode(node.roll, rng, rollCtx, env);
+    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 dcTotal = evalNode(node.dc, rng, dcCtx, env);
+    const dcResult = evalNode(node.dc, rng, dcCtx, env);
 
-    const degree = calculateDegree(rollTotal, dcTotal, natural);
+    const degree = calculateDegree(rollResult.total, dcResult.total, natural);
 
     ctx.rolls.push(...rollCtx.rolls, ...dcCtx.rolls);
 
@@ -741,9 +1432,19 @@ function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
 
     ctx.expressionParts.push(`${rollExpr} vs ${dcExpr}`);
     ctx.renderedParts.push(`${rollRendered} vs ${dcRendered}`);
-    ctx.versusMetadata = { degree, natural, dcTotal };
-
-    return rollTotal;
+    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;
   }
@@ -785,6 +1486,9 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
       ? Math.floor(options.maxRerollIterations)
       : DEFAULT_MAX_REROLL_ITERATIONS;
 
+  const context = options.context ?? {};
+  const onMissingVariable = options.onMissingVariable ?? 'throw';
+
   const env: EvalEnv = {
     maxDice,
     maxExplodeIterations,
@@ -792,6 +1496,8 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     totalDiceRolled: 0,
     hasSuccessCount: false,
     insideVersus: false,
+    context,
+    onMissingVariable,
   };
   const ctx: EvalContext = {
     rolls: [],
@@ -799,7 +1505,15 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     renderedParts: [],
   };
 
-  const total = evalNode(ast, rng, ctx, env);
+  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
@@ -813,6 +1527,7 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     expression,
     rendered,
     rolls: ctx.rolls,
+    parts: part,
   };
 
   if (env.hasSuccessCount) {