@yipe/dice 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -0,0 +1,456 @@
+# 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.9.0]
+
+Adds `Turn`: attacks plus conditional damage riders, resolved to one exact joint
+distribution. This is the roadmap's `Turn` / `DamageRider` item.
+
+### Added
+
+- **`turn()` / `Turn`** (`@yipe/dice/builder`). Declare attacks, then chain riders
+  in the same `onX` vocabulary the builders already use: `onFirstHit` (Sneak
+  Attack), `onAnyCrit` (Divine Smite), `onAnyMiss` (Unerring Accuracy, Lucky),
+  `onEveryHit` (Hunter's Mark, Hex, Rage), and `otherwise` for the branch where
+  the preceding rider did not fire ("flurry of blows if I didn't smite").
+
+  ```ts
+  const dagger = d20.plus(8).ac(16).onHit(d4.plus(4));
+  const unarmed = d20.plus(8).ac(16).onHit(d6.plus(4));
+
+  const rogue = turn([dagger, dagger]).onFirstHit(roll(3, d6));
+  rogue.mean();     // 18.6225
+  rogue.pmf.pAt(0); // 0.1225
+
+  const goliath = turn([dagger, dagger])
+    .onFirstHit(roll(3, d6))
+    .onAnyCrit(roll(2, d8), { id: "smite" })
+    .otherwise([unarmed, unarmed])
+    .onEveryHit(d6);
+  ```
+
+  Each method takes an optional `{ id, of, critDamage }`, where `of` selects which
+  attacks the rider watches and defaults to all of them. All of them are sugar
+  over `rider({ damage, on, of })`, which takes the trigger as plain data.
+
+  Motivation: the pattern the README used to recommend — build a rider PMF with
+  `firstSuccessSplit` + `PMF.exclusive`, then convolve it alongside the attacks —
+  is only correct in the mean. A rider is perfectly correlated with the attacks
+  that trigger it, so treating it as an independent single corrupts the
+  distribution. For two `d20+8 AC 16 → 1d4+4` daggers plus `3d6` Sneak Attack it
+  reports P(0 damage) = 0.015 against a true 0.1225, and a standard deviation of
+  7.18 against 8.89. Because the means agreed, DPR checks never caught it while
+  every distribution chart and percentile was wrong. `Turn` owns the sources and
+  walks the joint outcome space instead, carrying one packed byte of state per
+  trigger group.
+
+  Riders sharing a trigger resolve jointly, so Sneak Attack and Fire's Burn fire
+  together or not at all, and a `not-fired` rider is the other branch of the same
+  decision rather than an independent event — mutually exclusive riders can never
+  both land. Riders may be attacks themselves, and may be sources for other riders.
+
+- **`tryParse(expression)`** — `parse` without the throw, returning an empty PMF
+  for junk. It also accepts a *signed* integer, which the grammar rejects:
+  `parse("7")` already returns a delta, but `parse("-3")` throws, and a
+  half-typed damage field is a bare signed number often enough to matter. Every
+  consumer had written this try/catch; dprcalc's version fell back to
+  `1d1 + (n - 1)`, which the parser then rejected for a negative `n`. This one
+  builds the delta directly, and refuses values outside the safe-integer range
+  rather than quietly rounding them.
+
+- **`withRollType(expression, rollType)`** — rewrite an expression's attack rolls
+  between flat / advantage / disadvantage / elven accuracy, leaving the damage,
+  crit and miss clauses alone. Each `d20` is resolved against the nearest
+  enclosing check, so nesting works and an expression with several attacks is
+  fully converted: `AC` is an attack roll, `DC` is the target's saving throw,
+  which the attacker's advantage does not affect. Saves and pure damage come back
+  unchanged, so this is safe to map over a mixed list. A halfling-luck `h` prefix
+  is preserved.
+
+  dprcalc was doing this by round-tripping through its own `AttackModel` parser
+  and re-serializing, 47 lines deep, because there was no way to say "same attack,
+  with advantage" to the library.
+
+- **`DiceQuery.outcomeStats(outcomes?)`** — per-outcome `atLeastOneProbability`,
+  `allProbability` and `damageRange`, with the range summed over the singles that
+  can produce the outcome rather than read off the combined PMF. `snapshot()`
+  takes its range from the combined `count`, which the convolution accumulates as
+  an expected count, so its `avg` is size-biased for two or more attacks (its own
+  doc comment says so). `outcomeStats` is linear in the attack count by
+  construction, and the two agree for a single attack.
+
+- **`Turn.from(spec)`** for plain-data construction from
+  `{ attacks: [{ id, source }], riders: [{ id, damage, on, of }] }`, validated up
+  front with a typed `TurnSpecError.code` (`unknown-id`, `duplicate-id`,
+  `self-reference`, `cycle`, `not-an-attack`, `too-many-groups`), so a consumer UI
+  can map errors to field states rather than reimplementing the checks. `Trigger`
+  is JSON-safe and meant to be persisted verbatim.
+
+- **`Turn.toQuery()`**, named to match `RollBuilder`/`AttackBuilder`/`SaveBuilder`,
+  alongside a `pmf` getter as those have. There is no `toPMF(eps)`: a turn's
+  epsilon is fixed at construction, where its plan is validated and its sources
+  resolved.
+
+- **`Turn.attacks(count, source)`** for Extra Attack, mirroring `roll(count, die)`,
+  so a Fighter's four swings do not have to be spelled out as
+  `turn([sword, sword, sword, sword])`. `turn()` also takes a bare source now, so
+  a one-attack turn needs no brackets.
+
+- `TurnSpecError` code **`unused-crit-damage`**, for a `critDamage` passed to a
+  rider that rolls its own attack. Such a rider crits on its own terms — Great
+  Weapon Master's bonus swing does not deal doubled dice because the attack that
+  triggered it crit — so there was nothing for the value to mean and it was
+  being dropped in silence.
+
+- **`Turn.attackIds` / `Turn.riderIds`** in declaration order, including the
+  `attack 1` / `rider 2` defaults, so a caller can discover the names that `of`
+  and `fireProbability` accept instead of having to have supplied them all.
+
+- Every construction path — `Turn.from`, `attack()`, `rider()` and the `onX`
+  methods — validates immediately, so a bad `of` throws at the call that
+  introduced it rather than later at `pmf` access. Measured at 0.63ms for the
+  six validations in the full goliath chain, with an unchanged 26-AC sweep.
+
+- **`Turn.fireProbability(id)`** — P(a rider fired), which the walk already knows. For
+  `every-hit` riders it reports P(at least one source hit).
+
+- `examples/turn-examples.ts` and `yarn example turn`.
+
+### Changed
+
+- **`DiceQuery.combinedWithAttribution()` now honours an explicitly provided
+  `combined` distribution** instead of re-convolving `singles`. A provided
+  combined is not necessarily the independent product of the singles — a `Turn`'s
+  is strictly narrower — and re-convolving discarded it, dropping every rider's
+  damage from attribution charts. Queries that provide no combined are unaffected.
+
+### Removed
+
+- `examples/sneak-attack-examples.ts` (~800 lines, six hand-rolled variants of the
+  same turn). It only existed because there was no primitive for conditional
+  riders. Its state-machine variant is the ancestor of `Turn`'s walk, and its
+  agreement checks are now `tests/turn-exactness.test.ts`, which compares `Turn`
+  against a brute-force enumeration of every attack-outcome sequence.
+
+## [0.8.1]
+
+Extends the resolved-PMF cache to every builder kind, so no consumer has to
+key its own cache by the AST-walking `toExpression()`.
+
+### Changed
+
+- **`RollBuilder.toPMF`, `DCBuilder.toPMF` and `SaveBuilder.toPMF` now cache their
+  resolved PMFs**, joining `AttackBuilder` (0.8.0). All four key by a cheap
+  serialization of their `RollConfig`s and return `null` — resolving uncached —
+  whenever a transform's PMF is not captured by those configs, so a conservative
+  miss is always preferred to a wrong hit.
+  - `RollBuilder` reuses the `cacheKey()` that already existed for
+    `AttackBuilder`'s benefit. Subclasses overriding `toPMF`
+    (`Half`/`Scale`/`MaxOf`/`Composite`) return a `null` key and stay uncached.
+  - `DCBuilder` gains a `cacheKey()` extending the base with the save DC.
+  - `SaveBuilder` gains a `cacheKey()` over the check, the failure effect and the
+    save outcome.
+
+  Motivation: profiling a dprcalc DPR plan put `toExpression()` at ~18% of self
+  time — the largest single cost — because only attacks had an internal cache, so
+  the consumer keyed its own by the expression string. Save-based builds have no
+  such fallback: removing that consumer cache without this change regressed a
+  Swords Bard by 15% and an Evoker Wizard by 11%. With it, the consumer layer can
+  be deleted outright (measured −1% to −4% across five character canaries).
+
+### Added
+
+- `clearRollCache()`, `clearDCCache()` and `clearSaveCache()` test/bench seams,
+  mirroring `clearAttackCache()`.
+
+## [0.8.0]
+
+### Added
+
+- **`AttackBuilder.toPMF` caches its resolved PMF**, keyed by a cheap
+  serialization of the check + effect `RollConfig`s rather than the AST-walking
+  `toExpression()`. A DPR sweep resolves the same attack thousands of times
+  (~99.9% repeats measured in dprcalc). `clearAttackCache()` is the test seam.
+
+## [0.7.0]
+
+Moves the full stacked damage-attribution chart pipeline into the library, so
+consumers own no dice-or-probability logic for that chart.
+
+### Added
+
+- **`PMF.damageAttributionChartModel(options?)`** (and a `DiceQuery` convenience)
+  returns the complete numeric model for the stacked damage-attribution chart:
+  bucket `labels`/`binRanges`, discovered `outcomes` in stack order, per-outcome
+  per-bucket `series` (bar-height mass) and `shares` (conditional tooltip share,
+  with an `epsilon` divide-by-~0 guard), per-bucket `totals`, reversed-convention
+  CCDF `percentiles`, and the `mean`. Options: `maxBuckets` (coarsen wide
+  distributions — split-first-then-bin, so sub-`binSize` damage is never folded
+  into the miss credit), `stackOrder`, `epsilon`. Exported type
+  `DamageAttributionChartModel`.
+
+### Removed
+
+- **BREAKING:** removed the superseded, unused `DiceQuery` chart-series methods
+  `toAttributionChartSeries`, `toDamageAttributionChartSeries`, and
+  `toOutcomeAttributionChartSeries`. Use `attributionByValue()` for the raw split
+  or `damageAttributionChartModel()` for the full chart model.
+
+## [0.6.0]
+
+Toolchain release: migrates the build to **TypeScript 7.0** (the Go-native
+compiler). No library API or runtime behavior changes — the compiler port is
+behavior-preserving, and consumer type resolution is verified equivalent across
+`node16`, `nodenext`, and `bundler`.
+
+### Changed
+
+- **Migrated to TypeScript 7.0.2** (native Go `tsc`). Type-checking and
+  declaration emit are ~5× faster on this codebase.
+- Declarations are now emitted by the native `tsc` (tsup handles JS bundling
+  only; its `rollup-plugin-dts` path does not support the TS 7 compiler API). A
+  small post-build step adds explicit `.js` extensions to relative specifiers so
+  the output resolves under `node16`/`nodenext`/`bundler`. The published `.d.ts`
+  changes from a single bundled file to a mirrored tree; **named exports and
+  type resolution are unchanged**.
+- Bumped the dev toolchain: Yarn 4.17.1, plus latest `@types/node`,
+  `typescript-eslint`, `eslint`, `tsx`, and `vitest`. Added the
+  `@typescript/typescript6` bridge so `typescript-eslint` (which does not yet
+  support TS 7) continues to lint against the 6.0 API while `tsc` runs on 7.0.
+
+## [0.5.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, and adds a
+**composable scale node** so a scaled/rounded sub-roll can nest inside a larger
+damage payload (per-damage-type resistance / immunity / vulnerability). All
+additive except the Elemental-Adept bounce fix noted below.
+
+### Added
+
+- **`RollBuilder.scaleResult(numerator, denominator = 1, rounding = 'floor')`** —
+  wraps a builder in a composable `scale` AST node that scales its resolved PMF
+  by `numerator / denominator` with the given rounding. Unlike the old
+  `.half()` wrapper, a scaled builder composes: it survives `sumRolls(...)`
+  instead of being dropped on a flat-config merge, so a per-type resisted or
+  doubled sub-roll keeps its own scaling inside a larger hit/crit payload. The
+  rendered expression reflects it — `denominator === 1 → "N * (child)"`,
+  `numerator === 1 → "(child) // D"`, general → `"(child) * N // D"`. `.half()`
+  is now `scaleResult(1, 2, 'floor')`.
+- **`sumRolls(parts: RollBuilder[])`** — additive factory whose `toAST()` is an
+  `add` node over each part's AST, letting scaled and plain children sit side by
+  side without the flat `.plus()` merge collapsing them. `toExpression()` joins
+  the parts with ` + ` and `toPMF()` convolves them.
+- **`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/README.md

@@ -121,6 +121,11 @@ src/
 ├── parser/           # String-based dice expression parser
 │   ├── parser.ts     # Main parser implementation
 │   └── dice.ts       # Dice class (legacy parser representation)
+├── turn/             # Turns: attacks + conditional damage riders
+│   ├── types.ts      # Trigger, Rider, TurnSpec, TurnSpecError
+│   ├── plan.ts       # Spec validation and step/group resolution
+│   ├── state.ts      # Packed per-group trigger state
+│   └── turn.ts       # Turn class - exact joint distribution
 ├── pmf/              # Probability Mass Function core
 │   ├── pmf.ts        # PMF class - core data structure
 │   ├── query.ts      # DiceQuery - analysis interface
@@ -329,27 +334,172 @@ try {
 }
 ```
 
-### Sneak Attack (Conditional Damage)
+For UI code that parses on every keystroke, `tryParse()` returns an empty PMF
+instead of throwing, and accepts a bare integer — which the grammar rejects, but
+a half-typed damage field is one for a keystroke or two:
 
-Conditional damage ("once-per-turn damage riders") like Sneak Attack can be modeled easily:
+```ts
+import { tryParse } from "@yipe/dice";
+
+tryParse("1d6 + 2").mean(); // 5.5
+tryParse("-3").mean(); // -3   — signed integers, which the grammar rejects
+tryParse("0x10").mass(); // 0  — decimal only
+tryParse("1d").mass(); // 0   — empty PMF
+```
+
+The failure value has **mass 0**, not a distribution, and convolving it collapses
+the whole result to mass 0 — check `mass()` or skip empties when combining
+several expressions. Where a bad expression should surface rather than be
+absorbed, use `parse()` and handle `DiceParseError`.
+
+### Roll Types
+
+`withRollType()` rewrites an expression's attack roll, leaving the damage, crit
+and miss clauses alone — the usual way to chart one attack across advantage
+states:
 
 ```ts
-import { DiceQuery, PMF, roll } from "@yipe/dice";
-
-function sneakAttack() {
-  const attackPMF = d20.plus(8).ac(16).onHit(d4.plus(4)).pmf;
-  const sneakAttack = roll(3, d6);
-  const attacks = new DiceQuery([attackPMF, attackPMF]);
-  const [pHit, pCrit] = attacks.firstSuccessSplit(onAnyHit, onCritOnly);
-  const sneakPMF = PMF.exclusive([
-    [sneakAttack.pmf, pHit],
-    [sneakAttack.doubleDice().pmf, pCrit],
-  ]);
-
-  return new DiceQuery([attackPMF, attackPMF, sneakPMF]);
-}
+import { withRollType } from "@yipe/dice";
+
+const attack = "(d20 + 8 AC 16) * (1d4 + 4) crit (2d4 + 4)";
+
+withRollType(attack, "advantage"); // "(d20 > d20 + 8 AC 16) * (1d4 + 4) crit (2d4 + 4)"
+withRollType(attack, "elven accuracy"); // "(d20 > d20 > d20 + 8 AC 16) * ..."
+```
+
+Every attack roll is rewritten, so an expression holding several attacks is fully
+converted, nesting and all. Each `d20` is resolved against the nearest enclosing
+check: `AC` is an attack roll, while `DC` is the *target's* saving throw, which
+the attacker's advantage does not affect. Saves therefore come back unchanged, as
+does anything with no check at all, which makes this safe to map over a mixed
+list. A halfling-luck `h` prefix is preserved.
+
+### Damage Riders (Sneak Attack, Smite, Hunter's Mark)
+
+Most of what makes 5e damage interesting is conditional: Sneak Attack needs *a* dagger to land,
+Divine Smite wants a crit, a flurry of blows only happens if you didn't smite. A **`turn()`** is
+attacks plus riders that fire based on what those attacks did.
+
+```ts
+import { turn, d20, d4, d6, roll } from "@yipe/dice/builder";
+
+const dagger = d20.plus(8).ac(16).onHit(d4.plus(4));
+
+const rogue = turn([dagger, dagger]).onFirstHit(roll(3, d6));
+
+rogue.mean();      // 18.6225
+rogue.pmf.pAt(0);  // 0.1225 — chance the whole turn whiffs
+```
+
+That is the whole API for the common case. A `Turn` resolves the **exact joint distribution**: a
+rider is correlated with the attacks that trigger it, so building one as a separate PMF and
+convolving it in gets the right mean but the wrong shape — the example above would report a whiff
+chance of 0.015 instead of 0.1225.
+
+| method | fires | example |
+|---|---|---|
+| `onFirstHit` | once, on the first attack that lands — doubled if it crit | Sneak Attack |
+| `onAnyCrit` | once, if any attack crit | Divine Smite |
+| `onAnyMiss` | once, if any attack missed | Unerring Accuracy, Lucky |
+| `onEveryHit` | once per attack that lands | Hunter's Mark, Hex, Rage |
+| `otherwise` | when the rider before it did *not* | flurry of blows if you didn't smite |
+
+#### Extra Attack
+
+`attacks(count, source)` mirrors `roll(count, die)`, so the Fighter's four — or eight, with Action
+Surge — stays one line:
+
+```ts
+const sword = d20.plus(9).ac(16).onHit(d6.plus(5));
+
+turn().attacks(4, sword).onEveryHit(d6).mean(); // 35.0  — hunter's mark on each hit
+turn().attacks(8, sword).onEveryHit(d6).mean(); // 70.0  — action surge
+```
+
+#### A rider can be anything that makes damage
+
+Riders take the same builders attacks do, so "extra damage" and "an extra attack" are the same call.
+A whole attack, a list of attacks, a flat bonus, or a saving throw all work:
+
+```ts
+const dagger = d20.plus(8).ac(16).onHit(d4.plus(4));
+const sword = d20.plus(9).ac(16).onHit(d6.plus(5));
+const greatsword = d20.plus(9).ac(16).onHit(roll(2, d6).plus(5));
+const unarmed = d20.plus(8).ac(16).onHit(d6.plus(4));
+const poison = d20.dc(13).onSaveFailure(roll(3, d6)).saveHalf();
+
+turn([greatsword, greatsword]).onAnyCrit(greatsword);   // Great Weapon Master's bonus attack
+turn([dagger]).onFirstHit(poison);                      // hit, then the target saves
+turn([sword, sword]).onEveryHit(flat(2));               // Rage
+turn([dagger, dagger]).onAnyCrit(roll(4, d8)).otherwise([unarmed, unarmed]); // smite, or flurry
+```
+
+#### The hard build
+
+A goliath rogue/monk/paladin, every trigger at once:
+
+```ts
+const goliath = turn([dagger, dagger])
+  .onFirstHit(roll(3, d6))       // sneak attack
+  .onFirstHit(d10)               // fire's burn
+  .onAnyCrit(roll(2, d8))        // divine smite
+  .otherwise([unarmed, unarmed]) // flurry of blows, if the smite didn't happen
+  .onEveryHit(d6);               // hunter's mark
+
+goliath.mean();                                // 39.5903
+goliath.toQuery().damageAttributionChartModel();
+```
+
+Two things that would be easy to get wrong are handled for you. Riders sharing a trigger resolve
+**jointly** — sneak attack and fire's burn fire together or not at all, which shows up in the spread
+even though it never moves the mean. And `otherwise()` binds to the rider immediately before it, so
+the smite and the flurry are two branches of one decision and can never both land.
+
+#### Asking questions
+
+```ts
+const t = turn([dagger, dagger]).onFirstHit(roll(3, d6));
+
+t.mean();                                   // 18.6225
+t.pmf.pAt(0);                               // 0.1225  — P(whiff)
+t.pmf.stdev();                              // 8.8860
+t.toQuery().probTotalAtLeast(20);           // 0.5062  — P(20+ damage)
+t.toQuery().percentiles([0.25, 0.5, 0.75]); // [15, 20, 24]
+```
+
+#### Ids, errors, and plain data
+
+Nothing above needs an `id`: attacks and riders get `attack 1`, `rider 2`, … in declaration order,
+and `otherwise()` finds its own target. Name a rider when you want to ask about it afterwards:
+
+```ts
+const paladin = turn([dagger, dagger]).onAnyCrit(roll(2, d8), { id: "smite" });
+
+paladin.fireProbability("smite"); // 0.0975
+paladin.attackIds;                // ["attack 1", "attack 2"]
+paladin.riderIds;                 // ["smite"]
+```
+
+Every construction path validates immediately and throws a `TurnSpecError` whose `code` —
+`unknown-id`, `cycle`, `not-an-attack`, `duplicate-id`, `self-reference`, `unused-crit-damage`,
+`too-many-groups` — maps
+straight onto a UI field state. A bad `of` fails at the call that introduced it, not later at
+`.mean()`.
+
+Each `onX` method takes an optional `{ id, of, critDamage }`, where `of` picks which attacks the
+rider watches and defaults to all of them. All of them are sugar over `rider()`, which takes the
+trigger as plain data — and `Trigger` is JSON-safe, so a UI can persist one and hand it straight
+back:
+
+```ts
+import { Turn, d20, d4, d6, roll } from "@yipe/dice/builder";
+
+const dagger = d20.plus(8).ac(16).onHit(d4.plus(4));
 
-console.log("DPR with once-per-turn sneak attack: ", sneakAttack().mean());
+const fromUI = Turn.from({
+  attacks: [{ id: "dagger 1", source: dagger }, { id: "dagger 2", source: dagger }],
+  riders: [{ id: "sneak", damage: roll(3, d6), on: "first-hit" }],
+});
 ```
 
 ### Statistics and Charts
@@ -386,7 +536,7 @@ This repository includes example scripts:
 ```bash
 yarn example basic
 yarn example stats
-yarn example sneakattack
+yarn example turn
 yarn example misc
 ```
 
@@ -467,7 +617,7 @@ This enables rich statistics like "how much damage comes from crits vs hits".
 ## 🧱 Roadmap
 
 - [ ] Create a **web playground** with live examples
-- [ ] Consider creating higher-level APIs: `Turn`, `Attack`, `DamageRider`
+- [x] Higher-level `Turn` API for conditional damage riders (0.9.0)
 - [ ] Add more comprehensive 5e rule examples
 - [ ] Performance improvements for DPR-only calculations
 - [ ] Multi-round and sustained vs nova simulations