# Data Model: Combatant HP Tracking

**Feature**: 009-combatant-hp | **Date**: 2026-03-05

## Entities

### Combatant (extended)

| Field | Type | Required | Constraints |
|-------|------|----------|-------------|
| id | CombatantId (branded string) | Yes | Unique within encounter |
| name | string | Yes | Non-empty |
| initiative | number or undefined | No | Integer when set |
| **maxHp** | **number or undefined** | **No** | **Positive integer (>= 1) when set** |
| **currentHp** | **number or undefined** | **No** | **Integer in [0, maxHp] when set; requires maxHp** |

**Invariants**:
- If `maxHp` is undefined, `currentHp` must also be undefined (no current HP without a max).
- If `maxHp` is defined, `currentHp` must be defined and satisfy `0 <= currentHp <= maxHp`.
- When `maxHp` is first set, `currentHp` defaults to `maxHp` (full health).
- When `maxHp` changes and `currentHp === maxHp` (full health), `currentHp` stays synced to the new `maxHp`.
- When `maxHp` changes and `currentHp < maxHp` (not full health), `currentHp` is unchanged unless it exceeds the new `maxHp`, in which case it is clamped.
- When `maxHp` is cleared (set to undefined), `currentHp` is also cleared.

### Encounter (unchanged structure)

No structural changes. The encounter continues to hold `readonly combatants: readonly Combatant[]`, `activeIndex`, and `roundNumber`. HP state lives on individual combatants.

## Domain Events (new)

### MaxHpSet

Emitted when a combatant's max HP is set, changed, or cleared.

| Field | Type | Description |
|-------|------|-------------|
| type | "MaxHpSet" | Event discriminant |
| combatantId | CombatantId | Target combatant |
| previousMaxHp | number or undefined | Max HP before change |
| newMaxHp | number or undefined | Max HP after change |
| previousCurrentHp | number or undefined | Current HP before change |
| newCurrentHp | number or undefined | Current HP after change (may differ due to clamping) |

### CurrentHpAdjusted

Emitted when a combatant's current HP is adjusted via +/- or direct entry.

| Field | Type | Description |
|-------|------|-------------|
| type | "CurrentHpAdjusted" | Event discriminant |
| combatantId | CombatantId | Target combatant |
| previousHp | number | Current HP before adjustment |
| newHp | number | Current HP after adjustment (clamped) |
| delta | number | Requested change amount (positive = heal, negative = damage) |

## State Transitions

### setHp(encounter, combatantId, maxHp)

```
Input:  Encounter, CombatantId, number | undefined
Output: { encounter: Encounter, events: [MaxHpSet] } | DomainError

- combatant not found       → DomainError("combatant-not-found")
- maxHp <= 0 or non-integer → DomainError("invalid-max-hp")
- maxHp = undefined         → clear both maxHp and currentHp
- maxHp = N (new)           → set maxHp=N, currentHp=N
- maxHp = N (changed, at full health: currentHp=prevMaxHp) → set maxHp=N, currentHp=N
- maxHp = N (changed, not full health) → set maxHp=N, currentHp=min(currentHp, N)
```

### adjustHp(encounter, combatantId, delta)

```
Input:  Encounter, CombatantId, number
Output: { encounter: Encounter, events: [CurrentHpAdjusted] } | DomainError

- combatant not found        → DomainError("combatant-not-found")
- combatant has no maxHp set → DomainError("no-hp-tracking")
- delta = 0                  → DomainError("zero-delta")
- delta non-integer          → DomainError("invalid-delta")
- result                     → currentHp = clamp(currentHp + delta, 0, maxHp)
```