# Handoff Report: Progression, Combat, Death Penalty & Godhood Ascension Survey

**Author**: `explorer_survey_progression_1`  
**Recipient**: `orchestrator_4` (and downstream workers/architects)  
**Date**: 2026-10-01  
**Status**: COMPLETE (Hard Handoff)  

---

## 1. Observation

1. **Combat Engine & Death Handling**:
   - `server/world/combat_engine.py`:
     - Lines 27-36: `DamageEventResult` contains `attacker_id`, `defender_id`, `raw_damage`, `final_damage`, `is_critical`, `is_evaded`, `element`. It has no `is_fatal` or `is_dead` flag.
     - Line 120: `defender.current_hp = max(0.0, defender.current_hp - final_damage)` updates HP, but no death event is fired, no EXP is awarded, and dead entities remain in memory.
   - `server/world/server_engine_loop.py`:
     - Lines 160-179: In `step_tick()` Phase 3 (Combat resolution), `calculate_damage()` is called for each skill command, but no post-hit death or kill rewards are processed.

2. **Zoning & Respawn Logic**:
   - `server/world/zone_types.py`:
     - Lines 68-70: `ZoneDefinition` dataclass defines `respawn_zone_id: str`, `respawn_x: float`, `respawn_y: float`.
   - `server/world/zone_catalog.py`:
     - Lines 43-45, 124-126: Sets canonical respawn points (`zone_boundless_sanctuary` and `zone_player_hideout` at `(0.0, 0.0)`).
   - `server/world/zone_engine.py`:
     - Lines 103-124: `can_spawn_hostile_monsters(zone_id)` and `validate_monster_spawn(zone_id, is_dummy)` enforce safe zone purity (prohibiting hostile mobs in sanctuary/hideout).
     - Lines 144-162: `spawn_player(player_id, zone_id, x, y)` positions players.
     - Lines 336-351: `close_instance` evacuates players to `"zone_boundless_sanctuary"`.
     - No explicit `respawn_player()` method exists for combat death.

3. **Monster EXP Source**:
   - `server/world/monster_types.py`:
     - Line 112: `ProceduralMonster.experience_reward: int`.
   - `server/world/monster_procedural_engine.py`:
     - Line 188: `experience_reward=int(level * 25 * rank_hp_m)`. Currently unconsumed.

4. **Ascendancy & Trial Architecture**:
   - `server/world/ascendancy_types.py`:
     - Lines 44-55: `AscendancyTrial` defines `trial_index: int`, `required_level: int`, `reward_points: int = 3`.
     - Lines 95-134: `AscendancyAppliedEffects` defines modifiers, but lacks `avatar_metamorphosis_active: bool` and `max_resists_bonus: float`.
   - `server/world/ascendancy_catalog.py`:
     - Lines 121-130: Trial 10 is canonical: `trial_id="TRIAL_10_GODHOOD_TRANSCENDENCE"`, `required_level=100`, `reward_points=3`, `boss_name="Thượng Cổ Thần Ma Tàn Thể"`.
     - Lines 141-544: 10 class trees exist, but no `GODHOOD_AVATAR_METAMORPHOSIS` keystone is registered.
   - `server/world/ascendancy_engine.py`:
     - Line 45: `complete_trial(actor_id: int, trial_index: int)`. Does not accept or check `player_level`.

5. **Existing EXP Curve & Database Matrix**:
   - `server/world/game_design_matrix_seeder.py`:
     - Line 243: `target_xp = int(500 * (lvl ** 1.85))` yields 2.476M at Lv 99 and 2.500M at Lv 100 (delta is only 23,789 XP, < 0.03% of total).
   - `server/world/game_design_matrix_service.py`:
     - Lines 240-248: `validate_game_design_integrity()` requires strict monotonicity (`r["target_exp"] <= prev_xp`).

---

## 2. Logic Chain

1. **From Observation 1 & 3 to EXP Award Gap**:
   - `ProceduralMonster` has an explicit `experience_reward`, and `CombatEngine` reduces target HP to 0.0, but does not emit a kill event. Therefore, players never gain EXP from combat.
   - *Implication*: `LevelProgressionService.award_monster_exp()` must be invoked when a monster's HP reaches 0 from a player attack.

2. **From Observation 1 & 2 to Player Death & Respawn Gap**:
   - When a player defender's HP reaches 0.0 in combat, no logic applies the death penalty or triggers respawn.
   - `ZoneDefinition` already defines `respawn_zone_id` and `(respawn_x, respawn_y)`.
   - *Implication*: When a player dies, the engine must call `LevelProgressionService.apply_death_penalty()` and then relocate the player to `respawn_zone_id` via `ZoneEngine`.

3. **From Observation 5 to EXP Curve Redesign**:
   - The current `500 * lvl^1.85` curve violates Requirement R1 (which mandates that Lv 99->100 delta is $\ge 30\%$ of total 1-99 XP and 25-35% of total lifetime XP, and Lv 1-20 is $< 0.1\%$).
   - *Implication*: The seeder must be upgraded to the 7-segment piecewise exponential curve specified in `report.md`.

4. **From Observation 4 to Trial 10 & Keystone Integration**:
   - `AscendancyEngine.complete_trial` lacks a `player_level` check; any character can currently complete Trial 10 if called sequentially.
   - Requirement R3 requires Trial 10 to be gated strictly to `level == 100`.
   - Keystone `GODHOOD_AVATAR_METAMORPHOSIS` must be added with `avatar_metamorphosis_active = True`, +40% More Damage, and +5% Max Resists into `AscendancyAppliedEffects`.

---

## 3. Caveats

1. **Database Persistence vs. Tick Performance**:
   - SQLite writes must not be executed synchronously on every monster kill within the 30Hz simulation loop (SLA < 33.3ms). In-memory state tracking with asynchronous or dirty-flag write-behind to the `characters` table is required.
2. **Multiplayer Party EXP Sharing**:
   - The current scope focuses on solo player attribution. If parties are supported, party radius and allocation splits should be addressed as a separate sub-milestone.
3. **Hardcore Realm Mortality**:
   - In Hardcore mode (GEMINI.md § 2.4), death demotes the character to the Standard Realm (The Forsaken Realm). The softcore tiered EXP penalty applies to characters in the Challenge Realm who survive via standard respawn.

---

## 4. Conclusion

The architectural survey is complete. The system requirements, mathematical formulas, and service designs are fully specified:
1. `LevelProgressionService` must be created in `server/world/level_progression_service.py` with companion types in `server/world/level_progression_types.py`.
2. The 7-segment Piecewise EXP curve replaces the naive `lvl^1.85` formula in `game_design_matrix_seeder.py`.
3. Level gap penalty formula: $\max(0.01, 0.54^{gap-5})$ for $gap > 5$.
4. Tiered death penalty: 1-60: 0%, 61-80: 5%, 81-89: 10%, 90-99: 15%, 99->100: 25%, with the Safe Floor at 0%.
5. Trial 10 strictly gated at `level == 100`, unlocking `GODHOOD_AVATAR_METAMORPHOSIS` keystone (`avatar_metamorphosis_active = True`, +40% More Damage, +5% Max Resists).

---

## 5. Verification Method

To verify these observations independently:
1. **Ascendancy Suite**:
   ```bash
   pytest tests/unit/test_ascendancy_system.py
   ```
2. **Combat Suite**:
   ```bash
   pytest tests/unit/test_combat_engine.py
   ```
3. **Zone Purity Suite**:
   ```bash
   pytest tests/unit/test_zone_monster_spawning_rules.py
   ```
4. **Code & Doc Hygiene Check**:
   ```bash
   python tools/lint/check_code_and_doc_hygiene.py --strict
   ```
5. **Inspect Artifacts**:
   - Comprehensive Design Report: `c:\Projects\FreeExile\.agents\teamwork\explorer_survey_progression_1\report.md`