dnd5e-engine 0.3.2__tar.gz → 0.5.0__tar.gz

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/CHANGELOG.md

@@ -7,6 +7,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0]
+
+Lockstep release with `dnd5e-srd-data` 0.5.0 and `nat20-bridge` 0.5.0.
+
+Removes the legacy (Gen 1) rules surface deprecated in 0.4.0. The engine now
+ships exactly one, seedable, documented rules implementation
+(`orchestrator` + `activities/`). See `docs/migration/v0.4-to-v0.5.md`.
+
+### Removed
+
+- Modules `dispatch`, `event_dicts`, `types.dice`, `types.intent`, and
+  `rules.{combat, combat_data, combat_helpers, equipment, gambits, resolution,
+  spells}` (plus the private `rules._parsing` / `rules._class_meta`).
+- `dnd5e_engine.ActionType`, `CombatNPC`, and the lazy
+  `dnd5e_engine.types.{ActionType, CombatOutcome, DiceOutcome, CombatNPC}`
+  re-exports; the 0.4.0 `DeathSaveState` / `BehaviorProfile` re-export shims.
+- The cross-generation parity test; its Gen 2 assertions live on in
+  `tests/test_attack_classification.py`.
+
+## [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.

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: dnd5e-engine
-Version: 0.3.2
+Version: 0.5.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.2 → dnd5e_engine-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.3.2"
+version = "0.5.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,10 @@ max-complexity = 23
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+filterwarnings = [
+    # Any DeprecationWarning the engine itself raises is a bug.
+    "error::DeprecationWarning:dnd5e_engine",
+]
 
 [tool.coverage.run]
 source = ["dnd5e_engine"]

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/__init__.py

@@ -79,11 +79,9 @@ from dnd5e_engine.types.effects import (
     ActiveEffectChange,
     ActiveEffectDuration,
 )
-from dnd5e_engine.types.intent import ActionType
 
 __all__ = [
     "AbilityScores",
-    "ActionType",
     "ActiveEffect",
     "ActiveEffectChange",
     "ActiveEffectDuration",

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/death_saves.py

@@ -22,6 +22,7 @@ from __future__ import annotations
 
 import random
 from dataclasses import dataclass
+from typing import Any
 
 from dnd5e_engine.events import (
     CombatEvent,
@@ -30,9 +31,98 @@ from dnd5e_engine.events import (
     DeathSaveStarted,
     Stabilized,
 )
-from dnd5e_engine.rules.combat_helpers import DeathSaveState
 from dnd5e_engine.types.combat import Combatant
 
+
+@dataclass
+class DeathSaveState:
+    """Mutable state machine for D&D 5e death saving throws.
+
+    Designed for host persistence via to_dict / from_dict.
+    """
+
+    successes: int = 0
+    failures: int = 0
+    is_stable: bool = False
+
+    # ------------------------------------------------------------------
+    # Core state transitions
+    # ------------------------------------------------------------------
+
+    def apply_save(self, success: bool, is_critical: bool) -> str:
+        """Apply a death saving throw result.
+
+        Returns one of: "critical_success" | "stabilized" | "dead" | "ongoing".
+
+        Rules:
+        - Nat 20 (success=True, is_critical=True): regain 1 HP -> "critical_success"
+        - Nat 1  (success=False, is_critical=True): 2 failures
+        - Normal success: 1 success; 3 successes -> "stabilized"
+        - Normal failure: 1 failure; 3 failures  -> "dead"
+        """
+        # Nat 20 takes priority — regain 1 HP, no counter update needed
+        if success and is_critical:
+            return "critical_success"
+
+        if success:
+            self.successes += 1
+        elif is_critical:
+            # Nat 1 counts as 2 failures
+            self.failures += 2
+        else:
+            self.failures += 1
+
+        return self._check_outcome()
+
+    def apply_damage_while_unconscious(self, is_melee_within_5ft: bool) -> str:
+        """Apply death save failures from damage while unconscious.
+
+        D&D 5e RAW: taking any damage while at 0 HP is a death save failure.
+        Melee attack within 5 ft = auto-crit = 2 failures. Otherwise 1 failure.
+
+        Returns "dead" if 3+ failures reached, else "ongoing".
+        """
+        self.failures += 2 if is_melee_within_5ft else 1
+        return self._check_outcome()
+
+    def reset(self) -> None:
+        """Reset all counters (called when character regains HP via nat 20)."""
+        self.successes = 0
+        self.failures = 0
+        self.is_stable = False
+
+    # ------------------------------------------------------------------
+    # Serialization (plain dicts for host persistence)
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "successes": self.successes,
+            "failures": self.failures,
+            "is_stable": self.is_stable,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict[str, Any]) -> DeathSaveState:
+        return cls(
+            successes=d.get("successes", 0),
+            failures=d.get("failures", 0),
+            is_stable=d.get("is_stable", False),
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _check_outcome(self) -> str:
+        if self.failures >= 3:
+            return "dead"
+        if self.successes >= 3:
+            self.is_stable = True
+            return "stabilized"
+        return "ongoing"
+
+
 # Outcome literal returned alongside events/state for the caller to drive
 # turn skip / combat-end / consciousness restore.
 DeathSaveOutcome = str  # "ongoing" | "stabilized" | "dead" | "critical_success"
@@ -150,6 +240,7 @@ def reset_death_saves(combatant: Combatant) -> Combatant:
 __all__ = [
     "DeathSaveOutcome",
     "DeathSaveResult",
+    "DeathSaveState",
     "reset_death_saves",
     "roll_death_save",
 ]

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/orchestrator.py

@@ -119,7 +119,6 @@ from dnd5e_engine.rules.conditions import (
     project_passive_damage_modifiers,
     project_passive_save_modifiers,
 )
-from dnd5e_engine.rules.gambits import BehaviorProfile
 from dnd5e_engine.spatial import GridTopology, SpatialTopology
 from dnd5e_engine.specs import (
     EncounterMemberSpec,
@@ -128,7 +127,7 @@ from dnd5e_engine.specs import (
     SceneTopology,
     ZoneEdge,
 )
-from dnd5e_engine.types.combat import Combatant
+from dnd5e_engine.types.combat import BehaviorProfile, Combatant
 from dnd5e_engine.types.conditions import ActiveCondition
 from dnd5e_engine.types.effects import ActiveEffect, ActiveEffectDuration
 from dnd5e_engine.views import LiveCombatView

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/specs.py

@@ -170,7 +170,7 @@ class EncounterMemberSpec(BaseModel):
     # Person targets humanoids; Sleep autopasses undead/elves; etc.).
     creature_type: str | None = None
     # SRD §Damage Resistance / §Damage Immunity — per-monster type lists,
-    # populated from MonsterTemplate (via CombatMonster / CombatNPC). Empty
+    # populated from the host's monster template record. Empty
     # by default for fixtures that don't specify.
     damage_resistances: list[str] = Field(default_factory=list)
     damage_immunities: list[str] = Field(default_factory=list)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/types/__init__.py

@@ -1,24 +1,18 @@
 """dnd5e-engine type surface — host-agnostic Pydantic + Literal types."""
 
-from dnd5e_engine.types.combat import Combatant, CombatNPC
+from dnd5e_engine.types.combat import Combatant
 from dnd5e_engine.types.conditions import ActiveCondition, ConditionScope
-from dnd5e_engine.types.dice import DiceOutcome
 from dnd5e_engine.types.effects import (
     ActiveEffect,
     ActiveEffectChange,
     ActiveEffectDuration,
 )
-from dnd5e_engine.types.intent import ActionType, CombatOutcome
 
 __all__ = [
-    "ActionType",
     "ActiveCondition",
     "ActiveEffect",
     "ActiveEffectChange",
     "ActiveEffectDuration",
-    "CombatNPC",
-    "CombatOutcome",
     "Combatant",
     "ConditionScope",
-    "DiceOutcome",
 ]

{dnd5e_engine-0.3.2 → dnd5e_engine-0.5.0}/src/dnd5e_engine/types/combat.py

@@ -1,4 +1,4 @@
-"""Combat participant types — ``Combatant`` + ``CombatNPC``.
+"""Combat participant types — ``Combatant`` and ``BehaviorProfile``.
 
 Host-agnostic value types: stdlib + pydantic + the engine's own
 ``ActiveCondition``. ``Combatant`` is the engine's per-creature runtime combat
@@ -7,6 +7,7 @@ state; hosts read it through ``dnd5e_engine.views.LiveCombatView``.
 
 from __future__ import annotations
 
+from enum import StrEnum
 from typing import Any
 
 from pydantic import BaseModel, Field, model_validator
@@ -15,33 +16,12 @@ from dnd5e_engine.activities.passive_stats import CombatantMovementModes, Combat
 from dnd5e_engine.types.conditions import ActiveCondition
 
 
-class CombatNPC(BaseModel):
-    """Ephemeral sidecar record for an NPC in combat. Host-scoped;
-    cleared at end of combat. Owns template-derived combat stats that don't
-    fit on the narrow Combatant: saves, resistances, immunities, ability
-    scores, behavior_profile. Symmetric to CombatMonster for non-Character
-    entities."""
+class BehaviorProfile(StrEnum):
+    """Monster AI posture consumed by the orchestrator's flee heuristic."""
 
-    npc_id: str  # persistent NPC node ID (npc:hex12)
-    template_id: str  # MonsterTemplate node ID used at materialization
-    name: str
-    hp_current: int
-    hp_max: int
-    ac: int
-    attack_bonus: int
-    damage_dice: str
-    damage_type: str
-    has_ranged_attack: bool = False
-    dexterity: int = 10
-    strength: int = 10
-    constitution: int = 10
-    wisdom: int = 10
-    intelligence: int = 10
-    charisma: int = 10
-    behavior_profile: str = "AGGRESSIVE"
-    damage_resistances: list[str] = Field(default_factory=list)
-    damage_immunities: list[str] = Field(default_factory=list)
-    is_alive: bool = True
+    AGGRESSIVE = "AGGRESSIVE"
+    RANGED = "RANGED"
+    DEFENSIVE = "DEFENSIVE"
 
 
 class Combatant(BaseModel):
@@ -101,7 +81,7 @@ class Combatant(BaseModel):
     # application path (``activities/effects.py::apply_activity_effects``)
     # suppresses a ``ConditionApplied`` whose condition is in this list
     # . Empty by default. NOTE: distinct from the dead, host-supplied
-    # ``dispatch.py::DispatchContext.condition_immunities`` legacy surface.
+    # legacy dispatch surface's ``condition_immunities`` (removed in 0.5.0).
     condition_immunities: list[str] = Field(default_factory=list)
     # SRD §Senses — special senses in feet (darkvision/blindsight/tremorsense/
     # truesight). Projected from PC species + always-on feature passive_effects
@@ -214,6 +194,6 @@ class Combatant(BaseModel):
 
 
 __all__ = [
-    "CombatNPC",
+    "BehaviorProfile",
     "Combatant",
 ]

dnd5e_engine-0.5.0/tests/activities/test_save_dc_and_damage_exprs.py

@@ -0,0 +1,129 @@
+"""Direct pins on ``activities/save.py::_resolve_dc`` and the damage-expression
+builders in ``activities/dice.py`` / ``activities/formula.py``.
+
+The end-to-end scenarios reach these only through the corpus' common shapes
+(spellcasting DC, automatic ``{n}d{d}`` formulas); the flat-DC, custom-formula
+and scaling-token branches are pinned here.
+"""
+
+from __future__ import annotations
+
+import random
+
+import pytest
+from dnd5e_srd_data.loader import BundledAssetLoader
+from dnd5e_srd_data.schema.common import (
+    DamageCustomBlock,
+    DamagePart,
+    DamagePartBlock,
+    DamageScalingBlock,
+    SaveActivity,
+)
+
+from dnd5e_engine.activities.context import ActivityResolutionContext
+from dnd5e_engine.activities.dice import damage_part_to_expr
+from dnd5e_engine.activities.formula import resolve_damage_block
+from dnd5e_engine.activities.save import _resolve_dc
+from dnd5e_engine.types.combat import Combatant
+
+
+def _ctx(**overrides: object) -> ActivityResolutionContext:
+    kwargs: dict[str, object] = dict(
+        rng=random.Random(1),
+        caster=Combatant(
+            entity_id="char:wiz",
+            entity_type="Character",
+            name="Wiz",
+            initiative=10,
+            hp_current=10,
+            hp_max=10,
+        ),
+        targets=[],
+        event_emitter=lambda ev: None,
+        caster_abilities={"str": 10, "dex": 10, "con": 10, "int": 16, "wis": 10, "cha": 10},
+        caster_proficiency_bonus=2,
+        spellcasting_ability="int",
+    )
+    kwargs.update(overrides)
+    return ActivityResolutionContext(**kwargs)  # type: ignore[arg-type]
+
+
+@pytest.fixture(scope="module")
+def fireball_save() -> SaveActivity:
+    spell = BundledAssetLoader().get_spell("fireball")
+    assert spell is not None
+    activity = next(a for a in spell.activities if a.kind == "save")
+    assert isinstance(activity, SaveActivity)
+    return activity
+
+
+def _with_dc(activity: SaveActivity, calculation: str, formula: str = "") -> SaveActivity:
+    dc = activity.save.dc.model_copy(update={"calculation": calculation, "formula": formula})
+    return activity.model_copy(update={"save": activity.save.model_copy(update={"dc": dc})})
+
+
+# ── _resolve_dc ──────────────────────────────────────────────────────────────
+
+
+def test_spellcasting_dc_is_8_plus_prof_plus_mod(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(fireball_save, _ctx()) == 8 + 2 + 3
+
+
+def test_spellcasting_dc_without_a_casting_ability_is_loud(fireball_save: SaveActivity) -> None:
+    with pytest.raises(ValueError, match="spellcasting ability"):
+        _resolve_dc(fireball_save, _ctx(spellcasting_ability=None))
+
+
+def test_flat_dc_resolves_the_formula(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(_with_dc(fireball_save, "flat", "13"), _ctx()) == 13
+
+
+def test_flat_dc_resolves_roll_data_tokens(fireball_save: SaveActivity) -> None:
+    # @prof folds to the caster's proficiency bonus before evaluation.
+    assert _resolve_dc(_with_dc(fireball_save, "flat", "10 + @prof"), _ctx()) == 12
+
+
+def test_unknown_dc_calculation_is_loud(fireball_save: SaveActivity) -> None:
+    with pytest.raises(ValueError, match="not resolvable"):
+        _resolve_dc(_with_dc(fireball_save, "mystery"), _ctx())
+
+
+def test_save_dc_override_bypasses_the_calculation(fireball_save: SaveActivity) -> None:
+    assert _resolve_dc(_with_dc(fireball_save, "mystery"), _ctx(save_dc_override=18)) == 18
+
+
+# ── damage_part_to_expr ──────────────────────────────────────────────────────
+
+
+def test_weapon_damage_part_passes_its_dice_string_through() -> None:
+    assert damage_part_to_expr(DamagePart(dice="2d6+3", damage_type="slashing")) == "2d6+3"
+
+
+def test_activity_block_builds_the_automatic_formula() -> None:
+    assert damage_part_to_expr(DamagePartBlock(number=2, denomination=6, bonus="3")) == "2d6+3"
+
+
+def test_activity_block_with_only_a_bonus_is_the_bare_bonus() -> None:
+    assert damage_part_to_expr(DamagePartBlock(bonus="5")) == "5"
+
+
+def test_activity_block_custom_formula_wins_when_enabled() -> None:
+    block = DamagePartBlock(
+        number=2, denomination=6, custom=DamageCustomBlock(enabled=True, formula="1d4")
+    )
+    assert damage_part_to_expr(block) == "1d4"
+
+
+# ── resolve_damage_block ─────────────────────────────────────────────────────
+
+
+def test_scaling_formula_tokens_are_resolved_off_the_context() -> None:
+    block = DamagePartBlock(number=1, denomination=8, scaling=DamageScalingBlock(formula="@prof"))
+    resolved = resolve_damage_block(block, _ctx(), ability="int")
+    assert resolved.scaling.formula == "2"
+    assert resolved.number == 1  # untouched fields survive the copy
+
+
+def test_block_without_tokens_is_returned_unchanged() -> None:
+    block = DamagePartBlock(number=1, denomination=8, bonus="2")
+    assert resolve_damage_block(block, _ctx(), ability="int") is block

dnd5e_engine-0.5.0/tests/test_attack_classification.py

@@ -0,0 +1,84 @@
+"""Pin the SRD hit / crit / miss classification of the attack resolver.
+
+Carried over from the (now retired) cross-generation parity test: these are
+the rules whose drift between the two former implementations motivated the
+0.5.0 consolidation, so they stay pinned on the surviving path.
+"""
+
+from __future__ import annotations
+
+import random
+
+import pytest
+from dnd5e_srd_data.loader import BundledAssetLoader
+from dnd5e_srd_data.schema.common import AttackActivity
+
+from dnd5e_engine.activities.attack import _resolve_hit_outcome, _roll_natural_d20
+from dnd5e_engine.activities.context import ActivityResolutionContext
+from dnd5e_engine.types.combat import Combatant
+
+
+@pytest.fixture(scope="module")
+def attack() -> AttackActivity:
+    longsword = BundledAssetLoader().get_weapon("longsword")
+    assert longsword is not None
+    activity = next(a for a in longsword.activities if a.kind == "attack")
+    assert isinstance(activity, AttackActivity)
+    return activity
+
+
+def _ctx(seed: int) -> ActivityResolutionContext:
+    hero = Combatant(
+        entity_id="char:hero",
+        entity_type="Character",
+        name="Hero",
+        initiative=10,
+        hp_current=10,
+        hp_max=10,
+    )
+    return ActivityResolutionContext(
+        rng=random.Random(seed),
+        caster=hero,
+        targets=[],
+        event_emitter=lambda ev: None,
+        caster_abilities={"str": 10, "dex": 10, "con": 10, "int": 10, "wis": 10, "cha": 10},
+    )
+
+
+def test_natural_one_always_misses_even_with_a_huge_bonus(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(1, 1 + 50, 10, attack) == (False, False)
+
+
+def test_natural_twenty_always_crits_even_against_impossible_ac(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(20, 20, 99, attack) == (True, True)
+
+
+def test_meeting_the_ac_exactly_is_a_hit(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(10, 15, 15, attack) == (False, True)
+
+
+def test_falling_one_short_of_the_ac_is_a_miss(attack: AttackActivity) -> None:
+    assert _resolve_hit_outcome(10, 14, 15, attack) == (False, False)
+
+
+@pytest.mark.parametrize("seed", range(32))
+def test_advantage_keeps_the_higher_and_disadvantage_the_lower_die(seed: int) -> None:
+    rng = random.Random(seed)
+    a, b = rng.randint(1, 20), rng.randint(1, 20)
+    assert _roll_natural_d20(_ctx(seed), "advantage") == max(a, b)
+    assert _roll_natural_d20(_ctx(seed), "disadvantage") == min(a, b)
+    assert _roll_natural_d20(_ctx(seed), "normal") == a
+
+
+def test_disadvantage_does_not_crit_on_the_discarded_die(attack: AttackActivity) -> None:
+    # Find a seed whose two dice are (20, x<20): the kept die under disadvantage
+    # must not be the discarded 20.
+    for seed in range(500):
+        rng = random.Random(seed)
+        a, b = rng.randint(1, 20), rng.randint(1, 20)
+        if 20 in (a, b) and min(a, b) < 20:
+            natural = _roll_natural_d20(_ctx(seed), "disadvantage")
+            assert natural == min(a, b)
+            assert _resolve_hit_outcome(natural, natural, 99, attack)[0] is False
+            return
+    pytest.fail("no seed with a discarded 20 in 500 tries")

dnd5e_engine-0.5.0/tests/test_combat_bucket_keys.py

@@ -0,0 +1,61 @@
+"""Regression — combat resolvers use Foundry-shaped bucket keys (Phase 6).
+
+Codex review of Phase 6 caught that ``rules/combat.py`` was passing legacy
+bucket strings (``"saving_throw"``, ``"damage"``, ``"attack_roll"``, ``"ac"``)
+into ``apply_changes_to_check``. The seed templates emit Foundry-shaped keys
+(``save.bonus``, ``damage.bonus``, ``attack.roll.bonus``, ``ac.bonus``); the
+helper does exact key matching, so the resolvers were silently no-op-ing
+every effect. These tests lock the alignment.
+"""
+
+from __future__ import annotations
+
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+    ActiveEffectDuration,
+)
+
+
+def _bless(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped Bless: +1d4 on attack rolls and saves (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:bless",
+        name="Bless",
+        origin="cast:bless:1",
+        target_id=target_id,
+        duration=ActiveEffectDuration(rounds=10),
+        changes=[
+            ActiveEffectChange(key="attack.roll.bonus", mode="add", value="1d4"),
+            ActiveEffectChange(key="save.bonus", mode="add", value="1d4"),
+        ],
+        flags={"concentration": True},
+    )
+
+
+def _cloak(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped Cloak of Protection: +1 AC and +1 saves (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:cloak_of_protection",
+        name="Cloak of Protection",
+        origin="item:cloak_of_protection:1",
+        target_id=target_id,
+        changes=[
+            ActiveEffectChange(key="ac.bonus", mode="add", value=1),
+            ActiveEffectChange(key="save.bonus", mode="add", value=1),
+        ],
+    )
+
+
+def _plus_one_sword(target_id: str = "char:hero") -> ActiveEffect:
+    """Seed-shaped +1 Weapon: +1 attack and +1 damage (Foundry keys)."""
+    return ActiveEffect(
+        id="effect:weapon_plus_1",
+        name="+1 Weapon",
+        origin="item:weapon_plus_1:1",
+        target_id=target_id,
+        changes=[
+            ActiveEffectChange(key="attack.roll.bonus", mode="add", value=1),
+            ActiveEffectChange(key="damage.bonus", mode="add", value=1),
+        ],
+    )

dnd5e_engine-0.5.0/tests/test_combat_flag_advantage.py

@@ -0,0 +1,25 @@
+"""Regression — combat resolvers honor flag-based advantage / disadvantage.
+
+Codex Phase 6 review iter-12 P2: combat.py's saving_throw and
+resolve_player_attack didn't read flag-based advantage / disadvantage
+from active_effects, so Restrained / Guidance-style / Faerie Fire /
+Invisible effects didn't shift the d20 mechanic in combat. Now both
+mirror the iter-10/11 resolve_check fix.
+"""
+
+from __future__ import annotations
+
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+)
+
+
+def _flag_effect(key: str, target_id: str = "char:hero") -> ActiveEffect:
+    return ActiveEffect(
+        id=f"effect:test_{key}",
+        name=f"test_{key}",
+        origin=f"cast:test:{key}",
+        target_id=target_id,
+        changes=[ActiveEffectChange(key=key, mode="override", value=True)],
+    )