DL-25: Manage Combat State by spuentesp · Pull Request #99 · spuentesp/monitor_dm_system

spuentesp · 2026-01-04T23:03:55Z

Summary

Implements comprehensive MongoDB combat management system for initiative-based encounters with full participant tracking, combat log, and outcome recording.

This is a CRITICAL priority feature that enables combat encounter management for the MONITOR system.

Implementation Details

Combat Schemas (`combat.py`)

CombatCreate/Update/Response: Full CRUD operations for combat encounters
CombatParticipant: Entity participation with initiative, conditions, and resources
Condition: Temporary status effects (Stunned, Blessed, etc.)
CombatEnvironment: Terrain, lighting, hazards, and cover positions
CombatLogEntry: Round-by-round action tracking with resolution links
CombatOutcome: Final results (victory/defeat, survivors, loot, XP)
CombatFilter/ListResponse: Flexible querying by scene/story/status

Combat Enums (`base.py`)

CombatStatus: INITIALIZING, INITIATIVE, ACTIVE, PAUSED, RESOLVED
CombatSide: PC, ALLY, ENEMY, NEUTRAL

MongoDB Tools (`mongodb_tools.py`)

Implemented 10 combat operations:

Combat CRUD:

mongodb_create_combat: Create encounter with participants/environment
mongodb_get_combat: Retrieve full combat state with all data
mongodb_list_combats: Filter by scene_id, story_id, status
mongodb_update_combat: Update status, round, turn_order, current_turn_index
mongodb_delete_combat: Remove encounter record

Participant Management:

mongodb_add_combat_participant: Add entity to combat
mongodb_update_combat_participant: Update initiative, conditions, resources, position
mongodb_remove_combat_participant: Remove entity from combat

Combat Tracking:

mongodb_add_combat_log_entry: Append action to combat log
mongodb_set_combat_outcome: Set final result (auto-sets status to RESOLVED)

Authority Matrix (`auth.py`)

All 10 combat tools added with proper authorization:

Create/Update/Delete: ["Orchestrator", "CanonKeeper"]
Read operations: ["*"]

Testing

Created 21 comprehensive tests (test_combat_tools.py) covering:

✅ Combat creation with scene/story validation
✅ Full state retrieval and filtering
✅ Round/status updates and turn tracking
✅ Participant lifecycle (add/update/remove)
✅ Initiative, condition, and resource management
✅ Combat log appending
✅ Outcome recording with auto-resolution

All 236 tests passing ✅

Use Case

Implements: DL-25 (CRITICAL priority)
Depends on: DL-4 (Scenes/Turns ✅), DL-2 (Entities ✅)
Blocks: P-16 (Combat encounter management)

Checklist

🤖 Generated with Claude Code

Implements complete MongoDB combat management system for initiative-based encounters with participant tracking, combat log, and outcome recording. ## Combat Schemas (combat.py) New schemas: - CombatCreate/Update/Response: Full CRUD for combat encounters - CombatParticipant: Entity participation with initiative, conditions, resources - Condition: Temporary status effects (Stunned, Blessed, etc.) - CombatEnvironment: Terrain, lighting, hazards, cover positions - CombatLogEntry: Round-by-round action tracking with resolution links - CombatOutcome: Final results (victory/defeat, survivors, loot, XP) - CombatFilter/ListResponse: Flexible querying by scene/story/status ## Combat Enums (base.py) - CombatStatus: INITIALIZING, INITIATIVE, ACTIVE, PAUSED, RESOLVED - CombatSide: PC, ALLY, ENEMY, NEUTRAL ## MongoDB Tools (mongodb_tools.py) Implemented 10 combat operations: **Combat CRUD:** - mongodb_create_combat: Create encounter with participants/environment - mongodb_get_combat: Retrieve full combat state with all data - mongodb_list_combats: Filter by scene_id, story_id, status - mongodb_update_combat: Update status, round, turn_order, current_turn_index - mongodb_delete_combat: Remove encounter record **Participant Management:** - mongodb_add_combat_participant: Add entity to combat - mongodb_update_combat_participant: Update initiative, conditions, resources, position - mongodb_remove_combat_participant: Remove entity from combat **Combat Tracking:** - mongodb_add_combat_log_entry: Append action to combat log - mongodb_set_combat_outcome: Set final result (auto-sets status to RESOLVED) ## Authority Matrix (auth.py) All 10 combat tools added: - Create/Update/Delete: ["Orchestrator", "CanonKeeper"] - Read operations: ["*"] ## Tests (test_combat_tools.py) Created 21 comprehensive tests covering: - Combat creation with scene/story validation - Full state retrieval and filtering - Round/status updates and turn tracking - Participant lifecycle (add/update/remove) - Initiative, condition, and resource management - Combat log appending - Outcome recording with auto-resolution All 236 tests passing ✅ Implements: DL-25 (CRITICAL priority) Depends on: DL-4 (Scenes/Turns ✅), DL-2 (Entities ✅) Blocks: P-16 (Combat encounter management) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Copilot

Pull request overview

This PR implements a comprehensive MongoDB-based combat management system for initiative-based encounters (DL-25), including participant tracking, combat log, and outcome recording. The implementation provides 10 new combat operations with proper authorization controls and extensive test coverage.

Key Changes:

New combat schemas with support for participants, conditions, environment, log entries, and outcomes
Combat state management enums (CombatStatus, CombatSide) added to base schemas
Full CRUD operations for combat encounters with participant lifecycle management

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`packages/data-layer/src/monitor_data/schemas/combat.py`	Comprehensive combat schemas including participants, conditions, environment, log entries, and outcomes (250 lines)
`packages/data-layer/src/monitor_data/schemas/base.py`	Added CombatStatus and CombatSide enums for combat state management
`packages/data-layer/src/monitor_data/schemas/__init__.py`	Exported new combat enums to public API
`packages/data-layer/src/monitor_data/tools/mongodb_tools.py`	Implemented 10 combat operations including CRUD, participant management, logging, and outcome tracking (547 lines)
`packages/data-layer/src/monitor_data/middleware/auth.py`	Added authorization rules for all 10 combat operations
`packages/data-layer/tests/test_tools/test_combat_tools.py`	Comprehensive test suite with 21 tests covering all combat operations (905 lines)

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-01-04T23:07:12Z

+        result = session.run(
+            "MATCH (s:Story {id: $story_id}) RETURN s", story_id=str(params.story_id)
+        )
+        if not result.single():


The result.single() method raises a ResultNotSingleError exception when no records are found, rather than returning None or a falsy value. This will cause an unhandled exception instead of the intended ValueError.

The code should either catch the exception or use a pattern consistent with other validations in this file, such as using neo4j_client.execute_read() which returns an empty list when no results are found (see mongodb_create_scene for reference).

Handled by using execute_read for story existence instead of session().run(...).single(); raises ValueError on missing story without exceptions.

Copilot · 2026-01-04T23:07:12Z

+@patch("monitor_data.tools.mongodb_tools.get_neo4j_client")
+@patch("monitor_data.tools.mongodb_tools.get_mongodb_client")
+def test_create_combat_scene_not_found(
+    mock_get_mongodb: Mock,
+    mock_get_neo4j: Mock,
+):
+    """Test creating combat with invalid scene_id."""
+    scene_id = uuid4()
+    story_id = uuid4()
+
+    mock_mongodb = MagicMock()
+    mock_combats = MagicMock()
+    mock_scenes = MagicMock()
+
+    mock_get_mongodb.return_value = mock_mongodb
+    mock_mongodb.get_collection.side_effect = lambda name: (
+        mock_combats if name == "combat_encounters" else mock_scenes
+    )
+
+    # Scene does not exist
+    mock_scenes.find_one.return_value = None
+
+    params = CombatCreate(
+        scene_id=scene_id,
+        story_id=story_id,
+    )
+
+    with pytest.raises(ValueError, match=f"Scene {scene_id} not found"):
+        mongodb_create_combat(params)
+


The test suite is missing a test case for when the story_id doesn't exist in Neo4j. This validation path in mongodb_create_combat should be tested to ensure proper error handling. Consider adding a test similar to test_create_combat_scene_not_found but for an invalid story_id.

Added test_create_combat_story_not_found to cover missing story_id validation path in combat creation.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 585474f8e2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-01-04T23:07:29Z

+    # Validate story exists (via Neo4j)
+    neo4j = get_neo4j_client()
+    with neo4j.session() as session:  # type: ignore[attr-defined]
+        result = session.run(


Avoid calling nonexistent neo4j.session() in combat creation

Combat creation currently validates the story with with neo4j.session() as session, but get_neo4j_client() returns the Neo4jClient wrapper which only exposes execute_read/execute_write and has no session() method. In production (where get_neo4j_client is not mocked) this raises AttributeError before any database work, so every call to mongodb_create_combat fails. Use the wrapper’s read API instead of session() to keep combat creation working.

Useful? React with 👍 / 👎.

Fixed by switching to Neo4j client wrapper (execute_read) for story validation in combat creation.

Copilot AI review requested due to automatic review settings January 4, 2026 23:03

spuentesp added data-layer epic-0 mongodb priority-critical labels Jan 4, 2026

Copilot started reviewing on behalf of spuentesp January 4, 2026 23:04 View session

github-actions Bot added area/data-layer Data layer changes type/tests Tests touched labels Jan 4, 2026

spuentesp pushed a commit that referenced this pull request Jan 4, 2026

docs: Mark DL-25 as in_progress with PR #99

f78e040

Copilot AI reviewed Jan 4, 2026

View reviewed changes

chatgpt-codex-connector Bot reviewed Jan 4, 2026

View reviewed changes

Merge branch 'master' into feature/DL-25-manage-combat-state

29a6108

spuentesp self-assigned this Jan 4, 2026

spuentesp merged commit 0f297c6 into master Jan 4, 2026
1 check passed

This was referenced Jan 5, 2026

fix(data-layer): DL-25 followup - Add story validation test #100

Closed

fix(data-layer): DL-25 followup - Add story validation test #101

Merged

spuentesp deleted the feature/DL-25-manage-combat-state branch July 25, 2026 00:14

Navigation Menu

DL-25: Manage Combat State - #99

DL-25: Manage Combat State#99
spuentesp merged 2 commits into
masterfrom
feature/DL-25-manage-combat-state

spuentesp commented Jan 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 4, 2026

Uh oh!

spuentesp Jan 4, 2026

Uh oh!

Copilot AI Jan 4, 2026

Uh oh!

spuentesp Jan 4, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jan 4, 2026

Uh oh!

spuentesp Jan 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

spuentesp commented Jan 4, 2026

Summary

Implementation Details

Combat Schemas (combat.py)

Combat Enums (base.py)

MongoDB Tools (mongodb_tools.py)

Authority Matrix (auth.py)

Testing

Use Case

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

spuentesp Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

spuentesp Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

spuentesp Jan 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Combat Schemas (`combat.py`)

Combat Enums (`base.py`)

MongoDB Tools (`mongodb_tools.py`)

Authority Matrix (`auth.py`)