roll-parser 3.1.0 → 3.2.1

package/src/evaluator/evaluator.ts

@@ -5,6 +5,7 @@
  */
 
 import { describeValue, EvaluatorError, RollParserError, stampEvaluatorSpan } from '../errors.js';
+import { joinModifierCode } from '../notation.js';
 import type {
   ASTNode,
   BinaryOpNode,
@@ -59,6 +60,8 @@ import {
   rewriteFlags,
   SELECTION_AND_TALLY_FLAGS,
   SELECTION_FLAGS,
+  stripFlags,
+  TALLY_FLAGS,
 } from './modifiers/flags.js';
 import { markDroppedIndices, sumKeptDice } from './modifiers/keep-drop.js';
 import {
@@ -204,6 +207,26 @@ function appendAll<T>(target: T[], source: readonly T[]): void {
   }
 }
 
+/**
+ * Message for an operand that has to be a whole number — dice count, dice
+ * sides, keep/drop count. A fractional value there is almost always an
+ * unrounded division (`5d(20/3)`, `4d6kh(3/2)`), and the fix is a function the
+ * notation already carries, so the message names it rather than leaving the
+ * author to find it. Only finite positive values get the hint: no rounding
+ * rescues a negative count or a `NaN`.
+ *
+ * The value prints in full, repeating decimals and all. Shortening it to a
+ * fixed width read better on `20/3` but rounded `1.00001` to `1` — naming a
+ * side count the evaluator accepts, which reads as a bug in the library rather
+ * than in the notation. Exactness is worth more than the digits it costs.
+ */
+function invalidIntegerOperand(label: string, value: number): string {
+  if (Number.isInteger(value) || !Number.isFinite(value) || value <= 0) {
+    return `${label}: ${value}`;
+  }
+  return `${label}: ${value} (use 'floor', 'ceil', or 'round')`;
+}
+
 /** Drops the internal notation `code`, leaving the public `KeepDropSpec` shape. */
 function toPublicSpecs(specs: KeepDropChainEntry[]): KeepDropSpec[] {
   return specs.map(({ code: _code, ...spec }) => spec);
@@ -480,15 +503,39 @@ function evalMetaOperand(node: ASTNode, rng: RNG, ctx: EvalContext, env: EvalEnv
   }
 
   const metaCtx = createContext();
-  const value = evalNode(node, rng, metaCtx, env).total;
+  // The tally counterpart of the `TALLY_FLAGS` strip in `mergeMetaRolls`.
+  const value = evalDiscardingSubtotals(node, rng, metaCtx, env).total;
   mergeMetaRolls(ctx, metaCtx);
   return value;
 }
 
+/**
+ * Evaluates a node whose result is consumed as a scalar — a meta operand or a
+ * `vs` DC — rolling back any subtotal verdicts it scored so they never reach
+ * the top-level tally.
+ */
+function evalDiscardingSubtotals(
+  node: ASTNode,
+  rng: RNG,
+  ctx: EvalContext,
+  env: EvalEnv,
+): EvalResult {
+  const successTally = env.subtotalSuccesses;
+  const failureTally = env.subtotalFailures;
+  const result = evalNode(node, rng, ctx, env);
+  env.subtotalSuccesses = successTally;
+  env.subtotalFailures = failureTally;
+  return result;
+}
+
 /** 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);
+    throw new EvaluatorError(
+      invalidIntegerOperand('Invalid dice count', count),
+      'INVALID_DICE_COUNT',
+      nodeType,
+    );
   }
 }
 
@@ -541,7 +588,11 @@ function evalDice(node: DiceNode, rng: RNG, ctx: EvalContext, env: EvalEnv): Eva
 
   requireDiceCount(count, 'Dice');
   if (!Number.isInteger(sides) || sides < 1) {
-    throw new EvaluatorError(`Invalid dice sides: ${sides}`, 'INVALID_DICE_SIDES', 'Dice');
+    throw new EvaluatorError(
+      invalidIntegerOperand('Invalid dice sides', sides),
+      'INVALID_DICE_SIDES',
+      'Dice',
+    );
   }
   if (sides > MAX_DICE_SIDES) {
     throw new EvaluatorError(
@@ -929,7 +980,7 @@ function flattenKeepDropChain(
 
     if (!Number.isInteger(modCount) || modCount < 0) {
       throw new EvaluatorError(
-        `Invalid keep/drop count: ${modCount}`,
+        invalidIntegerOperand('Invalid keep/drop count', modCount),
         'INVALID_KEEP_DROP_COUNT',
         'KeepDrop',
       );
@@ -1067,11 +1118,11 @@ function evalExplode(node: ExplodeNode, rng: RNG, ctx: EvalContext, env: EvalEnv
 function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv): EvalResult {
   const targetCtx = createContext();
   const target = evalNode(node.target, rng, targetCtx, env);
-  const targetExpr = targetCtx.expressionParts.join('');
 
   const thresholdValue = evalMetaOperand(node.condition.value, rng, ctx, env);
 
   const code = `${node.once ? 'ro' : 'r'}${node.condition.operator}${thresholdValue}`;
+  const modifierExpr = joinModifierCode(targetCtx.expressionParts.join(''), code);
   const condition: ResolvedComparePoint = {
     operator: node.condition.operator,
     value: thresholdValue,
@@ -1079,8 +1130,8 @@ function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
 
   // 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}`);
+    ctx.expressionParts.push(modifierExpr);
+    ctx.renderedParts.push(modifierExpr);
     const total = sumKeptDice(targetCtx.rolls, env.hasVersusDc);
     return {
       total,
@@ -1101,8 +1152,8 @@ function evalReroll(node: RerollNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
     : applyRecursiveReroll(targetCtx.rolls, node.condition.operator, thresholdValue, rng, env);
 
   appendAll(ctx.rolls, pool);
-  ctx.expressionParts.push(`${targetExpr}${code}`);
-  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(pool)}`);
+  ctx.expressionParts.push(modifierExpr);
+  ctx.renderedParts.push(`${modifierExpr}${renderDice(pool)}`);
 
   const total = sumKeptDice(pool, env.hasVersusDc);
   return {
@@ -1145,13 +1196,13 @@ function evalDieBound(node: DieBoundNode, rng: RNG, ctx: EvalContext, env: EvalE
   // ! 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}`;
+  const modifierExpr = joinModifierCode(targetCtx.expressionParts.join(''), code);
 
-  ctx.expressionParts.push(`${targetExpr}${code}`);
-  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
+  ctx.expressionParts.push(modifierExpr);
+  ctx.renderedParts.push(`${modifierExpr}${renderDice(targetCtx.rolls)}`);
 
   const total = sumKeptDice(targetCtx.rolls, env.hasVersusDc);
   return {
@@ -1193,10 +1244,10 @@ function evalSort(node: SortNode, rng: RNG, ctx: EvalContext, env: EvalEnv): Eva
   propagateMetadata(ctx, targetCtx.versusMetadata);
 
   const code = node.order === 'ascending' ? 's' : 'sd';
-  const targetExpr = targetCtx.expressionParts.join('');
+  const modifierExpr = joinModifierCode(targetCtx.expressionParts.join(''), code);
 
-  ctx.expressionParts.push(`${targetExpr}${code}`);
-  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(sortedRolls)}`);
+  ctx.expressionParts.push(modifierExpr);
+  ctx.renderedParts.push(`${modifierExpr}${renderDice(sortedRolls)}`);
 
   return {
     total: target.total,
@@ -1254,14 +1305,13 @@ function evalCritThreshold(
   appendAll(ctx.rolls, targetCtx.rolls);
   propagateMetadata(ctx, targetCtx.versusMetadata);
 
-  const targetExpr = targetCtx.expressionParts.join('');
-  const codes = [
+  const modifierExpr = [
     ...successResolved.map((t) => (t === 'default' ? 'cs' : `cs${t.operator}${t.value}`)),
     ...failResolved.map((t) => (t === 'default' ? 'cf' : `cf${t.operator}${t.value}`)),
-  ].join('');
+  ].reduce(joinModifierCode, targetCtx.expressionParts.join(''));
 
-  ctx.expressionParts.push(`${targetExpr}${codes}`);
-  ctx.renderedParts.push(`${targetExpr}${codes}${renderDice(targetCtx.rolls)}`);
+  ctx.expressionParts.push(modifierExpr);
+  ctx.renderedParts.push(`${modifierExpr}${renderDice(targetCtx.rolls)}`);
 
   return {
     total: target.total,
@@ -1321,7 +1371,7 @@ function evalKeepDrop(node: KeepDropNode, rng: RNG, ctx: EvalContext, env: EvalE
   const targetExpr = targetCtx.expressionParts.join('');
   const keepDropCodes = specs.map((s) => `${s.code}${s.count}`).join('');
 
-  ctx.expressionParts.push(`${targetExpr}${keepDropCodes}`);
+  ctx.expressionParts.push(joinModifierCode(targetExpr, keepDropCodes));
   ctx.renderedParts.push(`${targetExpr}${renderDice(mergedDice)}`);
 
   return {
@@ -1344,10 +1394,17 @@ function evalKeepDrop(node: KeepDropNode, rng: RNG, ctx: EvalContext, env: EvalE
  * 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');
+  return stripTallyMarkers(rendered).replace(/~~(-?\d+)~~/g, '$1');
+}
+
+/**
+ * Strips success (`**`) and failure (`__`) markers from an already-rendered
+ * sub-roll, leaving dropped dice struck. Pairs with a `TALLY_FLAGS` strip: the
+ * tags and the text they produced have to go together, or `renderBreakdown`
+ * stops reproducing `rendered`.
+ */
+function stripTallyMarkers(rendered: string): string {
+  return rendered.replace(/\*\*(-?\d+)\*\*/g, '$1').replace(/__(-?\d+)__/g, '$1');
 }
 
 /**
@@ -1374,10 +1431,16 @@ function evalGroupKeepDrop(
     expr: string;
     rendered: string;
     versusMetadata: EvalContext['versusMetadata'];
+    scoredSuccesses: number;
+    scoredFailures: number;
   };
 
   const subRolls: SubRoll[] = group.expressions.map((expr) => {
     const subCtx = createContext();
+    // What a subtotal count inside this sub-roll scored, so a drop can take it
+    // back — the tally counterpart of the `TALLY_FLAGS` rewrite below.
+    const successTally = env.subtotalSuccesses;
+    const failureTally = env.subtotalFailures;
     const sub = evalNode(expr, rng, subCtx, env);
     return {
       subtotal: sub.total,
@@ -1386,6 +1449,8 @@ function evalGroupKeepDrop(
       expr: subCtx.expressionParts.join(''),
       rendered: subCtx.renderedParts.join(''),
       versusMetadata: subCtx.versusMetadata,
+      scoredSuccesses: env.subtotalSuccesses - successTally,
+      scoredFailures: env.subtotalFailures - failureTally,
     };
   });
 
@@ -1418,6 +1483,10 @@ function evalGroupKeepDrop(
       for (const die of sub.rolls) {
         die.modifiers = rewriteFlags(die.modifiers, SELECTION_AND_TALLY_FLAGS, 'dropped');
       }
+      // A count on subtotals left no tag for the rewrite above to strip, so its
+      // verdicts come back from the env tally instead.
+      env.subtotalSuccesses -= sub.scoredSuccesses;
+      env.subtotalFailures -= sub.scoredFailures;
       appendAll(ctx.rolls, sub.rolls);
       outerRendered.push(`~~${stripInnerMarkers(sub.rendered)}~~`);
     } else {
@@ -1505,14 +1574,24 @@ function evalSuccessCount(
   ctx: EvalContext,
   env: EvalEnv,
 ): EvalResult {
-  // Flag tracks syntactic presence of success-count notation, not pool size —
-  // set before any early return so empty pools still populate successes/failures.
-  env.hasSuccessCount = true;
+  // Rolled back below, so a subtotal count nested in the target
+  // (`{{2d6, 2d6}>=10, 1d8}>=1`) is not reported alongside the subtotal this
+  // pass re-scores it into.
+  const successTallyBefore = env.subtotalSuccesses;
+  const failureTallyBefore = env.subtotalFailures;
 
   const targetCtx = createContext();
   const target = evalNode(node.target, rng, targetCtx, env);
   const targetExpr = targetCtx.expressionParts.join('');
 
+  // True once any count has run: an inner one that tagged this very pool (only
+  // a group can arrange that — `{4d6>=5}<=2f5`), or an unrelated earlier one,
+  // which costs a redundant strip over dice nothing tagged. The flag otherwise
+  // tracks syntactic presence of success-count notation, not pool size — set
+  // before any early return so empty pools still populate successes/failures.
+  const poolAlreadyCounted = env.hasSuccessCount;
+  env.hasSuccessCount = true;
+
   const thresholdValue = resolveThreshold(node.threshold.value, rng, ctx, env, 'threshold');
   const failValue =
     node.failThreshold != null
@@ -1543,27 +1622,66 @@ function evalSuccessCount(
     return part;
   };
 
-  // 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) {
+  // Multi-sub-roll group: the units are sub-roll subtotals, not dice. The
+  // `sides = 0` synthetics are `evalGroupKeepDrop`'s sentinel and never reach
+  // `ctx.rolls`. Only a direct group target arrives here — the parser refuses
+  // every form that would reach the count with the subtotals already gone.
+  const bySubtotal = node.target.type === 'Group' && node.target.expressions.length >= 2;
+  const pool: DieResult[] = bySubtotal
+    ? (target.part as Extract<RollPart, { type: 'group' }>).parts.map((sub) => ({
+        sides: 0,
+        result: sub.total,
+        modifiers: [],
+        critical: false,
+        fumble: false,
+      }))
+    : targetCtx.rolls;
+
+  // ! Releases every die an inner count tagged, `vs` DC dice included, though
+  // ! `countSuccesses` spares those. The marker strip below reads rendered text
+  // ! and cannot tell a DC die apart, so sparing one here leaves a tag whose
+  // ! `**` is already gone and `renderBreakdown` stops reproducing `rendered`.
+  if (bySubtotal && poolAlreadyCounted) {
+    for (const die of targetCtx.rolls) {
+      die.modifiers = stripFlags(die.modifiers, TALLY_FLAGS);
+    }
+  }
+
+  // An empty pool (`0d6>=4`) scores zero of both, so its total is 0 — never
+  // `target.total`, which would break `total === successes - failures`.
+  // Reachable only through a zero-count pool — a target holding no dice node at
+  // all is rejected at parse time.
+  if (pool.length === 0) {
     ctx.expressionParts.push(`${targetExpr}${code}`);
     ctx.renderedParts.push(`${targetExpr}${code}`);
-    return { total: target.total, part: buildPart(target.total, 0, 0) };
+    return { total: 0, part: buildPart(0, 0, 0) };
   }
 
   const result = countSuccesses(
-    targetCtx.rolls,
+    pool,
     { operator: node.threshold.operator, value: thresholdValue },
     failValue != null && node.failThreshold != null
       ? { operator: node.failThreshold.operator, value: failValue }
       : undefined,
-    env.hasVersusDc,
+    !bySubtotal && env.hasVersusDc,
+    !bySubtotal && poolAlreadyCounted,
   );
 
+  if (bySubtotal) {
+    env.subtotalSuccesses = successTallyBefore + result.successes;
+    env.subtotalFailures = failureTallyBefore + result.failures;
+  }
+
   appendAll(ctx.rolls, targetCtx.rolls);
   ctx.expressionParts.push(`${targetExpr}${code}`);
-  ctx.renderedParts.push(`${targetExpr}${code}${renderDice(targetCtx.rolls)}`);
+  // A subtotal count renders through the group — its sub-rolls carry their own
+  // brackets, and one flat bracket would spell out the units it never used. The
+  // strip pairs with the tag release above: markers and tags go together.
+  ctx.renderedParts.push(
+    bySubtotal
+      ? `${stripTallyMarkers(targetCtx.renderedParts.join(''))}${code}`
+      : `${targetExpr}${code}${renderDice(targetCtx.rolls)}`,
+  );
 
   return {
     total: result.total,
@@ -1581,22 +1699,18 @@ function evalSuccessCount(
  * `undefined`.
  *
  * Excludes dropped (`kh`/`kl`/`dh`/`dl`/`r`/`ro`) dice — these aren't the
- * final kept result. Explosion continuation dice (appended by standard/
- * penetrating explode, tagged `'exploded'` with no `initialResult`) are not
- * primaries either — `1d20! vs DC` keeps the natural from the original d20.
- * Compound explode accumulates into the original die and sets
- * `initialResult`, so it stays a primary and the raw first face is used.
- * Multiple primary kept d20s (e.g., `1d20+1d20`) yield `undefined` so no
- * ambiguous upgrade/downgrade is applied.
+ * final kept result — and the continuation dice `env.explosionDice` marks, so
+ * `1d20! vs DC` keeps the natural from the original d20. A compound explode
+ * accumulates into that original instead of appending, so it stays a primary
+ * and its 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 {
+function extractNatural(rolls: DieResult[], env: EvalEnv): number | undefined {
   // Rerolled intermediates are always stamped `['rerolled', 'dropped']`
   // (see `modifiers/reroll.ts`), so filtering by `'dropped'` covers them.
+  const appended = env.explosionDice;
   const primaries = rolls.filter(
-    (d) =>
-      d.sides === 20 &&
-      !d.modifiers.includes('dropped') &&
-      !(d.modifiers.includes('exploded') && d.initialResult == null),
+    (d) => d.sides === 20 && !d.modifiers.includes('dropped') && !appended?.has(d),
   );
   if (primaries.length !== 1) return undefined;
   const die = primaries[0];
@@ -1642,10 +1756,13 @@ function evalVersus(node: VersusNode, rng: RNG, ctx: EvalContext, env: EvalEnv):
   try {
     const rollCtx = createContext();
     const rollResult = evalNode(node.roll, rng, rollCtx, env);
-    const natural = extractNatural(rollCtx.rolls);
+    const natural = extractNatural(rollCtx.rolls, env);
 
     const dcCtx = createContext();
-    const dcResult = evalNode(node.dc, rng, dcCtx, env);
+    // A subtotal count on the DC side (`1d20 vs {{2d6, 2d6}>=10}`) is rolled
+    // back for the same reason `countTaggedDice` skips DC dice: no pool pass
+    // may tally that side.
+    const dcResult = evalDiscardingSubtotals(node.dc, rng, dcCtx, env);
 
     const degree = calculateDegree(rollResult.total, dcResult.total, natural);
 
@@ -1751,9 +1868,12 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     maxRerollIterations,
     totalDiceRolled: 0,
     hasSuccessCount: false,
+    subtotalSuccesses: 0,
+    subtotalFailures: 0,
     insideVersus: false,
     hasVersusDc: false,
     critRules: undefined,
+    explosionDice: undefined,
     context,
     onMissingVariable,
   };
@@ -1785,24 +1905,27 @@ export function evaluate(ast: ASTNode, rng: RNG, options: EvaluateOptions = {}):
     rendered,
     rolls: ctx.rolls,
     parts: part,
-    ...(env.hasSuccessCount ? countTaggedDice(ctx.rolls, env.hasVersusDc) : {}),
+    ...(env.hasSuccessCount ? countTaggedDice(ctx.rolls, env) : {}),
     ...(versus ? { degree: versus.degree } : {}),
     ...(versus?.natural != null ? { natural: versus.natural } : {}),
   };
 }
 
-/** Tallies the `'success'` / `'failure'` tags across a whole roll. */
+/**
+ * Tallies the `'success'` / `'failure'` tags across a whole roll, on top of
+ * what a group count scored on subtotals — those carry no tag to find.
+ */
 function countTaggedDice(
   rolls: DieResult[],
-  hasVersusDc: boolean,
+  env: EvalEnv,
 ): { successes: number; failures: number } {
-  let successes = 0;
-  let failures = 0;
+  let successes = env.subtotalSuccesses;
+  let failures = env.subtotalFailures;
 
   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 (hasVersusDc && isVersusDc(die)) continue;
+    if (env.hasVersusDc && isVersusDc(die)) continue;
     if (die.modifiers.includes('success')) successes += 1;
     else if (die.modifiers.includes('failure')) failures += 1;
   }

package/src/evaluator/modifiers/crit-threshold.ts

@@ -11,13 +11,13 @@
  *
  * The two threshold kinds deliberately read different values. `'default'`
  * reads `initialResult ?? result`, the same source as the versus `natural`,
- * so "rolled the maximum face" survives the two modifiers that overwrite
- * `result` while recording the face they replaced — compound explode and
- * `minN`/`maxN`. An explicit threshold (`cs>4`, `cf<=2`) reads the die's
- * current `result`: it is a predicate over the die's value, and postfix
- * modifiers are order-sensitive by design, so `4d6min5cs>4` is meant to
- * see the clamped faces. The two can therefore disagree on one die —
- * `4d6min5cs>4` flags a clamped natural 1 as both critical and fumble.
+ * so "rolled the maximum face" survives every modifier that overwrites
+ * `result` while recording the face it replaced — compound explode,
+ * penetrating explode, and `minN`/`maxN`. An explicit threshold (`cs>4`,
+ * `cf<=2`) reads the die's current `result`: it is a predicate over the die's
+ * value, and postfix modifiers are order-sensitive by design, so `4d6min5cs>4`
+ * is meant to see the clamped faces. The two can therefore disagree on one
+ * die — `4d6min5cs>4` flags a clamped natural 1 as both critical and fumble.
  *
  * They also diverge on Fate dice. `'default'` carries a `sides > 1` guard, so
  * it never fires on a `sides = 0` pool; an explicit threshold has none and
@@ -26,15 +26,6 @@
  * `cs`/`cf` forms instead, since they would resolve to `'default'` and
  * silently do nothing.
  *
- * ! Penetrating explode is not covered: it stores `raw - 1` in `result`
- * ! without recording `initialResult`, so `1d6!pcs` still judges a natural
- * ! 6 by its decremented 5. An *inherited* rule is handed the raw roll
- * ! instead, which keeps `1d6cf>5!p` agreeing with `1d6!p` on the side the
- * ! user never overrode — at the cost of `1d6cf>5!p` and `1d6!pcf>5`
- * ! disagreeing on it. Recording `initialResult` here would settle both, but
- * ! `extractNatural` reads that field to tell an appended explosion die from
- * ! a compounded one, and would start counting these as versus primaries.
- *
  * The rule is recorded per die on `env.critRules`, so dice that explode and
  * reroll mint *after* the crit node has run inherit it from the die they
  * descended from. `cs`/`cf` therefore covers the whole pool wherever it sits
@@ -57,11 +48,8 @@ import { matchesCondition } from './compare.js';
 import { isVersusDc } from './flags.js';
 
 /**
- * Applies success/fail threshold arrays to a dice pool, overriding each
- * die's `critical` and `fumble` flags in place. Writing `natural` for
- * `initialResult ?? result`, a die matches `'default'` on the success side
- * when `natural === sides && sides > 1`, and on the fail side when
- * `natural === 1 && sides > 1`. Meta dice are skipped.
+ * Applies success/fail threshold arrays to a dice pool, overriding each die's
+ * `critical` and `fumble` flags in place. Meta and DC dice are skipped.
  *
  * Also records the rule against every die it touched, so later explode and
  * reroll dice can inherit it via {@link inheritCritRule}.
@@ -88,12 +76,11 @@ export function applyCritThresholds(
 /**
  * Judges one die by a recorded rule, overwriting both flags. A side always
  * carries at least `'default'` — `evalCritThreshold` fills the side the user
- * left out — so neither flag is silently left untouched. `natural` is the face
- * the `'default'` sentinel reads; an explicit threshold always reads `result`.
+ * left out — so neither flag is silently left untouched.
  */
 function applyCritRule(die: DieResult, rule: CritRule, natural: number): void {
-  die.critical = rule.success.some((t) => matchesCrit(t, die, natural));
-  die.fumble = rule.fail.some((t) => matchesFumble(t, die, natural));
+  die.critical = rule.success.some((t) => matchesThreshold(t, die, natural, die.sides));
+  die.fumble = rule.fail.some((t) => matchesThreshold(t, die, natural, 1));
 }
 
 /**
@@ -102,40 +89,34 @@ function applyCritRule(die: DieResult, rule: CritRule, natural: number): void {
  * reroll inherits it in turn. No-op when no `cs`/`cf` governs `parent`, which
  * leaves the `createDieResult` default rule in place.
  *
- * `natural` is the face the `'default'` sentinel reads, defaulting to the
- * child's own. Penetrating explode passes its raw roll — see the module note.
- *
- * ! Call this only once the child's final `result` is stored — an explicit
- * ! threshold is a predicate over `result`, so a penetrating die is judged by
- * ! its decremented value, matching `1d6!pcs<2`.
+ * ! Call this only once the child's final `result` and `initialResult` are
+ * ! stored — an explicit threshold is a predicate over `result`, so a
+ * ! penetrating die is judged by its decremented value, matching `1d6!pcs<2`.
  */
-export function inheritCritRule(
-  env: EvalEnv,
-  parent: DieResult,
-  child: DieResult,
-  natural = child.initialResult ?? child.result,
-): void {
+export function inheritCritRule(env: EvalEnv, parent: DieResult, child: DieResult): void {
   const rules = env.critRules;
   if (rules === undefined) return;
 
   const rule = rules.get(parent);
   if (rule === undefined) return;
 
-  applyCritRule(child, rule, natural);
+  applyCritRule(child, rule, child.initialResult ?? child.result);
   rules.set(child, rule);
 }
 
-function matchesCrit(threshold: ResolvedCritThreshold, die: DieResult, natural: number): boolean {
-  if (threshold === 'default') {
-    return natural === die.sides && die.sides > 1;
-  }
-  return matchesCondition(die.result, threshold.operator, threshold.value);
-}
-
-function matchesFumble(threshold: ResolvedCritThreshold, die: DieResult, natural: number): boolean {
+/**
+ * `defaultFace` is the face the `'default'` sentinel looks for — `die.sides`
+ * on the success side, `1` on the fail side. The `sides > 1` guard mirrors
+ * `createDieResult`: a d1 always rolls 1, so it is neither.
+ */
+function matchesThreshold(
+  threshold: ResolvedCritThreshold,
+  die: DieResult,
+  natural: number,
+  defaultFace: number,
+): boolean {
   if (threshold === 'default') {
-    // Mirrors `createDieResult` — a d1 always rolls 1, never a fumble.
-    return natural === 1 && die.sides > 1;
+    return natural === defaultFace && die.sides > 1;
   }
   return matchesCondition(die.result, threshold.operator, threshold.value);
 }

package/src/evaluator/modifiers/explode.ts

@@ -98,11 +98,14 @@ function canExplode(die: DieResult, hasVersusDc: boolean): boolean {
  * the value recorded on the appended die, which is the only thing standard
  * and penetrating explosions disagree about.
  *
+ * A die whose stored value differs from its raw roll records the raw face in
+ * `initialResult`, so `initialResult ?? result` recovers what was rolled.
+ *
  * `critical`/`fumble` are likewise derived from the raw roll — a penetrating
  * die that rolled its max face is still a crit even though it stores one less.
- * An inherited `cs`/`cf` keeps that: it is applied after `storeResult`, so an
- * explicit threshold reads the stored value, while the raw roll is handed over
- * for the `'default'` sentinel to read.
+ * A `cs`/`cf` rule keeps that: it is applied after `storeResult`, so an
+ * explicit threshold reads the stored value while the `'default'` sentinel
+ * reads `initialResult`.
  */
 function applyAppendingExplode(
   pool: DieResult[],
@@ -128,7 +131,13 @@ function applyAppendingExplode(
       const raw = rollExplosion(sides, rng, env);
       const die = createDieResult(sides, raw, ['exploded', 'kept']);
       die.result = storeResult(raw);
-      inheritCritRule(env, original, die, raw);
+      if (die.result !== raw) die.initialResult = raw;
+      // Only `extractNatural` reads this, and only inside a `vs`.
+      if (env.insideVersus) {
+        env.explosionDice ??= new WeakSet();
+        env.explosionDice.add(die);
+      }
+      inheritCritRule(env, original, die);
       result.push(die);
       lastRaw = raw;
       iterations += 1;

package/src/evaluator/modifiers/flags.ts

@@ -22,8 +22,8 @@ import type { DieModifier, DieResult } from '../../types.js';
  * `{1d20 vs 2d10, 1d4}>=5` must not count the DC faces as successes.
  *
  * ! Call this behind the shared `hasVersusDc` env flag, never bare. Unguarded
- * ! inside a per-die loop it cost 11-38% on notation that cannot carry the tag
- * ! (#281); the flag is `false` until a `vs` has actually tagged something.
+ * ! inside a per-die loop it cost 11-38% on notation that cannot carry the
+ * ! tag; the flag is `false` until a `vs` has actually tagged something.
  */
 export function isVersusDc(die: DieResult): boolean {
   return die.modifiers.includes('dc');
@@ -32,16 +32,22 @@ export function isVersusDc(die: DieResult): boolean {
 /** Kept/dropped selection flags — rebuilt by every keep/drop pass. */
 export const SELECTION_FLAGS: readonly DieModifier[] = ['kept', 'dropped'];
 
+/**
+ * Success-count tally flags — rebuilt by every counting pass. A group lets a
+ * second count reach a pool the first one already tagged (`{4d6>=5}<=2f5`);
+ * stripping these first is what keeps the outermost count the only one the
+ * tags describe.
+ */
+export const TALLY_FLAGS: readonly DieModifier[] = ['success', 'failure'];
+
 /**
  * Selection flags plus the success-count tally flags. Stripped when a die
  * leaves the pool that tagged it (meta sub-expressions, dropped group
  * sub-rolls) so the top-level successes/failures scan cannot count it.
  */
 export const SELECTION_AND_TALLY_FLAGS: readonly DieModifier[] = [
-  'kept',
-  'dropped',
-  'success',
-  'failure',
+  ...SELECTION_FLAGS,
+  ...TALLY_FLAGS,
 ];
 
 /**
@@ -49,13 +55,7 @@ export const SELECTION_AND_TALLY_FLAGS: readonly DieModifier[] = [
  * into a parent. Meta operands nest (`((1d2)d4)d6`), so a die passes through
  * the merge once per level and the tag must be rebuilt, not appended.
  */
-export const META_MERGE_FLAGS: readonly DieModifier[] = [
-  'kept',
-  'dropped',
-  'success',
-  'failure',
-  'meta',
-];
+export const META_MERGE_FLAGS: readonly DieModifier[] = [...SELECTION_AND_TALLY_FLAGS, 'meta'];
 
 /** Selection flags plus `rerolled` — reassigned on every reroll pass. */
 export const REROLL_SLOT_FLAGS: readonly DieModifier[] = ['kept', 'dropped', 'rerolled'];