Add modern death recovery

[Mattie]

Summary

Adds the clearly named modern_death_recovery feature for non-honor deaths while preserving the existing honor and forced-honor death reset path.

Routes command damage, YAML room damage, and Zar animation deaths through a shared death recovery plan, and documents modern behavior in docs/MODERN_FEATURES.md.

Changes

• Add modern feature constants, registry docs, and shared DeathRecoveryPlan plumbing.
• Implement one-level modern death recovery, willow relocation, exhaustion, spell-effect clearing, spell point and hit point regeneration, memorized-spell clearing, and spellbook preservation.
• Implement modern inventory drops with castle soulstone/kyragem filtering, adjacent-room spill, dark-forest fallback, vanish reporting, and room broadcasts.
• Emit drop notifications before death/arrival messaging; YAML keeps the victim in the old-room broadcast path, while command and Zar send target-only pre-death DROPIT3 notices and exclude the victim from room fan-out to avoid duplicate notices.
• Apply modern death persistence before live WebSocket broadcasts for command, YAML, and Zar deaths.
• Harden recovery ordering so Zar and YAML modern deaths avoid intermediate dead-state or split player/room persistence.
• Scope command-path modern item-drop refreshes/messages to the actual rooms receiving drops.
• Expand unit, steer, and WebSocket coverage for modern recovery, honor/forced-honor legacy resets, GOTKYG behavior, placement invariants, stale spill-room state, recipient scoping, victim pre-death drop sequencing, and persistence failure handling.
• Document the modern feature taxonomy, extraction notes, and manual demo checklist.

Motivation & Context

Intent

• Give non-honor players a less punishing death outcome that still has meaningful cost: one level lost, gold lost, inventory dropped, memorized spells forgotten, and temporary effects cleared.
• Keep all modern behavior explicitly named as modern_death_recovery so maintainers can review, disable, or extract it separately from legacy behavior.

Context

• Issue / ticket: requested in thread.
• Legacy parity / constraints / related work:
  • Honor mode and forced-honor deaths keep the existing full reset behavior.
  • Modern GOTKYG clearing matches the legacy level threshold from legacy/KYRSYSP.C:148 and adds the requested castle soulstone/kyragem recovery rule.
  • Messaging reuses existing death, kill, arrival, drop, and room object event surfaces where available.

Legacy code being ported

• Source (legacy) locations:
  • legacy/KYRSYSP.C - death reset and GOTKYG threshold behavior.
  • Existing message catalog entries for DIEMSG, KILLED, holy-light arrival, DROPIT3, S11M06, and room_objects event behavior.
• New locations:
  • backend/kyrgame/player_lifecycle.py - shared DeathRecoveryPlan, modern state mutation, and item placement rules.
  • backend/kyrgame/commands.py - command damage modern recovery and atomic persistence path.
  • backend/kyrgame/yaml_rooms.py / backend/kyrgame/rooms.py - YAML damage modern recovery, deferred recovery planning, live spill-room refresh, and multi-room object sync.
  • backend/kyrgame/world/animation_tick_system.py / backend/kyrgame/runtime.py / backend/kyrgame/webapp.py - Zar death recovery, persistence, and WebSocket refresh metadata.
  • backend/kyrgame/constants.py / backend/kyrgame/modern_features.py - named constants and modern feature registry.
  • docs/MODERN_FEATURES.md / docs/PORTING_PLAN.md - canonical documentation and manual demo checklist.
• Intentional differences from legacy behavior:
  • Non-honor modern players recover at willow one level lower with spellbook ownership preserved.
  • Inventory drops into the death room, nearby rooms, then dark forest fallback; castle soulstone/kyragem items are filtered from drops when recovery flags are reset.
  • Modern drop notifications are sent before DIEMSG, KILLED, and willow arrival messages.
• Known missing pieces / follow-ups:
  • Full manual E2E should be run against a browser session before merge.

Testing

• cd legacy && make -f ELWKYR (Worldgroup build)
• pytest backend/tests
• cd backend && python -m kyrgame.scripts.package_content --output ../legacy/Dist/offline-content.json
• python.exe -m py_compile backend\kyrgame\commands.py backend\kyrgame\yaml_rooms.py backend\kyrgame\rooms.py backend\kyrgame\runtime.py backend\kyrgame\webapp.py backend\kyrgame\world\animation_tick_system.py
• python.exe -m pytest backend\tests\world\test_animation_tick_system.py::test_zarfood_modern_death_persister_failure_keeps_predeath_state backend\tests\test_room_scripts.py::test_yaml_modern_death_deferred_mode_stages_spill_until_caller_commits backend\tests\test_commands_cast.py::test_cast_zelastone_target_hit_modern_death_recovery_drops_and_filters_items -q
• python.exe -m pytest backend\tests\test_commands_cast.py::test_cast_zelastone_target_hit_modern_death_recovery_drops_and_filters_items backend\tests\test_yaml_room_engine.py::test_damage_action_uses_modern_death_recovery_for_non_honor_player backend\tests\world\test_animation_tick_system.py::test_zarfood_uses_modern_death_recovery_for_non_honor_player backend\tests\test_gateway_dispatch_bridge.py::test_websocket_zar_death_uses_modern_recovery_for_non_honor_player -q
• python.exe -m pytest backend\tests\test_player_lifecycle.py backend\tests\test_commands_cast.py backend\tests\test_yaml_room_engine.py backend\tests\test_room_scripts.py backend\tests\world\test_animation_tick_system.py backend\tests\test_modern_features.py backend\tests\test_gateway_dispatch_bridge.py::test_websocket_zar_death_refreshes_target_room_and_arrival_witness backend\tests\test_gateway_dispatch_bridge.py::test_websocket_zar_death_uses_modern_recovery_for_non_honor_player backend\tests\test_gateway_dispatch_bridge.py::test_websocket_spell_death_refreshes_target_room_and_arrival_witness -q
• python.exe -m pytest backend\tests\test_command_dispatcher.py::test_rub_dragonstaff_uses_legacy_rub_path backend\tests\test_command_dispatcher.py::test_rub_dragonstaff_attacks_when_zar_is_already_here -q
• git diff --cached --check
• Local compose smoke: backend http://127.0.0.1:8000/openapi.json, frontend http://127.0.0.1:5173/, backend container source inspection for modern_death_recovery.

Details:

• Focused regression set passed: 4 tests.
• Impacted related suite passed: 237 tests.
• Additional dispatcher coverage passed: 2 tests.
• Critical/unit-test review found persistence ordering, YAML spill-room live sync, WebSocket metadata propagation, stale spill-room planning, command-path drop recipient-scope risks, and duplicate victim-notice risk. All were addressed with code changes and regression coverage.
• Final review found no blockers. Residual risk: no full WebSocket YAML deferred persistence-failure E2E; manual browser E2E remains recommended before merge.

Manual E2E Demo Checklist

• Start backend and frontend with Docker Compose project kyrgame-local.
• Create or reset a zt... non-honor test player near Zar with level, spellbook bits, memorized spells, charms/effects, gold, soulstone/kyragem, and ordinary inventory.
• Trigger Zar death in room 302 and confirm the dying player sees item-drop text before death text, then willow arrival, one-level reduction, max HP/SP for the new level, exhaustion, gold loss, memorized-spell loss, spellbook preservation, effect clearing, and castle soulstone/kyragem filtering.
• Confirm dropped ordinary items appear in death room or spill/fallback rooms and visible room occupants receive drop notifications.
• Reconnect and confirm persisted player state and room object state match the modern recovery outcome.
• Repeat an honor or forced-honor death and confirm the legacy level-1 full reset still occurs.
• Exercise a command/YAML death outside the castle with crowded ground slots and confirm death-room, adjacent-room, and dark-forest spill behavior.

Risk & Rollback

• Risk level: medium
• Rollback plan:
  • Revert the PR commits to restore the previous legacy-only death handling.
  • If a production data issue appears, inspect affected player records and room object rows; modern recovery mutations are concentrated around DeathRecoveryPlan metadata and room-object updates.

UI Changes

• Screenshots / description:
  • No direct UI layout changes. WebSocket room/player refresh events now include modern death recovery metadata for death flows.

[Copilot]

Pull request overview

This PR introduces a named modern feature gate (modern_death_recovery) that provides a less-punishing death outcome for non-honor players, while preserving the legacy full-reset behavior for honor-mode and force-honor deaths. It centralizes death recovery into a shared DeathRecoveryPlan so command damage, YAML room-script damage, and Zar animation deaths follow the same modern recovery rules and persistence ordering.

Changes:

• Added modern_death_recovery to the modern feature registry and documented its contract in docs/MODERN_FEATURES.md, with an accompanying manual E2E checklist update in docs/PORTING_PLAN.md.
• Implemented shared modern death recovery planning/application logic (DeathRecoveryPlan) including level loss, effect/spell clearing, inventory drop placement (spill + dark forest fallback), and metadata for WebSocket/UI refreshes.
• Routed command-path, YAML damage, and Zar deaths through the shared recovery plan with atomic persistence and expanded unit/WebSocket test coverage.

Reviewed changes

Copilot reviewed 17 out of 17 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/PORTING_PLAN.md	Adds modern-death recovery checklist coverage to the porting plan.
docs/MODERN_FEATURES.md	Documents the modern feature taxonomy and the modern_death_recovery contract.
backend/kyrgame/constants.py	Introduces named constants for modern death recovery (rooms, object ids, exhaustion, thresholds).
backend/kyrgame/modern_features.py	Registers modern_death_recovery as an active modern feature with refs/tests.
backend/kyrgame/player_lifecycle.py	Adds DeathRecoveryPlan + modern recovery planning and application logic, including item placement.
backend/kyrgame/commands.py	Applies modern recovery to command damage deaths, with atomic persistence and per-room drop broadcasts.
backend/kyrgame/yaml_rooms.py	Applies modern recovery to YAML damage, including deferred-mode planning and event metadata.
backend/kyrgame/rooms.py	Plumbs deferred modern death recovery through the room script engine and room-object syncing.
backend/kyrgame/webapp.py	Commits deferred YAML modern recovery plans before mutating live state / broadcasting.
backend/kyrgame/world/animation_tick_system.py	Applies modern recovery to Zar deaths, with optional atomic persister support.
backend/kyrgame/runtime.py	Implements Zar modern-death atomic persistence and forwards modern recovery metadata in events.
backend/tests/test_player_lifecycle.py	Adds unit coverage for modern recovery plan behavior (spellbook preservation, GOTKYG clearing, drops).
backend/tests/test_commands_cast.py	Adds command-path modern recovery tests including persistence-failure safety.
backend/tests/test_yaml_room_engine.py	Adds YAML damage modern recovery behavior coverage.
backend/tests/test_room_scripts.py	Adds integration coverage for spill-room syncing and deferred-mode staging.
backend/tests/world/test_animation_tick_system.py	Adds Zar modern recovery coverage (force-honor legacy path, modern path, persister failure).
backend/tests/test_gateway_dispatch_bridge.py	Adds WebSocket end-to-end coverage for Zar modern death recovery metadata and persistence.

---

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

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2580c46cee

ℹ️ 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9152f9c44d

ℹ️ 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]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 194728d46f

ℹ️ 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".

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated no new comments.