dnd5e-engine 0.1.0__tar.gz

dnd5e_engine-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+dist/
+build/
+
+# uv
+# (uv.lock at root IS tracked; member uv.lock files are removed)
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Docs build output
+site/
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/
+
+# Upstream raw sources (regenerated locally via `make refresh-upstream`; never committed)
+packages/dnd5e-srd-data/raw_sources/foundry/
+packages/dnd5e-srd-data/raw_sources/open5e/
+packages/dnd5e-srd-data/raw_sources/five_e_bits/

dnd5e_engine-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# 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.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.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tapestria contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

dnd5e_engine-0.1.0/Makefile

@@ -0,0 +1,10 @@
+.PHONY: check lint type test smoke
+check: lint type test
+lint:
+	uv run ruff check .
+type:
+	uv run mypy src/
+test:
+	uv run pytest -q
+smoke:
+	bash scripts/smoke_clean_install.sh

dnd5e_engine-0.1.0/NOTICE

@@ -0,0 +1,20 @@
+dnd5e-engine — pure-Python D&D 5e SRD rules engine.
+
+The engine CODE is licensed under the MIT License (see LICENSE). It ships NO
+SRD data: the canonical rules content lives in the separate dnd5e-srd-data
+package, which the engine consumes at runtime via BundledAssetLoader.
+
+The rules this engine implements derive from the D&D 5e System Reference
+Document. The provenance of that ruleset (carried by the dnd5e-srd-data
+dataset, distributed under CC-BY-4.0) is:
+
+Attribution:
+- Portions derived from the Foundry VTT dnd5e system
+  (https://github.com/foundryvtt/dnd5e), CC-BY-4.0.
+- Cross-checked against open5e (https://open5e.com), CC-BY-4.0, and the
+  5e-bits/5e-database project (https://github.com/5e-bits/5e-database), MIT.
+- Original source: System Reference Document 5.1 and 5.2 by Wizards of the
+  Coast LLC, CC-BY-4.0.
+
+See the dnd5e-srd-data package for the bundled dataset and its upstream
+license texts.

dnd5e_engine-0.1.0/PKG-INFO

@@ -0,0 +1,217 @@
+Metadata-Version: 2.4
+Name: dnd5e-engine
+Version: 0.1.0
+Summary: Pure-Python D&D 5e SRD rules engine — combat, checks, effects. Host-agnostic, zero I/O.
+Author: Tapestria contributors
+License: MIT License
+        
+        Copyright (c) 2026 Tapestria contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in
+        all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+        THE SOFTWARE.
+License-File: LICENSE
+License-File: NOTICE
+Keywords: 5e,dnd,rules-engine,srd,ttrpg
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+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: pydantic>=2.10.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.13.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dnd5e-engine
+
+Pure-Python D&D 5e SRD rules engine — host-agnostic, zero I/O. Combat, checks, effects,
+on a zone graph or a 2-D grid.
+
+## Status
+
+Working engine. It resolves combat against the typed 2024-SRD corpus shipped by
+[`dnd5e-srd-data`](../dnd5e-srd-data) (the `BundledAssetLoader` reads the bundled
+`canonical/` data — no network, no DB). The engine is edition-agnostic: it consumes
+whatever typed content it is handed.
+
+Two spatial backends are supported, selected at `start_combat`:
+
+- **Zone graph** — pass `scene_zones=SceneTopology(zones=..., edges=...)`; range/reach are
+  resolved as shortest-path distance over a weighted, undirected zone graph.
+- **2-D grid** — pass `grid_scene=GridScene(width, height)`; positions are `"col,row"` cell
+  ids (`cell_id(col, row)`), distance is Chebyshev (8-direction, one cell = `cell_size_ft`).
+
+## Install
+
+Dev (editable, from this directory):
+
+```bash
+cd packages/dnd5e-engine
+uv venv && uv pip install -e '.[dev]'
+uv run --extra dev pytest -q
+uv run --extra dev ruff check src/ tests/ scripts/
+uv run --extra dev mypy src/
+```
+
+Standalone wheel:
+
+```bash
+uv build          # builds dist/dnd5e_engine-*.whl (+ sdist)
+```
+
+A clean-room install smoke builds both wheels, installs them into a throwaway venv with no
+editable path deps, and runs a real grid combat through the public API:
+
+```bash
+bash scripts/smoke_clean_install.sh   # ends with "==> SMOKE PASSED"
+```
+
+## Quickstart
+
+A minimal grid combat: open it, move a PC one cell, then close it.
+
+```python
+import asyncio
+
+from dnd5e_engine import (
+    EncounterMemberSpec,
+    GridScene,
+    PartyMemberSpec,
+    PlayerIntent,
+    cell_id,
+    end_combat,
+    start_combat,
+    submit_player_intent,
+)
+
+
+async def main() -> None:
+    start = await start_combat(
+        session_id="demo",
+        party=[
+            PartyMemberSpec(
+                entity_id="char:hero",
+                name="Hero",
+                initiative=20,
+                hp_current=12,
+                hp_max=12,
+                ac=12,
+                zone_id=cell_id(0, 0),
+            )
+        ],
+        encounter=[
+            EncounterMemberSpec(
+                entity_id="mon:foe",
+                entity_type="Monster",
+                name="Foe",
+                initiative=1,
+                hp_current=7,
+                hp_max=7,
+                zone_id=cell_id(5, 0),
+            )
+        ],
+        grid_scene=GridScene(width=10, height=10),
+        rng_seed=1,
+    )
+
+    # The hero won initiative; move one cell diagonally.
+    await submit_player_intent(
+        start.handle,
+        actor_id="char:hero",
+        intent=PlayerIntent(intent_type="move", target_zone_id=cell_id(1, 1)),
+    )
+
+    result = await end_combat(start.handle)
+    print("ended reason:", result.outcome.ended_reason)
+
+
+asyncio.run(main())
+```
+
+An attack instead of a move: submit
+`PlayerIntent(intent_type="attack", target_id="mon:foe", weapon_id="longsword")` — the
+engine fetches the typed weapon from the bundled corpus and walks its activities.
+
+## Public API
+
+All exported names live in `__all__` in `src/dnd5e_engine/__init__.py`. The key entry points:
+
+- `start_combat(*, session_id, party, encounter, scene_zones=|grid_scene=, rng_seed, ...)` —
+  open a combat, materialize runtime state, return a `StartCombatResult` (`.handle`, opening
+  `.events`).
+- `submit_player_intent(handle, actor_id, intent)` — validate and resolve a PC's
+  `PlayerIntent` for the current turn.
+- `advance_monster_turn(handle)` — resolve the active monster's turn via its typed action
+  repertoire + behavior gambits.
+- `end_combat(handle)` — close a combat and return an `EndCombatResult` (`.outcome`,
+  `.events`, `.final_active_effects`).
+- `narration_events(handle)` — async iterator streaming the `CombatEvent` union for the
+  narrator.
+- `get_actor_active_effects(handle, entity_id)` — read-only snapshot of one combatant's
+  active effects.
+- `resolve_check(spec)` — resolve an out-of-combat ability check / saving throw
+  (`CheckSpec` → `CheckResult`).
+- `build_party_member(spec, ...)` — project a `CharacterBuildSpec` into a combat-ready
+  `PartyMemberSpec`.
+- `make_build_spec(...)` — assemble a `CharacterBuildSpec` (ability scores, class, species).
+
+Spatial helpers and spec types:
+
+- `GridScene` / `cell_id(col, row)` / `parse_cell(cell_id)` — 2-D grid scene + cell-id codec.
+- `SceneTopology` / `ZoneEdge` — zone-graph scene description.
+- `PartyMemberSpec` / `EncounterMemberSpec` — combatant inputs to `start_combat`.
+- `PlayerIntent` — a PC's submitted intent (move / attack / cast_spell / use_item / ...).
+- `CombatHandle`, `StartCombatResult`, `EndCombatResult`, `CombatOutcome`, `CombatEvent`,
+  `ActiveEffect`, `CheckSpec`/`CheckResult`/`CheckKind`, `CharacterBuildSpec`,
+  `AbilityScores`, and the `IntentType` / `ActionType` literals.
+
+## Layout
+
+```
+packages/dnd5e-engine/
+├── pyproject.toml          hatchling build; pydantic + d20 + dnd5e-srd-data deps
+├── LICENSE                 MIT (engine code)
+├── scripts/
+│   ├── _smoke_grid_combat.py     clean-room smoke program (runs in a fresh venv)
+│   └── smoke_clean_install.sh    builds wheels + installs them + runs the smoke
+├── src/dnd5e_engine/
+│   ├── __init__.py         public API (__all__)
+│   ├── orchestrator.py     start/submit/advance/end combat seam + live state
+│   ├── spatial.py          grid + zone topologies, cell_id / parse_cell
+│   ├── specs.py            GridScene, SceneTopology, party/encounter specs
+│   ├── check.py            out-of-combat ability check / saving throw resolver
+│   ├── build_party.py / build_spec.py   character build → combat spec projection
+│   ├── lib_loader.py       BundledAssetLoader singleton (typed SRD corpus)
+│   ├── events.py / outcome.py / results.py   event union, outcome, result envelopes
+│   ├── activities/         typed-Activity resolvers (attack / save / monster actions)
+│   ├── rules/              dice, conditions, gambits, ...
+│   └── types/              combat / effects / conditions / intent value types
+└── tests/                  pytest suite
+```
+
+## License
+
+- Engine code: MIT — see [`LICENSE`](LICENSE). The engine ships no SRD data.
+- SRD content (the typed corpus consumed via `dnd5e-srd-data`): CC-BY-4.0 — see the
+  [`dnd5e-srd-data`](../dnd5e-srd-data) package's `LICENSE` and `NOTICE` for the
+  dataset license and attribution chain.

dnd5e_engine-0.1.0/README.md

@@ -0,0 +1,173 @@
+# dnd5e-engine
+
+Pure-Python D&D 5e SRD rules engine — host-agnostic, zero I/O. Combat, checks, effects,
+on a zone graph or a 2-D grid.
+
+## Status
+
+Working engine. It resolves combat against the typed 2024-SRD corpus shipped by
+[`dnd5e-srd-data`](../dnd5e-srd-data) (the `BundledAssetLoader` reads the bundled
+`canonical/` data — no network, no DB). The engine is edition-agnostic: it consumes
+whatever typed content it is handed.
+
+Two spatial backends are supported, selected at `start_combat`:
+
+- **Zone graph** — pass `scene_zones=SceneTopology(zones=..., edges=...)`; range/reach are
+  resolved as shortest-path distance over a weighted, undirected zone graph.
+- **2-D grid** — pass `grid_scene=GridScene(width, height)`; positions are `"col,row"` cell
+  ids (`cell_id(col, row)`), distance is Chebyshev (8-direction, one cell = `cell_size_ft`).
+
+## Install
+
+Dev (editable, from this directory):
+
+```bash
+cd packages/dnd5e-engine
+uv venv && uv pip install -e '.[dev]'
+uv run --extra dev pytest -q
+uv run --extra dev ruff check src/ tests/ scripts/
+uv run --extra dev mypy src/
+```
+
+Standalone wheel:
+
+```bash
+uv build          # builds dist/dnd5e_engine-*.whl (+ sdist)
+```
+
+A clean-room install smoke builds both wheels, installs them into a throwaway venv with no
+editable path deps, and runs a real grid combat through the public API:
+
+```bash
+bash scripts/smoke_clean_install.sh   # ends with "==> SMOKE PASSED"
+```
+
+## Quickstart
+
+A minimal grid combat: open it, move a PC one cell, then close it.
+
+```python
+import asyncio
+
+from dnd5e_engine import (
+    EncounterMemberSpec,
+    GridScene,
+    PartyMemberSpec,
+    PlayerIntent,
+    cell_id,
+    end_combat,
+    start_combat,
+    submit_player_intent,
+)
+
+
+async def main() -> None:
+    start = await start_combat(
+        session_id="demo",
+        party=[
+            PartyMemberSpec(
+                entity_id="char:hero",
+                name="Hero",
+                initiative=20,
+                hp_current=12,
+                hp_max=12,
+                ac=12,
+                zone_id=cell_id(0, 0),
+            )
+        ],
+        encounter=[
+            EncounterMemberSpec(
+                entity_id="mon:foe",
+                entity_type="Monster",
+                name="Foe",
+                initiative=1,
+                hp_current=7,
+                hp_max=7,
+                zone_id=cell_id(5, 0),
+            )
+        ],
+        grid_scene=GridScene(width=10, height=10),
+        rng_seed=1,
+    )
+
+    # The hero won initiative; move one cell diagonally.
+    await submit_player_intent(
+        start.handle,
+        actor_id="char:hero",
+        intent=PlayerIntent(intent_type="move", target_zone_id=cell_id(1, 1)),
+    )
+
+    result = await end_combat(start.handle)
+    print("ended reason:", result.outcome.ended_reason)
+
+
+asyncio.run(main())
+```
+
+An attack instead of a move: submit
+`PlayerIntent(intent_type="attack", target_id="mon:foe", weapon_id="longsword")` — the
+engine fetches the typed weapon from the bundled corpus and walks its activities.
+
+## Public API
+
+All exported names live in `__all__` in `src/dnd5e_engine/__init__.py`. The key entry points:
+
+- `start_combat(*, session_id, party, encounter, scene_zones=|grid_scene=, rng_seed, ...)` —
+  open a combat, materialize runtime state, return a `StartCombatResult` (`.handle`, opening
+  `.events`).
+- `submit_player_intent(handle, actor_id, intent)` — validate and resolve a PC's
+  `PlayerIntent` for the current turn.
+- `advance_monster_turn(handle)` — resolve the active monster's turn via its typed action
+  repertoire + behavior gambits.
+- `end_combat(handle)` — close a combat and return an `EndCombatResult` (`.outcome`,
+  `.events`, `.final_active_effects`).
+- `narration_events(handle)` — async iterator streaming the `CombatEvent` union for the
+  narrator.
+- `get_actor_active_effects(handle, entity_id)` — read-only snapshot of one combatant's
+  active effects.
+- `resolve_check(spec)` — resolve an out-of-combat ability check / saving throw
+  (`CheckSpec` → `CheckResult`).
+- `build_party_member(spec, ...)` — project a `CharacterBuildSpec` into a combat-ready
+  `PartyMemberSpec`.
+- `make_build_spec(...)` — assemble a `CharacterBuildSpec` (ability scores, class, species).
+
+Spatial helpers and spec types:
+
+- `GridScene` / `cell_id(col, row)` / `parse_cell(cell_id)` — 2-D grid scene + cell-id codec.
+- `SceneTopology` / `ZoneEdge` — zone-graph scene description.
+- `PartyMemberSpec` / `EncounterMemberSpec` — combatant inputs to `start_combat`.
+- `PlayerIntent` — a PC's submitted intent (move / attack / cast_spell / use_item / ...).
+- `CombatHandle`, `StartCombatResult`, `EndCombatResult`, `CombatOutcome`, `CombatEvent`,
+  `ActiveEffect`, `CheckSpec`/`CheckResult`/`CheckKind`, `CharacterBuildSpec`,
+  `AbilityScores`, and the `IntentType` / `ActionType` literals.
+
+## Layout
+
+```
+packages/dnd5e-engine/
+├── pyproject.toml          hatchling build; pydantic + d20 + dnd5e-srd-data deps
+├── LICENSE                 MIT (engine code)
+├── scripts/
+│   ├── _smoke_grid_combat.py     clean-room smoke program (runs in a fresh venv)
+│   └── smoke_clean_install.sh    builds wheels + installs them + runs the smoke
+├── src/dnd5e_engine/
+│   ├── __init__.py         public API (__all__)
+│   ├── orchestrator.py     start/submit/advance/end combat seam + live state
+│   ├── spatial.py          grid + zone topologies, cell_id / parse_cell
+│   ├── specs.py            GridScene, SceneTopology, party/encounter specs
+│   ├── check.py            out-of-combat ability check / saving throw resolver
+│   ├── build_party.py / build_spec.py   character build → combat spec projection
+│   ├── lib_loader.py       BundledAssetLoader singleton (typed SRD corpus)
+│   ├── events.py / outcome.py / results.py   event union, outcome, result envelopes
+│   ├── activities/         typed-Activity resolvers (attack / save / monster actions)
+│   ├── rules/              dice, conditions, gambits, ...
+│   └── types/              combat / effects / conditions / intent value types
+└── tests/                  pytest suite
+```
+
+## License
+
+- Engine code: MIT — see [`LICENSE`](LICENSE). The engine ships no SRD data.
+- SRD content (the typed corpus consumed via `dnd5e-srd-data`): CC-BY-4.0 — see the
+  [`dnd5e-srd-data`](../dnd5e-srd-data) package's `LICENSE` and `NOTICE` for the
+  dataset license and attribution chain.

dnd5e_engine-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "dnd5e-engine"
+version = "0.1.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"
+license = { file = "LICENSE" }
+authors = [{ name = "Tapestria contributors" }]
+keywords = ["dnd", "5e", "srd", "ttrpg", "rules-engine"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic>=2.10.0",
+    "d20>=1.1.2",
+    # 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",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "ruff>=0.9.0",
+    "mypy>=1.13.0",
+]
+
+[tool.uv.sources]
+dnd5e-srd-data = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/dnd5e_engine"]
+
+[tool.mypy]
+python_version = "3.12"
+plugins = ["pydantic.mypy"]
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+warn_unused_ignores = true
+
+# d20 ships no py.typed marker / stubs.
+[[tool.mypy.overrides]]
+module = ["d20"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "I", "N", "UP", "B", "SIM", "T20", "BLE",
+    "ASYNC", "PT", "RUF", "TRY",
+]
+ignore = [
+    "TRY003",
+    "RUF001", "RUF002", "RUF003",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["E501", "F841", "PT006", "PT011"]
+# Smoke scripts print human-readable progress/result lines (T201) by design.
+"scripts/**/*.py" = ["T201"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

dnd5e_engine-0.1.0/scripts/_smoke_grid_combat.py

@@ -0,0 +1,86 @@
+"""Clean-room smoke: exercise the installed dnd5e-engine wheel end-to-end.
+
+Run by scripts/smoke_clean_install.sh inside a fresh venv that has ONLY the
+built wheels installed. Exits non-zero on any failure.
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from dnd5e_engine import (
+    EncounterMemberSpec,
+    GridScene,
+    PartyMemberSpec,
+    PlayerIntent,
+    cell_id,
+    end_combat,
+    start_combat,
+    submit_player_intent,
+)
+from dnd5e_engine.lib_loader import get_lib_loader
+from dnd5e_engine.orchestrator import get_live
+
+# A genuine bundled monster slug — canonical/monsters/ ships goblin-warrior.json
+# (there is no bare "goblin.json"). The smoke asserts the corpus resolves a slug
+# that really ships in the dnd5e-srd-data wheel.
+_BUNDLED_MONSTER_SLUG = "goblin-warrior"
+
+
+def _check_corpus() -> None:
+    loader = get_lib_loader()  # BundledAssetLoader → reads bundled canonical/
+    monster = loader.get_monster(_BUNDLED_MONSTER_SLUG)
+    assert monster is not None, (
+        f"bundled corpus did not resolve monster {_BUNDLED_MONSTER_SLUG!r}"
+    )
+
+
+async def _run_grid_combat() -> None:
+    start = await start_combat(
+        session_id="smoke",
+        party=[
+            PartyMemberSpec(
+                entity_id="char:hero",
+                name="Hero",
+                initiative=20,
+                hp_current=12,
+                hp_max=12,
+                ac=12,
+                zone_id=cell_id(0, 0),
+            )
+        ],
+        encounter=[
+            EncounterMemberSpec(
+                entity_id="mon:foe",
+                entity_type="Monster",
+                name="Foe",
+                initiative=1,
+                hp_current=7,
+                hp_max=7,
+                zone_id=cell_id(5, 0),
+            )
+        ],
+        grid_scene=GridScene(width=10, height=10),
+        rng_seed=1,
+    )
+    live = get_live(start.handle)
+    assert live.actor_zone["char:hero"] == "0,0"
+    # One legal single-cell move proves the grid MOVE path resolves end-to-end.
+    await submit_player_intent(
+        start.handle,
+        actor_id="char:hero",
+        intent=PlayerIntent(intent_type="move", target_zone_id=cell_id(1, 1)),
+    )
+    assert live.actor_zone["char:hero"] == "1,1", "grid move did not apply"
+    result = await end_combat(start.handle)
+    assert result is not None
+    print("SMOKE OK: corpus loaded + grid combat ran (hero moved 0,0 -> 1,1)")
+
+
+def main() -> None:
+    _check_corpus()
+    asyncio.run(_run_grid_combat())
+
+
+if __name__ == "__main__":
+    main()