feat: support extra health state mechanics

docs/DESIGN_SYSTEM.md

@@ -2178,13 +2178,16 @@ The summary reports `CAPTURE ONLY · MODEL LATER` or the configured branch count
 in text. Its native disclosure semantics preserve keyboard and assistive
 technology support; mobile targets remain at least 44 pixels tall.
 
-The direct-event picker reads the 19 normalized events from the code-defined
+The direct-event picker reads the 28 normalized events from the code-defined
 event registry. Use searchable single-assignment because the vocabulary exceeds
 the compact segmented-choice limit. Each branch presents its event, match
 policy and parameters, optional cooldown, condition, state mutations, and
 outcomes. The branch condition offers `ALWAYS`, `HEALTH BAND`, `EVENT FIELD`,
-and `STATE THRESHOLD` for manual authoring. Event-field conditions expose the
-field path, comparison operator, scalar type, and typed value. State thresholds
+and `STATE THRESHOLD` for manual authoring. When the selected event publishes
+field metadata, event-field conditions derive their available paths and scalar
+types from that metadata. Events without a bounded field contract retain the
+explicit field-path and value-type controls. Event-field conditions expose the
+comparison operator and typed value. State thresholds
 compare an agent-scoped pool with a numeric value. Health bands expose an
 optional inclusive lower Health percentage and a required exclusive upper
 percentage; helper text states how exact thresholds resolve. Predicates outside
@@ -2363,7 +2366,7 @@ definition.
 
 Present bounded syntax, state, phase, outcome, and calculation-stage
 vocabularies as connected reference matrices with shared borders and aligned
-columns. Generate the 19-event registry and Action Family recipe catalog from
+columns. Generate the event registry and Action Family recipe catalog from
 code-defined metadata so the reference matches the available editor controls.
 Explain that events are runtime contracts and recipes only seed editable source
 branches. Pair complex mechanics with a worked `PseudoScript` example. Keep

docs/TALENT_MECHANIC_RULES.md

@@ -26,7 +26,14 @@ Use these event boundaries:
 - **Healing:** Count each healing event. A heal-over-time effect counts each
   tick as a separate event.
 - **Extra Health gained:** Count every Extra Health grant, including a grant
-  received while the Agent already has Extra Health.
+  received while the Agent already has Extra Health. Use
+  `extra_health_granted` for the grant action.
+- **Extra Health state changed:** `extra_health_changed` is Agent-scoped. Emit
+  it when the Agent receives a grant, when the remaining amount changes, and
+  when it is depleted to zero. Every event requires the boolean
+  `values.hasExtraHealth`. It may include the non-negative
+  `values.currentExtraHealth`, which must agree with that status. This state
+  event is distinct from the `extra_health_granted` grant action.
 - **Reloading:** Trigger on reload completion when the weapon had at least one
   round to load. A canceled reload does not count. A weapon that loads one
   round at a time produces one completed-reload event for each round.

docs/architecture.md

@@ -431,17 +431,28 @@ configuration state, and one of three simulation-readiness states:
 - `captured_only`: ISAC preserves the authored mechanic, but the runtime cannot
   calculate it.
 
-The code-defined `MECHANIC_EVENT_REGISTRY` is the event authority. Its 19
+The code-defined `MECHANIC_EVENT_REGISTRY` is the event authority. Its 28
 normalized events are `shot_fired`, `weapon_hit`, `skill_deployed`,
-`skill_hit`, `agent_hit`, `health_damage_taken`, `damage_dealt`,
-`enemy_killed`, `assist`, `healing_applied`, `extra_health_granted`,
-`movement_snapshot`, `proximity_snapshot`, `firing_started`, `firing_stopped`,
-`reload_started`, `reload_completed`, `weapon_swapped`, and `tick`. Event
-details such as target, distance, critical state, source, movement, and nearby
-counts travel as typed event values. The event registry publishes authoritative
-field metadata where branches need a bounded contract. For example,
-`weapon_hit.values.headshot` is a boolean that distinguishes headshots from
-body shots.
+`signature_ability_deployed`, `skill_hit`, `skill_multishot_triggered`,
+`agent_hit`, `health_damage_taken`, `damage_dealt`, `enemy_killed`, `assist`,
+`ally_downed`, `agent_downed`, `ally_rescued`, `grenade_thrown`,
+`medical_kit_used`, `healing_applied`, `extra_health_granted`,
+`extra_health_changed`, `movement_snapshot`, `proximity_snapshot`,
+`firing_started`, `firing_stopped`, `reload_started`, `reload_completed`,
+`weapon_swapped`, and `tick`. Event details such as target, distance, critical
+state, source, movement, and nearby counts travel as typed event values. The
+event registry publishes authoritative field metadata where branches need a
+bounded contract. For those events, the mechanic editor derives its event-field
+controls from that metadata. For example, `weapon_hit.values.headshot` is a
+boolean that distinguishes headshots from body shots.
+
+`extra_health_changed` is Agent-scoped. Normalized timeline producers emit it
+when the Agent receives an Extra Health grant, when the remaining amount
+changes, and when it is depleted to zero. Every event requires the boolean
+`values.hasExtraHealth`. An event may include the non-negative
+`values.currentExtraHealth`; when present, the amount must agree with the
+boolean status. `extra_health_granted` represents a grant action and remains a
+separate event from changes to the Agent's current Extra Health state.
 
 The optional Action Family catalog provides authoring recipes for common
 mechanics. Applying a recipe copies its typed scenario inputs, state pools, and
@@ -462,10 +473,10 @@ The program graph uses three child tables:
 - `conditional_effect_state_pools` defines agent- or target-scoped flags,
   counts, stacks, durations, scalar values, marks, and resources. Each pool
   owns its bounds, expiry policy, refresh policy, and best-case value.
-- `conditional_effect_clauses` listens for one of the 19 events. A clause owns
-  a typed predicate, reducer, optional cooldown, optional weight expression,
-  state mutations, and optional recipe provenance. Reducers convert event
-  streams into counts, distinct or consecutive matches, sliding windows,
+- `conditional_effect_clauses` listens for one event from the registry. A
+  clause owns a typed predicate, reducer, optional cooldown, optional weight
+  expression, state mutations, and optional recipe provenance. Reducers convert
+  event streams into counts, distinct or consecutive matches, sliding windows,
   durations, intervals, or derived values. Mutations can set, add, consume,
   clear, derive, or transfer state. A mutation may bind a target-scoped pool to
   the current event target, event actor, or another typed entity selector. Each