initiative/specs/026-roll-initiative/data-model.md

Data Model: Roll Initiative

Existing Entities (no changes)

Combatant

Field	Type	Notes
id	CombatantId	Branded string identifier
name	string	Display name
initiative	number | undefined	The initiative value (set by manual input OR roll)
creatureId	CreatureId | undefined	Link to bestiary creature — presence determines roll eligibility
maxHp	number | undefined	From bestiary or manual
currentHp	number | undefined	Current hit points
ac	number | undefined	Armor class
conditions	ConditionId[]	Active conditions
isConcentrating	boolean	Concentration flag

Creature (from bestiary)

Field	Type	Notes
id	CreatureId	Branded string identifier
dexScore	number	Dexterity ability score (used for initiative modifier)
cr	string	Challenge rating (determines proficiency bonus)
initiativeProficiency	number	0 = none, 1 = proficiency, 2 = expertise

Initiative Modifier (derived, not stored)

Calculated on demand via calculateInitiative(creature):

• modifier = Math.floor((dexScore - 10) / 2) + (initiativeProficiency × proficiencyBonus(cr))
• passive = 10 + modifier

New Concepts (no new stored entities)

Roll Result (transient)

Not persisted — computed at the adapter boundary and immediately applied:

• diceRoll: integer 1–20 (generated via Math.random at adapter layer)
• initiativeValue = diceRoll + modifier (computed by domain function, stored as combatant's initiative)

State Transitions

Single Roll

Combatant(initiative: any | undefined)
  → rollInitiative(diceRoll, modifier)
  → Combatant(initiative: diceRoll + modifier)
  → encounter re-sorted by initiative descending

Batch Roll

Encounter(combatants: [...])
  → for each combatant with creatureId:
      → rollInitiative(diceRoll_i, modifier_i)
      → setInitiative(encounter, id, value)
  → single save with final sorted state

Validation Rules

• diceRoll must be an integer in range [1, 20]
• modifier is any integer (can be negative)
• Final initiative value is any integer (can be negative, e.g., 1 + (−3) = −2)
• Only combatants with a non-undefined creatureId are eligible for rolling