@yipe/dice 0.2.23 → 0.3.0

package/dist/index.js

@@ -1,12 +1,19 @@
-var __defProp = Object.defineProperty;
-var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
-var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+// src/common/errors.ts
+var DiceParseError = class _DiceParseError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "DiceParseError";
+    this.expression = options?.expression;
+    this.cause = options?.cause;
+    Object.setPrototypeOf(this, _DiceParseError.prototype);
+  }
+};
 
 // src/common/lru-cache.ts
 var LRUCache = class {
   constructor(maxSize = 1e3) {
     this.maxSize = maxSize;
-    __publicField(this, "cache", /* @__PURE__ */ new Map());
+    this.cache = /* @__PURE__ */ new Map();
   }
   get(key) {
     const value = this.cache.get(key);
@@ -58,15 +65,30 @@ var onPotentCantripOnly = ["pc"];
 // src/pmf/query.ts
 var _DiceQuery = class _DiceQuery {
   constructor(singles, combined, eps = EPS) {
-    __publicField(this, "singles");
-    __publicField(this, "combined");
-    __publicField(this, "_combinedWithAttr");
     this.singles = Array.isArray(singles) ? singles : [singles];
     if (this.singles.some((s) => s === void 0)) {
       throw new Error("DiceQuery contains undefined singles");
     }
-    const c = combined ?? PMF.convolveMany(this.singles);
-    this.combined = Math.abs(c.mass() - 1) <= eps ? c : c.normalize();
+    this._eps = eps;
+    this._combinedProvided = combined !== void 0;
+    if (combined !== void 0) {
+      this._combined = Math.abs(combined.mass() - 1) <= eps ? combined : combined.normalize();
+    }
+  }
+  /**
+   * The combined damage distribution of all single PMFs (their convolution),
+   * normalized to total probability 1.
+   *
+   * Computed lazily on first access and cached. Queries that only need
+   * additive statistics — {@link DiceQuery.mean}, {@link DiceQuery.variance},
+   * {@link DiceQuery.stddev} — never trigger this convolution.
+   */
+  get combined() {
+    if (this._combined === void 0) {
+      const c = PMF.convolveMany(this.singles);
+      this._combined = Math.abs(c.mass() - 1) <= this._eps ? c : c.normalize();
+    }
+    return this._combined;
   }
   /**
    * Returns a new PMF with damage attribution metadata populated.
@@ -91,6 +113,10 @@ var _DiceQuery = class _DiceQuery {
     if (this._combinedWithAttr) {
       return this._combinedWithAttr;
     }
+    if (this.singles.every((pmf) => pmf.hasAttribution())) {
+      this._combinedWithAttr = this.combined;
+      return this._combinedWithAttr;
+    }
     const singlesWithAttr = this.singles.map((pmf) => pmf.withAttribution());
     const combined = PMF.convolveMany(singlesWithAttr, this.combined.epsilon);
     const normalized = Math.abs(combined.mass() - 1) <= this.combined.epsilon ? combined : combined.normalize();
@@ -104,11 +130,18 @@ var _DiceQuery = class _DiceQuery {
    * Use case: "What's my average damage per round?"
    */
   mean() {
-    let totalSum = 0;
-    for (const [damageValue, probabilityBin] of this.combined) {
-      totalSum += damageValue * probabilityBin.p;
+    if (this._combinedProvided) {
+      let m = 0;
+      for (const [damageValue, bin] of this.combined) m += damageValue * bin.p;
+      return m;
+    }
+    let totalMean = 0;
+    for (const single of this.singles) {
+      const mass = single.mass();
+      if (mass <= 0) continue;
+      totalMean += Math.abs(mass - 1) <= this._eps ? single.mean() : single.mean() / mass;
     }
-    return totalSum;
+    return totalMean;
   }
   /**
    * Returns the variance of the damage distribution.
@@ -118,13 +151,33 @@ var _DiceQuery = class _DiceQuery {
    * High variance means higher risk/reward. Lower variance means more consistent damage.
    */
   variance() {
-    const meanValue = this.mean();
-    let varianceSum = 0;
-    for (const [damageValue, probabilityBin] of this.combined) {
-      const deviationFromMean = damageValue - meanValue;
-      varianceSum += deviationFromMean * deviationFromMean * probabilityBin.p;
+    if (this._combinedProvided) {
+      const mu = this.mean();
+      let v = 0;
+      for (const [damageValue, bin] of this.combined) {
+        const dev = damageValue - mu;
+        v += dev * dev * bin.p;
+      }
+      return v;
+    }
+    let totalVariance = 0;
+    for (const single of this.singles) {
+      const mass = single.mass();
+      if (mass <= 0) continue;
+      if (Math.abs(mass - 1) <= this._eps) {
+        totalVariance += single.variance();
+      } else {
+        let mu = 0;
+        for (const [d, b] of single) mu += d * (b.p / mass);
+        let v = 0;
+        for (const [d, b] of single) {
+          const dev = d - mu;
+          v += dev * dev * (b.p / mass);
+        }
+        totalVariance += v;
+      }
     }
-    return varianceSum;
+    return totalVariance;
   }
   /**
    * Returns the standard deviation of the damage distribution.
@@ -136,6 +189,10 @@ var _DiceQuery = class _DiceQuery {
   stddev() {
     return Math.sqrt(this.variance());
   }
+  /** Alias of {@link DiceQuery.stddev}, matching {@link PMF.stdev}. */
+  stdev() {
+    return this.stddev();
+  }
   /**
    * Returns the Cumulative Distribution Function.
    */
@@ -226,20 +283,49 @@ var _DiceQuery = class _DiceQuery {
     return this.combined.max();
   }
   singleProb(diceIndex, label) {
+    const single = this.singles[diceIndex];
     let probabilitySum = 0;
-    for (const [, probabilityBin] of this.singles[diceIndex]) {
+    for (const [, probabilityBin] of single) {
       probabilitySum += probabilityBin.count[label] || 0;
     }
-    return probabilitySum;
+    const mass = single.mass();
+    return mass > 0 ? probabilitySum / mass : 0;
+  }
+  /**
+   * Full count distribution [P(0), P(1), …, P(n)] for "an attack succeeds if it
+   * carries ANY of `labels`", over the n independent singles.
+   *
+   * Each single's per-event success probability is the Poisson-binomial
+   * marginal P(≥1 of labels) from {@link probabilityOf} (i.e. probAtLeastOne),
+   * computed exactly once. The binomial DP then runs once to produce the whole
+   * distribution, so the array-label paths of probExactlyK / probAtLeastK /
+   * probAtMostK can slice or sum from it instead of rebuilding a DiceQuery and
+   * re-running the DP per requested k.
+   */
+  countDistribution(labels) {
+    const n = this.singles.length;
+    const successProbabilities = this.singles.map(
+      (single) => new _DiceQuery([single]).probabilityOf(labels)
+    );
+    const dist = new Array(n + 1).fill(0);
+    dist[0] = 1;
+    for (const successProb of successProbabilities) {
+      for (let outcomeCount = n; outcomeCount >= 1; outcomeCount--) {
+        dist[outcomeCount] = dist[outcomeCount] * (1 - successProb) + dist[outcomeCount - 1] * successProb;
+      }
+      dist[0] *= 1 - successProb;
+    }
+    return dist;
   }
   probAtLeastK(labels, k) {
     const L = Array.isArray(labels) ? [...new Set(labels)] : [labels];
     const n = this.singles.length;
     if (k <= 0) return 1;
     if (k > n) return 0;
+    const dist = this.countDistribution(L);
     let tail = 0;
     for (let i = k; i <= n; i++) {
-      tail += this.probExactlyK(L, i);
+      tail += dist[i];
     }
     if (tail < 0) return 0;
     if (tail > 1) return 1;
@@ -271,9 +357,12 @@ var _DiceQuery = class _DiceQuery {
       for (const label of labels) {
         combinedProbability += this.singleProb(diceIndex, label);
       }
+      if (combinedProbability < 0) combinedProbability = 0;
+      else if (combinedProbability > 1) combinedProbability = 1;
       productOfNonOccurrence *= 1 - combinedProbability;
     }
-    return 1 - productOfNonOccurrence;
+    const result = 1 - productOfNonOccurrence;
+    return result < 0 ? 0 : result > 1 ? 1 : result;
   }
   /**
    * Computes binomial probabilities for exactly 0, 1, 2, ..., maxK occurrences of a label.
@@ -314,7 +403,7 @@ var _DiceQuery = class _DiceQuery {
    * Array examples:
    * - probExactlyK(['hit', 'crit'], 2) = probability exactly 2 attacks succeed
    * - probExactlyK(['hit', 'crit'], 1) = probability exactly 1 attack succeeds
-   * - probExactlyK(['miss', 'missNone'], 0) = probability no attacks miss
+   * - probExactlyK(['missDamage', 'missNone'], 0) = probability no attacks miss
    *
    * Use cases:
    * - "What's the chance exactly one of my attacks hits?"
@@ -329,19 +418,8 @@ var _DiceQuery = class _DiceQuery {
       const probabilityArray = this.computeBinomialProbabilities(labels, k);
       return probabilityArray[k];
     }
-    const successProbabilities = this.singles.map((single) => {
-      const singleQuery = new _DiceQuery([single]);
-      return singleQuery.probabilityOf(labels);
-    });
-    const binomialProbs = new Array(k + 1).fill(0);
-    binomialProbs[0] = 1;
-    for (const successProb of successProbabilities) {
-      for (let outcomeCount = k; outcomeCount >= 1; outcomeCount--) {
-        binomialProbs[outcomeCount] = binomialProbs[outcomeCount] * (1 - successProb) + binomialProbs[outcomeCount - 1] * successProb;
-      }
-      binomialProbs[0] *= 1 - successProb;
-    }
-    return binomialProbs[k];
+    const dist = this.countDistribution(labels);
+    return k >= 0 && k < dist.length ? dist[k] : 0;
   }
   /**
    * Returns the probability that AT MOST K attacks result in the specified outcome(s).
@@ -349,7 +427,7 @@ var _DiceQuery = class _DiceQuery {
    * Single label examples:
    * - probAtMostK('hit', 1) = probability 0 or 1 attacks hit (at most 1)
    * - probAtMostK('crit', 0) = probability no attacks crit
-   * - probAtMostK('miss', 2) = probability at most 2 attacks miss
+   * - probAtMostK('missDamage', 2) = probability at most 2 attacks miss
    *
    * Array examples:
    * - probAtMostK(['hit', 'crit'], 1) = probability at most 1 attack succeeds
@@ -370,9 +448,11 @@ var _DiceQuery = class _DiceQuery {
       }
       return cumulativeSum2;
     }
+    const dist = this.countDistribution(labels);
+    const upper = Math.min(k, dist.length - 1);
     let cumulativeSum = 0;
-    for (let outcomeCount = 0; outcomeCount <= k; outcomeCount++) {
-      cumulativeSum += this.probExactlyK(labels, outcomeCount);
+    for (let outcomeCount = 0; outcomeCount <= upper; outcomeCount++) {
+      cumulativeSum += dist[outcomeCount];
     }
     return cumulativeSum;
   }
@@ -418,7 +498,7 @@ var _DiceQuery = class _DiceQuery {
    *
    * Array examples:
    * - damageStatsFrom(['hit', 'crit']) = damage range when at least one attack succeeds
-   * - damageStatsFrom(['miss', 'missNone']) = damage range when at least one attack misses
+   * - damageStatsFrom(['missDamage', 'missNone']) = damage range when at least one attack misses
    *
    * Tactical Use Cases:
    * - "Given that I don't completely whiff (99% of turns), what damage should I expect?"
@@ -436,6 +516,12 @@ var _DiceQuery = class _DiceQuery {
    * This includes mixed scenarios (2 hits + 1 crit, 3 hits + 1 miss, etc.) which
    * occur far more frequently than pure scenarios. For pure scenarios, use combinedDamageStats.
    *
+   * KNOWN LIMITATION (multi-attack, single label): the returned `count` is an
+   * EXPECTED COUNT (E[#label], so > 1 for N≥2 attacks, not a probability), and
+   * `avg` is the size-biased conditional mean E[dmg·#label]/E[#label] rather than
+   * E[dmg | the label occurs]. For a single attack both are the plain
+   * conditional figures. Use {@link probAtLeastOne} for the scenario probability.
+   *
    * @example
    * // High-level tactical planning
    * const successStats = query.damageStatsFrom('hit')
@@ -540,7 +626,8 @@ var _DiceQuery = class _DiceQuery {
     };
   }
   /**
-   * Returns the probability that a result includes ANY of the specified labels.
+   * Returns the probability that at least one attack carries ANY of the
+   * specified labels (the marginal P(≥1) across the independent attacks).
    *
    * Examples:
    * - `query.probabilityOf('hit')` → 0.88 (probability at least one hit occurs)
@@ -549,25 +636,15 @@ var _DiceQuery = class _DiceQuery {
    * Use cases:
    * - "What's the chance my resolution includes a success label?"
    * - "How likely am I to get any hits or crits across all attacks?"
+   *
+   * Note: this must NOT be computed by summing `combined` bin probabilities. A
+   * single combined damage total is reachable by many outcome combinations and
+   * a bin can hold several labels at once, so summing `bin.p` over bins that
+   * contain a label over-counts. The correct marginal is the Poisson-binomial
+   * complement over the per-attack probabilities, i.e. {@link probAtLeastOne}.
    */
   probabilityOf(labels) {
-    if (typeof labels === "string") {
-      labels = [labels];
-    }
-    let totalProbability = 0;
-    for (const [, probabilityBin] of this.combined) {
-      let binHasAnyLabel = false;
-      for (const label of labels) {
-        if (probabilityBin.count[label] && probabilityBin.count[label] > 0) {
-          binHasAnyLabel = true;
-          break;
-        }
-      }
-      if (binHasAnyLabel) {
-        totalProbability += probabilityBin.p;
-      }
-    }
-    return totalProbability;
+    return this.probAtLeastOne(labels);
   }
   /**
    * Returns the probability of missing (any type of miss).
@@ -627,10 +704,6 @@ var _DiceQuery = class _DiceQuery {
    */
   toStackedChartData(labels = [], epsilon = EPS) {
     const damageValues = this.combined.support();
-    damageValues.map((dmg) => {
-      const bin = this.combined.map.get(dmg);
-      return labels.reduce((sum, lab) => sum + (bin.count[lab] || 0), 0);
-    });
     const datasets = labels.map((outcomeLabel) => ({
       label: outcomeLabel,
       data: damageValues.map((dmg) => {
@@ -1067,6 +1140,16 @@ var _DiceQuery = class _DiceQuery {
    * Snapshot of the distribution in the exact shape the UI consumes.
    * - outcome probabilities are "at least one" (and equal to "all" for a single PMF)
    * - damageRange is conditional on the outcome occurring
+   *
+   * The outcome probabilities use the correct Poisson-binomial marginals
+   * (`atLeastOneProbability` = P(≥1 attack has it), `allProbability` = P(all do)),
+   * so they are always valid probabilities in [0,1].
+   *
+   * KNOWN LIMITATION (multi-attack): `damageRange.avg` is still aggregated from
+   * the combined PMF's `count`, which the convolution accumulates as an EXPECTED
+   * COUNT, so for N≥2 attacks it is the size-biased mean E[dmg·#label]/E[#label]
+   * rather than a clean conditional expectation. It is correct for a single
+   * attack.
    */
   snapshot(order) {
     const discovered = /* @__PURE__ */ new Set();
@@ -1088,10 +1171,8 @@ var _DiceQuery = class _DiceQuery {
       );
     }
     const rows = this.toLabeledTable(outcomes);
-    const totals = /* @__PURE__ */ new Map();
     const rangeAcc = /* @__PURE__ */ new Map();
     for (const ot of outcomes) {
-      totals.set(ot, 0);
       rangeAcc.set(ot, { sum: 0, mass: 0 });
     }
     for (const row of rows) {
@@ -1099,7 +1180,6 @@ var _DiceQuery = class _DiceQuery {
       for (const ot of outcomes) {
         const p = row[ot] || 0;
         if (p <= 0) continue;
-        totals.set(ot, (totals.get(ot) || 0) + p);
         const r = rangeAcc.get(ot);
         r.sum += dmg * p;
         r.mass += p;
@@ -1107,15 +1187,14 @@ var _DiceQuery = class _DiceQuery {
         if (r.max === void 0 || dmg > r.max) r.max = dmg;
       }
     }
+    const n = this.singles.length;
     const outcomeMap = /* @__PURE__ */ new Map();
     for (const ot of outcomes) {
-      const total = totals.get(ot) || 0;
       const r = rangeAcc.get(ot);
       const avg = r.mass > 0 ? r.sum / r.mass : 0;
       outcomeMap.set(ot, {
-        atLeastOneProbability: total,
-        allProbability: total,
-        // single aggregate PMF: same value
+        atLeastOneProbability: this.probAtLeastOne(ot),
+        allProbability: this.probAtLeastK(ot, n),
         damageRange: { min: r.min ?? 0, avg, max: r.max ?? 0 }
       });
     }
@@ -1300,11 +1379,11 @@ var _DiceQuery = class _DiceQuery {
     return [a, b, any, none];
   }
 };
-__publicField(_DiceQuery, "DEFAULT_OUTCOMES", [
+_DiceQuery.DEFAULT_OUTCOMES = [
   "hit",
   "crit",
   "missNone"
-]);
+];
 var DiceQuery = _DiceQuery;
 var pmfCache = new LRUCache(1e3);
 var _PMF = class _PMF {
@@ -1314,14 +1393,6 @@ var _PMF = class _PMF {
     this.normalized = normalized;
     this.identifier = identifier;
     this._preservedProvenance = _preservedProvenance;
-    // Cached computed values
-    __publicField(this, "_support");
-    __publicField(this, "_min");
-    __publicField(this, "_max");
-    __publicField(this, "_totalMass");
-    __publicField(this, "_mean");
-    __publicField(this, "_variance");
-    __publicField(this, "_stdev");
   }
   static empty(epsilon = EPS, identifier = "empty") {
     return new _PMF(/* @__PURE__ */ new Map(), epsilon, false, identifier);
@@ -1361,8 +1432,14 @@ var _PMF = class _PMF {
     if (p === 1) return successPMF.scaleMass(1);
     const eps = successPMF.epsilon ?? failurePMF.epsilon;
     const id = `branch(${failurePMF.identifier}*${q.toFixed(6)} + ${successPMF.identifier}*${p.toFixed(6)})`;
-    const out = _PMF.empty(eps, id).addScaled(failurePMF, q).addScaled(successPMF, p);
-    return out;
+    const resultMap = /* @__PURE__ */ new Map();
+    for (const [damageValue, bin] of failurePMF.map) {
+      _PMF.mergeInto(resultMap, damageValue, _PMF.scaleBin(bin, q));
+    }
+    for (const [damageValue, bin] of successPMF.map) {
+      _PMF.mergeInto(resultMap, damageValue, _PMF.scaleBin(bin, p));
+    }
+    return new _PMF(resultMap, eps, false, id);
   }
   /**
    * withProbability()
@@ -1410,8 +1487,8 @@ var _PMF = class _PMF {
    * @param fallback PMF to apply when this PMF is *not* selected.
    * @returns A new PMF representing the weighted mixture of this PMF and the fallback.
    */
-  gate(p, zero) {
-    return _PMF.branch(this, zero, p);
+  gate(p, fallback) {
+    return _PMF.branch(this, fallback, p);
   }
   /**
    * PMF.exclusive()
@@ -1494,13 +1571,23 @@ var _PMF = class _PMF {
    *
    * @returns New PMF with attr field populated in each bin
    */
-  withAttribution() {
+  /**
+   * Returns true if this PMF already carries damage attribution metadata.
+   *
+   * Only the first positive-damage bin is inspected (parser-generated PMFs
+   * populate `attr` uniformly), so this is O(1) in practice.
+   */
+  hasAttribution() {
     for (const [damage, bin] of this.map) {
       if (damage !== 0 && bin.attr && Object.keys(bin.attr).length > 0) {
-        return this;
+        return true;
       }
       if (damage > 0) break;
     }
+    return false;
+  }
+  withAttribution() {
+    if (this.hasAttribution()) return this;
     const newMap = /* @__PURE__ */ new Map();
     for (const [damage, bin] of this.map) {
       const attr = {};
@@ -1617,7 +1704,7 @@ var _PMF = class _PMF {
    */
   replicate(n) {
     if (!Number.isInteger(n) || n <= 0) {
-      throw new Error("combineN(n): n must be a positive integer");
+      throw new Error("replicate(n): n must be a positive integer");
     }
     if (n === 1) return [this];
     return Array.from({ length: n }, () => this);
@@ -1649,7 +1736,6 @@ var _PMF = class _PMF {
     if (normalizationFactor === 0) return this;
     const normalizedMap = /* @__PURE__ */ new Map();
     for (const [damageValue, probabilityBin] of this.map) {
-      const normalizedProbability = probabilityBin.p / normalizationFactor;
       const normalizedCount = {};
       for (const labelKey in probabilityBin.count) {
         normalizedCount[labelKey] = probabilityBin.count[labelKey] / normalizationFactor;
@@ -1662,7 +1748,7 @@ var _PMF = class _PMF {
         }
       }
       normalizedMap.set(damageValue, {
-        p: normalizedProbability,
+        p: probabilityBin.p / normalizationFactor,
         count: normalizedCount,
         attr: normalizedAttributes
       });
@@ -1685,22 +1771,23 @@ var _PMF = class _PMF {
     for (const [damageValue, probabilityBin] of this.map) {
       const shouldKeep = probabilityBin.p >= eps || keepFinalBin && damageValue === maxKey;
       if (!shouldKeep) continue;
-      for (const labelKey in probabilityBin.count) {
-        if (Math.abs(probabilityBin.count[labelKey] || 0) < eps) {
-          delete probabilityBin.count[labelKey];
+      const cleanedBin = _PMF.cloneBin(probabilityBin);
+      for (const labelKey in cleanedBin.count) {
+        if (Math.abs(cleanedBin.count[labelKey] || 0) < eps) {
+          delete cleanedBin.count[labelKey];
         }
       }
-      if (probabilityBin.attr) {
-        for (const labelKey in probabilityBin.attr) {
-          if (Math.abs(probabilityBin.attr[labelKey] || 0) < eps) {
-            delete probabilityBin.attr[labelKey];
+      if (cleanedBin.attr) {
+        for (const labelKey in cleanedBin.attr) {
+          if (Math.abs(cleanedBin.attr[labelKey] || 0) < eps) {
+            delete cleanedBin.attr[labelKey];
           }
         }
-        if (Object.keys(probabilityBin.attr).length === 0) {
-          probabilityBin.attr = void 0;
+        if (Object.keys(cleanedBin.attr).length === 0) {
+          cleanedBin.attr = void 0;
         }
       }
-      compactedMap.set(damageValue, probabilityBin);
+      compactedMap.set(damageValue, cleanedBin);
     }
     return new _PMF(compactedMap, eps, this.normalized, this.identifier);
   }
@@ -1767,14 +1854,33 @@ var _PMF = class _PMF {
     }
     return this._stdev;
   }
+  /** Deep-copies a Bin, cloning its count and (optional) attr maps. */
+  static cloneBin(bin) {
+    return {
+      p: bin.p,
+      count: { ...bin.count },
+      attr: bin.attr ? { ...bin.attr } : void 0
+    };
+  }
+  /** Returns a new Bin with p, count, and attr all multiplied by `factor`. */
+  static scaleBin(bin, factor) {
+    const count = {};
+    for (const k in bin.count) {
+      count[k] = bin.count[k] * factor;
+    }
+    let attr;
+    if (bin.attr) {
+      attr = {};
+      for (const k in bin.attr) {
+        attr[k] = bin.attr[k] * factor;
+      }
+    }
+    return { p: bin.p * factor, count, attr };
+  }
   static mergeInto(destinationMap, damageValue, binToAdd) {
     const existingBin = destinationMap.get(damageValue);
     if (!existingBin) {
-      destinationMap.set(damageValue, {
-        p: binToAdd.p,
-        count: { ...binToAdd.count },
-        attr: binToAdd.attr ? { ...binToAdd.attr } : void 0
-      });
+      destinationMap.set(damageValue, _PMF.cloneBin(binToAdd));
       return;
     }
     existingBin.p += binToAdd.p;
@@ -1805,29 +1911,14 @@ var _PMF = class _PMF {
     if (probability === 0) return this;
     const resultMap = /* @__PURE__ */ new Map();
     for (const [dmg, bin] of this.map) {
-      resultMap.set(dmg, {
-        p: bin.p,
-        count: { ...bin.count },
-        attr: bin.attr ? { ...bin.attr } : void 0
-      });
+      resultMap.set(dmg, _PMF.cloneBin(bin));
     }
     for (const [damageValue, probabilityBin] of branch.map) {
-      const scaledCount = {};
-      for (const k in probabilityBin.count) {
-        scaledCount[k] = probability * probabilityBin.count[k];
-      }
-      let scaledAttributes;
-      if (probabilityBin.attr) {
-        scaledAttributes = {};
-        for (const k in probabilityBin.attr) {
-          scaledAttributes[k] = probability * probabilityBin.attr[k];
-        }
-      }
-      _PMF.mergeInto(resultMap, damageValue, {
-        p: probability * probabilityBin.p,
-        count: scaledCount,
-        attr: scaledAttributes
-      });
+      _PMF.mergeInto(
+        resultMap,
+        damageValue,
+        _PMF.scaleBin(probabilityBin, probability)
+      );
     }
     return new _PMF(
       resultMap,
@@ -1840,22 +1931,7 @@ var _PMF = class _PMF {
     if (factor === 1) return this;
     const scaledMap = /* @__PURE__ */ new Map();
     for (const [damageValue, probabilityBin] of this.map) {
-      const scaledCount = {};
-      for (const labelKey in probabilityBin.count) {
-        scaledCount[labelKey] = probabilityBin.count[labelKey] * factor;
-      }
-      let scaledAttributes;
-      if (probabilityBin.attr) {
-        scaledAttributes = {};
-        for (const labelKey in probabilityBin.attr) {
-          scaledAttributes[labelKey] = probabilityBin.attr[labelKey] * factor;
-        }
-      }
-      scaledMap.set(damageValue, {
-        p: probabilityBin.p * factor,
-        count: scaledCount,
-        attr: scaledAttributes
-      });
+      scaledMap.set(damageValue, _PMF.scaleBin(probabilityBin, factor));
     }
     return new _PMF(
       scaledMap,
@@ -1868,11 +1944,11 @@ var _PMF = class _PMF {
     const transformedMap = /* @__PURE__ */ new Map();
     for (const [originalDamage, probabilityBin] of this.map) {
       const transformedDamage = damageTransformFunction(originalDamage);
-      _PMF.mergeInto(transformedMap, transformedDamage, {
-        p: probabilityBin.p,
-        count: { ...probabilityBin.count },
-        attr: probabilityBin.attr ? { ...probabilityBin.attr } : void 0
-      });
+      _PMF.mergeInto(
+        transformedMap,
+        transformedDamage,
+        _PMF.cloneBin(probabilityBin)
+      );
     }
     return new _PMF(
       transformedMap,
@@ -1887,14 +1963,21 @@ var _PMF = class _PMF {
   }
   getPMFCombineCacheKey(p1, p2, eps, raw) {
     const [id1, id2] = [p1.identifier, p2.identifier].sort();
-    const fp = (x) => {
-      const m = x.mass().toFixed(12);
-      const n = x.map.size;
+    return `v4:${raw ? "RAW" : "N"}:${id1}+${id2}@${eps}|${p1.fingerprint()}|${p2.fingerprint()}`;
+  }
+  /**
+   * A small content fingerprint (mass + bin count + face sum) so convolution
+   * cache keys change if the underlying numbers do. Memoized because a PMF is
+   * immutable once constructed — this avoids re-summing every key on each
+   * convolve() call (including cache hits).
+   */
+  fingerprint() {
+    if (this._fingerprint === void 0) {
       let faceSum = 0;
-      for (const k of x.map.keys()) faceSum += k;
-      return `${m}|${n}|${faceSum}`;
-    };
-    return `v4:${raw ? "RAW" : "N"}:${id1}+${id2}@${eps}|${fp(p1)}|${fp(p2)}`;
+      for (const k of this.map.keys()) faceSum += k;
+      this._fingerprint = `${this.mass().toFixed(12)}|${this.map.size}|${faceSum}`;
+    }
+    return this._fingerprint;
   }
   convolve(other, eps, raw = false) {
     const epsilon = eps ?? this.epsilon;
@@ -1907,25 +1990,34 @@ var _PMF = class _PMF {
     if (cached) return cached;
     const combinedMap = /* @__PURE__ */ new Map();
     for (const [aVal, aBin] of A.map) {
+      const ap = aBin.p;
+      const aCount = aBin.count;
+      const aAttr = aBin.attr;
       for (const [bVal, bBin] of B.map) {
-        const p = aBin.p * bBin.p;
+        const bp = bBin.p;
         const dmg = aVal + bVal;
-        const count = {};
-        for (const k in aBin.count)
-          count[k] = (count[k] || 0) + aBin.count[k] * bBin.p;
+        let dest = combinedMap.get(dmg);
+        if (dest === void 0) {
+          dest = { p: 0, count: {} };
+          combinedMap.set(dmg, dest);
+        }
+        dest.p += ap * bp;
+        const dc = dest.count;
+        for (const k in aCount) dc[k] = (dc[k] || 0) + aCount[k] * bp;
         for (const k in bBin.count)
-          count[k] = (count[k] || 0) + bBin.count[k] * aBin.p;
-        let attr;
-        if (aBin.attr || bBin.attr) {
-          attr = {};
-          if (aBin.attr)
-            for (const k in aBin.attr)
-              attr[k] = (attr[k] || 0) + aBin.attr[k] * bBin.p;
+          dc[k] = (dc[k] || 0) + bBin.count[k] * ap;
+        if (aAttr || bBin.attr) {
+          let da = dest.attr;
+          if (da === void 0) {
+            da = {};
+            dest.attr = da;
+          }
+          if (aAttr)
+            for (const k in aAttr) da[k] = (da[k] || 0) + aAttr[k] * bp;
           if (bBin.attr)
             for (const k in bBin.attr)
-              attr[k] = (attr[k] || 0) + bBin.attr[k] * aBin.p;
+              da[k] = (da[k] || 0) + bBin.attr[k] * ap;
         }
-        _PMF.mergeInto(combinedMap, dmg, { p, count, attr });
       }
     }
     let result = new _PMF(
@@ -1936,10 +2028,10 @@ var _PMF = class _PMF {
     );
     const mExp = (raw ? A.mass() : 1) * (raw ? B.mass() : 1);
     const mGot = result.mass();
-    if (mExp !== 0 && Math.abs(mGot - mExp) > epsilon) {
+    if (mExp !== 0 && mGot !== 0 && Math.abs(mGot - mExp) > epsilon) {
       result = result.scaleMass(mExp / mGot);
     }
-    if (!raw && Math.abs(result.mass() - 1) > epsilon)
+    if (!raw && mGot !== 0 && Math.abs(result.mass() - 1) > epsilon)
       result = result.normalize();
     pmfCache?.set(cacheKey, result);
     return result;
@@ -1948,27 +2040,6 @@ var _PMF = class _PMF {
   combineRaw(other, eps) {
     return this.convolve(other, eps, true);
   }
-  // Collapse repeated identical PMFs using power() and return a sorted list
-  // Temporarily disabled for now. This was used for a performance optimization, but can lose data provenance.
-  //   private static collapseIdentical(pmfList: PMF[], eps: number): PMF[] {
-  //     const grouped = new Map<string, { pmf: PMF; count: number }>();
-  //     for (const pmf of pmfList) {
-  //       const id = pmf.identifier;
-  //       const g = grouped.get(id);
-  //       if (g) g.count++;
-  //       else grouped.set(id, { pmf, count: 1 });
-  //     }
-  //     if (grouped.size >= pmfList.length) return pmfList;
-  //     const collapsed: PMF[] = [];
-  //     for (const { pmf, count } of grouped.values()) {
-  //       collapsed.push(count > 1 ? pmf.power(count, eps) : pmf);
-  //     }
-  //     // Stable order for better cache locality
-  //     collapsed.sort((a, b) =>
-  //       a.identifier < b.identifier ? -1 : a.identifier > b.identifier ? 1 : 0
-  //     );
-  //     return collapsed;
-  //   }
   // Reduce a list of PMFs by left-folding convolve() with the given eps
   static reduceConvolveLeft(pmfList, eps) {
     let result = pmfList[0];
@@ -1992,12 +2063,23 @@ var _PMF = class _PMF {
     if (pmfList.length === 1) return pmfList[0];
     return _PMF.reduceConvolveLeft(pmfList, eps);
   }
+  /**
+   * Returns a plain, JSON-serializable representation of this PMF.
+   *
+   * Follows the standard `toJSON` contract, so `JSON.stringify(pmf)` produces
+   * the expected output (no double-encoding). Use {@link PMF.fromJSON} to
+   * reconstruct, or {@link PMF.toJSONString} if you need the string directly.
+   */
   toJSON() {
-    return JSON.stringify({
+    return {
       bins: [...this.map.entries()],
       normalized: this.normalized,
       identifier: this.identifier
-    });
+    };
+  }
+  /** Serializes this PMF to a JSON string (equivalent to `JSON.stringify(pmf)`). */
+  toJSONString() {
+    return JSON.stringify(this);
   }
   static fromJSON(jsonData) {
     return new _PMF(
@@ -2068,7 +2150,6 @@ var _PMF = class _PMF {
     }
     return new _PMF(prunedMap, epsRel, false, `prune(${this.identifier})`);
   }
-  /** NEW - REVIEW IF THESE ARE USEFUL OR DUPLCIATIVE?  */
   /** Probability mass at exactly x. */
   pAt(x) {
     return this.map.get(x)?.p ?? 0;
@@ -2150,9 +2231,8 @@ var _PMF = class _PMF {
   }
   tailProbGE(t) {
     let s = 0;
-    for (const [x, rec] of this) {
-      const p = typeof rec === "number" ? rec : rec.p;
-      if (p > 0 && x >= t) s += p;
+    for (const [x, bin] of this) {
+      if (bin.p > 0 && x >= t) s += bin.p;
     }
     return s;
   }
@@ -2213,6 +2293,11 @@ var _PMF = class _PMF {
    *  - pAny: Probability that at least one success occurred
    */
   static firstSuccessWeights(pSuccess, pSpecial, n) {
+    if (!Number.isFinite(pSuccess) || !Number.isFinite(pSpecial) || pSuccess < 0 || pSuccess > 1 || pSpecial < 0 || pSpecial - pSuccess > EPS) {
+      throw new Error(
+        `firstSuccessWeights: require 0 <= pSpecial <= pSuccess <= 1 (got pSuccess=${pSuccess}, pSpecial=${pSpecial})`
+      );
+    }
     const pFail = 1 - pSuccess;
     const pFailAll = Math.pow(pFail, n);
     const pAny = 1 - pFailAll;
@@ -2228,13 +2313,12 @@ var _PMF = class _PMF {
     const round = (x) => rounding === "floor" ? Math.floor(x) : rounding === "ceil" ? Math.ceil(x) : rounding === "round" ? Math.round(x) : x;
     const probs = /* @__PURE__ */ new Map();
     const counts = /* @__PURE__ */ new Map();
-    for (const [v, rec] of this) {
-      if (Math.abs(rec.p) < eps) continue;
+    for (const [v, bin] of this) {
+      if (Math.abs(bin.p) < eps) continue;
       const u = round(f(v));
-      probs.set(u, (probs.get(u) ?? 0) + rec.p);
+      probs.set(u, (probs.get(u) ?? 0) + bin.p);
       if (preserveCounts) {
-        const rec2 = this.map.get(v);
-        const src = typeof rec2 === "number" ? void 0 : rec2?.count;
+        const src = bin.count;
         if (src) {
           const dest = counts.get(u) ?? {};
           for (const k in src) {
@@ -2287,17 +2371,20 @@ var _PMF = class _PMF {
   }
 };
 // Unique ID generator for anonymous PMFs to avoid cache key collisions
-__publicField(_PMF, "__anonIdCounter", 1);
+_PMF.__anonIdCounter = 1;
 var PMF = _PMF;
 
 // src/parser/dice.ts
+var MAX_BINARY_OUTCOMES = 1e8;
 var Dice = class _Dice {
   constructor(x = 0) {
-    __publicField(this, "faces", {});
-    __publicField(this, "privateData", {});
-    __publicField(this, "outcomeData", {});
-    __publicField(this, "hasHitDistributionCalculated", false);
-    __publicField(this, "identifier");
+    this.faces = {};
+    this.privateData = {};
+    // Partial: the object starts empty and gains keys as outcomes are recorded,
+    // so the type must not claim every OutcomeType is present. (Previously typed
+    // as a full Record via an `as` cast, which lied about missing keys.)
+    this.outcomeData = {};
+    this.hasHitDistributionCalculated = false;
     if (x <= 0) return;
     for (let i = 1; i <= x; i++) {
       this.faces[i] = 1;
@@ -2348,27 +2435,27 @@ var Dice = class _Dice {
   // TODO this can be private later if we change how testing works
   calculateHitDistribution() {
     const hitValues = {};
+    const subtractedOutcomes = [
+      this.outcomeData.crit,
+      this.outcomeData.missNone,
+      this.outcomeData.missDamage,
+      this.outcomeData.saveHalf,
+      this.outcomeData.saveFail,
+      this.outcomeData.pc
+    ];
     for (const [face, totalCount] of Object.entries(this.faces)) {
       const numFace = Number(face);
       let hitCount = totalCount;
-      for (const outcomeType of [
-        "crit",
-        "missNone",
-        "missDamage",
-        "saveHalf",
-        "saveFail",
-        "pc"
-      ]) {
-        const distribution = this.getOutcomeDistribution(outcomeType);
-        if (distribution && distribution[numFace]) {
-          hitCount -= distribution[numFace];
+      for (const distribution of subtractedOutcomes) {
+        const outcomeCount = distribution?.[numFace];
+        if (outcomeCount) {
+          hitCount -= outcomeCount;
         }
       }
       if (numFace === 0) {
         hitCount = 0;
       }
       if (hitCount < 0) {
-        console.error("hitCount is <=0?", face, totalCount, hitCount);
         hitCount = 0;
       }
       hitValues[numFace] = hitCount;
@@ -2387,13 +2474,18 @@ var Dice = class _Dice {
     const result = diceConstructor ? diceConstructor() : new _Dice();
     const isScalar = typeof other === "number";
     const keys1 = this.keys();
+    const keys2 = isScalar ? [] : other.keys();
+    if (!isScalar && keys1.length * keys2.length > MAX_BINARY_OUTCOMES) {
+      throw new DiceParseError(
+        `Dice operation over ${keys1.length}\xD7${keys2.length} face pairs exceeds the maximum of ${MAX_BINARY_OUTCOMES}`
+      );
+    }
     for (const key1 of keys1) {
       const value1 = this.faces[key1];
       if (isScalar) {
         const resultKey = op(key1, other);
         result.increment(resultKey, value1);
       } else {
-        const keys2 = other.keys();
         for (const key2 of keys2) {
           const value2 = other.faces[key2];
           const resultKey = op(key1, key2);
@@ -2415,7 +2507,7 @@ var Dice = class _Dice {
     result.outcomeData = { ...this.outcomeData };
     return result;
   }
-  // PUBLIC FUNTIONS
+  // PUBLIC FUNCTIONS
   getFaceEntries() {
     return Object.entries(this.faces).map(([k, v]) => [Number(k), v]);
   }
@@ -2545,10 +2637,12 @@ var Dice = class _Dice {
   }
   reroll(toReroll) {
     const rerollDice = typeof toReroll === "number" ? _Dice.scalar(toReroll) : toReroll;
-    const removed = this.removeFaces(rerollDice.keys());
+    const rerollKeys = rerollDice.keys();
+    const rerollSet = new Set(rerollKeys);
+    const removed = this.removeFaces(rerollKeys);
     let result = new _Dice();
     for (const face of this.keys()) {
-      const wasRerolled = rerollDice.keys().includes(face);
+      const wasRerolled = rerollSet.has(face);
       result = result.combine(removed);
       if (wasRerolled) {
         result = result.combine(this);
@@ -2616,17 +2710,10 @@ var Dice = class _Dice {
     const missDistro = this.getOutcomeDistribution("missDamage") || {};
     const saveDistro = this.getOutcomeDistribution("saveHalf") || {};
     const pcDistro = this.getOutcomeDistribution("pc") || {};
-    let isSaveHalf = false;
-    for (const halfDamage of Object.keys(saveDistro).map(Number)) {
-      const fullDamage = halfDamage * 2;
-      if (fullDamage > 0 && hitDistro[fullDamage]) {
-        isSaveHalf = true;
-        break;
-      }
-    }
+    const isSaveHalf = Object.keys(saveDistro).length > 0;
     const isDCCheck = this.privateData.isDCCheck === true;
     const clampNonNeg = (x) => x < 0 && x > -1e-15 ? 0 : x;
-    for (const [faceStr, faceCountRaw] of Object.entries(this.getFaceMap())) {
+    for (const [faceStr, faceCountRaw] of Object.entries(this.faces)) {
       const face = Number(faceStr);
       const faceCount = Number(faceCountRaw);
       if (faceCount <= 0) continue;
@@ -2700,14 +2787,14 @@ var Dice = class _Dice {
       map.set(face, bin);
     }
     const identifier = this.identifier || "ERROR";
-    if (identifier === "ERROR") {
-      console.error("Dice identifier is undefined", this);
-    }
     return new PMF(map, numEpsilon, true, identifier).compact(numEpsilon, true);
   }
 };
 
 // src/parser/parser.ts
+var MAX_DIE_SIDES = 1e6;
+var MAX_DICE_COUNT = 1e4;
+var MAX_KEEP_OUTCOMES = 1e6;
 var parseCache = new LRUCache(1e3);
 var cachingEnabled = true;
 function setCachingEnabled(enabled) {
@@ -2728,20 +2815,21 @@ function parse(expression, n = 0) {
     if (cached) return cached;
   }
   const chars = [...cleaned];
-  let result = void 0;
+  let result;
   try {
     result = parseExpression(chars, n);
   } catch (error) {
-    throw new Error(`Cannot parse dice expression [${expression}]: ${error}`);
-  }
-  try {
-    result.privateData = result.privateData || {};
-    result.identifier = cleaned;
-  } catch {
+    throw new DiceParseError(
+      `Cannot parse dice expression [${expression}]: ${error}`,
+      { expression, cause: error }
+    );
   }
+  result.privateData = result.privateData || {};
+  result.identifier = cleaned;
   if (chars.length > 0) {
-    throw new Error(
-      `Unexpected token: '${chars[0]}' from expression: '${expression}'`
+    throw new DiceParseError(
+      `Unexpected token: '${chars[0]}' from expression: '${expression}'`,
+      { expression }
     );
   }
   const resultPMF = result.toPMF(-1);
@@ -2895,7 +2983,7 @@ function multiplyDiceByDice(d1, d2) {
   if (typeof d1 === "number") d1 = Dice.scalar(d1);
   if (typeof d2 === "number") d2 = Dice.scalar(d2);
   const result = new Dice();
-  const faces = {};
+  const faces = /* @__PURE__ */ new Map();
   let normalizationFactor = 1;
   for (const key of d1.keys()) {
     let face;
@@ -2903,17 +2991,21 @@ function multiplyDiceByDice(d1, d2) {
       continue;
     }
     if (d2.privateData.keep) {
+      const faceCount = d2.keys().length;
+      if (Math.pow(faceCount, key) > MAX_KEEP_OUTCOMES) {
+        throw new DiceParseError(
+          `Keep enumeration of ${faceCount}^${key} outcomes exceeds the maximum of ${MAX_KEEP_OUTCOMES}`
+        );
+      }
       const repeat = Array(key).fill(d2);
       face = opDice(repeat, d2.privateData.keep);
     } else {
       face = multiplyDice(key, d2);
     }
     normalizationFactor *= face.total();
-    faces[key] = face;
+    faces.set(key, face);
   }
-  for (const key of Object.keys(faces)) {
-    const k = parseFloat(key);
-    const face = faces[k];
+  for (const [k, face] of faces) {
     const count = d1.get(k);
     result.combineInPlace(
       face.normalize(count * normalizationFactor / face.total())
@@ -2923,6 +3015,11 @@ function multiplyDiceByDice(d1, d2) {
   return result;
 }
 function multiplyDice(n, d) {
+  if (n > MAX_DICE_COUNT) {
+    throw new DiceParseError(
+      `Dice count ${n} exceeds the maximum of ${MAX_DICE_COUNT}`
+    );
+  }
   if (n === 0) return new Dice(0);
   if (n === 1) return d;
   const half = Math.floor(n / 2);
@@ -3005,9 +3102,14 @@ function parseDice(s, n) {
     return;
   }
   const sides = parseNumber(s, n);
+  if (sides > MAX_DIE_SIDES) {
+    throw new DiceParseError(
+      `Die size ${sides} exceeds the maximum of ${MAX_DIE_SIDES}`
+    );
+  }
   let result = new Dice(sides);
   if (rerollOne) {
-    result = result.deleteFace(1).combine(result);
+    result = result.reroll(1);
   }
   return result;
 }
@@ -3122,11 +3224,9 @@ function parseOperation(s) {
 // src/pmf/mixture.ts
 var Mixture = class _Mixture {
   constructor(eps = EPS) {
-    __publicField(this, "totals", /* @__PURE__ */ new Map());
+    this.totals = /* @__PURE__ */ new Map();
     // raw mass per outcome (pre-normalization)
-    __publicField(this, "labelMass", /* @__PURE__ */ new Map());
-    // raw mass per outcome per label
-    __publicField(this, "eps");
+    this.labelMass = /* @__PURE__ */ new Map();
     this.eps = Number.isFinite(eps) ? eps : EPS;
   }
   /** Remove all accumulated state. */
@@ -3150,9 +3250,8 @@ var Mixture = class _Mixture {
    */
   add(label, pmf, weight = 1) {
     if (!Number.isFinite(weight) || weight <= 0) return this;
-    for (const [v, binOrNumber] of pmf) {
-      const isNumber = typeof binOrNumber === "number";
-      const p = isNumber ? binOrNumber : binOrNumber?.p ?? 0;
+    for (const [v, bin] of pmf) {
+      const p = bin.p;
       if (p <= 0) continue;
       const add = weight * p;
       if (!Number.isFinite(add) || Math.abs(add) < this.eps) continue;
@@ -3240,6 +3339,6 @@ var Mixture = class _Mixture {
   }
 };
 
-export { DiceQuery, EPS, LRUCache, Mixture, PMF, clearParserCache, getCachingEnabled, onAnyHit, onCritOnly, onHitOnly, onMissDamageOnly, onMissOnly, onPotentCantripOnly, onSaveFailOnly, onSaveHalfOnly, parse, pmfCache, setCachingEnabled };
+export { DiceParseError, DiceQuery, EPS, LRUCache, Mixture, PMF, clearParserCache, getCachingEnabled, onAnyHit, onCritOnly, onHitOnly, onMissDamageOnly, onMissOnly, onPotentCantripOnly, onSaveFailOnly, onSaveHalfOnly, parse, pmfCache, setCachingEnabled };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map