Stabilize entity unique IDs across config migrations (#388)

## Summary
- collapse all migration work into `v1.3` so this release uses a single
migration step
- in `v1.3`, migrate legacy pricing fields into policy rules and
normalize section-prefixed unique IDs to stable IDs
- in `v1.3`, handle duplicate conflicts by removing section-prefixed
duplicates when stable unique IDs already exist

## Test plan
- [x] `uv run pytest
custom_components/haeo/migrations/tests/test_v1_3.py
custom_components/haeo/migrations/tests/test_runner.py
custom_components/haeo/entities/tests/test_haeo_number.py
custom_components/haeo/entities/tests/test_haeo_switch.py`
- [x] `uv run ruff check custom_components/haeo/migrations/__init__.py
custom_components/haeo/migrations/v1_3.py
custom_components/haeo/migrations/tests/test_v1_3.py`

Author: TrentHouliston

custom_components/haeo/entities/haeo_number.py

@@ -34,6 +34,23 @@
 
 # Attributes to exclude from recorder when forecast recording is disabled
 FORECAST_UNRECORDED_ATTRIBUTES: frozenset[str] = frozenset({"forecast"})
+LIST_ITEM_FIELD_PATH_LENGTH = 3
+SECTION_FIELD_PATH_LENGTH = 2
+
+
+def _field_name_is_reused_in_other_sections(
+    subentry_data: Mapping[str, Any],
+    *,
+    current_section: str,
+    field_name: str,
+) -> bool:
+    """Return True when another section reuses this field name."""
+    for section_key, section_data in subentry_data.items():
+        if section_key == current_section or not isinstance(section_data, Mapping):
+            continue
+        if field_name in section_data:
+            return True
+    return False
 
 
 class ConfigEntityMode(Enum):
@@ -107,9 +124,23 @@ def __init__(
                 msg = f"Invalid config value for field {field_info.field_name}"
                 raise RuntimeError(msg)
 
-        # Unique ID for multi-hub safety: entry_id + subentry_id + field_name
+        # Unique ID: entry_id + subentry_id + stable_key.
+        # Keep leaf-only keys for simple fields, but disambiguate section fields
+        # when the same leaf appears in multiple sections.
         field_path_key = ".".join(self._field_path)
-        self._attr_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{field_path_key}"
+        is_list_item_field = len(self._field_path) >= LIST_ITEM_FIELD_PATH_LENGTH
+        unique_key = field_info.field_name
+        if is_list_item_field:
+            unique_key = field_path_key
+        elif len(self._field_path) == SECTION_FIELD_PATH_LENGTH and _field_name_is_reused_in_other_sections(
+            subentry.data,
+            current_section=self._field_path[0],
+            field_name=field_info.field_name,
+        ):
+            unique_key = (
+                f"{field_info.device_type}.{field_info.field_name}" if field_info.device_type else field_path_key
+            )
+        self._attr_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{unique_key}"
 
         # Use entity description directly from field info
         self.entity_description = field_info.entity_description
@@ -166,8 +197,8 @@ def format_placeholder(value: Any) -> str:
             self._base_extra_attrs["direction"] = field_info.direction
 
         # For list item fields, expose sibling fields from the list item
-        if len(self._field_path) > 2:  # noqa: PLR2004
-            own_field = self._field_path[2]
+        if len(self._field_path) >= LIST_ITEM_FIELD_PATH_LENGTH:
+            own_field = field_info.field_name
             item = get_nested_config_value_by_path(subentry.data, self._field_path[:2])
             if isinstance(item, Mapping):
                 for key, value in item.items():

custom_components/haeo/entities/haeo_switch.py

@@ -31,6 +31,23 @@
 
 # Attributes to exclude from recorder when forecast recording is disabled
 FORECAST_UNRECORDED_ATTRIBUTES: frozenset[str] = frozenset({"forecast"})
+LIST_ITEM_FIELD_PATH_LENGTH = 3
+SECTION_FIELD_PATH_LENGTH = 2
+
+
+def _field_name_is_reused_in_other_sections(
+    subentry_data: Mapping[str, Any],
+    *,
+    current_section: str,
+    field_name: str,
+) -> bool:
+    """Return True when another section reuses this field name."""
+    for section_key, section_data in subentry_data.items():
+        if section_key == current_section or not isinstance(section_data, Mapping):
+            continue
+        if field_name in section_data:
+            return True
+    return False
 
 
 class HaeoInputSwitch(SwitchEntity):
@@ -101,9 +118,21 @@ def __init__(
                 msg = f"Invalid config value for field {field_info.field_name}"
                 raise RuntimeError(msg)
 
-        # Unique ID for multi-hub safety: entry_id + subentry_id + field_name
+        # Unique ID: stable key with section disambiguation when required.
         field_path_key = ".".join(self._field_path)
-        self._attr_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{field_path_key}"
+        is_list_item_field = len(self._field_path) >= LIST_ITEM_FIELD_PATH_LENGTH
+        unique_key = field_info.field_name
+        if is_list_item_field:
+            unique_key = field_path_key
+        elif len(self._field_path) == SECTION_FIELD_PATH_LENGTH and _field_name_is_reused_in_other_sections(
+            subentry.data,
+            current_section=self._field_path[0],
+            field_name=field_info.field_name,
+        ):
+            unique_key = (
+                f"{field_info.device_type}.{field_info.field_name}" if field_info.device_type else field_path_key
+            )
+        self._attr_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{unique_key}"
 
         # Use entity description directly from field info
         self.entity_description = field_info.entity_description

custom_components/haeo/entities/tests/test_haeo_number.py

@@ -658,7 +658,57 @@ async def test_unique_id_includes_all_components(
         horizon_manager=horizon_manager,
     )
 
-    expected_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_efficiency.{power_field_info.field_name}"
+    expected_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{power_field_info.field_name}"
+    assert entity.unique_id == expected_unique_id
+
+
+async def test_unique_id_disambiguates_reused_section_field_names(
+    hass: HomeAssistant,
+    config_entry: MockConfigEntry,
+    device_entry: Mock,
+    horizon_manager: Mock,
+) -> None:
+    """Section fields with repeated leaf names use a collision-proof key."""
+    partition_field_info = InputFieldInfo(
+        field_name="partition_percentage",
+        entity_description=NumberEntityDescription(
+            key="partition_percentage",
+            translation_key="partition_percentage",
+            native_unit_of_measurement="%",
+            native_min_value=0.0,
+            native_max_value=100.0,
+            native_step=1.0,
+        ),
+        output_type=OutputType.STATE_OF_CHARGE,
+        time_series=True,
+        boundaries=True,
+        device_type="undercharge_partition",
+    )
+    subentry = ConfigSubentry(
+        data=MappingProxyType(
+            {
+                "element_type": "battery",
+                CONF_NAME: "Test Battery",
+                "undercharge": {"partition_percentage": as_constant_value(5.0)},
+                "overcharge": {"partition_percentage": as_constant_value(95.0)},
+            }
+        ),
+        subentry_type="battery",
+        title="Test Battery",
+        unique_id=None,
+    )
+    config_entry.runtime_data = None
+
+    entity = HaeoInputNumber(
+        config_entry=config_entry,
+        subentry=subentry,
+        field_info=partition_field_info,
+        device_entry=device_entry,
+        horizon_manager=horizon_manager,
+        field_path=("undercharge", "partition_percentage"),
+    )
+
+    expected_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_undercharge_partition.partition_percentage"
     assert entity.unique_id == expected_unique_id
 
 

custom_components/haeo/entities/tests/test_haeo_switch.py

@@ -485,9 +485,51 @@ async def test_unique_id_includes_all_components(
         horizon_manager=horizon_manager,
     )
 
-    expected_unique_id = (
-        f"{config_entry.entry_id}_{subentry.subentry_id}_curtailment.{curtailment_field_info.field_name}"
+    expected_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_{curtailment_field_info.field_name}"
+    assert entity.unique_id == expected_unique_id
+
+
+async def test_unique_id_disambiguates_reused_section_field_names(
+    hass: HomeAssistant,
+    config_entry: MockConfigEntry,
+    device_entry: Mock,
+    horizon_manager: Mock,
+) -> None:
+    """Section switch fields with repeated leaf names use a unique stable key."""
+    field_info = InputFieldInfo(
+        field_name="enabled",
+        entity_description=SwitchEntityDescription(
+            key="enabled",
+            translation_key="enabled",
+        ),
+        output_type=OutputType.STATUS,
+        device_type="undercharge_toggle",
     )
+    subentry = ConfigSubentry(
+        data=MappingProxyType(
+            {
+                "element_type": "battery",
+                CONF_NAME: "Test Battery",
+                "undercharge": {"enabled": as_constant_value(True)},
+                "overcharge": {"enabled": as_constant_value(False)},
+            }
+        ),
+        subentry_type="battery",
+        title="Test Battery",
+        unique_id=None,
+    )
+    config_entry.runtime_data = None
+
+    entity = HaeoInputSwitch(
+        config_entry=config_entry,
+        subentry=subentry,
+        field_info=field_info,
+        device_entry=device_entry,
+        horizon_manager=horizon_manager,
+        field_path=("undercharge", "enabled"),
+    )
+
+    expected_unique_id = f"{config_entry.entry_id}_{subentry.subentry_id}_undercharge_toggle.enabled"
     assert entity.unique_id == expected_unique_id
 
 

custom_components/haeo/migrations/__init__.py

@@ -7,14 +7,11 @@
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 
-from . import v1_3, v1_4
+from . import v1_3
 
 type MigrationHandler = Callable[[HomeAssistant, ConfigEntry], Awaitable[bool]]
 
-MIGRATIONS: tuple[tuple[int, MigrationHandler], ...] = (
-    (v1_3.MINOR_VERSION, v1_3.async_migrate_entry),
-    (v1_4.MINOR_VERSION, v1_4.async_migrate_entry),
-)
+MIGRATIONS: tuple[tuple[int, MigrationHandler], ...] = ((v1_3.MINOR_VERSION, v1_3.async_migrate_entry),)
 
 MIGRATION_MINOR_VERSION = MIGRATIONS[-1][0] if MIGRATIONS else 0