fix: preserve collector-only cloud analysis and clarify capture readiness

Author: Maksym Shtembuliak

CHANGELOG.md

@@ -7,6 +7,17 @@ the GitHub release body should be rendered from the matching version section her
 
 ## [Unreleased]
 
+### Fixed
+
+- Read-only cloud analysis now retains its results for collector-only entries
+  with no local inverter driver. Recognized cloud readings no longer cause the
+  result-building step to fail while checking local sensor coverage (#23).
+  Failure artifacts now also include the selected source, workflow stage and
+  exception category without exception messages or credentials.
+- Proxy-capture guidance now distinguishes the collector's configured server
+  address from Home Assistant's callback address (#43). Capture still requires
+  a connected collector and a known endpoint that can be safely restored.
+
 ## [0.3.0-beta.5] - 2026-09-09
 
 ### Added

custom_components/eybond_local/button.py

@@ -399,7 +399,7 @@ def _collector_action_availability_reason(self) -> str | None:
             if overview.blocking_reason == "target_endpoint_unavailable":
                 return "Proxy target endpoint is not available."
             if overview.blocking_reason == "current_endpoint_unavailable":
-                return "Current collector callback endpoint is not available yet."
+                return "The collector's current server address has not been read yet."
             if overview.blocking_reason == "session_active":
                 return "Proxy capture session is already active."
             return "Proxy capture is not ready."

custom_components/eybond_local/flow_translations/en.json

@@ -121,7 +121,7 @@
       "proxy_capture_blocking_collector_control_disabled": "collector changes are currently disabled by the selected control mode",
       "proxy_capture_blocking_collector_not_connected": "the collector is not connected",
       "proxy_capture_blocking_target_endpoint_unavailable": "Home Assistant capture address is not available yet",
-      "proxy_capture_blocking_current_endpoint_unavailable": "the current collector callback address is not available yet",
+      "proxy_capture_blocking_current_endpoint_unavailable": "the collector's current server address has not been read yet",
       "proxy_capture_blocking_session_active": "a capture session is already running",
       "proxy_capture_blocking_operating_profile_requires_cloud_and_ha": "switch to Cloud + Home Assistant before starting a cloud traffic operation",
       "proxy_capture_blocking_transparent_wire_incompatible": "transparent capture is unavailable because the collector and cloud use different protocols",

custom_components/eybond_local/flow_translations/ru.json

@@ -121,7 +121,7 @@
       "proxy_capture_blocking_collector_control_disabled": "избранный режим управления сейчас не разрешает изменения коллектора",
       "proxy_capture_blocking_collector_not_connected": "коллектор не подключен",
       "proxy_capture_blocking_target_endpoint_unavailable": "адрес Home Assistant для захвата пока недоступен",
-      "proxy_capture_blocking_current_endpoint_unavailable": "текущий адрес обратного подключения коллектора пока неизвестен",
+      "proxy_capture_blocking_current_endpoint_unavailable": "ещё не удалось прочитать текущий адрес сервера, к которому подключается коллектор",
       "proxy_capture_blocking_session_active": "сеанс захвата уже запущен",
       "proxy_capture_blocking_operating_profile_requires_cloud_and_ha": "перед запуском операции переключитесь в профиль «Облако + Home Assistant»",
       "proxy_capture_blocking_transparent_wire_incompatible": "прозрачный захват недоступен: коллектор и облако используют разные протоколы",

custom_components/eybond_local/flow_translations/uk.json

@@ -121,7 +121,7 @@
       "proxy_capture_blocking_collector_control_disabled": "обраний режим керування зараз не дозволяє зміни колектора",
       "proxy_capture_blocking_collector_not_connected": "колектор не підключений",
       "proxy_capture_blocking_target_endpoint_unavailable": "адреса Home Assistant для захоплення поки недоступна",
-      "proxy_capture_blocking_current_endpoint_unavailable": "поточна адреса зворотного підключення колектора поки невідома",
+      "proxy_capture_blocking_current_endpoint_unavailable": "ще не вдалося прочитати поточну адресу сервера, до якого підключається колектор",
       "proxy_capture_blocking_session_active": "сеанс захоплення вже запущено",
       "proxy_capture_blocking_operating_profile_requires_cloud_and_ha": "перед запуском операції перейдіть до профілю «Хмара + Home Assistant»",
       "proxy_capture_blocking_transparent_wire_incompatible": "прозоре захоплення недоступне: колектор і хмара використовують різні протоколи",

custom_components/eybond_local/flows/options/shadow_run.py

@@ -68,6 +68,10 @@ def _metadata_with_local_coverage(
     """Attach exact typed local evidence without minting cloud bindings."""
 
     detached = dict(metadata_evidence)
+    # Coverage belongs to the current local driver, not to the cloud source or
+    # an earlier run. Collector-only entries have a valid empty telemetry frame
+    # but no driver against which semantic presence can be checked.
+    detached.pop("local_coverage", None)
     if (
         type(local_register_snapshot) is LocalRegisterSnapshot
         and type(expected_collector_pn) is str
@@ -94,7 +98,11 @@ def _metadata_with_local_coverage(
     semantic_report = CloudSemanticEvidenceReport.from_record(
         detached.get("semantic_report")
     )
-    if semantic_report is None or type(telemetry) is not TypedTelemetryFrame:
+    if (
+        semantic_report is None
+        or type(telemetry) is not TypedTelemetryFrame
+        or not telemetry.driver_key
+    ):
         return detached
     detached["local_coverage"] = build_cloud_local_coverage_report(
         semantic_report,
@@ -617,6 +625,24 @@ async def _async_run_control_discovery(self) -> None:
             self._shadow_learning_state["discovery"] = {
                 "status": "error",
                 "reason": failure_reason,
+                # Keep workflow-owned context in the archive too, not only in
+                # the Core log. Never persist exception text, request URLs or
+                # arbitrary provider attributes (which may contain credentials).
+                "diagnostics": {
+                    "learning_source": source_id,
+                    "stage": str(progress.get("stage") or "unknown"),
+                    "exception_category": next(
+                        (
+                            error_type.__name__
+                            for error_type in (
+                                TimeoutError, ConnectionError, ValueError,
+                                TypeError, RuntimeError,
+                            )
+                            if isinstance(exc, error_type)
+                        ),
+                        "Exception",
+                    ),
+                },
             }
             self._shadow_learning_state["status"] = self._tr(
                 "common.dynamic.control_discovery_failed",

custom_components/eybond_local/flows/options/shadow_runtime.py

@@ -395,6 +395,16 @@ def _publish_shadow_learning_artifacts(self, coordinator) -> dict[str, Any]:
                     "reason": str(discovery.get("reason") or ""),
                     "preflight": dict(state.get("preflight") or {}),
                 }
+        # A late failure must also be recorded when a successful provider
+        # result was already published; retain that result as partial evidence.
+        discovery = state.get("discovery")
+        if isinstance(discovery, dict) and discovery.get("status") == "error":
+            diagnostics = discovery.get("diagnostics")
+            if isinstance(diagnostics, dict):
+                orchestration["failure"] = {
+                    "reason": str(discovery.get("reason") or ""),
+                    **diagnostics,
+                }
         correlation = orchestration.get("correlation")
         if not isinstance(correlation, dict):
             correlation = {}

custom_components/eybond_local/support/proxy_capture/__init__.py

@@ -214,7 +214,7 @@ def build_proxy_capture_overview(
         return ProxyCaptureOverview(
             status="blocked",
             status_label=_status_label("blocked"),
-            summary="The current collector callback endpoint is not available yet.",
+            summary="The collector's current server address has not been read yet.",
             blocking_reason="current_endpoint_unavailable",
             can_start=False,
             can_stop=False,

docs/user/DEVICE_LEARNING.md

@@ -158,6 +158,12 @@ setting names and cloud field IDs alone do not prove local register addresses.
 Save the Support Archive after the check so the maintainer can review the data.
 SmartClient active control verification is not available yet.
 
+You can finish this analysis even if Home Assistant has identified only the
+collector, not the inverter. Cloud readings and setting descriptions are kept
+for support; comparison with existing local sensors is skipped until a local
+driver is available. A failed check also records its source and workflow stage
+in the Support Archive, without saving your cloud password.
+
 The goal is to learn what the device supports without permanently changing inverter settings.
 
 If the safe learning path is not ready, the integration stops instead of continuing.

tests/test_config_flow.py

@@ -9787,6 +9787,12 @@ async def test_smartclient_pipeline_keeps_exact_source_and_publishes_passive_evi
         from custom_components.eybond_local.support import smartclient_learning
 
         coordinator = self._RunnerCoordinator(ready=False)
+        # Real collector-only RuntimeSnapshot has a typed empty frame, not a
+        # missing telemetry attribute. Recognized cloud fields must not require
+        # a local driver (issue #23).
+        coordinator.effective_profile_name = ""
+        coordinator.effective_register_schema_name = ""
+        coordinator.data.telemetry = TypedTelemetryFrame(driver_key="", points=())
         options = self._runner_options_flow(coordinator)
         options._shadow_learning_state.update(
             {"wizard_method": LEARNING_METHOD_READ_ONLY_EVIDENCE, "wizard_source": "smartclient"}
@@ -9804,10 +9810,61 @@ async def test_smartclient_pipeline_keeps_exact_source_and_publishes_passive_evi
         self.assertTrue(coordinator.published)
         self.assertEqual(options._shadow_learning_state["discovery"]["status"], "ok")
         self.assertEqual(options._shadow_learning_state["cloud_metadata"]["source"], "smartclient")
+        self.assertNotIn("local_coverage", options._shadow_learning_state["cloud_metadata"])
+        self.assertGreater(
+            options._shadow_learning_state["cloud_metadata"]["semantic_report"]["read_candidate_count"], 0
+        )
         self.assertNotIn("demo@example.com", str(coordinator.published))
         self.assertNotIn("wizard_credentials", str(coordinator.published))
         self.assertEqual(options._shadow_learning_state.get("overlay", {}), {})
 
+    def test_cloud_coverage_drops_stale_driver_report_without_local_driver(self) -> None:
+        from custom_components.eybond_local.flows.options.shadow_run import _metadata_with_local_coverage
+
+        evidence = {"source": "smartclient", "local_coverage": {"driver_key": "smg"}}
+        for telemetry in (None, TypedTelemetryFrame(driver_key="", points=())):
+            with self.subTest(telemetry=telemetry):
+                enriched = _metadata_with_local_coverage(evidence, telemetry)
+                self.assertNotIn("local_coverage", enriched)
+                self.assertEqual(enriched["source"], "smartclient")
+                self.assertIn("local_coverage", evidence)
+
+    async def test_cloud_learning_failure_exports_phase_without_exception_secrets(self) -> None:
+        for partial_result in (False, True):
+            with self.subTest(partial_result=partial_result):
+                coordinator = self._RunnerCoordinator(ready=False)
+                options = self._runner_options_flow(coordinator)
+                options._shadow_learning_state.update({
+                    "wizard_method": LEARNING_METHOD_READ_ONLY_EVIDENCE,
+                    "wizard_source": "smartclient",
+                    "progress": {"stage": "building", "fraction": 0.82},
+                })
+                if partial_result:
+                    options._shadow_learning_state["orchestration"] = {
+                        "source": "smartclient", "metadata_only": True,
+                        "metadata_evidence": {"telemetry_fields": [{"title": "PV Voltage"}]},
+                    }
+                with (
+                    patch.object(
+                        options, "_async_execute_control_discovery",
+                        new=AsyncMock(side_effect=ValueError("https://private.invalid/?password=cloud-secret")),
+                    ),
+                    self.assertLogs("custom_components.eybond_local.flows.options.shadow_run", level="ERROR") as logs,
+                ):
+                    await options._async_run_control_discovery()
+                artifact = coordinator.published[-1]["orchestration"]
+                self.assertEqual(artifact["failure"], {
+                    "reason": "control_discovery_failure_generic",
+                    "learning_source": "smartclient", "stage": "building",
+                    "exception_category": "ValueError",
+                })
+                if partial_result:
+                    self.assertIn("metadata_evidence", artifact)
+                self.assertNotIn("private.invalid", str(coordinator.published) + str(logs.output))
+                self.assertNotIn("cloud-secret", str(coordinator.published) + str(logs.output))
+                self.assertEqual(coordinator.started, [])
+                self.assertEqual(coordinator.stopped, [])
+
     async def test_dessmonitor_runner_records_typed_local_semantic_coverage(self) -> None:
         coordinator = self._RunnerCoordinator(ready=False)
         coordinator.data.telemetry = TypedTelemetryFrame(