fix(search): floor-area and bulk-control hardening follow-ups (#2243)

* fix: name the cost of a floor-registry outage in area resolution

A dead floor registry suppresses all fuzzy area matching, but the only
line the caller saw was the generic fetch warning. Return a resolution
warning that names the consequence and the recovery, and derive the
availability flag from the parse outcome so the two predicates cannot
desync.

* fix: route ha_search partial_reason through the shared merger

_finalize_partial_state concatenated with its own separator and no
de-duplication while the module's other three writers used
_merge_partial_reason. Also fall back to the exception type name when a
branch exception's message is empty, so a timeout no longer produces
partial_reason 'entities: '.

* refactor: fold the bulk-row skip blocks into one helper

Seven copies of log/build/append collapse into _skip_bulk_operation, and
the dead err_response['index'] writes go with them — create_error_response
already lifts every context key to the top level. The allowed-key literal
now reads its keys back from BulkControlOperation so the runtime validator
cannot drift from the advertised schema.

* fix: reject boolean bulk timeouts at both validation layers

Pydantic's lax mode coerces true to 1.0 and float(True) is 1.0, so
timeout_seconds: true was silently accepted as a one-second wait on both
the transport schema and the runtime batch validator. The field now
carries strict=True (matching validate_first) and the runtime helper
rejects bools before float() sees them; its return collapses to
float | None so the caller no longer re-invalidates None. A swallowed
ValidationError in ha_bulk_control now logs the schema's reason, which is
the only place that detail survives.

* fix: fail a bulk batch whose every operation is invalid

An empty operations list already raised, but a batch where every row
failed validation returned the success-shaped response with
successful_commands: 0. The batch-item carve-out from AGENTS.md's
raise-on-failure rule exists to protect successful siblings, and there
are none — so raise with the skipped rows in the payload, still ahead of
the component probe so nothing dispatches. Mixed batches keep failing
soft.

* fix: name where a bulk parameters JSON string failed to parse

The JSONDecodeError was caught unbound, so the caller was told only that
its parameters were invalid JSON. Thread the decoder's reason and offset
into the message, and lead every bulk validation-failure suggestion list
with the row-shape guidance models get wrong most often.

* docs: correct the model-facing bulk descriptions and stale comments

validate_first said it prevents dispatch, but the component batch path
detects the missing entity from the captured pre-state afterwards. The
parameters description never said the per-domain key list is a silent
allowlist, and _DOMAIN_PARAMS carried no warning that a new parameter
disappears at dispatch until it is added there. Also restores the
exact-first rationale on _match_area_ids and reflects the shortened final
poll in get_device_operation_status.

* test: cover the bulk and floor-expansion branches nothing reached

Pins entity aggregation through floor expansion (a second area on the
floor with its own entity), a bare floor_id as the area filter, the
non-string entity_id branch, and a parameters string that parses to a
list rather than an object.

* chore: satisfy CodeQL implicit-concat check in bulk suggestions

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: reject string bulk timeouts at runtime to match the strict schema

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: skip oversized bulk timeouts instead of aborting the batch

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: reject null bulk parameters and classify non-dict rows as invalid

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: skip pathologically nested bulk parameters instead of aborting the batch

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: stringify non-string bulk operation keys before sorting

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

* fix: redact logged bulk inputs and treat a missing registry result as an outage

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Xih4pUWhifP1zhQe3iaKVD

---------

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/tools/device_control.py

@@ -40,9 +40,14 @@ def _extract_registry_list(
             logger.debug(f"Could not fetch {label}: {result}")
             cause = str(result) or type(result).__name__
         elif isinstance(result, dict) and result.get("success"):
-            payload = result.get("result", [])
+            # No default for a missing key: a legitimate empty registry is
+            # "result": [], so an absent result is a malformed envelope and
+            # must degrade loudly, not read as available-and-empty.
+            payload = result.get("result")
             if isinstance(payload, list):
                 registry = payload
+            elif payload is None and "result" not in result:
+                cause = "malformed result payload: result key missing"
             else:
                 cause = (
                     "malformed result payload: expected list, "

src/ha_mcp/tools/smart_search/_base.py

@@ -473,13 +473,15 @@ async def get_entities_by_area(
             area_registry = self._parse_area_registry(results[1], registry_warnings)
             entity_reg_map = self._parse_entity_reg_map(results[2], registry_warnings)
             device_area_map = self._parse_device_area_map(results[3], registry_warnings)
-            floor_result = results[4]
-            floor_registry_available = (
-                isinstance(floor_result, dict)
-                and floor_result.get("success") is True
-                and isinstance(floor_result.get("result"), list)
-            )
-            floor_registry = self._parse_floor_registry(floor_result, registry_warnings)
+            # Availability is read back OUT of the parse rather than re-derived
+            # from the raw payload: the parser already decides what counts as
+            # usable floor data, and a second predicate here drifted from it
+            # once. An empty warnings list means the parser accepted the
+            # payload; anything else disables the fuzzy floor/area fallback.
+            floor_warnings: list[str] = []
+            floor_registry = self._parse_floor_registry(results[4], floor_warnings)
+            floor_registry_available = not floor_warnings
+            registry_warnings.extend(floor_warnings)
             degraded_warnings = registry_warnings + visibility_warnings
 
             matched_area_ids, resolution_warnings = self._resolve_area_query(
@@ -657,8 +659,15 @@ def _resolve_area_query(
 
         if not floor_registry_available:
             # Without the floor registry, fuzzy area matching could silently
-            # recreate the original floor->partial-area misresolution.
-            return set(), []
+            # recreate the original floor->partial-area misresolution. The
+            # fetch warning names the outage; this one names what the outage
+            # cost the caller, so "no match" is not read as "no such area".
+            return set(), [
+                f"Floor data is unavailable, so '{area_query}' was matched only "
+                "against exact area IDs, names, and aliases; close-spelling "
+                "matching was skipped. Retry, or pass an exact area_id from "
+                "ha_list_floors_areas."
+            ]
 
         fuzzy_floor_ids, floor_score = cls._match_fuzzy_registry_ids(
             floor_registry, "floor_id", query_lower
@@ -768,7 +777,10 @@ def _match_area_ids(
         """Resolve the query to area IDs: exact id/name/alias, then fuzzy.
 
         Exact matches delegate to the shared registry matcher so area and floor
-        precedence use identical case-insensitive semantics.
+        precedence use identical case-insensitive semantics. Exact must win
+        outright: a query like "bedroom_kids" partial-matches its parent
+        "bedroom" at ratio 100, so falling through to the fuzzy pass would
+        aggregate every sibling area's entities under an exact hit.
         """
         exact_area_ids = cls._match_exact_registry_ids(
             area_registry, "area_id", area_query_lower

src/ha_mcp/tools/smart_search/_entities.py

@@ -321,12 +321,11 @@ def _finalize_partial_state(
     if partial_local:
         response["partial"] = True
         response["errors"].extend(errors_local)
-        local_reason = "; ".join(
-            f"{error['surface']}: {error['error']}" for error in errors_local
-        )
-        existing_reason = response.get("partial_reason")
-        response["partial_reason"] = (
-            f"{existing_reason}; {local_reason}" if existing_reason else local_reason
+        _merge_partial_reason(
+            response,
+            "; ".join(
+                f"{error['surface']}: {error['error']}" for error in errors_local
+            ),
         )
 
 
@@ -2217,7 +2216,11 @@ async def _legacy_ha_search(
                 raise outcome
             if isinstance(outcome, Exception):
                 partial = True
-                errors.append({"surface": label, "error": str(outcome)})
+                # ``str(asyncio.TimeoutError())`` is "" — fall back to the type
+                # name so partial_reason never reads "entities: ".
+                errors.append(
+                    {"surface": label, "error": str(outcome) or type(outcome).__name__}
+                )
                 logger.warning("ha_search %s branch failed: %r", label, outcome)
                 continue
             _apply_search_outcome(response, label, outcome)

src/ha_mcp/tools/tools_search.py

@@ -83,7 +83,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 description=(
                     "Optional action parameters, e.g. {'brightness_pct': 30} "
-                    "when action='on'."
+                    "when action='on'. Each domain has a fixed allowlist of "
+                    "supported keys; keys outside it are ignored rather than "
+                    "rejected. Use ha_call_service for parameters this tool "
+                    "does not carry."
                 )
             ),
         ]
@@ -94,6 +97,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 ge=0,
                 allow_inf_nan=False,
+                # ``strict`` for the same reason validate_first carries it:
+                # lax mode coerces ``true`` to 1.0, so a bool would land
+                # downstream as a silent one-second timeout.
+                strict=True,
                 description=(
                     "Optional confirmation timeout. On the component path, all "
                     "operations share the maximum requested wait (default 10s, "
@@ -108,8 +115,10 @@ class BulkControlOperation(TypedDict):
             Field(
                 strict=True,
                 description=(
-                    "Validate that the entity exists before dispatch; default true. "
-                    "The action is always validated."
+                    "Report an ENTITY_NOT_FOUND failure when the target entity "
+                    "does not exist; default true. On the component batch path "
+                    "this is detected from the captured pre-state rather than by "
+                    "preventing dispatch. The action is always validated."
                 ),
             ),
         ]
@@ -1531,7 +1540,8 @@ async def ha_bulk_control(
 
         Caveats: put every target in ``operations`` and call the tool once. Parallel
         execution is the default, and invalid items are reported without aborting
-        valid operations in the same batch.
+        valid operations in the same batch. A batch in which every item fails
+        validation dispatches nothing and fails the call.
         """
         parallel_bool = parallel
 
@@ -1559,14 +1569,24 @@ async def ha_bulk_control(
             )
 
         operations_list: list[Any] = []
-        for operation in parsed_operations:
+        for index, operation in enumerate(parsed_operations):
             try:
                 operations_list.append(
                     _BULK_CONTROL_OPERATION_ADAPTER.validate_python(operation)
                 )
-            except ValidationError:
+            except ValidationError as exc:
                 # Preserve malformed rows for the runtime batch validator, which
                 # reports them in skipped_details instead of rejecting the call.
+                # The schema's reason is richer than the runtime validator's and
+                # is the only place it survives, so log it here.
+                # include_input=False: a malformed row can carry sensitive
+                # values (lock or alarm codes in a mistyped field), and
+                # str(exc) would write them to persistent server logs.
+                logger.warning(
+                    "ha_bulk_control operation %d failed schema validation: %s",
+                    index,
+                    exc.errors(include_url=False, include_input=False),
+                )
                 operations_list.append(operation)
 
         result = await self._device_tools.bulk_device_control(

src/ha_mcp/tools/tools_service.py

@@ -360,6 +360,16 @@ def _basement_client(*, area_aliases: list[str] | None = None):
             ],
         )
 
+    @staticmethod
+    def _entity_ids(result: dict) -> set[str]:
+        """Collect every entity id across a domain-grouped area result."""
+        return {
+            record["entity_id"]
+            for area in result["areas"].values()
+            for records in area["entities"].values()
+            for record in records
+        }
+
     @pytest.mark.asyncio
     async def test_floor_name_expands_to_all_areas_on_floor(self):
         """An exact floor name expands instead of fuzzy-matching one area."""
@@ -370,14 +380,46 @@ async def test_floor_name_expands_to_all_areas_on_floor(self):
                 {"area_id": "garage", "name": "Garage", "floor_id": "ground"},
             ]
         )
+        # A second area on the floor needs its own entity, or the expansion
+        # could aggregate zero entities from it and still look correct.
+        client.entities.append(
+            {
+                "entity_id": "light.cave_lamp",
+                "attributes": {"friendly_name": "Cave Lamp"},
+                "state": "off",
+            }
+        )
+        client.entity_registry.append(
+            {"entity_id": "light.cave_lamp", "area_id": "cave", "device_id": None}
+        )
         tools = SmartSearchTools(client=client, fuzzy_threshold=60)
 
         result = await tools.get_entities_by_area("sous-sol")
 
         assert result["total_areas_found"] == 2
         assert set(result["areas"]) == {"couloir_sous_sol", "cave"}
+        assert self._entity_ids(result) == {"light.basement_hall", "light.cave_lamp"}
+        assert result["total_entities"] == 2
         assert any("expanded to 2 area(s)" in warning for warning in result["warnings"])
 
+    @pytest.mark.asyncio
+    async def test_bare_floor_id_expands_to_all_areas_on_floor(self):
+        """A literal floor_id expands the same way the floor's name does.
+
+        The collision test below renames an AREA to ``sous_sol``; nothing else
+        covered passing the floor's own identifier while it stays unique.
+        """
+        client = self._basement_client()
+        client.areas.append({"area_id": "cave", "name": "Cave", "floor_id": "sous_sol"})
+        tools = SmartSearchTools(client=client, fuzzy_threshold=60)
+
+        result = await tools.get_entities_by_area("sous_sol")
+
+        assert set(result["areas"]) == {"couloir_sous_sol", "cave"}
+        assert any(
+            "is a floor, not an area" in warning for warning in result["warnings"]
+        )
+
     @pytest.mark.asyncio
     async def test_floor_alias_expands_to_areas_on_floor(self):
         """An exact floor alias follows the same deterministic expansion."""