fix(search): align membership projection contracts

Author: swissmo

custom_components/ha_mcp_tools/websocket_api.py

@@ -1588,11 +1588,13 @@ def _normalize_member_entity_ids(attributes: Any) -> list[str] | None:
         if not isinstance(raw, Collection):
             continue
         members: set[str] = set()
+        valid = True
         for value in raw:
             if not _is_entity_id(value):
+                valid = False
                 break
             members.add(value)
-        else:
+        if valid:
             return sorted(members)
     return None
 

src/ha_mcp/tools/tools_search.py

@@ -761,9 +761,9 @@ def _normalized_domain_filter(raw: str | None) -> str | None:
 _ENRICHMENT_FIELDS: tuple[str, ...] = ("area", "floor", "labels", "aliases")
 _MEMBERSHIP_FIELDS: tuple[str, ...] = ("is_group", "member_entity_ids")
 
-# Every field name result_fields= accepts — base record keys plus the opt-in
-# enrichment keys. A requested name outside this set is rejected up front with the
-# standard validation error rather than silently projecting to empty records.
+# Every field name result_fields= accepts — base record keys plus opt-in
+# enrichment and membership keys. Unknown names are rejected up front rather
+# than silently projecting to empty records.
 _ALLOWED_RESULT_FIELDS: frozenset[str] = (
     frozenset(_ENTITY_RECORD_KEYS)
     | frozenset(_ENRICHMENT_FIELDS)
@@ -1134,12 +1134,10 @@ def _shape_component_search_response(
 
     if req.registry_eligible:
         parsed_result_fields = _parse_component_result_fields(req.result_fields)
-        # Base record is the six documented keys. result_fields may additionally
-        # request enrichment fields (area/floor/labels/aliases) that the component
-        # already computed per hit via its registry join — retain exactly those
-        # requested keys before the result_fields projection so the enrichment
-        # survives it, while a search that requests none still emits the default
-        # six-key shape (parity with the legacy path).
+        # Base records contain the six documented keys. Requested enrichment
+        # fields retain the component's area/floor/labels/aliases registry join;
+        # requested membership fields append its opt-in state-derived metadata.
+        # With neither class requested, the default six-key shape is unchanged.
         record_keys = (
             *_ENTITY_RECORD_KEYS,
             *_requested_enrichment(parsed_result_fields),
@@ -2472,7 +2470,7 @@ async def _ha_search_entities(
                     'E.g. ["entity_id", "state"] returns slim entity records. '
                     "None = full records (default). "
                     "Base keys: entity_id, friendly_name, domain, state, score, match_type. "
-                    "Opt-in enrichment/membership keys (computed on request): area, floor, labels, aliases. "
+                    "Opt-in enrichment/membership keys (computed on request): area, floor, labels, aliases, is_group, member_entity_ids. "
                     "An unknown key is rejected."
                 ),
             ),

tests/src/unit/test_component_search_contract.py

@@ -591,9 +591,45 @@ def test_component_body_search_types_lockstep() -> None:
 @pytest.mark.parametrize(
     ("attributes", "expected"),
     [
-        ({"group_entities": ["light.two", "light.one"]}, ["light.one", "light.two"]),
+        (
+            {
+                "group_entities": ["light.two", "light.one", "light.two"],
+                "entity_id": ["light.legacy"],
+            },
+            ["light.one", "light.two"],
+        ),
+        ({"entity_id": ("light.two", "light.one")}, ["light.one", "light.two"]),
         ({"group_entities": [], "entity_id": ["light.legacy"]}, []),
         ({"entity_id": "light.reference"}, None),
+        ({"entity_id": b"light.reference"}, None),
+        ({"entity_id": bytearray(b"light.reference")}, None),
+        ({"group_entities": {"light.member": True}}, None),
+        (
+            {"group_entities": frozenset({"light.two", "light.one"})},
+            ["light.one", "light.two"],
+        ),
+        ({"entity_id": ["light.Not_Valid"]}, None),
+        ({"entity_id": ["light.not-valid"]}, None),
+        ({"entity_id": ["light.lämp"]}, None),
+        ({"group_entities": ["light.valid", "not-an-entity"]}, None),
+        (
+            {
+                "group_entities": ["light.valid", "not-an-entity"],
+                "entity_id": ["light.legacy"],
+            },
+            ["light.legacy"],
+        ),
+        (
+            {
+                "group_entities": ["light.modern"],
+                "entity_id": ["light.legacy"],
+            },
+            ["light.modern"],
+        ),
+        (
+            {"group_entities": ["light.group", "light.member"]},
+            ["light.group", "light.member"],
+        ),
         ({"group_members": ["light.not_supported"]}, None),
     ],
 )
@@ -604,7 +640,7 @@ def test_component_body_search_types_lockstep() -> None:
 def test_membership_normalizer_artifacts_remain_in_lockstep(
     normalizer, attributes, expected
 ) -> None:
-    """Keep server and component normalization aligned across edge cases."""
+    """Keep server and component normalization aligned across all edge cases."""
     assert normalizer(attributes) == expected
 
 

tests/src/unit/test_search_fields_projection.py

@@ -839,7 +839,7 @@ async def send_websocket_message(payload):
         return client
 
     @pytest.fixture
-    def mock_smart_tools(self, mock_client):
+    def real_smart_tools(self, mock_client):
         """Use the real smart-search transform chain for membership redaction."""
         smart = SmartSearchTools(mock_client)
         smart.deep_search = AsyncMock(
@@ -854,9 +854,15 @@ def mock_smart_tools(self, mock_client):
         )
         return smart
 
+    @pytest.fixture
+    def search_tool(self, mock_mcp, mock_client, real_smart_tools):
+        """Register ha_search with the real smart-search fixture."""
+        register_search_tools(mock_mcp, mock_client, smart_tools=real_smart_tools)
+        return self.registered_tools["ha_search"]
+
     @pytest.mark.asyncio
     async def test_fuzzy_search_redacts_hidden_member_but_keeps_group(
-        self, search_tool, mock_smart_tools
+        self, search_tool
     ):
         result = await search_tool(
             query="group",