dnd5e-engine 0.3.1__tar.gz → 0.4.0__tar.gz

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/CHANGELOG.md

@@ -7,6 +7,96 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.4.0]
+
+Lockstep release with `dnd5e-srd-data` 0.4.0 and `nat20-bridge` 0.4.0.
+
+Deprecates the legacy (Gen 1) rules surface. **Nothing is removed**; every
+deprecated import warns. Removal lands in 0.5.0 — see
+`docs/migration/v0.3-to-v0.4.md`.
+
+### Deprecated
+
+- **The legacy (Gen 1) rules surface — removed in 0.5.0.** `dispatch`,
+  `event_dicts`, `types.dice`, `types.intent`, and `rules.{combat, combat_data,
+  combat_helpers, equipment, gambits, resolution, spells}` emit a
+  `DeprecationWarning` on import. The top-level `dnd5e_engine.ActionType` and
+  `dnd5e_engine.types.{ActionType, CombatOutcome, DiceOutcome, CombatNPC}`
+  re-exports now resolve lazily and warn on access. Every symbol's supported
+  route is in `docs/migration/v0.3-to-v0.4.md`. Rationale: two drifting
+  implementations of the same SRD rules, a non-seedable legacy path, and host
+  transport/persistence shapes inside a zero-I/O package.
+
+### Changed
+
+- `DeathSaveState` canonical home is now `dnd5e_engine.death_saves`;
+  `BehaviorProfile` is now `dnd5e_engine.types.combat`. The old locations
+  re-export until 0.5.0. The supported engine's import tree no longer reaches
+  any legacy module (pinned by `tests/test_gen2_has_no_gen1_imports.py`).
+
+### Added
+
+- Cross-generation attack-roll parity test
+  (`tests/test_generation_parity_attack.py`): `rules/combat.attack_roll` /
+  `resolve_player_attack` and `activities/attack.py` are fed the same d20
+  stream and must keep the same natural die and agree on hit / crit / miss
+  under advantage, disadvantage and flat rolls. This is the guard that would
+  have caught the drift fixed in 0.3.1 (#11). No runtime behavior change.
+
+## [0.3.2]
+
+Lockstep release with `dnd5e-srd-data` 0.3.2 and `nat20-bridge` 0.3.2.
+
+Additive maturity pass from an independent review of the packages as a
+standalone engine. **No public name is removed or changed shape.**
+
+### Fixed
+
+- **Multiattack fan-out resolved the wrong attack mix for most monsters.** The
+  prose parser only matched `[[/item .id]]{label}`, but the corpus mostly ships
+  `[[/item Name]]` or bare mnemonic ids, so 174 of 180 multiattacks fell back to
+  "repeat one sibling N times" — silently wrong for every heterogeneous
+  multiattacker. The parser now reads per-token counts from the multiattack's
+  first sentence (excluding "It can replace one attack with …" riders) and
+  recovers names from Foundry's mnemonic ids. Precise joins: **6/180 → 119/180**.
+  Chuul, Otyugh, Cloaker, Unicorn, Mummy, Pit Fiend, Xorn and Marilith now make
+  their correct attack sequences. **Behaviour change for consumers:** affected
+  monsters deal their correct (higher) damage per round and consume more of the
+  dice stream, so combat transcripts seeded against 0.3.x will diverge.
+- `__version__` now derives from installed package metadata instead of a
+  hand-maintained literal, so it cannot drift from `pyproject.toml` (0.3.0 shipped
+  reporting `0.2.0`). Pinned by `tests/test_determinism_contract.py`.
+
+### Added
+
+- **`CheckSpec.rng`** — `resolve_check` previously drew its d20 from the
+  process-global `random` module with no way to inject a generator,
+  contradicting the documented determinism guarantee. Pass a seeded
+  `random.Random` for a reproducible standalone check; `None` preserves the old
+  behaviour. `rules.dice`, `rules.skills` and `roll_dice_str` /
+  `apply_changes_to_check` gain matching optional `rng` parameters. Combat
+  resolution was already seeded and is unchanged.
+- **`docs/capabilities.md`** — a per-mechanic matrix of what the engine
+  resolves, what loads but produces no events, and what is not modelled. Its
+  published counts are recomputed from the corpus by
+  `tests/test_capability_matrix.py`.
+- Concept pages for reactions (the pre-armed model) and monsters (the built-in
+  AI, multiattack join rate, absent legendary actions).
+- `tests/test_docstrings_are_host_agnostic.py` — fails the build on a docstring
+  that names a private downstream application, retired tooling, or a doc path
+  that does not exist in this repo. 104 such references were rendered onto the
+  public API site; all removed.
+
+### Changed
+
+- `CONDITION_EFFECTS[EXHAUSTION]` / `[PRONE]` descriptive strings corrected from
+  2014 to SRD 5.2 wording and labelled as not-enforced; the enforced exhaustion
+  rule is still the 2014 one (tracked in `BACKLOG.md`).
+- Sphinx cross-reference roles in docstrings, which rendered as literal markup
+  on the API site, converted to inline code.
+- Monkeypatching `roll_dice_str` now requires a two-parameter double
+  (`lambda expr, rng=None: …`).
+
 ## [0.3.0]
 
 Lockstep release with `dnd5e-srd-data` 0.3.0 — the item charge lifecycle: gate

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/Makefile

@@ -12,7 +12,7 @@ test:
 	uv run pytest -q
 # Baseline-and-ratchet coverage gate (75% observed today; floor set 2pts under).
 coverage:
-	uv run pytest -q --cov=dnd5e_engine --cov-report=term-missing --cov-fail-under=73
+	uv run pytest -q --cov=dnd5e_engine --cov-report=term-missing --cov-fail-under=90
 security:
 	uv run bandit -r src/ -c pyproject.toml -q
 smoke:

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dnd5e-engine
-Version: 0.3.1
+Version: 0.4.0
 Summary: Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O.
 Author: Tapestria contributors
 License: MIT License

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.3.1"
+version = "0.4.0"
 description = "Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -87,6 +87,12 @@ max-complexity = 23
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+filterwarnings = [
+    # Any DeprecationWarning the engine itself raises is a bug — except the
+    # 0.4.0 legacy-surface deprecations, which the suite exercises on purpose.
+    "error::DeprecationWarning:dnd5e_engine",
+    "ignore:.*legacy \\(Gen 1\\) surface.*:DeprecationWarning",
+]
 
 [tool.coverage.run]
 source = ["dnd5e_engine"]

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/__init__.py

@@ -1,19 +1,31 @@
-"""dnd5e-engine — host-agnostic D&D 5e SRD rules engine.
+"""dnd5e-engine — a host-agnostic, zero-I/O D&D 5e SRD 5.2 rules engine.
 
-Public API per docs/superpowers/specs/2026-05-26-dnd5e-engine-extraction-design.md.
+Everything exported here is listed in ``__all__`` below; that list is the
+package's stable contract and is pinned by ``tests/test_public_api_surface.py``.
 
-Asset loading runs through ``dnd5e_srd_data.BundledAssetLoader`` (the typed
-2024-SRD corpus), wired via :mod:`dnd5e_engine.lib_loader`.
+The four combat-loop coroutines are ``start_combat``, ``submit_player_intent``,
+``advance_monster_turn`` and ``end_combat``; ``resolve_check`` is the standalone
+ability/skill/saving-throw resolver, and ``build_party_member`` turns a
+``CharacterBuildSpec`` into a combat-ready ``PartyMemberSpec``.
 
-Deferred for later phases:
-  - roll (ad-hoc dice) — Phase 7
-  - get_state_snapshot / list_active_handles (diagnostic introspection)
-    — not yet implemented in orchestrator; will land alongside Phase 5 or 6.
+Rules content is never bundled with the engine. It is read at runtime from the
+companion ``dnd5e-srd-data`` package; call ``configure_lib_loader`` to
+substitute your own typed corpus.
+
+See the ``docs/`` tree (published at https://tapestria.github.io/nat20/) for the
+combat model, the activity corpus, and a per-mechanic capability matrix
+describing exactly which SRD rules this engine resolves today.
 """
 
 from __future__ import annotations
 
-__version__ = "0.3.1"
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:  # pragma: no cover - trivial packaging fallback
+    __version__ = _pkg_version("dnd5e-engine")
+except PackageNotFoundError:  # pragma: no cover - source tree without install
+    __version__ = "0.0.0+unknown"
 
 from dnd5e_engine.build_party import build_party_member
 from dnd5e_engine.build_spec import (
@@ -67,7 +79,6 @@ from dnd5e_engine.types.effects import (
     ActiveEffectChange,
     ActiveEffectDuration,
 )
-from dnd5e_engine.types.intent import ActionType
 
 __all__ = [
     "AbilityScores",
@@ -118,3 +129,25 @@ __all__ = [
     "start_combat",
     "submit_player_intent",
 ]
+
+_GEN1_LAZY = {"ActionType": ("dnd5e_engine.types.intent", "ActionType")}
+
+
+def __getattr__(name: str) -> object:
+    # PEP 562 — keep the 0.3.x names resolvable without importing the
+    # deprecated modules eagerly (which would warn on every ``import dnd5e_engine``).
+    if name in _GEN1_LAZY:
+        import importlib
+        import warnings
+
+        module, attr = _GEN1_LAZY[name]
+        warnings.warn(
+            f"dnd5e_engine.{name} belongs to the legacy (Gen 1) surface — a host-side "
+            f"shape, not an engine type — and will be removed in dnd5e-engine 0.5.0. "
+            f"Import it from {module} (also deprecated) or copy it into your host; "
+            f"see docs/migration/v0.3-to-v0.4.md.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return getattr(importlib.import_module(module), attr)
+    raise AttributeError(f"module 'dnd5e_engine' has no attribute {name!r}")

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/__init__.py

@@ -1,6 +1,6 @@
 """Typed Foundry Activity resolver.
 
-Parallel to the Avrae-IR ``effects/`` package: consumes the typed
+Parallel to the legacy ``effects/`` package: consumes the typed
 ``dnd5e_srd_data`` ``Activity`` discriminated union and emits the engine's
 existing ``CombatEvent`` union via an ``event_emitter`` callback.
 """

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/apply.py

@@ -4,7 +4,7 @@ target-side vulnerability / resistance / immunity, emit ``DamageApplied``.
 MIRRORS, does not import from, ``effects/damage.py``:
 
 * Apply order is vulnerability ×2 → resistance //2 (integer floor) → immunity ⇒ 0,
-  matching ``_apply_resistance`` (Avrae's ``do_resistances`` order). An ``"all"``
+  matching ``_apply_resistance`` (the legacy ``do_resistances`` order). An ``"all"``
   wildcard is honored in each list (SRD §Conditions/Petrified emits "all").
 * ``is_overkill`` mirrors ``effects/damage.py:192`` — ``final_amount >
   target.hp_current`` (strictly greater).
@@ -88,7 +88,7 @@ def _apply_modifiers(
     immunities: set[str],
     vulnerabilities: set[str],
 ) -> int:
-    """Apply vuln (×2) → resist (//2 floor) → immune (⇒0) in Avrae order.
+    """Apply vuln (×2) → resist (//2 floor) → immune (⇒0) in the legacy evaluator order.
 
     Mirrors ``effects/damage.py:_apply_resistance``. The ``"all"`` wildcard is
     honored in each list (SRD §Conditions/Petrified resistance-to-all).

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/attack.py

@@ -106,7 +106,7 @@ def resolve_attack(
 
     # SRD §Advantage and Disadvantage — read the attacker's own
     # ``flags.advantage.attack`` / ``flags.disadvantage.attack`` override
-    # changes (both present cancel to normal, Avrae ``reconcile_adv``). These
+    # changes (both present cancel to normal, the legacy evaluator ``reconcile_adv``). These
     # gate the SRD §Sneak Attack trigger below; they deliberately do NOT change
     # the natural-d20 ``mode`` on this live path. Doing so would shift the
     # seeded dice stream and the crit outcome of the base attack, perturbing
@@ -127,7 +127,7 @@ def resolve_attack(
         # target's EFFECTIVE AC for this attack only; total cover is filtered
         # upstream (the target is never reachable as a resolver target at all).
         # SRD Shield — "+5 bonus to AC, including against the triggering
-        # attack" (C06-S03): a pre-armed reaction can land an AC-bonus active
+        # attack" a pre-armed reaction can land an AC-bonus active
         # effect on the target between the trigger and this comparison; the
         # natural roll itself is never touched, only this comparison.
         effective_ac = (
@@ -193,7 +193,7 @@ def attacker_advantage_flags(ctx: ActivityResolutionContext) -> tuple[bool, bool
                 has_advantage = True
             elif ch.key == "flags.disadvantage.attack":
                 has_disadvantage = True
-    # Both present cancel to normal (Avrae ``reconcile_adv``).
+    # Both present cancel to normal (the legacy evaluator ``reconcile_adv``).
     if has_advantage and has_disadvantage:
         return False, False
     return has_advantage, has_disadvantage
@@ -290,7 +290,7 @@ def _is_ranged_weapon(weapon: Weapon | None) -> bool:
     """True iff ``weapon`` is a ranged weapon (Foundry rwak scope).
 
     The ranged analog of ``_is_melee_weapon`` — the scope of
-    ``system.bonuses.rwak.damage`` (C04-S03).
+    ``system.bonuses.rwak.damage`` .
     """
     return weapon is not None and weapon.weapon_category in _RANGED_CATEGORIES
 
@@ -311,7 +311,7 @@ def _weapon_default_ability(weapon: Weapon, ctx: ActivityResolutionContext) -> s
     """SRD default attack/damage ability for a weapon with no explicit ability.
 
     * ranged weapon (``weapon_category`` in the ranged set) → DEX.
-    * finesse weapon (the ``finesse`` :class:`WeaponProperty`) → the better of the
+    * finesse weapon (the ``finesse`` ``WeaponProperty``) → the better of the
       caster's STR/DEX modifier (SRD §Finesse: the wielder chooses).
     * otherwise (melee non-finesse) → STR.
 
@@ -482,7 +482,7 @@ def _apply_on_hit_damage(
             if melee_bonus_expr:
                 by_type[first_type] += roll_expr(melee_bonus_expr, ctx.rng)
 
-        # C04-S03 / Foundry ``system.bonuses.rwak.damage`` — a ranged weapon
+        # / Foundry ``system.bonuses.rwak.damage`` — a ranged weapon
         # attack damage bonus, the ranged analog of the melee-only bonus just
         # above. Add it once to the first damage type, RANGED WEAPON only.
         if first_type is not None and _is_ranged_weapon(weapon):

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/build_context.py

@@ -1,49 +1,13 @@
-"""Build an :class:`ActivityResolutionContext` from live combat state.
+"""Build an ``ActivityResolutionContext`` from live combat state.
 
-The integration crux of the Avrae→Foundry resolver cutover (Task 2 of
-``docs/superpowers/plans/2026-06-03-bundled-asset-loader-cutover-plan.md``).
+This is the bridge between the orchestrator's mutable ``_LiveCombat`` and the
+pure activity resolvers. It reads the caster's real six ability scores,
+level-derived proficiency bonus, spellcasting ability and ``@scale`` values,
+folds in the passive attack/damage/save/check modifiers projected from active
+effects and conditions, and hands the resolvers a single immutable context.
 
-The new typed resolver consumes :class:`ActivityResolutionContext`. The OLD
-Avrae path faked caster magnitudes off the narrow :class:`Combatant`
-(``attack_bonus``, ``dexterity`` only — no per-ability scores, proficiency,
-or spellcasting ability). A Character caster's real six-ability scores +
-``character_level``-derived proficiency bonus have since landed (piece 4)
-and, per Cluster 4 (C04-S01), its save DC now runs the honest SRD 5.2
-formula (``8 + proficiency bonus + spellcasting-ability mod``, ``_save_dc``
-below) whenever a spellcasting ability resolves. The OLD flat
-approximations below are the byte-for-byte FALLBACK for the paths that still
-have no better ground truth:
-
-* PC fallback (no resolvable spellcasting ability — e.g. a non-caster class,
-  or a ``use_item`` cast, which never sets one) mirrors
-  ``intent_resolver._spellcasting_mod`` / ``_proficiency_bonus`` /
-  ``_spell_save_dc``: ``mod = max(0, attack_bonus-2)``, ``pb = 2``,
-  ``save_dc = 8 + pb + mod``.
-* Monster magnitudes (unaffected by Cluster 4 — no monster stat block threads
-  a per-ability sheet through here) mirror ``monster_ai._monster_save_dc``:
-  ``mod = attack_bonus``, ``save_dc = 8 + attack_bonus``.
-
-``caster_abilities`` is set uniformly across all six abilities to ``10 +
-2*mod`` FOR A MONSTER caster so the attack/damage handler — which resolves
-the governing ability *dynamically* (explicit ``attack.ability`` → weapon
-SRD default → finesse better-of-str/dex → spellcasting ability) — yields the
-old uniform ``@mod`` regardless of which ability it picks. A Character
-caster's ``caster_abilities`` are its real six scores (see below).
-
-This module is PURE: no I/O, no orchestrator import, no double-compute. The
-orchestrator already builds the per-entity passive sidecars (its
-``_build_hydration_payload`` projection) and passes the two dicts this builder
-needs — ``passive_damage_modifiers`` and ``save_modifiers`` — in as parameters at
-the Task 5/6 cutover. This builder only RESHAPES them into the typed context:
-
-* ``save_modifiers[id]["saves"]`` → ``passive_save_modifiers[id]`` ({ability:int})
-* ``save_modifiers[id]["passive_save_bonus"]`` (signed dice string) → carried verbatim
-* ``save_modifiers[id]["passive_save_adv"/"_dis"/"_auto_fail"]`` (UPPER-case
-  ability-code lists) → carried verbatim
-
-so the typed save path (``save_primitive.roll_save``) consumes the SAME bless/bane
-bonus, advantage/disadvantage, and auto-fail the OLD Avrae ``effects/save.py``
-path did. Empty / absent sidecar fields reproduce the prior behavior exactly.
+The resolvers never touch live combat state directly — everything they need
+arrives on the context, which is what keeps them pure and testable.
 """
 
 from __future__ import annotations
@@ -99,7 +63,7 @@ def _save_dc(
     intent such as ``use_item``, which never sets ``spellcasting_ability``)
     fall back to the OLD flat approximation byte-for-byte: Monster
     ``8 + attack_bonus`` (``_monster_save_dc``); PC ``8 + 2 + mod`` (the
-    Avrae-era ``_spell_save_dc``, ``pb`` hardcoded to ``2``).
+    the legacy evaluator-era ``_spell_save_dc``, ``pb`` hardcoded to ``2``).
     """
     if caster.entity_type == "Monster":
         return 8 + caster.attack_bonus
@@ -154,9 +118,9 @@ def build_activity_context(
     sneak_attack_ally_adjacent: dict[str, bool] | None = None,
 ) -> ActivityResolutionContext:
     """Adapt the caster + the pre-computed hydration sidecars into the typed
-    :class:`ActivityResolutionContext` the new resolver consumes.
+    ``ActivityResolutionContext`` the new resolver consumes.
 
-    Caster magnitudes reproduce the OLD Avrae approximations (see module
+    Caster magnitudes reproduce the OLD the legacy evaluator approximations (see module
     docstring). ``passive_damage_modifiers`` and ``save_modifiers`` are the two
     dicts the orchestrator's ``_build_hydration_payload`` already produces —
     passed IN so this builder stays pure (no orchestrator import, no I/O, no
@@ -188,7 +152,7 @@ def build_activity_context(
     path keeps the blanket override.
 
     ``cast_level_override`` passes straight through to
-    :class:`ActivityResolutionContext` — a ``use_item`` charges_to_spend
+    ``ActivityResolutionContext`` — a ``use_item`` charges_to_spend
     upcast's forced delegated-cast level (orchestrator-computed off the
     charge gate's own cost accounting). ``None`` (the default) leaves
     ``resolve_cast`` (``activities/cast.py``) to fall back to the wrapper
@@ -209,7 +173,7 @@ def build_activity_context(
         }
         caster_proficiency_bonus = proficiency_bonus(caster.character_level)
     else:
-        # Monsters/NPCs have no per-ability sheet here: keep the Avrae-era
+        # Monsters/NPCs have no per-ability sheet here: keep the legacy evaluator-era
         # uniform fake (10 + 2*mod across all six abilities, PB 2) so the
         # dynamic governing-ability resolution in attack.py reproduces the old
         # uniform @mod for any ability it picks.
@@ -253,7 +217,7 @@ def build_activity_context(
     for entity_id, dmg_entry in passive_damage_modifiers.items():
         # ``passive_damage_modifiers`` is a WIDE dict: resistance/immunity/
         # vulnerability lists PLUS the signed-dice ``passive_to_hit_bonus`` STRING
-        # the orchestrator projection wedges in (mirrors the OLD Avrae sidecar).
+        # the orchestrator projection wedges in (mirrors the OLD the legacy evaluator sidecar).
         to_hit: object = dmg_entry.get("passive_to_hit_bonus")
         if isinstance(to_hit, str) and to_hit:
             passive_attack_bonus[entity_id] = to_hit

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/cast.py

@@ -8,7 +8,7 @@ level, the referenced spell's base level / concentration flag / own
 ``resolve_activity`` for each activity on the referenced spell. ``cast`` emits
 NOTHING itself — the delegated child activities emit their own events.
 
-MIRRORS, does not import from, ``effects/spell.py`` (the Avrae-IR ``type:
+MIRRORS, does not import from, ``effects/spell.py`` (the legacy ``type:
 "spell"`` analogue). Reproduces its semantics with the typed lib shapes:
 
 * Spell-within-itself cycle guard FIRST (cheap, before the lookup): a ``uuid``

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/check.py

@@ -20,7 +20,7 @@ MIRRORS, does not import from, ``effects/check.py``:
 * The skill→ability mapping mirrors ``effects/check.py:_SKILL_TO_ABILITY`` but is
   keyed by the Foundry 3-letter skill *codes* the canonical ``check.associated``
   field actually carries (``"ath"``, ``"slt"``, ``"inv"``, ...) rather than the
-  Avrae long-form (``"athletics"``). Source: ``CONFIG.DND5E.skills`` in
+  the legacy evaluator long-form (``"athletics"``). Source: ``CONFIG.DND5E.skills`` in
   ``foundry/module/config.mjs``.
 * The modifier is the RESOLVED integer off a per-actor sidecar
   (``ctx.check_modifiers``), mirroring ``effects/check.py:_read_check_modifiers``
@@ -67,7 +67,7 @@ _ABILITIES: Final[frozenset[str]] = frozenset(get_args(Ability))
 # Foundry 3-letter skill code → governing SRD ability. Source: CONFIG.DND5E.skills
 # in foundry/module/config.mjs (each skill's ``ability`` field). The canonical
 # ``check.associated`` field carries these codes verbatim. Mirrors
-# ``effects/check.py:_SKILL_TO_ABILITY`` (which keys the Avrae long-form names).
+# ``effects/check.py:_SKILL_TO_ABILITY`` (which keys the legacy evaluator long-form names).
 _SKILL_TO_ABILITY: Final[dict[str, Ability]] = {
     "acr": "dex",
     "ani": "wis",

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/context.py

@@ -76,7 +76,7 @@ class ActivityResolutionContext:
     passive_damage_modifiers: dict[str, dict[str, list[str]]] = field(default_factory=dict)
     # Per-target saving-throw modifier sidecar, keyed entity_id -> {ability ->
     # resolved save bonus}. Mirrors how ``effects/save.py`` sources the target
-    # save modifier (``effect_store._save_modifiers[target_id]["saves"][ability]``)
+    # save modifier (``the host effect store._save_modifiers[target_id]["saves"][ability]``)
     # — the resolved per-ability integer, NOT rebuilt from ability score +
     # proficiency. ``Combatant`` carries no per-ability save table, so the save
     # handler reads this sidecar; an absent target / ability contributes +0
@@ -85,8 +85,8 @@ class ActivityResolutionContext:
     passive_save_modifiers: dict[str, dict[str, int]] = field(default_factory=dict)
     # Per-target additive save bonus, keyed entity_id -> a signed dice-expression
     # STRING (e.g. ``"+1d4"`` for Bless, ``"-1d4"`` for Bane; stacked sources
-    # pre-joined as ``"a + b"``). Mirrors the OLD Avrae path's
-    # ``effect_store._save_modifiers[id]["passive_save_bonus"]`` (orchestrator
+    # pre-joined as ``"a + b"``). Mirrors the OLD the legacy evaluator path's
+    # ``the host effect store._save_modifiers[id]["passive_save_bonus"]`` (orchestrator
     # hydration, ``_build_hydration_payload``); rolled through ``ctx.rng`` so the
     # bless/bane d4 lands in the same seed stream as the save d20. Absent target →
     # +0 (no bonus). Empty default keeps the golden corpus identical.
@@ -148,7 +148,7 @@ class ActivityResolutionContext:
     # ``"STR"``, ``"DEX"``, ...), keyed entity_id -> list[ability]. Mirrors the
     # OLD path's ``passive_save_adv`` / ``passive_save_dis`` (Faerie Fire,
     # Restrained, etc.). An ability present in both cancels to normal
-    # (Avrae ``reconcile_adv``). Empty defaults keep the golden corpus identical.
+    # (the legacy evaluator ``reconcile_adv``). Empty defaults keep the golden corpus identical.
     passive_save_adv: dict[str, list[str]] = field(default_factory=dict)
     passive_save_dis: dict[str, list[str]] = field(default_factory=dict)
     # Per-target auto-fail ability-code list (UPPER-case), keyed entity_id ->
@@ -176,7 +176,7 @@ class ActivityResolutionContext:
     # ``_fold_active_effect_changes`` + extracted in ``build_activity_context``);
     # consumed in ``attack.py`` alongside the cover-AC fold, before the
     # ``total >= target_ac`` comparison. Absent target -> +0. Empty default
-    # keeps the golden corpus identical (C06-S03).
+    # keeps the golden corpus identical .
     passive_ac_bonus: dict[str, int] = field(default_factory=dict)
     # Per-actor ability/skill-check modifier sidecar, mirroring
     # ``effects/check.py:_read_check_modifiers``'s shape

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/damage.py

@@ -6,7 +6,7 @@ SRD 5.2 corpus: a single Magic Missile dart (``1d4+1`` force), or Divine Smite's
 radiant burst (``2d8``/``3d8`` radiant) nested under a melee hit.
 
 Crit rule (``DamageActivityDamageBlock.critical`` is a
-:class:`SaveDamageCriticalBlock` — ``{allow, bonus}``): this activity crits ONLY
+``SaveDamageCriticalBlock`` — ``{allow, bonus}``): this activity crits ONLY
 when ``critical.allow`` is True AND ``ctx.variables["in_crit"]`` is truthy (the
 caller sets ``in_crit`` when the activity is nested under a crit attack). On crit
 the dice double (``roll_damage_part(crit=True)``) and the parsed ``critical.bonus``
@@ -24,7 +24,7 @@ coercion). A typeless part (empty ``types`` — a DATA defect in a handful of
 SRD spells; e.g. Call Lightning's 4d10 part) is logged loudly
 (``damage_part_untyped``) and skipped: ``apply_damage`` keys strictly by SRD
 type and has no untyped bucket, and the resolver cannot invent the SRD-correct
-type. Tracked as a ``dnd5e-srd-data`` data bug in ``docs/BACKLOG.md``.
+type. Tracked as a ``dnd5e-srd-data`` data bug in ``BACKLOG.md``.
 
 MIRRORS, does not import from, ``effects/damage.py``: @-token resolution runs
 through ``formula.resolve_damage_block`` (governing ability = the caster's
@@ -111,7 +111,7 @@ def _part_type(
     * Empty list: a DATA defect (the SRD part should carry a type). There is no
       untyped bucket in ``apply_damage``, so the part is logged loudly
       (``damage_part_untyped``) and skipped. Tracked as a ``dnd5e-srd-data`` bug
-      (see ``docs/BACKLOG.md``); the resolver must not invent the SRD-correct type.
+      (see ``BACKLOG.md``); the resolver must not invent the SRD-correct type.
     """
     if not part.types:
         _LOGGER.warning(

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/dice.py

@@ -302,7 +302,7 @@ def _cantrip_dice_count(character_level: int) -> int:
 def _double_dice(ast: d20.ast.Node) -> d20.ast.Node:
     """SRD §Critical Hits — double every ``Dice.num``, leave literals alone.
 
-    Mirrors ``effects/damage.py:_apply_crit_doubling`` (Avrae's default
+    Mirrors ``effects/damage.py:_apply_crit_doubling`` (the legacy default
     ``crit_mapper``): ``d20.utils.tree_map`` rebuilds each ``Dice(num, size)``
     as ``Dice(num*2, size)``; numeric modifiers are untouched.
     """

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/effects.py

@@ -228,7 +228,7 @@ def apply_activity_effects(
         # gated on the mapping.
         for status in sorted(pe.statuses):
             if status in _CONDITION_VALUES:
-                # C08-S02: condition-immunity gate. A target immune to this
+                # condition-immunity gate. A target immune to this
                 # condition (Nature's Ward → "poisoned") never has it attach —
                 # the ConditionApplied is SUPPRESSED outright (the EffectApplied
                 # rider above still fired narratively). Suppress, not

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/formula.py

@@ -6,11 +6,11 @@ their dice/DC formula fields — e.g. Cure Wounds' healing bonus is verbatim
 read these tokens, so each one is replaced with its caster-derived integer (as a
 string) before the dice helper parses the formula.
 
-MIRRORS, does not import from, the old Avrae-IR path's
+MIRRORS, does not import from, the old the legacy path's
 ``intent_resolver._walk_and_patch`` / ``_parse_with_injection``: that path
 injected the same caster magnitudes (ability mods, proficiency, spell DC) into
 formula strings before rolling. The caster's numbers live on
-:class:`ActivityResolutionContext`; the typed Activity only declares WHICH
+``ActivityResolutionContext``; the typed Activity only declares WHICH
 ability/DC-calc applies.
 
 Scope — the roll-data tokens that appear in canonical DICE/DC FORMULA fields

{dnd5e_engine-0.3.1 → dnd5e_engine-0.4.0}/src/dnd5e_engine/activities/heal.py

@@ -1,14 +1,14 @@
 """``heal`` kind handler for the Activity resolver.
 
 Foundry ``heal-data.mjs`` stores healing as a single ``DamagePartBlock``
-(:class:`HealActivity.healing`), not a list. The ``types`` list carries a
+(``healing``), not a list. The ``types`` list carries a
 single token: ``"healing"`` for HP restoration, ``"temphp"`` for a temporary
 HP buffer — both confirmed against canonical SRD 5.2 data (cure-wounds.json
 emits ``"healing"``; false-life.json emits ``"temphp"``). When ``temphp`` is
-present we emit :class:`TempHpApplied`, otherwise :class:`HealingApplied`.
+present we emit ``TempHpApplied``, otherwise ``HealingApplied``.
 
 MIRRORS, does not import from, ``effects/temphp.py`` for the temp-hp token
-distinction. The keep-higher replacement policy lives only on the Avrae-IR
+distinction. The keep-higher replacement policy lives only on the legacy
 ``effects/`` path (which carries an existing-temp-HP lookup); the typed
 Activity resolver emits the rolled grant directly, matching how ``apply.py``
 emits the rolled magnitude for damage.