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

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

@@ -7,6 +7,42 @@ 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.

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

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "dnd5e-engine"
-version = "0.3.2"
+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.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/__init__.py

@@ -79,7 +79,6 @@ from dnd5e_engine.types.effects import (
     ActiveEffectChange,
     ActiveEffectDuration,
 )
-from dnd5e_engine.types.intent import ActionType
 
 __all__ = [
     "AbilityScores",
@@ -130,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.2 → dnd5e_engine-0.4.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.4.0}/src/dnd5e_engine/dispatch.py

@@ -1,5 +1,7 @@
 """Library-side combat resolver subset of engine_dispatch.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Hosts the pure rules-engine resolvers for the four combat-flavored
 action types: ATTACK, CAST_SPELL, SKILL_CHECK, SAVING_THROW. Host
 callers (e.g. a host's the host)
@@ -352,3 +354,14 @@ __all__ = [
     "DispatchContext",
     "resolve_combat_action",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.dispatch is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/event_dicts.py

@@ -1,5 +1,7 @@
 """Pure CombatEvent → dict serialization.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Used by the host's WS-envelope adapter in the host.
 Library-internal only — no WS protocol concerns leak in here. The host
 owns host-specific envelope wrapping (SystemMessage, CombatEnd,
@@ -35,3 +37,14 @@ def events_to_dicts(events: Iterable[CombatEvent]) -> list[dict[str, Any]]:
 
 
 __all__ = ["event_to_dict", "events_to_dicts"]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.event_dicts is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.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.4.0}/src/dnd5e_engine/rules/combat.py

@@ -1,4 +1,7 @@
-"""Combat resolution — attack rolls, damage, saving throws."""
+"""Combat resolution — attack rolls, damage, saving throws.
+
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+"""
 
 from __future__ import annotations
 
@@ -579,3 +582,14 @@ __all__ = [
     "resolve_player_attack",
     "saving_throw",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.combat is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/combat_data.py

@@ -1,5 +1,7 @@
 """Combat data helpers — spell scaling, modifiers, weapon stats.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Pure functions with zero DB imports. Used by the combat engine to calculate
 derived stats from structured spell and weapon data.
 """
@@ -228,3 +230,14 @@ __all__ = [
     "unarmed_strike_damage",
     "weapon_attack_bonus",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.combat_data is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/combat_helpers.py

@@ -1,5 +1,7 @@
 """Combat utility helpers — initiative sorting, death save state, health descriptors.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Zero DB imports. All functions are pure or use only dnd5e_engine.rules.* imports.
 """
 
@@ -7,9 +9,9 @@ from __future__ import annotations
 
 import json
 import random
-from dataclasses import dataclass
 from typing import Any
 
+from dnd5e_engine.death_saves import DeathSaveState  # re-export; canonical home moved in 0.4.0
 from dnd5e_engine.rules.combat import initiative_roll
 from dnd5e_engine.rules.dice import ability_modifier
 from dnd5e_engine.types.combat import CombatNPC
@@ -200,95 +202,6 @@ def roll_and_sort_initiative(combatants: list[dict[str, Any]]) -> list[dict[str,
 # ---------------------------------------------------------------------------
 
 
-@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"
-
-
 def build_combatant_from_npc(
     npc_props: dict[str, Any],
     template_props: dict[str, Any],
@@ -412,3 +325,14 @@ __all__ = [
     "health_descriptor",
     "roll_and_sort_initiative",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.combat_helpers is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/equipment.py

@@ -1,5 +1,7 @@
 """Equipment rules — AC calculation and armor proficiency checks.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Pure functions with zero DB imports. Used by the combat engine to calculate
 AC from character equipment data fetched by build_dispatch_context().
 
@@ -106,3 +108,14 @@ __all__ = [
     "calculate_ac",
     "is_armor_proficient",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.equipment is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/gambits.py

@@ -1,5 +1,7 @@
 """Deterministic monster AI gambit system.
 
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+
 Selects actions for monsters based on behavior profile and current game state.
 Zero DB imports. Uses only dnd5e_engine.rules.* imports.
 """
@@ -8,22 +10,16 @@ from __future__ import annotations
 
 import re
 from dataclasses import dataclass
-from enum import StrEnum
 from typing import Any
 
 from dnd5e_engine.rules.combat import HitType, attack_roll, damage_roll
+from dnd5e_engine.types.combat import BehaviorProfile  # re-export; canonical home moved in 0.4.0
 
 # ---------------------------------------------------------------------------
 # Enums and dataclasses
 # ---------------------------------------------------------------------------
 
 
-class BehaviorProfile(StrEnum):
-    AGGRESSIVE = "AGGRESSIVE"
-    RANGED = "RANGED"
-    DEFENSIVE = "DEFENSIVE"
-
-
 @dataclass(frozen=True)
 class GambitAction:
     """An action selected by the gambit system for a monster."""
@@ -184,3 +180,14 @@ __all__ = [
     "parse_damage_dice",
     "resolve_monster_action",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.gambits is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/resolution.py

@@ -1,4 +1,6 @@
 """
+
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
 Dice resolution helpers used by the v2.2 engine dispatch layer.
 
 Pure module: zero imports from neo4j, asyncpg, redis, or the host (Neo4j/PG/host storage layers).
@@ -165,3 +167,14 @@ __all__ = [
     "extract_skill_from_roll_type",
     "parse_ability_scores",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.resolution is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

{dnd5e_engine-0.3.2 → dnd5e_engine-0.4.0}/src/dnd5e_engine/rules/spells.py

@@ -1,4 +1,7 @@
-"""Spell slot management and spell resolution helpers."""
+"""Spell slot management and spell resolution helpers.
+
+**DEPRECATED (0.4.0) — removed in 0.5.0.** See docs/migration/v0.3-to-v0.4.md.
+"""
 
 from __future__ import annotations
 
@@ -149,3 +152,14 @@ __all__ = [
     "spell_slots_for_class",
     "upcast_bonus_dice",
 ]
+
+
+# ── 0.4.0 deprecation (module-level, fires once on first import) ─────────────
+import warnings as _warnings  # noqa: E402
+
+_warnings.warn(
+    "dnd5e_engine.rules.spells is part of the legacy (Gen 1) surface and will be "
+    "removed in dnd5e-engine 0.5.0 — see docs/migration/v0.3-to-v0.4.md.",
+    DeprecationWarning,
+    stacklevel=2,
+)

dnd5e_engine-0.4.0/src/dnd5e_engine/types/__init__.py

@@ -0,0 +1,49 @@
+"""dnd5e-engine type surface — host-agnostic Pydantic + Literal types."""
+
+from dnd5e_engine.types.combat import Combatant
+from dnd5e_engine.types.conditions import ActiveCondition, ConditionScope
+from dnd5e_engine.types.effects import (
+    ActiveEffect,
+    ActiveEffectChange,
+    ActiveEffectDuration,
+)
+
+__all__ = [
+    "ActionType",
+    "ActiveCondition",
+    "ActiveEffect",
+    "ActiveEffectChange",
+    "ActiveEffectDuration",
+    "CombatNPC",
+    "CombatOutcome",
+    "Combatant",
+    "ConditionScope",
+    "DiceOutcome",
+]
+
+_GEN1_LAZY = {
+    "ActionType": ("dnd5e_engine.types.intent", "ActionType"),
+    "CombatOutcome": ("dnd5e_engine.types.intent", "CombatOutcome"),
+    "DiceOutcome": ("dnd5e_engine.types.dice", "DiceOutcome"),
+    "CombatNPC": ("dnd5e_engine.types.combat", "CombatNPC"),
+}
+
+
+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.types``).
+    if name in _GEN1_LAZY:
+        import importlib
+        import warnings
+
+        module, attr = _GEN1_LAZY[name]
+        warnings.warn(
+            f"dnd5e_engine.types.{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.types' has no attribute {name!r}")

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

@@ -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,6 +16,14 @@ from dnd5e_engine.activities.passive_stats import CombatantMovementModes, Combat
 from dnd5e_engine.types.conditions import ActiveCondition
 
 
+class BehaviorProfile(StrEnum):
+    """Monster AI posture consumed by the orchestrator's flee heuristic."""
+
+    AGGRESSIVE = "AGGRESSIVE"
+    RANGED = "RANGED"
+    DEFENSIVE = "DEFENSIVE"
+
+
 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
@@ -214,6 +223,7 @@ class Combatant(BaseModel):
 
 
 __all__ = [
+    "BehaviorProfile",
     "CombatNPC",
     "Combatant",
 ]