@yipe/dice 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,224 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.4.0]
+
+Pushes damage-attribution / provenance and D&D-probability logic that the
+consuming app (dprcalc) had hand-rolled over PMF internals down into the
+library, so the provenance model and dice math stay owned here. All additive
+except the Elemental-Adept bounce fix noted below.
+
+### Added
+
+- **`PMF.applyHitFrequency(frequency)`** — provenance-preserving mass
+  redistribution for effects that only occur with some probability (conditional
+  attacks, on-hit riders, sub-one AoE fractions): scales every hit bin (damage
+  > 0) by `frequency` and moves the freed mass into a `missNone` bin. Unlike a
+  bare `scaleMass`/`mapDamage`, it scales per-label `count` **and** `attr`, so a
+  frequency-scaled PMF still renders correctly in the damage-attribution charts.
+  Replaces the app's hand-rolled `applyFrequencyToPMF`, which dropped `attr`.
+- **`PMF.missNone(epsilon?)`** / **`MISS_NONE_OUTCOME`** — canonical "clean miss"
+  delta (point mass at 0 tagged with the `missNone` `OutcomeType`, distinct from
+  `PMF.zero`'s builder-side `miss` label), and the label as a single source of
+  truth.
+- **`PMF.hitProbability()` / `PMF.missProbability()`** — the `1 - P(0)` idiom
+  (miss encoded at damage 0), centralized.
+- **`PMF.rebin(maxBuckets)`** — coarsen a wide distribution into ≤ N contiguous
+  equal-width buckets, aggregating `count`/`attr` provenance. For charting wide
+  distributions, not DPR math.
+- **`PMF.attributionByValue()` / `DiceQuery.attributionByValue()`** — split each
+  damage value's probability mass across outcome labels (by `attr` for
+  damage-bearing bins, by `count` for the clean-miss bin), returning per-label
+  `value → mass` series. The provenance core of the stacked attribution chart.
+- **`DiceQuery.countSinglesWith(label)`** — how many independent single PMFs can
+  produce a given outcome label.
+- **`ALL_OUTCOME_TYPES`**, **`OUTCOME_DISPLAY_ORDER`**, **`sortOutcomes()`** —
+  canonical `OutcomeType` enumeration + stack / display orderings, replacing
+  per-consumer outcome tables.
+- **`critProbability(critRange, rollType)`** and **`RollType`** (now exported
+  from the package root as well as `@yipe/dice/builder`) — advantage-aware
+  P(crit) for a given crit window.
+- **`calculateBounceOdds(diceCount, dieFaces, options?)`** and
+  **`BounceOddsOptions`** — the "birthday problem" for bouncing damage dice
+  (Chromatic Orb), honoring Elemental Adept and Empowered Spell. Moved out of the
+  app; the base and Elemental-Adept cases are now computed **exactly** (verified
+  against brute-force enumeration in `tests/bounce.test.ts`).
+
+### Fixed
+
+- **`calculateBounceOdds` Elemental Adept was approximate.** The former
+  hand-derived adjustment factor drifted from the exact value by up to ~3.5%
+  (e.g. 3×d8, min-roll 3: 0.4965 → 0.5313). The Elemental-Adept branch now uses
+  an exact elementary-symmetric-polynomial computation. Consumers relying on the
+  old numbers for bouncing spells with Elemental Adept will see small DPR shifts.
+- **`calculateBounceOdds` Empowered Spell returned certainty when rerolling all
+  dice.** When `rerollDamageDice >= diceCount` (no dice kept), the model claimed
+  a guaranteed match (1.0) instead of treating the reroll as a second
+  independent roll. It now correctly yields `1 - (1 - pMatch)^2` in that case
+  (e.g. 3×d8 reroll-all: 1.0 → 0.5693).
+
+## [0.3.0]
+
+### Fixed (mathematical correctness)
+
+Every fix is verified against an independent brute-force enumeration (see
+`tests/math-correctness.test.ts`).
+
+- **`DiceQuery.probabilityOf(label)` over-counted.** It summed the full `bin.p`
+  of every combined bin that merely *contained* a label, but bins hold multiple
+  mutually-exclusive outcomes — so `probabilityOf('crit')` returned 0.49 where
+  the true P(crit)=0.05. It now returns the correct Poisson-binomial marginal
+  (= `probAtLeastOne`). `missChance()` is fixed by the same change.
+- **`DiceQuery.probExactlyK([labels], k)` array-path** delegated to the buggy
+  `probabilityOf`, disagreeing with the (correct) single-label string path; both
+  now match the true binomial.
+- **`DiceQuery.variance()/stddev()`** used the unstable `E[X²]−E[X]²` form and
+  lost all precision under a large constant damage offset (`1d6 + 1e8` gave
+  variance 2 instead of 35/12). Now uses the centered, additive-per-single form.
+- **`DiceQuery.mean()/variance()`** now stay consistent with an explicitly
+  supplied `combined` that diverges from `convolve(singles)`.
+- **`PMF.convolve()` produced `NaN`** for a zero-mass operand (divide-by-zero in
+  the mass rescale), silently poisoning `DiceQuery.combined`. A zero-mass
+  convolution now correctly yields mass 0.
+- **`probAtLeastOne` is now mass-invariant** (per-attack probability divided by
+  the single's mass) and clamped to `[0,1]` (was returning `1.0000000002`).
+- **`PMF.firstSuccessWeights`** throws on `pSpecial > pSuccess` instead of
+  returning out-of-range probabilities.
+- **Parser `hd6`/`hd20` (reroll-one)** used a weighted union giving
+  `P(1)=1/(2s−1)`; now uses `reroll(1)` for the correct `P(1)=1/s²`. The parser
+  `hd` distribution now matches the builder's `reroll(1)` exactly (the
+  previously loosened tests are tightened).
+- **`DiceQuery.snapshot()` outcome probabilities** (`atLeastOneProbability`,
+  `allProbability`) were aggregated as expected counts and could exceed 1 for
+  multi-attack queries. They now use the correct Poisson-binomial marginals
+  (P(≥1) and P(all)) and are always in [0,1]. (`damageRange.avg` remains a
+  size-biased mean for N≥2 — see Known limitations.)
+- **Parser save-for-half mislabeled outcomes** on odd/constant damage (e.g.
+  `(d20 DC 15) * (3) save half`): the brittle "2×half ∈ hit" detection
+  false-negatived, tagging the success mass as `saveFail` and the failure mass
+  as `hit`. Detection is now deterministic (the presence of a save distribution),
+  so `saveHalf`/`saveFail` are always labeled correctly.
+- **`PMF.compact()` corrupted PMFs that shared bin objects.** It deleted
+  sub-epsilon `count`/`attr` entries *in place* and reused that same bin
+  reference in the compacted map. Because bins are shared by reference across
+  PMFs (the `branch()` / `addScaled()` / `scaleMass()` fast paths can carry
+  another PMF's bin objects), this silently mutated the source PMF — and the
+  receiver's own bins. `compact()` now clones each surviving bin before pruning;
+  the compacted result is unchanged.
+
+### Security / hardening
+
+- **Parser resource-exhaustion guards.** Adversarial expressions are rejected
+  with a `DiceParseError` instead of exhausting CPU/memory: a die over 1,000,000
+  faces, a dice count over 10,000, a keep whose `faces^count` enumeration would
+  exceed 1,000,000 outcomes, and a binary operation whose `faces₁ × faces₂` work
+  would exceed 100,000,000 face pairs. The last closes a gap the per-operand
+  caps missed — two individually-legal large dice (e.g. `d100000 + d100000`,
+  ~10¹⁰ operations) previously hung for tens of seconds. All legitimate
+  expressions, including `d100000`, still parse.
+
+### Known limitations (documented; recommend maintainer review)
+
+These are real but require API/architecture decisions, so they are documented
+and pinned by tests rather than changed blindly:
+
+- **Parser crit probability with bonus to-hit dice is wrong.** With bonus dice in
+  the to-hit (e.g. Bless, `d20 + 5 + 1d4`), the string parser collapses crit to
+  `1/(20·∏bonusSides)` (and the DPR is off by a few %), because the natural-20
+  slice can't be separated after the bonus dice are convolved. **The builder API
+  computes it correctly** — use `d20.plus(..).plus(bonusDie).ac(..).onCrit(..)`.
+- **Multi-attack conditional damage `avg` is size-biased.** The `avg` returned by
+  `damageStatsFrom()` (single label), `outcomeDamageRanges()` and
+  `snapshot().damageRange` aggregates the combined PMF's `count` (an *expected
+  count* for N≥2 attacks), so it is the size-biased mean E[dmg·#label]/E[#label]
+  rather than a clean conditional expectation. It is correct for a single attack.
+  (The associated *probabilities* are now correct — see Fixed.)
+- **`PMF.mixN`/`gate`/`branch` build O(2ⁿ) identifier strings**, which can blow up
+  (multi-MB, eventual `RangeError`) for very deep (≈20+) gate chains. Prefer
+  `PMF.exclusive`/`PMF.mix` for large mixtures.
+
+### Breaking
+
+- **`PMF.toJSON()` now returns a plain object** (`{ bins, normalized, identifier }`)
+  instead of a JSON string, following the standard `toJSON` contract. This means
+  `JSON.stringify(pmf)` no longer double-encodes. If you relied on the old string
+  return, call the new `PMF.toJSONString()` instead.
+- **`DiceQuery.firstSuccessSplit()` is typed as `OutcomeType | OutcomeType[]`**
+  (previously `string | string[]`). Only affects callers passing arbitrary strings;
+  valid outcome labels are unchanged.
+
+### Added
+
+- **`DiceParseError`** — `parse()` now throws this typed error (a subclass of
+  `Error`) instead of a plain `Error`. Existing `try/catch` and message checks keep
+  working; you can now narrow with `instanceof DiceParseError` and read
+  `error.expression` / `error.cause`.
+- **`PMF.toJSONString()`** — returns the JSON string form (the previous
+  `toJSON()` behavior).
+- **`DiceQuery.stdev()`** — alias of `stddev()`, matching `PMF.stdev()`.
+- **`PMF.hasAttribution()`** — O(1) check for whether a PMF already carries
+  damage-attribution metadata.
+
+### Performance
+
+- **`DiceQuery.mean()` / `variance()` / `stddev()` use moment additivity**
+  (`E[ΣX]=ΣE[X]`, `Var[ΣX]=ΣVar[X]`) computed directly from the single PMFs.
+- **`DiceQuery.combined` is now built lazily** (on first access) instead of in
+  the constructor. Combined with the above, a query used only for DPR / mean /
+  variance never performs the N-way convolution — multi-attack stats-only
+  queries are ~10000× faster (e.g. ~17 ms → ~0.001 ms for a heavy 4-attack
+  expression). The materialized `combined` distribution is unchanged; mean and
+  variance may differ from the previous convolution-based values by at most a
+  few ULP (well within the library's tolerances).
+- **`DiceQuery.combinedWithAttribution()` reuses `combined`** when every single
+  already carries attribution (as parser-generated PMFs do), avoiding a
+  redundant convolution pass. Result is bit-for-bit identical.
+- **`PMF.convolve()` inner loop accumulates directly into destination bins**
+  instead of allocating a temporary bin per term and merging — ~1.6× faster
+  convolution (the cost of building the combined distribution for charts). The
+  probability channel is bit-identical; per-label `count`/`attr` provenance may
+  re-associate by at most a few ULP (≤1e-14 even at 16 attacks, ~100× below the
+  eps pruning threshold).
+- **Convolution cache-key fingerprint is memoized** on each (immutable) PMF
+  instead of re-summing every bin key on every `convolve()` call — ~36% faster
+  on warm cache hits. Bit-identical (`PMF.fingerprint()` returns the same string).
+- **`Dice.calculateHitDistribution()` no longer clones outcome distributions per
+  face** — it reads the stored maps once instead of `O(faces × outcomes)` clones,
+  ~10% faster cold parsing of wide-support expressions. Bit-identical.
+- **`DiceQuery.toStackedChartData()` drops a dead `O(N×L)` precomputation pass**
+  whose result was discarded — ~2× faster. Bit-identical.
+- Minor bit-identical cleanups on the parse path (`Dice.toPMF` iterates the
+  internal face map directly; `multiplyDiceByDice` uses a `Map`).
+- **`DiceQuery` count queries (`probExactlyK` / `probAtLeastK` / `probAtMostK`,
+  array-label paths)** compute each attack's success probability and the binomial
+  DP once instead of rebuilding a query per requested count (~3× on the looped
+  variants).
+- **`PMF.branch()` assembles its Bernoulli mixture in a single pass** rather than
+  chaining two `addScaled` calls (which copied the failure branch's bins twice).
+- **`keepSumPMF` packs its DP state into a single integer key** instead of a
+  `"used|r"` string parsed on every transition.
+- **`computeMaxOfPMF` walks the support once with a running CDF** for large pools,
+  reducing the max-of computation from O(N²) to O(N).
+- **`Dice.reroll()` uses a `Set` for membership** and **`Dice.binaryOp()` hoists
+  the inner die's face list** out of its loop.
+
+  All of the above were verified bit-for-bit identical (probabilities, counts,
+  means, variance) across the full expression corpus.
+
+### Changed
+
+- Removed the stale `package-lock.json` (the project uses Yarn 4) and dropped the
+  unused `ts-node` / `tsconfig-paths` dev dependencies.
+- Removed `console.error` calls from the parser so the library no longer writes to
+  a consumer's console.
+- Internal refactors with no behavioral change: deduplicated `Bin` clone/scale
+  logic in `PMF`, removed dead code and impossible iterator branches, and tightened
+  internal `any` usage.
+- `Dice.outcomeData` is typed `Partial<Record<OutcomeType, …>>` (dropping an
+  unsound `as Record<…>` cast); `getFullOutcomeDistribution()`'s return type
+  matches. Type-only change; runtime output is unchanged.
+- Added a `yarn format` script (ESLint autofix).

package/dist/builder/index.cjs

@@ -44,6 +44,7 @@ var LRUCache = class {
 
 // src/common/types.ts
 var EPS = 1e-12;
+var MISS_NONE_OUTCOME = "missNone";
 
 // src/pmf/query.ts
 var _DiceQuery = class _DiceQuery {
@@ -106,6 +107,29 @@ var _DiceQuery = class _DiceQuery {
     this._combinedWithAttr = normalized;
     return normalized;
   }
+  /**
+   * Per-label `damage value → probability mass` series for the combined,
+   * attribution-carrying distribution — the provenance core of the stacked
+   * damage-attribution chart. Convenience for
+   * `combinedWithAttribution().attributionByValue()`; see
+   * {@link PMF.attributionByValue}.
+   */
+  attributionByValue() {
+    return this.combinedWithAttribution().attributionByValue();
+  }
+  /**
+   * How many of the independent single PMFs can produce the given outcome
+   * label. Useful for "all of them succeeded" style probabilities where the
+   * exponent is the number of contributing attacks (see
+   * {@link DiceQuery.probExactlyK}).
+   */
+  countSinglesWith(label) {
+    let count = 0;
+    for (const single of this.singles) {
+      if (single.hasOutcome(label)) count++;
+    }
+    return count;
+  }
   /**
    * Returns the expected damage across all possible outcomes.
    *
@@ -1389,6 +1413,20 @@ var _PMF = class _PMF {
   static delta(value, epsilon = EPS) {
     return _PMF.fromMap(/* @__PURE__ */ new Map([[value, 1]]), epsilon);
   }
+  /**
+   * Point mass at damage 0 tagged with the canonical `missNone` outcome.
+   *
+   * Differs from {@link PMF.zero}, which labels its zero bin `miss` — the
+   * builder's attack-resolution vocabulary. This uses the `missNone`
+   * {@link OutcomeType} that the attribution charts and outcome stats key on,
+   * so it is the correct "clean miss / no damage" delta for provenance-aware
+   * mixtures feeding those consumers.
+   */
+  static missNone(epsilon = EPS) {
+    const m = /* @__PURE__ */ new Map();
+    m.set(0, { p: 1, count: { [MISS_NONE_OUTCOME]: 1 }, attr: {} });
+    return new _PMF(m, epsilon, false, "missNone");
+  }
   // This creates a single bin at value 0, but with weight 0.
   static emptyMass() {
     return _PMF.zero().scaleMass(0);
@@ -1910,6 +1948,49 @@ var _PMF = class _PMF {
       `${this.identifier}+scaled(${branch.identifier},${probability})`
     );
   }
+  /**
+   * Redistributes probability mass to model an effect that only occurs with
+   * probability `frequency` — a conditional attack, an on-hit rider, or a
+   * sub-one AoE target fraction.
+   *
+   * Every hit outcome (damage > 0) is scaled by `frequency` — probability mass,
+   * per-label `count`, AND per-label `attr` — and the freed mass is moved into
+   * the miss bin at damage 0, tagged with the canonical `missNone` outcome.
+   * Total probability mass is preserved.
+   *
+   * Unlike a bare {@link scaleMass} or {@link mapDamage}, this keeps damage
+   * attribution (`attr`) intact, so a frequency-scaled PMF still renders
+   * correctly in the damage-attribution charts.
+   *
+   * `frequency >= 1` (or non-finite) returns this PMF unchanged; `frequency <= 0`
+   * collapses all mass into the miss bin. The miss outcome is assumed to be
+   * encoded at damage value 0.
+   *
+   * @param frequency Probability in [0, 1] that the effect occurs.
+   */
+  applyHitFrequency(frequency) {
+    if (!Number.isFinite(frequency) || frequency >= 1) return this;
+    const freq = Math.max(0, frequency);
+    const pMiss = this.pAt(0);
+    const pHit = 1 - pMiss;
+    const newMissMass = pMiss + (1 - freq) * pHit;
+    const newMap = /* @__PURE__ */ new Map();
+    newMap.set(0, {
+      p: newMissMass,
+      count: { [MISS_NONE_OUTCOME]: newMissMass },
+      attr: {}
+    });
+    for (const [damage, bin] of this.map) {
+      if (damage <= 0) continue;
+      newMap.set(damage, _PMF.scaleBin(bin, freq));
+    }
+    return new _PMF(
+      newMap,
+      this.epsilon,
+      false,
+      `freq(${this.identifier},${freq})`
+    );
+  }
   scaleMass(factor) {
     if (factor === 1) return this;
     const scaledMap = /* @__PURE__ */ new Map();
@@ -2137,6 +2218,39 @@ var _PMF = class _PMF {
   pAt(x) {
     return this.map.get(x)?.p ?? 0;
   }
+  /**
+   * P(any damage) — the mass on all non-zero outcomes, i.e. `1 - P(0)`.
+   * Assumes a miss is encoded as the damage-0 bin (the convention used across
+   * attack/save PMFs). The dual of {@link missProbability}.
+   */
+  hitProbability() {
+    return 1 - this.pAt(0);
+  }
+  /** P(no damage) — the mass at damage 0. The dual of {@link hitProbability}. */
+  missProbability() {
+    return this.pAt(0);
+  }
+  /**
+   * Coarsen the distribution into at most `maxBuckets` contiguous, equal-width
+   * damage buckets, aggregating probability mass (and `count`/`attr`
+   * provenance) into each bucket's start value. Returns this PMF unchanged when
+   * its integer support already fits within `maxBuckets`.
+   *
+   * This is a lossy display/downsampling transform (bucket start replaces the
+   * exact damage value) — use it for charting wide distributions, not for DPR
+   * math.
+   */
+  rebin(maxBuckets) {
+    if (!(maxBuckets > 0)) return this;
+    const support = this.support();
+    if (support.length === 0) return this;
+    const min = support[0];
+    const max = support[support.length - 1];
+    const range = max - min;
+    if (range + 1 <= maxBuckets) return this;
+    const binSize = Math.ceil((range + 1) / maxBuckets);
+    return this.mapDamage((d2) => min + Math.floor((d2 - min) / binSize) * binSize);
+  }
   /** Dense integer support from min..max (inclusive).
    * Useful for showing empty bars in charts.
    */
@@ -2212,6 +2326,56 @@ var _PMF = class _PMF {
     }
     return false;
   }
+  /**
+   * Split each damage value's probability mass across outcome labels, returning
+   * per-label maps of `damage value → probability mass attributable to that
+   * label`. Summing over labels at a given value recovers that value's `p`.
+   *
+   * Damage-bearing bins are split by `attr` weight (the share of damage each
+   * outcome contributed); the clean-miss bin at 0 is split by `count` weight
+   * (there is no damage to attribute). Attribution is computed on demand via
+   * {@link withAttribution} when absent, so builder-generated PMFs work too.
+   *
+   * This is the provenance core of the stacked damage-attribution chart — the
+   * caller only maps these series into its rendering format (colors, binning,
+   * axis labels).
+   */
+  attributionByValue() {
+    const src = this.hasAttribution() ? this : this.withAttribution();
+    const result = /* @__PURE__ */ new Map();
+    const add = (label, damage, mass) => {
+      if (!(mass > 0)) return;
+      let series = result.get(label);
+      if (!series) {
+        series = /* @__PURE__ */ new Map();
+        result.set(label, series);
+      }
+      series.set(damage, (series.get(damage) ?? 0) + mass);
+    };
+    for (const [damage, bin] of src.map) {
+      const p = bin.p || 0;
+      if (p <= 0) continue;
+      const isMissBin = damage === 0;
+      if (isMissBin) {
+        let totalCount = 0;
+        for (const k in bin.count) totalCount += bin.count[k] || 0;
+        if (totalCount > 0) {
+          const c = bin.count[MISS_NONE_OUTCOME] || 0;
+          add(MISS_NONE_OUTCOME, damage, c / totalCount * p);
+        }
+        continue;
+      }
+      let totalAttr = 0;
+      if (bin.attr) for (const k in bin.attr) totalAttr += bin.attr[k] || 0;
+      if (bin.attr && totalAttr > 0) {
+        for (const k in bin.attr) {
+          if (k === MISS_NONE_OUTCOME) continue;
+          add(k, damage, (bin.attr[k] || 0) / totalAttr * p);
+        }
+      }
+    }
+    return result;
+  }
   tailProbGE(t) {
     let s = 0;
     for (const [x, bin] of this) {