roll-parser 3.0.0-beta.0 → 3.0.0

package/src/evaluator/evaluator.ts

@@ -4,21 +4,21 @@
  * @module evaluator/evaluator
  */
 
-import type { RollParserErrorCode } from '../errors.js';
-import { RollParserError } from '../errors.js';
+import { describeValue, EvaluatorError, RollParserError, stampEvaluatorSpan } from '../errors.js';
 import type {
   ASTNode,
   BinaryOpNode,
   CritThreshold,
   CritThresholdNode,
   DiceNode,
+  DieBoundNode,
   ExplodeNode,
   FateDiceNode,
   FunctionCallNode,
   GroupedNode,
   GroupNode,
+  KeepDropNode,
   LiteralNode,
-  ModifierNode,
   RerollNode,
   SortNode,
   SuccessCountNode,
@@ -26,18 +26,26 @@ import type {
   VariableNode,
   VersusNode,
 } from '../parser/ast.js';
-import { isModifier } from '../parser/ast.js';
+import { isKeepDrop } from '../parser/ast.js';
+import { containsVersus } from '../parser/guards.js';
 import type { RNG } from '../rng/types.js';
 import type {
+  CompareOp,
   ComparePoint,
+  DieModifier,
   DieResult,
   EvaluateOptions,
+  KeepDropSpec,
   ResolvedComparePoint,
+  ResolvedCritThreshold,
   RollPart,
   RollResult,
 } from '../types.js';
 import { DegreeOfSuccess } from '../types.js';
-import { applyCritThresholds, type ResolvedCritThreshold } from './modifiers/crit-threshold.js';
+import { createDieResult, createFateDieResult } from './die.js';
+import { chargeDice, type EvalEnv } from './env.js';
+import { applyCritThresholds } from './modifiers/crit-threshold.js';
+import { applyDieBound } from './modifiers/die-bound.js';
 import {
   applyCompoundExplode,
   applyPenetratingExplode,
@@ -46,13 +54,12 @@ import {
   DEFAULT_MAX_EXPLODE_ITERATIONS,
 } from './modifiers/explode.js';
 import {
-  applyDropHighest,
-  applyDropLowest,
-  applyKeepHighest,
-  applyKeepLowest,
-  markAllKept,
-  sumKeptDice,
-} from './modifiers/keep-drop.js';
+  isVersusDc,
+  rewriteFlags,
+  SELECTION_AND_TALLY_FLAGS,
+  SELECTION_FLAGS,
+} from './modifiers/flags.js';
+import { markDroppedIndices, sumKeptDice } from './modifiers/keep-drop.js';
 import {
   applyRecursiveReroll,
   applyRerollOnce,
@@ -61,74 +68,71 @@ import {
 import { sortDice } from './modifiers/sort.js';
 import { countSuccesses } from './modifiers/success-count.js';
 
+// Defined in `errors.ts` so the modifier modules can throw it without an ESM
+// value cycle back through here; re-exported for importers that expect it here.
+export { EvaluatorError };
+
+//
+// * Limits
+//
+
 /**
- * Error thrown during AST evaluation.
+ * Default value of `EvaluationOptions.maxDice`: the number of dice a single
+ * evaluation may roll before `DICE_LIMIT_EXCEEDED` is thrown.
+ *
+ * Counted across the whole expression, not per pool, so `6000d6+6000d6`
+ * breaches it. Includes dice rolled by explosions, rerolls, and
+ * meta-expressions.
+ *
+ * @category Limits
  */
-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 };
+/**
+ * Largest rollable `sides` value. `SeededRNG.nextInt` cannot sample ranges
+ * above 2^53 without bias and throws a bare `RangeError` there, so cap one
+ * below that and report an `EvaluatorError` instead — every failure the
+ * library raises must satisfy `isRollParserError`.
+ */
+const MAX_DICE_SIDES = Number.MAX_SAFE_INTEGER;
 
 /**
- * Per-evaluation shared environment (created once, shared across all branches).
+ * Resolves a user-supplied evaluation limit, failing closed.
  *
- * Exported for use by modifier implementations under `./modifiers/*`. Not part
- * of the public library API.
+ * Absent (`undefined` / `null`) takes the library default — the no-options
+ * path. Anything else must be a safe integer at or above `min`; strings,
+ * `NaN`, `±Infinity`, negatives, and fractions all throw — substituting the
+ * default for a rejected value would hand the caller a *higher* limit than
+ * they asked for.
  */
-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';
-};
+function resolveLimit(
+  value: number | undefined,
+  option: string,
+  fallback: number,
+  min: number,
+): number {
+  if (value == null) return fallback;
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) {
+    throw new RollParserError(
+      `Option '${option}' must be an integer >= ${min}, received ${describeValue(value)}`,
+      'INVALID_EVALUATION_LIMIT',
+    );
+  }
+  return value;
+}
+
+export { DEFAULT_MAX_EXPLODE_ITERATIONS, DEFAULT_MAX_REROLL_ITERATIONS };
+
+//
+// * Context
+//
 
 /**
  * Per-branch mutable accumulator for tracking rolls and output during recursion.
  *
- * @internal exported for targeted `mergeMetaRolls` tests only; not a public API.
+ * Module-level export, deliberately absent from `src/index.ts` — the package
+ * surface never mentions it. See {@link mergeMetaRolls} for why the export
+ * exists at all.
  */
 export type EvalContext = {
   rolls: DieResult[];
@@ -147,16 +151,20 @@ export type EvalContext = {
   };
 };
 
+/**
+ * Creates an empty per-branch accumulator. Every sub-evaluation runs in a
+ * fresh context so its rolls and rendered fragments can be merged back on the
+ * parent's terms.
+ */
+function createContext(): EvalContext {
+  return { rolls: [], expressionParts: [], renderedParts: [] };
+}
+
 /**
  * Flattened representation of a keep/drop modifier for chain evaluation.
- * Superset of the public `ModifierSpec` (adds the notation `code`).
+ * Superset of the public `KeepDropSpec` (adds the notation `code`).
  */
-type ModifierSpec = {
-  modifier: 'keep' | 'drop';
-  selector: 'highest' | 'lowest';
-  count: number;
-  code: string;
-};
+type KeepDropChainEntry = KeepDropSpec & { code: string };
 
 /**
  * Every branch returns its numeric total AND the `RollPart` it contributes
@@ -168,49 +176,36 @@ type EvalResult = {
   part: RollPart;
 };
 
+//
+// * Shared helpers
+//
+
 /**
  * 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 {};
+  if (node.start == null || node.end == null) 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.
+ * Appends every element of `source` to `target`.
+ *
+ * Replaces `target.push(...source)` — the spread form passes one argument per
+ * element and overflows the call stack somewhere above half a million dice,
+ * which a user-raised `maxDice` can reach. A `RangeError` there would escape
+ * the `isRollParserError` contract.
  */
-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,
-  };
+function appendAll<T>(target: T[], source: readonly T[]): void {
+  for (const item of source) {
+    target.push(item);
+  }
 }
 
-/**
- * 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,
-  };
+/** Drops the internal notation `code`, leaving the public `KeepDropSpec` shape. */
+function toPublicSpecs(specs: KeepDropChainEntry[]): KeepDropSpec[] {
+  return specs.map(({ code: _code, ...spec }) => spec);
 }
 
 /**
@@ -223,21 +218,40 @@ function createFateDieResult(result: number): DieResult {
  * `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(', ')}]`;
+  // Hot path: one pass into a single string — filter + map + join allocated two
+  // intermediate arrays plus a string per die.
+  let rendered = '[';
+  let isFirst = true;
+
+  for (const die of dice) {
+    const { modifiers } = die;
+
+    // Fast path: a die untouched by any modifier carries exactly ['kept'].
+    // Skipping the `meta` scan here and the three in `renderDie` more than
+    // halves a plain `1000d6` — rendering dominates large unmodified pools.
+    if (modifiers.length === 1 && modifiers[0] === 'kept') {
+      rendered = isFirst ? `${rendered}${die.result}` : `${rendered}, ${die.result}`;
+      isFirst = false;
+      continue;
+    }
+
+    if (modifiers.includes('meta')) continue;
+
+    if (!isFirst) rendered += ', ';
+    isFirst = false;
+
+    rendered += renderDie(die.result, modifiers);
+  }
+
+  return `${rendered}]`;
+}
+
+/** Marker-wrapped spelling of one die, per `renderDice`'s priority order. */
+function renderDie(result: number, modifiers: readonly DieModifier[]): string {
+  if (modifiers.includes('dropped')) return `~~${result}~~`;
+  if (modifiers.includes('success')) return `**${result}**`;
+  if (modifiers.includes('failure')) return `__${result}__`;
+  return String(result);
 }
 
 /**
@@ -253,23 +267,27 @@ function renderDice(dice: DieResult[]): string {
  * 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).
+ *
+ * `versusMetadata` is deliberately not forwarded — a meta sub-expression
+ * resolves to a scalar. `evalMetaOperand` rejects a versus before reaching
+ * here, so nothing is lost by the omission.
  */
-/** @internal exported for targeted defense-in-depth tests only. */
+// Exported rather than `@internal`: the tag strip above is unreachable through
+// any parseable notation, so pinning it needs a direct call with a hand-built
+// context — and `@internal` would hide that guarantee from the docs.
 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',
-      ],
+      modifiers: rewriteFlags(die.modifiers, SELECTION_AND_TALLY_FLAGS, 'meta', 'dropped'),
     });
   }
 }
 
+//
+// * Node dispatch
+//
+
 /**
  * Evaluates an AST node, returning its total and `RollPart` while updating
  * the context.
@@ -282,9 +300,8 @@ function evalNode(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): Eval
   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;
+    if (error instanceof EvaluatorError && node.start != null) {
+      stampEvaluatorSpan(error, node.start, node.end);
     }
     throw error;
   }
@@ -307,8 +324,8 @@ function evalNodeInner(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
     case 'UnaryOp':
       return evalUnaryOp(node, rng, ctx, env);
 
-    case 'Modifier':
-      return evalModifier(node, rng, ctx, env);
+    case 'KeepDrop':
+      return evalKeepDrop(node, rng, ctx, env);
 
     case 'Explode':
       return evalExplode(node, rng, ctx, env);
@@ -316,6 +333,9 @@ function evalNodeInner(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
     case 'Reroll':
       return evalReroll(node, rng, ctx, env);
 
+    case 'DieBound':
+      return evalDieBound(node, rng, ctx, env);
+
     case 'SuccessCount':
       return evalSuccessCount(node, rng, ctx, env);
 
@@ -351,6 +371,10 @@ function evalNodeInner(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   }
 }
 
+//
+// * Leaf nodes
+//
+
 function evalLiteral(node: LiteralNode, ctx: EvalContext): EvalResult {
   const { value } = node;
   ctx.expressionParts.push(String(value));
@@ -413,99 +437,149 @@ function evalVariable(node: VariableNode, ctx: EvalContext, env: EvalEnv): EvalR
   };
 }
 
+//
+// * Dice pools
+//
+
 /**
- * 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.
+ * Evaluates a meta sub-expression (dice count, dice sides, a modifier count, a
+ * threshold) in an isolated context and forwards its rolls into `ctx` as meta
+ * dice.
+ *
+ * A `Literal` operand — the overwhelming majority (`3d6`, `4d6kh3`, `1d20!>18`)
+ * — is answered from the node without allocating the throwaway context: a
+ * literal draws no RNG, produces no rolls, and cannot throw, so the merge has
+ * nothing to carry. Draw order is untouched (see README, Randomness).
+ *
+ * A versus operand is rejected rather than reduced to its total: this forwards
+ * rolls but not `versusMetadata`, so consuming one would drop the resolved
+ * `degree`/`natural` with no signal. `rejectVersusMetaOperand` refuses the same
+ * positions at parse time; this is the backstop for a hand-built AST.
+ *
+ * The scan is structural and runs first. Watching for surviving `versusMetadata`
+ * instead would miss a versus under a wrapper that voids it (`DieBound`,
+ * `KeepDrop`), lose the race to any other runtime error in the operand, and burn
+ * RNG draws before failing.
  */
-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);
+function evalMetaOperand(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv): number {
+  if (node.type === 'Literal') return node.value;
 
-  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 (containsVersus(node)) {
+    const error = new EvaluatorError(
+      'Versus cannot be used as a meta-expression',
+      'NESTED_VERSUS',
+      'Versus',
+    );
+    if (node.start != null) stampEvaluatorSpan(error, node.start, node.end);
+    throw error;
   }
 
-  if (env.totalDiceRolled + count > env.maxDice) {
-    throw new EvaluatorError(
-      `Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`,
-      'DICE_LIMIT_EXCEEDED',
-      'Dice',
-    );
+  const metaCtx = createContext();
+  const value = evalNode(node, rng, metaCtx, env).total;
+  mergeMetaRolls(ctx, metaCtx);
+  return value;
+}
+
+/** Rejects dice counts that cannot address a pool. */
+function requireDiceCount(count: number, nodeType: 'Dice' | 'FateDice'): void {
+  if (!Number.isInteger(count) || count < 0) {
+    throw new EvaluatorError(`Invalid dice count: ${count}`, 'INVALID_DICE_COUNT', nodeType);
   }
-  env.totalDiceRolled += count;
+}
 
+/**
+ * Rolls `count` dice and writes the pool into `ctx` — the tail shared by
+ * `evalDice` and `evalFateDice`. `rollDie` produces one die (drawing exactly
+ * one RNG value), `notation` is the canonical `NdX` / `NdF` spelling used by
+ * both the expression and rendered forms.
+ *
+ * `rollDie` is responsible for stamping `'kept'` at construction. A fresh pool
+ * has no pre-dropped dice, so the `markAllKept` pass this used to run could
+ * only ever append that one flag — at the cost of cloning every die. The same
+ * reasoning makes the running `total` exact: nothing here is dropped, so it
+ * equals `sumKeptDice(dice)`.
+ */
+function rollPool(
+  count: number,
+  notation: string,
+  rollDie: () => DieResult,
+  ctx: EvalContext,
+): { total: number; rolls: DieResult[] } {
   const dice: DieResult[] = [];
+  let total = 0;
+
   for (let i = 0; i < count; i++) {
-    const result = rng.nextInt(1, sides);
-    dice.push(createDieResult(sides, result));
+    const die = rollDie();
+    dice.push(die);
+    total += die.result;
   }
 
-  const markedDice = markAllKept(dice);
-  ctx.rolls.push(...markedDice);
-
-  const total = sumKeptDice(markedDice);
-  const notation = `${count}d${sides}`;
+  appendAll(ctx.rolls, dice);
 
   ctx.expressionParts.push(notation);
-  ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
+  ctx.renderedParts.push(`${notation}${renderDice(dice)}`);
 
-  return {
-    total,
-    part: { type: 'dice', count, sides, rolls: markedDice, total, ...partSpan(node) },
-  };
+  return { total, rolls: dice };
 }
 
-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);
+/**
+ * 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 keep/drop-argument
+ * meta-expressions like `4d6kh(1d2)`, `flattenKeepDropChain` draws the
+ * keep/drop args first, then `evalKeepDrop` calls `evalDice` for the base
+ * pool. See README, Randomness → Draw order, for the full spec.
+ */
+function evalDice(node: DiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const count = evalMetaOperand(node.count, rng, ctx, env);
+  const sides = evalMetaOperand(node.sides, rng, ctx, env);
 
-  if (!Number.isInteger(count) || count < 0) {
-    throw new EvaluatorError(`Invalid dice count: ${count}`, 'INVALID_DICE_COUNT', 'FateDice');
+  requireDiceCount(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) {
+  if (sides > MAX_DICE_SIDES) {
     throw new EvaluatorError(
-      `Total dice count ${env.totalDiceRolled + count} exceeds limit of ${env.maxDice}`,
-      'DICE_LIMIT_EXCEEDED',
-      'FateDice',
+      `Dice sides ${sides} exceeds maximum of ${MAX_DICE_SIDES}`,
+      'INVALID_DICE_SIDES',
+      'Dice',
     );
   }
-  env.totalDiceRolled += count;
 
-  const dice: DieResult[] = [];
-  for (let i = 0; i < count; i++) {
-    const result = rng.nextInt(-1, 1);
-    dice.push(createFateDieResult(result));
-  }
+  chargeDice(env, count, 'Dice');
+
+  const { total, rolls } = rollPool(
+    count,
+    `${count}d${sides}`,
+    // Fresh `['kept']` per die — `success-count` appends tally flags in
+    // place, so a shared literal would tag the whole pool at once.
+    () => createDieResult(sides, rng.nextInt(1, sides), ['kept']),
+    ctx,
+  );
 
-  const markedDice = markAllKept(dice);
-  ctx.rolls.push(...markedDice);
+  return { total, part: { type: 'dice', count, sides, rolls, total, ...partSpan(node) } };
+}
 
-  const total = sumKeptDice(markedDice);
-  const notation = `${count}dF`;
+function evalFateDice(node: FateDiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const count = evalMetaOperand(node.count, rng, ctx, env);
 
-  ctx.expressionParts.push(notation);
-  ctx.renderedParts.push(`${notation}${renderDice(markedDice)}`);
+  requireDiceCount(count, 'FateDice');
+  chargeDice(env, count, 'FateDice');
 
-  return {
-    total,
-    part: { type: 'fateDice', count, rolls: markedDice, total, ...partSpan(node) },
-  };
+  const { total, rolls } = rollPool(
+    count,
+    `${count}dF`,
+    () => createFateDieResult(rng.nextInt(-1, 1), ['kept']),
+    ctx,
+  );
+
+  return { total, part: { type: 'fateDice', count, rolls, total, ...partSpan(node) } };
 }
 
+//
+// * Context merging
+//
+
 /**
  * Propagates `versusMetadata` onto a parent so `degree`/`natural` survive
  * wrappers like `floor(...)`, `(vs) + 0`, or `-(vs)`. Throws `NESTED_VERSUS`
@@ -513,9 +587,27 @@ function evalFateDice(node: FateDiceNode, rng: RNG, ctx: EvalContext, env: EvalE
  * 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.
+ * itself. For the default case where the child's raw rolls flow up unchanged,
+ * use `mergeContext` instead.
+ *
+ * A **postfix modifier** may propagate only when it leaves `total` equal to the
+ * value the degree was resolved from — `evalVersus` computes `degree` once,
+ * against the total it saw, so a modifier that re-totals invalidates it. Among
+ * the modifiers only `evalSort` (reorders) and `evalCritThreshold` (tags)
+ * qualify. `evalExplode` adds dice, `evalReroll` replaces them, `evalKeepDrop`
+ * removes them, `evalDieBound` re-sums after clamping, and `evalSuccessCount`
+ * redefines `total` as a success tally, so none of those five may.
+ * `evalGroupKeepDrop` applies the rule per sub-roll, propagating only from
+ * sub-rolls it kept.
+ *
+ * Judge a modifier by what it does to `total`, not by which dice survive. The
+ * membership reading — "every die still contributes" — admits `evalDieBound`,
+ * which drops no dice and still invalidates the degree.
+ *
+ * Arithmetic wrappers are the deliberate exception named above: `(vs) + 100`
+ * reports `degree` beside a total of 103, because the wrapper post-processes a
+ * number without altering the comparison the degree came from. That is why they
+ * route through `mergeContext` rather than being held to the rule here.
  */
 function propagateMetadata(parent: EvalContext, metadata: EvalContext['versusMetadata']): void {
   if (!metadata) return;
@@ -537,13 +629,17 @@ function propagateMetadata(parent: EvalContext, metadata: EvalContext['versusMet
  * those with its own operator/function syntax.
  */
 function mergeContext(parent: EvalContext, child: EvalContext): void {
-  parent.rolls.push(...child.rolls);
+  appendAll(parent.rolls, child.rolls);
   propagateMetadata(parent, child.versusMetadata);
 }
 
+//
+// * Arithmetic
+//
+
 function evalBinaryOp(node: BinaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
-  const leftCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-  const rightCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const leftCtx = createContext();
+  const rightCtx = createContext();
 
   const left = evalNode(node.left, rng, leftCtx, env);
   const right = evalNode(node.right, rng, rightCtx, env);
@@ -606,7 +702,7 @@ function applyBinaryOperator(
 }
 
 function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
-  const innerCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const innerCtx = createContext();
   const inner = evalNode(node.operand, rng, innerCtx, env);
 
   mergeContext(ctx, innerCtx);
@@ -625,8 +721,12 @@ function evalUnaryOp(node: UnaryOpNode, rng: RNG, ctx: EvalContext, env: EvalEnv
   };
 }
 
+//
+// * Groups and functions
+//
+
 function evalGrouped(node: GroupedNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
-  const innerCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const innerCtx = createContext();
   const inner = evalNode(node.expression, rng, innerCtx, env);
 
   mergeContext(ctx, innerCtx);
@@ -646,7 +746,7 @@ function evalGrouped(node: GroupedNode, rng: RNG, ctx: EvalContext, env: EvalEnv
  * 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`
+ * keep/drop modifier with `expressions.length >= 2`, `evalKeepDrop`
  * intercepts first and never calls this function — dual semantics
  * (flat-pool vs sub-roll) are decided there.
  */
@@ -657,7 +757,7 @@ function evalGroup(node: GroupNode, rng: RNG, ctx: EvalContext, env: EvalEnv): E
   let total = 0;
 
   for (const expr of node.expressions) {
-    const subCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const subCtx = createContext();
     const sub = evalNode(expr, rng, subCtx, env);
     mergeContext(ctx, subCtx);
     subExprs.push(subCtx.expressionParts.join(''));
@@ -669,8 +769,8 @@ function evalGroup(node: GroupNode, rng: RNG, ctx: EvalContext, env: EvalEnv): E
   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.
+  // No `keptIndices` — bare groups (and single-sub passthroughs) perform
+  // no sub-roll selection; only `evalGroupKeepDrop` sets it.
   return { total, part: { type: 'group', parts: subParts, total, ...partSpan(node) } };
 }
 
@@ -684,7 +784,7 @@ function evalFunctionCall(
   const argResults: EvalResult[] = [];
 
   for (const arg of node.args) {
-    const argCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const argCtx = createContext();
     argResults.push(evalNode(arg, rng, argCtx, env));
     argCtxs.push(argCtx);
   }
@@ -723,26 +823,52 @@ 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`.
+      // `Math.round` breaks halves toward +∞: `round(2.5) === 3` but
+      // `round(-2.5) === -2`. Symmetric rounding must be composed via `floor`.
       return Math.round(requireUnaryArg(name, values));
     case 'abs':
       return Math.abs(requireUnaryArg(name, values));
+    case 'sqrt':
+      // A negative argument yields NaN, surfaced as `NON_FINITE_RESULT` by
+      // the top-level finiteness check — same policy as `1/0`.
+      return Math.sqrt(requireUnaryArg(name, values));
+    case 'pow': {
+      const [base, exponent] = requireBinaryArgs(name, values);
+      return base ** exponent;
+    }
     case 'max':
-      return Math.max(...values);
+      return extremumOf(values, 'max');
     case 'min':
-      return Math.min(...values);
+      return extremumOf(values, 'min');
     default:
       throw new EvaluatorError(`Unknown function: ${name}`, 'UNKNOWN_FUNCTION', 'FunctionCall');
   }
 }
 
+/**
+ * Folded replacement for `Math.max(...values)` / `Math.min(...values)`.
+ *
+ * `max`/`min` are variadic, so a pathological argument count blows the call
+ * stack with a bare `RangeError` in the spread form. NaN still poisons the
+ * result the way `Math.max` does, so a non-finite argument keeps surfacing as
+ * `NON_FINITE_RESULT` rather than being silently skipped.
+ */
+function extremumOf(values: number[], kind: 'max' | 'min'): number {
+  let result = kind === 'max' ? Number.NEGATIVE_INFINITY : Number.POSITIVE_INFINITY;
+
+  for (const value of values) {
+    if (Number.isNaN(value)) return Number.NaN;
+    if (kind === 'max' ? value > result : value < result) result = value;
+  }
+
+  return result;
+}
+
 function requireUnaryArg(name: string, values: number[]): number {
   const [x] = values;
-  if (x === undefined) {
-    // ? Unreachable: parser validates arity before evaluation. Defensive for
-    // `noNonNullAssertion`.
+  if (x == null) {
+    // Unreachable: the parser validates arity before evaluation. Present to
+    // satisfy `noNonNullAssertion`.
     throw new EvaluatorError(
       `Function '${name}' requires an argument`,
       'UNKNOWN_FUNCTION',
@@ -752,42 +878,64 @@ function requireUnaryArg(name: string, values: number[]): number {
   return x;
 }
 
+function requireBinaryArgs(name: string, values: number[]): [number, number] {
+  const [a, b] = values;
+  if (a == null || b == null) {
+    // ? Unreachable: parser validates arity before evaluation. Defensive for
+    // `noNonNullAssertion`.
+    throw new EvaluatorError(
+      `Function '${name}' requires two arguments`,
+      'UNKNOWN_FUNCTION',
+      'FunctionCall',
+    );
+  }
+  return [a, b];
+}
+
+//
+// * Keep/drop modifiers
+//
+
+/** Notation spelling of each keep/drop combination. */
+const KEEP_DROP_CODES = {
+  keep: { highest: 'kh', lowest: 'kl' },
+  drop: { highest: 'dh', lowest: 'dl' },
+} as const;
+
+function keepDropCode(kind: KeepDropSpec['kind'], selector: KeepDropSpec['selector']): string {
+  return KEEP_DROP_CODES[kind][selector];
+}
+
 /**
- * Walks a nested ModifierNode chain, collecting specs outermost-first,
+ * Walks a nested KeepDropNode chain, collecting specs outermost-first,
  * then reverses to notation order (innermost-first).
  */
-function flattenModifierChain(
-  node: ModifierNode,
+function flattenKeepDropChain(
+  node: KeepDropNode,
   rng: RNG,
   ctx: EvalContext,
   env: EvalEnv,
-): { specs: ModifierSpec[]; baseTarget: ASTNode } {
-  const specs: ModifierSpec[] = [];
+): { specs: KeepDropChainEntry[]; baseTarget: ASTNode } {
+  const specs: KeepDropChainEntry[] = [];
   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);
+  while (isKeepDrop(current)) {
+    const modCount = evalMetaOperand(current.count, rng, ctx, env);
 
     if (!Number.isInteger(modCount) || modCount < 0) {
       throw new EvaluatorError(
-        `Invalid modifier count: ${modCount}`,
-        'INVALID_MODIFIER_COUNT',
-        'Modifier',
+        `Invalid keep/drop count: ${modCount}`,
+        'INVALID_KEEP_DROP_COUNT',
+        'KeepDrop',
       );
     }
 
-    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 });
+    specs.push({
+      kind: current.kind,
+      selector: current.selector,
+      count: modCount,
+      code: keepDropCode(current.kind, current.selector),
+    });
     current = current.target;
   }
 
@@ -795,50 +943,57 @@ function flattenModifierChain(
   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.
+ * shared between `RollResult.rolls` and the `RollPart` tree. Each spec still
+ * selects against the unmodified pool: `markDroppedIndices` reads results and
+ * writes only into `droppedMask`, so no spec can observe another's outcome.
  */
-function mergeDropSets(baseDice: DieResult[], specs: ModifierSpec[]): DieResult[] {
-  const droppedIndices = new Set<number>();
+function mergeDropSets(baseDice: DieResult[], specs: KeepDropChainEntry[]): DieResult[] {
+  const droppedMask = new Uint8Array(baseDice.length);
 
   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);
-      }
-    }
+    markDroppedIndices(baseDice, spec.count, spec.kind, spec.selector, droppedMask);
   }
 
-  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'];
-  });
+  for (let index = 0; index < baseDice.length; index++) {
+    const die = baseDice[index];
+    if (die == null) continue;
+
+    const marker = droppedMask[index] === 1 ? 'dropped' : 'kept';
+    const { modifiers } = die;
+
+    // Already exactly this slot flag — `rewriteFlags` would rebuild an
+    // identical single-element array. Fresh pool dice hit this every time.
+    if (modifiers.length === 1 && modifiers[0] === marker) continue;
+
+    die.modifiers = rewriteFlags(modifiers, SELECTION_FLAGS, marker);
+  }
 
   return baseDice;
 }
 
+//
+// * Explode and reroll
+//
+
+/** Notation marker for each explode variant. */
+const EXPLODE_MARKERS: Record<ExplodeNode['variant'], string> = {
+  standard: '!',
+  compound: '!!',
+  penetrating: '!p',
+};
+
+/** Pool transform for each explode variant. */
+const EXPLODE_APPLIERS: Record<ExplodeNode['variant'], typeof applyStandardExplode> = {
+  standard: applyStandardExplode,
+  compound: applyCompoundExplode,
+  penetrating: applyPenetratingExplode,
+};
+
 /**
  * Builds the notation string for an explode modifier, e.g. `!`, `!!>=3`, `!p>5`.
  */
@@ -847,21 +1002,19 @@ function formatExplodeCode(
   threshold: ComparePoint | undefined,
   thresholdValue: number | undefined,
 ): string {
-  const marker = variant === 'standard' ? '!' : variant === 'compound' ? '!!' : '!p';
+  const marker = EXPLODE_MARKERS[variant];
   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 targetCtx = createContext();
   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);
+    thresholdValue = evalMetaOperand(node.threshold.value, rng, ctx, env);
   }
 
   const code = formatExplodeCode(node.variant, node.threshold, thresholdValue);
@@ -874,7 +1027,7 @@ function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv
       total,
       ...partSpan(node),
     };
-    if (node.threshold != null && thresholdValue !== undefined) {
+    if (node.threshold != null && thresholdValue != null) {
       part.threshold = { operator: node.threshold.operator, value: thresholdValue };
     }
     return part;
@@ -889,18 +1042,12 @@ function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv
 
   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);
+  const expanded = EXPLODE_APPLIERS[node.variant](targetCtx.rolls, shouldExplode, rng, env);
 
-  ctx.rolls.push(...expanded);
+  appendAll(ctx.rolls, 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.
+  // Rendered form carries the explode code — unlike kh/dl, whose dropped dice
+  // are self-evident, explosion origin is otherwise invisible.
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(expanded)}`);
 
   const total = sumKeptDice(expanded);
@@ -908,13 +1055,11 @@ function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv
 }
 
 function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
-  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const targetCtx = createContext();
   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 thresholdValue = evalMetaOperand(node.condition.value, rng, ctx, env);
 
   const code = `${node.once ? 'ro' : 'r'}${node.condition.operator}${thresholdValue}`;
   const condition: ResolvedComparePoint = {
@@ -944,7 +1089,7 @@ function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
     ? applyRerollOnce(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env)
     : applyRecursiveReroll(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env);
 
-  ctx.rolls.push(...pool);
+  appendAll(ctx.rolls, pool);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(pool)}`);
 
@@ -962,25 +1107,77 @@ function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   };
 }
 
+/**
+ * Evaluates a per-die clamp (`minN` / `maxN`). The bound expression draws
+ * *after* the target pool, like other threshold arguments (see README,
+ * Randomness → Draw order). Dice are clamped in place by `applyDieBound`
+ * and the total re-summed, since clamping changes kept-die values.
+ */
+function evalDieBound(node: DieBoundNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const targetCtx = createContext();
+  const target = evalNode(node.target, rng, targetCtx, env);
+
+  const boundValue = evalMetaOperand(node.value, rng, ctx, env);
+  if (!Number.isFinite(boundValue)) {
+    throw new EvaluatorError(
+      `Invalid ${node.bound} bound: ${boundValue}`,
+      'INVALID_THRESHOLD',
+      'DieBound',
+    );
+  }
+
+  applyDieBound(targetCtx.rolls, node.bound, boundValue);
+
+  appendAll(ctx.rolls, targetCtx.rolls);
+  // ! No `propagateMetadata` here: clamping re-sums, so a propagated `degree`
+  // ! would have been resolved against a total this node just replaced.
+  // ! See the rule on `propagateMetadata`.
+
+  const targetExpr = targetCtx.expressionParts.join('');
+  // Negative bounds render parenthesized so `result.expression` re-parses
+  // (`4d6min-2` is a syntax error; `4d6min(-2)` is not).
+  const code = boundValue < 0 ? `${node.bound}(${boundValue})` : `${node.bound}${boundValue}`;
+
+  ctx.expressionParts.push(`${targetExpr}${code}`);
+  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
+
+  const total = sumKeptDice(targetCtx.rolls);
+  return {
+    total,
+    part: {
+      type: 'dieBound',
+      bound: node.bound,
+      value: boundValue,
+      target: target.part,
+      total,
+      ...partSpan(node),
+    },
+  };
+}
+
+//
+// * Sort and crit thresholds
+//
+
 /**
  * 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
+ * Rendering mirrors `evalExplode` / `evalKeepDrop`: 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 targetCtx = createContext();
   const target = evalNode(node.target, rng, targetCtx, env);
 
   const sortedRolls = sortDice(targetCtx.rolls, node.order);
 
-  ctx.rolls.push(...sortedRolls);
+  appendAll(ctx.rolls, sortedRolls);
   propagateMetadata(ctx, targetCtx.versusMetadata);
 
   const code = node.order === 'ascending' ? 's' : 'sd';
@@ -994,6 +1191,7 @@ function evalSort(node: SortNode, rng: RNG, ctx: EvalContext, env: EvalEnv): Eva
     part: {
       type: 'sort',
       order: node.order,
+      rolls: sortedRolls,
       target: target.part,
       total: target.total,
       ...partSpan(node),
@@ -1023,21 +1221,21 @@ function evalCritThreshold(
   ctx: EvalContext,
   env: EvalEnv,
 ): EvalResult {
-  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const targetCtx = createContext();
   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.
+  // A side with no explicit threshold falls back to the default rule rather
+  // than 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);
+  appendAll(ctx.rolls, targetCtx.rolls);
   propagateMetadata(ctx, targetCtx.versusMetadata);
 
   const targetExpr = targetCtx.expressionParts.join('');
@@ -1069,9 +1267,8 @@ function resolveCritThreshold(
   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);
+
+  const resolved = evalMetaOperand(threshold.value, rng, ctx, env);
   if (!Number.isFinite(resolved)) {
     throw new EvaluatorError(
       `Invalid crit threshold: ${resolved}`,
@@ -1082,36 +1279,39 @@ function resolveCritThreshold(
   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);
+//
+// * Keep/drop evaluation
+//
 
-  // 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.
+function evalKeepDrop(node: KeepDropNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
+  const { specs, baseTarget } = flattenKeepDropChain(node, rng, ctx, env);
+
+  // Multi-sub-roll group: keep/drop treats each sub-roll subtotal as a compound
+  // die. Single-sub groups fall through to the flat-pool path, where
+  // `mergeDropSets` selects individual dice.
   if (baseTarget.type === 'Group' && baseTarget.expressions.length >= 2) {
-    return evalGroupModifier(node, baseTarget, specs, rng, ctx, env);
+    return evalGroupKeepDrop(node, baseTarget, specs, rng, ctx, env);
   }
 
-  const targetCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+  const targetCtx = createContext();
   const target = evalNode(baseTarget, rng, targetCtx, env);
 
   const mergedDice = mergeDropSets(targetCtx.rolls, specs);
 
-  ctx.rolls.push(...mergedDice);
+  appendAll(ctx.rolls, mergedDice);
 
   const total = sumKeptDice(mergedDice);
 
   const targetExpr = targetCtx.expressionParts.join('');
-  const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join('');
+  const keepDropCodes = specs.map((s) => `${s.code}${s.count}`).join('');
 
-  ctx.expressionParts.push(`${targetExpr}${modifierCodes}`);
+  ctx.expressionParts.push(`${targetExpr}${keepDropCodes}`);
   ctx.renderedParts.push(`${targetExpr}${renderDice(mergedDice)}`);
 
   return {
     total,
     part: {
-      type: 'modifier',
+      type: 'keepDrop',
       specs: toPublicSpecs(specs),
       target: target.part,
       total,
@@ -1143,10 +1343,10 @@ function stripInnerMarkers(rendered: string): string {
  * on the propagated rolls still agrees with the group total, and the
  * rendered form wraps them in strikethrough `~~...~~`.
  */
-function evalGroupModifier(
-  node: ModifierNode,
+function evalGroupKeepDrop(
+  node: KeepDropNode,
   group: GroupNode,
-  specs: ModifierSpec[],
+  specs: KeepDropChainEntry[],
   rng: RNG,
   ctx: EvalContext,
   env: EvalEnv,
@@ -1161,7 +1361,7 @@ function evalGroupModifier(
   };
 
   const subRolls: SubRoll[] = group.expressions.map((expr) => {
-    const subCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const subCtx = createContext();
     const sub = evalNode(expr, rng, subCtx, env);
     return {
       subtotal: sub.total,
@@ -1173,9 +1373,8 @@ function evalGroupModifier(
     };
   });
 
-  // ? 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.
+  // `sides = 0` sentinel: synthetic dice only feed `mergeDropSets`, never reach
+  // `ctx.rolls`, and crit/fumble is meaningless for a subtotal.
   const syntheticDice: DieResult[] = subRolls.map((sub) => ({
     sides: 0,
     result: sub.subtotal,
@@ -1196,51 +1395,41 @@ function evalGroupModifier(
     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.
+      // Flag every inner die dropped so propagated rolls still sum to the
+      // total, stripping `'success'`/`'failure'` too so the top-level tally
+      // cannot count a dropped sub-roll. 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',
-        ];
+        die.modifiers = rewriteFlags(die.modifiers, SELECTION_AND_TALLY_FLAGS, 'dropped');
       }
-      ctx.rolls.push(...sub.rolls);
+      appendAll(ctx.rolls, sub.rolls);
       outerRendered.push(`~~${stripInnerMarkers(sub.rendered)}~~`);
     } else {
       keptIndices.push(i);
-      ctx.rolls.push(...sub.rolls);
+      appendAll(ctx.rolls, 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`.
+    // Only kept sub-rolls propagate versus metadata — `degree` must reflect
+    // dice that contributed to the total. Two kept versus sub-rolls still
+    // collide via `propagateMetadata`'s `NESTED_VERSUS` guard.
     if (!isDropped) {
       propagateMetadata(ctx, sub.versusMetadata);
     }
   }
 
   const subExprStrs = subRolls.map((s) => s.expr);
-  const modifierCodes = specs.map((s) => `${s.code}${s.count}`).join('');
+  const keepDropCodes = 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.expressionParts.push(`{${subExprStrs.join(', ')}}${keepDropCodes}`);
+  // Keep/drop codes live in `expressionParts` only — the per-sub strikethrough
+  // already shows which sub-rolls were kept.
   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`.
+  // `keptIndices` sits on the inner `group` part even though the outer modifier
+  // computed it — it describes sub-roll selection. Dropped sub-rolls keep their
+  // complete parts; consumers filter by `keptIndices`.
   const groupPart: RollPart = {
     type: 'group',
     parts: subRolls.map((s) => s.part),
@@ -1252,7 +1441,7 @@ function evalGroupModifier(
   return {
     total,
     part: {
-      type: 'modifier',
+      type: 'keepDrop',
       specs: toPublicSpecs(specs),
       target: groupPart,
       total,
@@ -1261,6 +1450,10 @@ function evalGroupModifier(
   };
 }
 
+//
+// * Success counting
+//
+
 function resolveThreshold(
   value: ASTNode,
   rng: RNG,
@@ -1268,9 +1461,7 @@ function resolveThreshold(
   env: EvalEnv,
   role: 'threshold' | 'fail threshold',
 ): number {
-  const thresholdCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
-  const resolved = evalNode(value, rng, thresholdCtx, env).total;
-  mergeMetaRolls(ctx, thresholdCtx);
+  const resolved = evalMetaOperand(value, rng, ctx, env);
 
   if (!Number.isFinite(resolved)) {
     throw new EvaluatorError(`Invalid ${role}: ${resolved}`, 'INVALID_THRESHOLD', 'SuccessCount');
@@ -1279,17 +1470,30 @@ function resolveThreshold(
   return resolved;
 }
 
+/**
+ * Builds the failure-threshold suffix of a success-count expression, e.g.
+ * `f3`, `f<3`, `f>=3`.
+ *
+ * `'='` is elided because bare `fN` parses back to `{ operator: '=' }`, so
+ * `f3` is the canonical spelling. Every other operator must be emitted —
+ * dropping it silently rewrites `f<3` into `f3`, which counts a different
+ * set of dice as failures.
+ */
+function formatFailCode(operator: CompareOp, value: number): string {
+  return operator === '=' ? `f${value}` : `f${operator}${value}`;
+}
+
 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.
+  // 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 targetCtx = createContext();
   const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join('');
 
@@ -1299,9 +1503,12 @@ function evalSuccessCount(
       ? resolveThreshold(node.failThreshold.value, rng, ctx, env, 'fail threshold')
       : undefined;
 
-  const code = `${node.threshold.operator}${thresholdValue}${
-    failValue != null ? `f${failValue}` : ''
-  }`;
+  const failCode =
+    failValue != null && node.failThreshold != null
+      ? formatFailCode(node.failThreshold.operator, failValue)
+      : '';
+
+  const code = `${node.threshold.operator}${thresholdValue}${failCode}`;
 
   const buildPart = (total: number, successes: number, failures: number): RollPart => {
     const part: RollPart = {
@@ -1319,10 +1526,9 @@ function evalSuccessCount(
     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.
+  // No-op when the target produced no dice (`0d6>=4`); `containsDicePool`
+  // should already reject dice-less targets at parse time. `target.total` is 0
+  // for an empty pool, so `total === successes - failures` still holds.
   if (targetCtx.rolls.length === 0) {
     ctx.expressionParts.push(`${targetExpr}${code}`);
     ctx.renderedParts.push(`${targetExpr}${code}`);
@@ -1337,7 +1543,7 @@ function evalSuccessCount(
       : undefined,
   );
 
-  ctx.rolls.push(...targetCtx.rolls);
+  appendAll(ctx.rolls, targetCtx.rolls);
   ctx.expressionParts.push(`${targetExpr}${code}`);
   ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
 
@@ -1347,6 +1553,10 @@ function evalSuccessCount(
   };
 }
 
+//
+// * Versus
+//
+
 /**
  * Extracts the "natural" d20 value from a roll-side dice pool. Returns the
  * single value when exactly one primary kept d20 is present; otherwise
@@ -1368,7 +1578,7 @@ function extractNatural(rolls: DieResult[]): number | undefined {
     (d) =>
       d.sides === 20 &&
       !d.modifiers.includes('dropped') &&
-      !(d.modifiers.includes('exploded') && d.initialResult === undefined),
+      !(d.modifiers.includes('exploded') && d.initialResult == null),
   );
   if (primaries.length !== 1) return undefined;
   const die = primaries[0];
@@ -1412,18 +1622,22 @@ function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
 
   env.insideVersus = true;
   try {
-    const rollCtx: EvalContext = { rolls: [], expressionParts: [], renderedParts: [] };
+    const rollCtx = createContext();
     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 dcCtx = createContext();
     const dcResult = evalNode(node.dc, rng, dcCtx, env);
 
     const degree = calculateDegree(rollResult.total, dcResult.total, natural);
 
-    ctx.rolls.push(...rollCtx.rolls, ...dcCtx.rolls);
+    appendAll(ctx.rolls, rollCtx.rolls);
+    // ! Tag before merging: past this point the DC dice are indistinguishable
+    // ! from the roll side, and every pool modifier walks the merged array.
+    for (const die of dcCtx.rolls) {
+      die.modifiers.push('dc');
+    }
+    appendAll(ctx.rolls, dcCtx.rolls);
 
     const rollExpr = rollCtx.expressionParts.join('');
     const dcExpr = dcCtx.expressionParts.join('');
@@ -1450,41 +1664,61 @@ function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   }
 }
 
+//
+// * Entry point
+//
+
 /**
- * Evaluates a parsed AST and returns the roll result.
+ * Evaluates a parsed AST against an {@link RNG} and returns the roll result.
+ *
+ * The second half of the pipeline — {@link roll} is `evaluate(parse(...))`.
+ * Call it directly to reuse one AST across many rolls, or to drive a
+ * hand-built AST.
+ *
+ * Unlike `roll`, the RNG is required: `evaluate` never invents a randomness
+ * source, so a caller can never accidentally get an unseeded roll.
  *
- * @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
+ * @param ast - The AST to evaluate, from {@link parse} or hand-built
+ * @param rng - Randomness source; one `nextInt` call per die
+ * @param options - Evaluation limits plus the original `notation` string,
+ *   which the AST cannot supply
+ * @returns Complete {@link RollResult}
+ * @throws {EvaluatorError} On a limit breach, division by zero, an undefined
+ *   variable, or a non-finite total
+ * @throws {RollParserError} `INVALID_EVALUATION_LIMIT` when a supplied limit is
+ *   not an integer in range — raised before any die is rolled
  *
  * @example
  * ```typescript
+ * import { evaluate, parse } from 'roll-parser';
+ * import { createMockRng } from 'roll-parser/testing';
+ *
  * const ast = parse('2d6+3');
- * const rng = new SeededRNG('test');
- * const result = evaluate(ast, rng);
- * console.log(result.total); // Sum of dice plus 3
+ * const result = evaluate(ast, createMockRng([4, 2]), { notation: '2d6+3' });
+ * result.total; // 9
+ * result.rendered; // '2d6[4, 2] + 3 = 9'
  * ```
+ *
+ * Omitting `notation` falls back to the normalized `expression`, which is
+ * reconstructed from the AST — so `RollResult.notation` is always a string,
+ * just not necessarily the one the user typed.
+ *
+ * @category Core
  */
 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 maxDice = resolveLimit(options.maxDice, 'maxDice', DEFAULT_MAX_DICE, 1);
+  const maxExplodeIterations = resolveLimit(
+    options.maxExplodeIterations,
+    'maxExplodeIterations',
+    DEFAULT_MAX_EXPLODE_ITERATIONS,
+    0,
+  );
+  const maxRerollIterations = resolveLimit(
+    options.maxRerollIterations,
+    'maxRerollIterations',
+    DEFAULT_MAX_REROLL_ITERATIONS,
+    0,
+  );
 
   const context = options.context ?? {};
   const onMissingVariable = options.onMissingVariable ?? 'throw';
@@ -1499,11 +1733,7 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     context,
     onMissingVariable,
   };
-  const ctx: EvalContext = {
-    rolls: [],
-    expressionParts: [],
-    renderedParts: [],
-  };
+  const ctx = createContext();
 
   const { total, part } = evalNode(ast, rng, ctx, env);
 
@@ -1516,37 +1746,39 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
   }
 
   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.
+  // 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 = {
+  // `RollResult` is `Readonly` — optional fields fold in via conditional spreads.
+  const versus = ctx.versusMetadata;
+
+  return {
     total,
     notation: options.notation ?? expression,
     expression,
     rendered,
     rolls: ctx.rolls,
     parts: part,
+    ...(env.hasSuccessCount ? countTaggedDice(ctx.rolls) : {}),
+    ...(versus ? { degree: versus.degree } : {}),
+    ...(versus?.natural != null ? { natural: versus.natural } : {}),
   };
+}
 
-  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;
-    }
+/** Tallies the `'success'` / `'failure'` tags across a whole roll. */
+function countTaggedDice(rolls: DieResult[]): { successes: number; failures: number } {
+  let successes = 0;
+  let failures = 0;
+
+  for (const die of rolls) {
+    // A success-count inside the DC sub-expression tags its own dice before
+    // `evalVersus` marks them `'dc'`, so they arrive here already tagged.
+    if (isVersusDc(die)) continue;
+    if (die.modifiers.includes('success')) successes += 1;
+    else if (die.modifiers.includes('failure')) failures += 1;
   }
 
-  return result;
+  return { successes, failures };
 }