feat(data-layer): DL-24 - Implement Turn Resolution Management

[spuentesp]

Summary

Implements comprehensive turn resolution storage system for tracking mechanical resolution of actions during gameplay, including dice rolls, contested checks, card draws, and effect tracking.

Schemas (resolutions.py)

New Enums:

• ActionType: combat, skill, social, exploration, magic, other
• ResolutionType: dice, card, narrative, deterministic, contested
• SuccessLevel: critical_success, success, partial_success, failure, critical_failure
• EffectType: damage, healing, condition, buff, debuff, resource_change, stat_change, position_change, other

Data Structures:

• Modifier: source, value, reason for modifiers
• RollResult: raw/kept rolls, total, natural, critical/fumble flags
• ContestedRoll: opponent data with margin of victory
• CardDraw: cards drawn, total value, special results
• Mechanics: formula, modifiers, target, roll/contested/card data
• Effect: effect type, target, magnitude, duration, description

CRUD Schemas:

• ResolutionCreate/Update/Response: Full resolution management
• ResolutionFilter/ListResponse: Flexible querying

MongoDB Tools

New Tools:

• mongodb_create_resolution: Create resolution with validation

  • Validates turn exists in scene
  • Validates scene and story exist
  • Stores complete mechanics and effects data

• mongodb_get_resolution: Retrieve resolution by ID

• mongodb_list_resolutions: Filter by scene, turn, actor, action_type, success_level

• mongodb_update_resolution: Update effects, description, gm_notes

• mongodb_delete_resolution: Remove resolution record

Auth Middleware

Authority Checks:

• mongodb_create_resolution: Orchestrator, CanonKeeper
• mongodb_get_resolution: *
• mongodb_list_resolutions: *
• mongodb_update_resolution: Orchestrator, CanonKeeper
• mongodb_delete_resolution: CanonKeeper

Tests

Added 19 comprehensive tests:

• Create: success, scene/turn/story validation, contested rolls, card draws (6 tests)
• Get: success, not found (2 tests)
• List: all, by scene, by turn, by actor, by action_type, by success_level (6 tests)
• Update: success, not found, no changes (3 tests)
• Delete: success, not found (2 tests)

All 256 tests passing ✅

Architecture Decisions

✅ Pure data storage - Dice rolling/evaluation logic lives in agents layer
✅ Turn validation - Validates turn exists in scene before creating resolution
✅ Multi-resolution support - Dice, contested, card, narrative, deterministic types
✅ Flexible mechanics - Structure accommodates different game systems
✅ Effects tracking - Array tracks all changes resulting from resolution
✅ GM notes - Field for secret information

Implements: DL-24
Blocks Unblocked: P-4 (Player Action), P-9 (Dice Roll Mechanics)

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4.5 noreply@anthropic.com

[Copilot]

Pull request overview

This pull request implements a comprehensive turn resolution management system (DL-24) for tracking mechanical resolution of actions during gameplay. The implementation adds new schemas, MongoDB CRUD operations, auth middleware updates, and comprehensive test coverage.

Key Changes

• New resolution schemas defining data contracts for action resolutions including dice rolls, contested checks, card draws, and effect tracking
• MongoDB CRUD tools for creating, retrieving, updating, and deleting resolution records with validation against scenes, turns, and stories
• Auth middleware configuration with appropriate authority assignments for resolution operations

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/resolutions.py	New schema file defining enums (ActionType, ResolutionType, SuccessLevel, EffectType) and data structures (Modifier, RollResult, ContestedRoll, CardDraw, Mechanics, Effect) along with CRUD and query schemas
packages/data-layer/src/monitor_data/tools/mongodb_tools.py	Added 5 new resolution CRUD functions with proper validation, a helper conversion function, and updated combat tools to use consistent Neo4j client patterns
packages/data-layer/src/monitor_data/schemas/init.py	Exported all new resolution-related schemas and classes
packages/data-layer/src/monitor_data/middleware/auth.py	Added authority matrix entries for resolution operations with appropriate role restrictions
packages/data-layer/tests/test_tools/test_resolution_tools.py	Comprehensive test suite with 19 tests covering all CRUD operations, validation scenarios, and resolution types
packages/data-layer/tests/test_tools/test_combat_tools.py	Added story validation test and updated Neo4j client mocking to use execute_read pattern

---

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

[Copilot]

The magnitude field in the Effect schema is required and has no default value, but its usage varies by effect_type. For some effect types like CONDITION or POSITION_CHANGE, a numeric magnitude may not be meaningful or necessary (e.g., applying "grappled" condition, or moving to a new position). Consider making magnitude optional with a default value of 0, or adding validation to ensure magnitude is only required for effect types where it makes sense (DAMAGE, HEALING, RESOURCE_CHANGE, STAT_CHANGE).

Suggested change

	magnitude: int = Field(description="Numeric magnitude (damage, healing, etc.)")
	magnitude: int = Field(default=0, description="Numeric magnitude (damage, healing, etc.)")

[Copilot]

The natural field in RollResult is marked as required but doesn't have a default value, while other fields like critical and fumble have defaults. This creates an inconsistency where some optional roll data (critical/fumble) has defaults, but the natural field doesn't.

For contested rolls where only the opponent_roll is being created without modifiers, this could cause issues. Consider making natural have a default value of 0, or if it should always be calculated from kept_rolls, consider making it a computed property or ensuring it's always provided during construction.

Suggested change

	natural: int = Field(
	natural: int = Field(
	default=0,