dnd5e-engine 0.1.2__tar.gz → 0.2.0__tar.gz

dnd5e_engine-0.2.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+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).
+
+## [Unreleased]
+
+## [0.2.0]
+
+Lockstep release with `dnd5e-srd-data` 0.2.0 — the outcome of the gap-closing
+campaign (ten scenario clusters). See `docs/migration/v0.1-to-v0.2.md` for the
+full, host-facing migration guide. The engine now depends on
+`dnd5e-srd-data>=0.2.0` (the rest-cap path reads the new `Feature.uses` schema).
+
+### Added
+
+- **Rest & recovery** — new public, zero-I/O module `dnd5e_engine.rest`, called
+  *between* combats: `resolve_short_rest`, `resolve_long_rest`,
+  `recover_feature_uses`, the `HitDicePool` / `RestOutcome` value types, the
+  `RecoveryPeriod` literal — all added to the top-level `__all__`.
+  `FEATURE_USE_COUNTER_PREFIX` is also public, but is exported from the
+  submodule only: `from dnd5e_engine.rest import FEATURE_USE_COUNTER_PREFIX`.
+- **Spatial (grid) surface** — `WallSegment` value type (also a top-level
+  export); `GridScene.wall_segments`, `GridScene.cover_cells`, and
+  `GridScene.difficult_terrain_cells` fields (all default empty/off);
+  `SpatialTopology.cover_between(...)`; and `GridTopology.cells_in_template(...)`
+  for sphere/cone/line AoE templates.
+- **Passive-stat fields** — `condition_immunities` and `damage_vulnerabilities`
+  on `PartyMemberSpec` / `EncounterMemberSpec` / `Combatant`, and
+  `movement_modes` (`CombatantMovementModes`) plus `walk_speed_bonus` on
+  `PartyMemberSpec` / `Combatant`. All default empty and only take effect when
+  the backing dataset carries the trait.
+- **Intent field** `PlayerIntent.activity_id` (default `None`) — disambiguates a
+  `USE_FEATURE` invocation of a multi-activity feature (Channel Divinity,
+  Cunning Strike).
+- `PartyMemberSpec.reach_ft` (default `5`) — threads onto the live
+  `Combatant.melee_reach_ft`, making a reach weapon's opportunity-attack reach
+  reachable from the boundary spec.
+- **Reaction surface** — `"ready"` intents now register a pre-armed reaction;
+  `PlayerIntent.reaction_trigger` narrows to the `ReactionTrigger` literal.
+- `CastFailedReason` gained the values `"countered"` (Counterspell) and
+  `"no_uses_remaining"` (a capped, rest-recharged feature invoked over its cap).
+- New additive `ActivityResolutionContext` sidecar fields backing the above
+  (cover, per-category damage-bonus buckets, Sneak Attack gates, reaction AC
+  bonus) — all default empty.
+
+### Changed
+
+- **Spell save DC is now the real SRD 5.2 formula** (`8 + proficiency +
+  spellcasting-ability modifier`) for PC caster spells, replacing a flat
+  Avrae-era approximation — the campaign's widest-blast-radius change. Any host
+  casting a PC save-DC spell sees a different, SRD-correct DC. Item casts and
+  monster casters are unchanged.
+- **Sneak Attack rider** — a qualifying finesse/ranged rogue hit now deals the
+  `@scale`-resolved extra damage, doubled on a critical hit.
+- **Passive-projection behavioral flips** — Rage damage resistance now halves
+  matching damage; an immune condition never attaches; a matching damage
+  vulnerability doubles the hit; movement-mode / walk-speed bonuses (Fast
+  Movement, Roving) now fold onto `base_speed`.
+- **Monster behavior** — fleeing monsters now retreat away from their nearest
+  threat instead of standing still; a mixed melee+ranged multiattack now fires
+  the weapon that fits the current distance instead of always the first-listed
+  one; monsters Dash to close an out-of-reach movement gap.
+- **Reactions & action economy** — a countered `cast_spell` does **not** expend
+  its spell slot; a reaction-applied 1-round buff (Shield's +5 AC) now survives
+  until the owner's next turn; `"disengage"` is now a real turn-non-ending
+  action; PCs moving out of a monster's reach now provoke opportunity attacks.
+- **Active-effect changes** — `multiply` / `upgrade` / `downgrade` change modes
+  now apply; the `rwak` / `msak` / `rsak` damage and `spell.dc` bonus buckets
+  now fold; a weapon-tagged `damage.bonus` change now reaches swing damage.
+- Feature-owned `@scale` ids now resolve; the Foundry `(@scale.x)dN` dice-count
+  idiom now normalizes; capped features (Second Wind) are now per-rest limited.
+
+### Removed
+
+- `ActionType.SHORT_REST` (`dnd5e_engine.types.intent`) — a dead, unreachable
+  member of the legacy dispatch enum with no handler. It was never the
+  live-combat intent surface (`events.py::IntentType` has no `"short_rest"`).
+  Hosts wanting rest resolution use the new `dnd5e_engine.rest` module.
+- `rules/gambits.select_action` (with the private helpers `_PASS_ACTION` /
+  `_get_alive_targets` only it used) — the legacy per-profile gambit AI the live
+  monster-turn path never called. Every behaviour it offered now lives in
+  `advance_monster_turn` / `activities/monster_actions.py`. Verified caller-free;
+  it was not a top-level `__all__` export.
+  (`rules/gambits.assign_behavior_profile` was reviewed and **retained** — it is
+  a host-facing utility for constructing `EncounterMemberSpec.behavior_profile`
+  from raw monster stats, not dead code.)
+## [0.1.2]
+
+### Added
+- `ActionType.USE_ITEM` parser-facing action member.
+
+## [0.1.1]
+
+### Added
+- `LiveCombatView` — public read-model projection of live combat state.
+- `get_live(handle) -> LiveCombatView` is now part of the public API (`__all__`);
+  it returns a point-in-time snapshot view instead of the private `_LiveCombat`.
+- `roll_dice_str` — the dice-expression evaluator is now a public test seam
+  (renamed from the private `_roll_dice_str`).
+
+## [0.1.0]
+
+First public release.
+
+### Added
+
+- Pure-Python, host-agnostic D&D 5e SRD rules engine: combat orchestration,
+  ability checks and saving throws, and combat-scoped effects.
+- SRD 5.2 (2024) content resolution against the typed-Activity corpus via
+  `BundledAssetLoader`, reading the canonical dataset from the
+  `dnd5e-srd-data` package.
+- Curated public API surface (`__all__`) with a surface guard test.
+- `py.typed` marker — the package ships inline type information.
+- Zero-I/O guarantee: no DB, network, or async dependencies in the engine.

{dnd5e_engine-0.1.2 → dnd5e_engine-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dnd5e-engine
-Version: 0.1.2
+Version: 0.2.0
 Summary: Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O.
 Author: Tapestria contributors
 License: MIT License
@@ -34,7 +34,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
 Requires-Dist: d20>=1.1.2
-Requires-Dist: dnd5e-srd-data>=0.1.0
+Requires-Dist: dnd5e-srd-data>=0.2.0
 Requires-Dist: pydantic>=2.10.0
 Provides-Extra: dev
 Requires-Dist: bandit>=1.8.0; extra == 'dev'

{dnd5e_engine-0.1.2 → dnd5e_engine-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.1.2"
+version = "0.2.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"
@@ -24,7 +24,7 @@ dependencies = [
     # lib_loader imports BundledAssetLoader at runtime; the typed-Activity
     # resolver reads the canonical corpus through it. The data lib's >=3.12
     # floor is why this package now also requires >=3.12 (see requires-python).
-    "dnd5e-srd-data>=0.1.0",
+    "dnd5e-srd-data>=0.2.0",
 ]
 
 [project.optional-dependencies]

{dnd5e_engine-0.1.2 → dnd5e_engine-0.2.0}/src/dnd5e_engine/__init__.py

@@ -13,7 +13,7 @@ Deferred for later phases:
 
 from __future__ import annotations
 
-__version__ = "0.1.1"
+__version__ = "0.2.0"
 
 from dnd5e_engine.build_party import build_party_member
 from dnd5e_engine.build_spec import (
@@ -41,6 +41,14 @@ from dnd5e_engine.outcome import (
     DeathRecord,
     LootDrop,
 )
+from dnd5e_engine.rest import (
+    HitDicePool,
+    RecoveryPeriod,
+    RestOutcome,
+    recover_feature_uses,
+    resolve_long_rest,
+    resolve_short_rest,
+)
 from dnd5e_engine.results import EndCombatResult, StartCombatResult
 from dnd5e_engine.rules.effects import roll_dice_str
 from dnd5e_engine.spatial import cell_id, parse_cell
@@ -49,6 +57,7 @@ from dnd5e_engine.specs import (
     GridScene,
     PartyMemberSpec,
     SceneTopology,
+    WallSegment,
     ZoneEdge,
 )
 from dnd5e_engine.types.effects import (
@@ -76,13 +85,17 @@ __all__ = [
     "EncounterMemberSpec",
     "EndCombatResult",
     "GridScene",
+    "HitDicePool",
     "IntentType",
     "LiveCombatView",
     "LootDrop",
     "PartyMemberSpec",
     "PlayerIntent",
+    "RecoveryPeriod",
+    "RestOutcome",
     "SceneTopology",
     "StartCombatResult",
+    "WallSegment",
     "ZoneEdge",
     "advance_monster_turn",
     "build_party_member",
@@ -93,7 +106,10 @@ __all__ = [
     "make_build_spec",
     "narration_events",
     "parse_cell",
+    "recover_feature_uses",
     "resolve_check",
+    "resolve_long_rest",
+    "resolve_short_rest",
     "roll_dice_str",
     "start_combat",
     "submit_player_intent",

{dnd5e_engine-0.1.2 → dnd5e_engine-0.2.0}/src/dnd5e_engine/activities/attack.py

@@ -12,11 +12,13 @@ MIRRORS, does not import from, ``effects/attack.py`` + ``effects/damage.py``:
 
 * The natural-d20 roll honors ``ctx.variables["force_d20"]`` (the test seam),
   else draws from ``ctx.rng`` — ``max`` of two for advantage, ``min`` of two for
-  disadvantage, one otherwise (SRD §Advantage and Disadvantage). The mode is
-  always ``"normal"`` today: the typed Outlined-effect layer does not yet encode
-  an attack-advantage change, so no producer feeds a per-target adv/dis flag.
-  Re-add a per-target reconciliation (consumer + producer together) when the
-  data layer encodes Faerie-Fire-style ``flags.advantage.attack``.
+  disadvantage, one otherwise (SRD §Advantage and Disadvantage). The d20 ``mode``
+  itself stays ``"normal"`` on this live path: ``ctx.active_effects`` IS now read
+  for the attacker's ``flags.advantage.attack`` / ``flags.disadvantage.attack``
+  (``attacker_advantage_flags``), but only to GATE the SRD §Sneak Attack trigger
+  below — not to reroll the base attack. Rolling the base d20 with advantage/
+  disadvantage would shift the seeded stream and crit outcome; that separate
+  delta is deferred (see ``docs/migration/v0.1-to-v0.2.md`` / ``BACKLOG.md``).
 * Hit / crit / miss mirrors ``effects/attack.py:_resolve_hit_outcome``: natural
   20 → auto crit+hit, natural 1 → auto miss, else ``total >= AC`` (SRD §Rolling
   1 or 20 / §Making an Attack). The crit threshold is ``attack.critical.threshold
@@ -62,6 +64,7 @@ from dnd5e_engine.activities.effects import apply_activity_effects
 from dnd5e_engine.activities.formula import resolve_damage_block, resolve_roll_data
 from dnd5e_engine.activities.mastery import apply_mastery_on_hit, apply_mastery_on_miss
 from dnd5e_engine.events import AdvantageMode, AttackRolled
+from dnd5e_engine.spatial import cover_bonus
 
 if TYPE_CHECKING:
     from dnd5e_srd_data.schema.common import AttackActivity, DamagePartBlock
@@ -101,17 +104,38 @@ def resolve_attack(
     # fresh d4 in the seeded stream — mirrors save_primitive's passive_save_bonus.
     attack_bonus_expr = ctx.passive_attack_bonus.get(ctx.caster.entity_id)
 
+    # 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
+    # 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
+    # the very damage magnitudes the once-per-turn / ally-adjacent scenarios
+    # isolate (a Sneak Attack rider must be the ONLY damage delta a qualifying
+    # trigger introduces). Rolling the base attack itself with advantage/
+    # disadvantage on the live path is a separate, deferred delta — see
+    # ``docs/migration/v0.1-to-v0.2.md`` and ``BACKLOG.md``.
+    attacker_has_advantage, attacker_has_disadvantage = attacker_advantage_flags(ctx)
+
     for index, target in enumerate(ctx.targets):
-        # No producer feeds per-target attack adv/dis today (the typed Outlined
-        # effect layer does not yet encode an attack-advantage change), so the
-        # mode is always normal. Re-add a per-target reconciliation when the data
-        # layer encodes Faerie-Fire-style ``flags.advantage.attack``.
         mode: AdvantageMode = "normal"
         natural = _roll_natural_d20(ctx, mode, target_index=index)
         total = natural + attack_bonus
         if attack_bonus_expr:
             total += roll_expr(attack_bonus_expr, ctx.rng)
-        is_crit, is_hit = _resolve_hit_outcome(natural, total, target.ac, activity)
+        # SRD 5.2 §Cover — half (+2) / three-quarters (+5) cover raises the
+        # 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
+        # effect on the target between the trigger and this comparison; the
+        # natural roll itself is never touched, only this comparison.
+        effective_ac = (
+            target.ac
+            + cover_bonus(ctx.target_cover.get(target.entity_id, "none"))
+            + ctx.passive_ac_bonus.get(target.entity_id, 0)
+        )
+        is_crit, is_hit = _resolve_hit_outcome(natural, total, effective_ac, activity)
 
         ctx.event_emitter(
             AttackRolled(
@@ -126,7 +150,16 @@ def resolve_attack(
         )
 
         if is_hit:
-            _apply_on_hit_damage(activity, ctx, target, weapon, governing_ability, is_crit=is_crit)
+            _apply_on_hit_damage(
+                activity,
+                ctx,
+                target,
+                weapon,
+                governing_ability,
+                is_crit=is_crit,
+                attacker_has_advantage=attacker_has_advantage,
+                attacker_has_disadvantage=attacker_has_disadvantage,
+            )
             apply_mastery_on_hit(weapon, ctx, target, governing_ability)
             apply_activity_effects(
                 activity, ctx, target, save_succeeded=None, cast_level=cast_level
@@ -135,6 +168,84 @@ def resolve_attack(
             apply_mastery_on_miss(weapon, ctx, target, governing_ability)
 
 
+# ── attacker advantage / Sneak Attack production ─────────────────────────────
+
+
+def attacker_advantage_flags(ctx: ActivityResolutionContext) -> tuple[bool, bool]:
+    """Read the attacker's ``flags.advantage/disadvantage.attack`` override changes.
+
+    SRD §Advantage and Disadvantage. Mirrors the attacker-flag half of
+    ``rules/combat.py``'s reconciliation: an ``override``-mode change with value
+    ``True`` on an effect the CASTER carries flips the corresponding flag. Only
+    the caster's own effects count here (target-side Faerie-Fire production is
+    deferred — see the migration note); an absent/empty ``active_effects`` yields
+    ``(False, False)`` (``normal``), byte-identical to the prior hardcode.
+    """
+    has_advantage = False
+    has_disadvantage = False
+    for eff in ctx.active_effects:
+        if eff.target_id != ctx.caster.entity_id:
+            continue
+        for ch in eff.changes:
+            if ch.mode != "override" or ch.value is not True:
+                continue
+            if ch.key == "flags.advantage.attack":
+                has_advantage = True
+            elif ch.key == "flags.disadvantage.attack":
+                has_disadvantage = True
+    # Both present cancel to normal (Avrae ``reconcile_adv``).
+    if has_advantage and has_disadvantage:
+        return False, False
+    return has_advantage, has_disadvantage
+
+
+def sneak_attack_dice(ctx: ActivityResolutionContext) -> str | None:
+    """The caster's Sneak Attack extra-damage dice expression, if granted.
+
+    SRD §Sneak Attack (Rogue): the feature's ``damage.parts[0]`` formula is
+    ``@scale.<class>.sneak-attack`` (``"3d6"`` at Rogue level 5). The
+    orchestrator pre-resolves that ``@scale`` token into ``ctx.scale_values``
+    at the build-party seam (loader access there); this pure resolver reads the
+    already-resolved dice STRING keyed ``"<class>.sneak-attack"``. Absent ⇒ the
+    caster has no Sneak Attack (``None``, no rider).
+    """
+    for key, value in ctx.scale_values.items():
+        if key.endswith(".sneak-attack") and isinstance(value, str) and value:
+            return value
+    return None
+
+
+def sneak_attack_triggers(
+    ctx: ActivityResolutionContext,
+    weapon: Weapon | None,
+    target: Combatant,
+    *,
+    attacker_has_advantage: bool,
+    attacker_has_disadvantage: bool,
+) -> bool:
+    """SRD §Sneak Attack trigger: a Finesse-or-Ranged weapon hit made with
+    Advantage, OR (the ally-adjacent alternative) an ally within 5 ft of the
+    target who is not Incapacitated while the attacker is not at Disadvantage.
+
+    The ally-adjacent spatial predicate is evaluated orchestrator-side (a new
+    consumer of ``spatial.py``) and delivered as the per-target
+    ``ctx.sneak_attack_ally_adjacent`` flag; this pure resolver only reads it.
+    A spell attack (no weapon) never qualifies.
+    """
+    if weapon is None:
+        return False
+    is_finesse = WeaponProperty.FINESSE in weapon.properties
+    is_ranged = weapon.weapon_category in _RANGED_CATEGORIES
+    if not (is_finesse or is_ranged):
+        return False
+    if attacker_has_advantage:
+        return True
+    # Ally-adjacent alternative: an adjacent, non-Incapacitated ally (computed
+    # orchestrator-side) while the attacker is not at Disadvantage.
+    ally_adjacent = bool(ctx.sneak_attack_ally_adjacent.get(target.entity_id))
+    return ally_adjacent and not attacker_has_disadvantage
+
+
 # ── attack-bonus resolution ──────────────────────────────────────────────────
 
 
@@ -175,6 +286,27 @@ def _is_melee_weapon(weapon: Weapon | None) -> bool:
     return weapon is not None and weapon.weapon_category not in _RANGED_CATEGORIES
 
 
+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).
+    """
+    return weapon is not None and weapon.weapon_category in _RANGED_CATEGORIES
+
+
+def _is_melee_spell_attack(activity: AttackActivity, weapon: Weapon | None) -> bool:
+    """True iff this is a melee SPELL attack (Foundry msak scope: no weapon,
+    ``attack.type.value == "melee"`` — e.g. Shocking Grasp)."""
+    return weapon is None and activity.attack.type.value == "melee"
+
+
+def _is_ranged_spell_attack(activity: AttackActivity, weapon: Weapon | None) -> bool:
+    """True iff this is a ranged SPELL attack (Foundry rsak scope: no weapon,
+    ``attack.type.value == "ranged"`` — e.g. Fire Bolt)."""
+    return weapon is None and activity.attack.type.value == "ranged"
+
+
 def _weapon_default_ability(weapon: Weapon, ctx: ActivityResolutionContext) -> str:
     """SRD default attack/damage ability for a weapon with no explicit ability.
 
@@ -295,6 +427,8 @@ def _apply_on_hit_damage(
     governing_ability: str | None,
     *,
     is_crit: bool,
+    attacker_has_advantage: bool = False,
+    attacker_has_disadvantage: bool = False,
 ) -> None:
     """Roll base weapon damage + activity parts for one hit target and apply.
 
@@ -348,6 +482,72 @@ 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
+        # 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):
+            ranged_bonus_expr = ctx.passive_ranged_damage_bonus.get(ctx.caster.entity_id)
+            if ranged_bonus_expr:
+                by_type[first_type] += roll_expr(ranged_bonus_expr, ctx.rng)
+
+        # Foundry ``system.bonuses.msak.damage`` / ``system.bonuses.rsak.damage``
+        # — melee / ranged SPELL-attack damage bonuses (e.g. Shocking Grasp /
+        # Fire Bolt). No weapon is present for a spell attack; gate on the
+        # activity's own melee/ranged classification instead.
+        if first_type is not None and _is_melee_spell_attack(activity, weapon):
+            melee_spell_bonus_expr = ctx.passive_melee_spell_damage_bonus.get(ctx.caster.entity_id)
+            if melee_spell_bonus_expr:
+                by_type[first_type] += roll_expr(melee_spell_bonus_expr, ctx.rng)
+        if first_type is not None and _is_ranged_spell_attack(activity, weapon):
+            ranged_spell_bonus_expr = ctx.passive_ranged_spell_damage_bonus.get(
+                ctx.caster.entity_id
+            )
+            if ranged_spell_bonus_expr:
+                by_type[first_type] += roll_expr(ranged_spell_bonus_expr, ctx.rng)
+
+        # SRD §Making an Attack / §Magic Items — a magic weapon's bonus
+        # applies to BOTH the attack roll and the damage roll made with it.
+        # Folded into the ``passive_weapon_damage_bonus`` sidecar by the
+        # orchestrator (action-type-tagged so it never leaks into spell
+        # attacks). Applies to ANY weapon swing (melee or ranged), unlike the
+        # Rage-only melee bonus above. Add it once to the first damage type,
+        # rolled through ``ctx.rng`` so a dice-valued bonus lands in the same
+        # seed stream.
+        if first_type is not None and weapon is not None:
+            weapon_bonus_expr = ctx.passive_weapon_damage_bonus.get(ctx.caster.entity_id)
+            if weapon_bonus_expr:
+                by_type[first_type] += roll_expr(weapon_bonus_expr, ctx.rng)
+
+        # SRD §Sneak Attack (Rogue) — once per turn, on a qualifying hit (Finesse
+        # or Ranged weapon, made with Advantage OR the ally-adjacent alternative,
+        # rider unspent this turn), add the feature's extra dice. Folded into the
+        # FIRST damage type ("the extra damage's type is the same as the
+        # weapon's"). Rolled through ``ctx.rng`` (via ``roll_expr``, matching the
+        # passive-bonus fold pattern) so the dice land in the same seed stream.
+        # On a crit the rider dice DOUBLE — SRD 5.2 §Critical Hit ("Roll all of
+        # the attack's damage dice twice and add them together",
+        # 09_rules_glossary.md; the rider is part of the attack's damage dice) —
+        # via the SAME ``_double_dice`` count-doubling idiom the base-weapon
+        # crit path (``roll_damage_part(crit=...)``) uses.
+        # The once-per-turn cap gates the FOLD itself (``sneak_attack_spent``);
+        # recording "spent" is an orchestrator-side concern (a per-turn
+        # ``Combatant`` flag cleared at ``TurnStarted``).
+        if (
+            first_type is not None
+            and weapon is not None
+            and not ctx.sneak_attack_spent.get(ctx.caster.entity_id)
+            and sneak_attack_triggers(
+                ctx,
+                weapon,
+                target,
+                attacker_has_advantage=attacker_has_advantage,
+                attacker_has_disadvantage=attacker_has_disadvantage,
+            )
+        ):
+            sneak_dice = sneak_attack_dice(ctx)
+            if sneak_dice:
+                by_type[first_type] += roll_expr(sneak_dice, ctx.rng, crit=is_crit)
+
         apply_damage(target, dict(by_type), ctx)
     finally:
         if is_crit: