Merge pull request #233 from traktore-org/develop

Release v1.5.8: Calculation audit fixes and quality assurance

Author: traktore-org

.gitignore

@@ -78,6 +78,21 @@ Thumbs.db
 .claude/
 CLAUDE.md
 
+# Ruflo / Agent databases (local only, not for distribution)
+ruvector.db
+agentdb.rvf
+agentdb.rvf.lock
+.claude-flow/
+dashboard/card/ruvector.db
+dashboard/card/.claude-flow/
+
+# GStack browser data
+.gstack/
+
+# Temporary image assets (not for distribution)
+dashboard/card/sem-solar-diagram-bg*.png
+dashboard/card/sem-system-diagram-v2-card.js
+
 # Logo source assets (large files, only sized outputs in root)
 logo/
 

coordinator/coordinator.py

@@ -44,6 +44,7 @@
     HeatPumpSensorData, PVAnalyticsData, EnergyAssistantSensorData,
     UtilitySignalSensorData, SessionData, BatterySessionData,
 )
+from .health_check import HealthCheck
 from .sensor_reader import SensorReader
 from .energy_calculator import EnergyCalculator
 from .flow_calculator import FlowCalculator
@@ -138,6 +139,7 @@ def __init__(self, hass: HomeAssistant, config: Dict[str, Any]) -> None:
             custom_entities=None,  # Was config.get("forecast_entities") — never set via UI
         )
         self._forecast_tracker = ForecastTracker()
+        self._forecast_tracker.set_hass(hass)
 
         # Phase 1: Tariff provider
         tariff_mode = config.get("tariff_mode", "static")
@@ -210,6 +212,9 @@ def __init__(self, hass: HomeAssistant, config: Dict[str, Any]) -> None:
         self._ev_taper_detector = EVTaperDetector(config)  # Primary charger
         self._ev_taper_detectors: Dict[str, EVTaperDetector] = {}  # Per-charger (#112)
 
+        # Calculation integrity checker (runs every cycle)
+        self._health_check = HealthCheck()
+
         # Hourly activity tracker for schedule card (#63)
         self._today_surplus_hours: list = [False] * 24
         self._today_ev_hours: list = [False] * 24
@@ -898,6 +903,15 @@ async def _async_update_data(self) -> Dict[str, Any]:
                 last_update=dt_util.now(),
             )
 
+            # Step 11.5: Energy balance / calculation health check
+            self._health_check.run_all_checks(
+                power,
+                flows=power_flows,
+                autarky=performance.autarky_rate,
+                self_consumption=performance.self_consumption_rate,
+                costs=costs,
+            )
+
             # Step 12: Notifications (extracted for readability, #29)
             await self._send_notifications(
                 charging_state, power, energy, costs, performance,
@@ -1024,6 +1038,7 @@ async def _async_update_data(self) -> Dict[str, Any]:
             result["diag_observer_mode"] = self._observer_mode
             unavail_count = sum(1 for eid in self._sensor_reader._sensor_unavailable)
             result["diag_sensors_unavailable"] = unavail_count
+            result["diag_health_violations"] = self._health_check.total_violations
 
             # Tariff schedule for dashboard card (#25)
             if hasattr(self._tariff_provider, 'get_schedule_for_day'):
@@ -2030,12 +2045,14 @@ def _update_battery_session_tracking(
             session.grid_energy_kwh += grid_increment
             if session.energy_kwh > 0:
                 session.solar_share_pct = (session.solar_energy_kwh / session.energy_kwh) * 100
-            import_rate = self.config.get("electricity_import_rate", 0.30)
+            # Use live dynamic tariff rate instead of static config value (#223)
+            import_rate = self._energy_calculator._import_rate
             session.cost += grid_increment * import_rate
         else:  # discharge
             discharge_increment = (power.battery_discharge_power * hours) / 1000.0
             session.energy_kwh += discharge_increment
-            import_rate = self.config.get("electricity_import_rate", 0.30)
+            # Use live dynamic tariff rate instead of static config value (#223)
+            import_rate = self._energy_calculator._import_rate
             session.savings += discharge_increment * import_rate
 
         # Update duration and average power

coordinator/energy_calculator.py

@@ -171,13 +171,17 @@ def calculate_energy(self, power: PowerReadings) -> EnergyTotals:
         energy.monthly_battery_discharge = self._get_monthly("battery_discharge", month_key)
         energy.yearly_battery_discharge = self._get_yearly("battery_discharge", year_key)
 
-        # Self-consumption savings (incremental, rate-weighted for dynamic tariff accuracy)
+        # Solar self-consumption savings (incremental, rate-weighted for dynamic tariff accuracy)
+        # Only tracks savings from solar — battery discharge savings are in cost_batt_savings.
+        # Subtracting discharge_incr prevents double-counting: battery discharge is not solar.
         home_incr = (power.home_consumption_power * interval_hours) / 1000 if power.home_consumption_power >= MIN_POWER_THRESHOLD else 0.0
         ev_incr = (power.ev_power * interval_hours) / 1000 if power.ev_power >= MIN_POWER_THRESHOLD else 0.0
         import_incr = (power.grid_import_power * interval_hours) / 1000 if power.grid_import_power >= MIN_POWER_THRESHOLD else 0.0
-        savings_incr = max(0.0, (home_incr + ev_incr) - import_incr)
-        if savings_incr > 0.0:
-            self._accumulate_cost("cost_savings", today, month_key, year_key, savings_incr * self._import_rate)
+        discharge_incr = (power.battery_discharge_power * interval_hours) / 1000 if power.battery_discharge_power >= MIN_POWER_THRESHOLD else 0.0
+        # Solar self-consumed = total consumption minus what came from grid or battery discharge
+        solar_self_consumed = max(0.0, (home_incr + ev_incr) - import_incr - discharge_incr)
+        if solar_self_consumed > 0.0:
+            self._accumulate_cost("cost_savings", today, month_key, year_key, solar_self_consumed * self._import_rate)
 
         # Sanity checks — warn and cap if values exceed physical limits
         battery_capacity = self.config.get("battery_capacity_kwh", 15)
@@ -603,6 +607,7 @@ def calculate_costs(self, energy: EnergyTotals) -> CostData:
         costs.monthly_export_revenue = self._get_monthly_cost("cost_export", month_key)
         costs.monthly_net_cost = round(costs.monthly_costs - costs.monthly_export_revenue, 2)
         costs.monthly_savings = max(0, self._get_monthly_cost("cost_savings", month_key))
+        costs.monthly_battery_savings = self._get_monthly_cost("cost_batt_savings", month_key)
 
         # Yearly calculations
         costs.yearly_costs = self._get_yearly_cost("cost_import", year_key)
@@ -817,11 +822,13 @@ def _snapshot_daily_costs(self, today: date) -> None:
         self._accumulated_self_consumed_kwh += daily_self_consumed
         self._accumulated_export_kwh += daily_grid_export
 
-        # Store today's rate for averaging
+        # Store today's rate for averaging; also record whether snapshot had meaningful data
+        # (used by _check_rollover to detect trivial snapshots that should be retried)
         self._rate_history.append({
             "date": today_str,
             "import_rate": self._import_rate,
             "export_rate": self._export_rate,
+            "energy_kwh": round(daily_solar + daily_grid_import, 4),
         })
 
     def _check_rollover(self, today: date, month_key: str, year_key: str = None) -> None:
@@ -838,9 +845,13 @@ def _check_rollover(self, today: date, month_key: str, year_key: str = None) ->
             k.endswith(yesterday_str) and not k.startswith("ev_daily_sun")
             for k in self._daily_accumulators
         )
-        already_snapshotted = any(
-            r.get("date") == yesterday_str for r in self._rate_history
+        # A prior snapshot is only considered valid if it captured non-zero energy.
+        # If the system restarted around midnight and snapshotted before real data
+        # accumulated, allow a re-snapshot when meaningful data is now present. (#225)
+        prior_snapshot = next(
+            (r for r in self._rate_history if r.get("date") == yesterday_str), None
         )
+        already_snapshotted = prior_snapshot is not None and prior_snapshot.get("energy_kwh", 1.0) > 0
         if has_yesterday_data and not already_snapshotted:
             self._snapshot_daily_costs(yesterday)
 

coordinator/ev_control.py

@@ -152,8 +152,11 @@ async def _execute_ev_control(
                     watts_per_amp = power.ev_power / max(1, ev._current_setpoint)
 
                     peak_limit_w = self._get_peak_limit_w()
-                    headroom_w = peak_limit_w - power.grid_import_power
-                    target = headroom_w / max(1, watts_per_amp)
+                    # Subtract EV's own draw: grid_import includes EV, so
+                    # non_ev_grid = home + other loads (what the grid would
+                    # import if the EV were off)
+                    non_ev_grid = power.grid_import_power - power.ev_power
+                    target = (peak_limit_w - non_ev_grid) / max(1, watts_per_amp)
 
                     # Clamp: configurable min current, max from charger config
                     target = min(ev.max_current, max(min_amps, round(target)))

coordinator/ev_taper_detector.py

@@ -567,11 +567,21 @@ async def async_seed_from_history(
             _LOGGER.debug("Could not read EV history from recorder: %s", e)
             return None
 
+        # Detect sensor unit to apply correct scale factor.
+        # Some EV power sensors report in W (e.g. KEBA actual_power),
+        # others report in kW. Thresholds below assume kW, so W values need /1000.
+        entity = hass.states.get(ev_power_entity)
+        is_watts = (
+            entity is not None
+            and entity.attributes.get("unit_of_measurement", "").strip().lower() == "w"
+        )
+        scale = 0.001 if is_watts else 1.0  # convert W → kW if needed
+
         # Parse into (timestamp, power_kw) pairs
         readings = []
         for state in states:
             try:
-                val = float(state.state)
+                val = float(state.state) * scale
                 readings.append((state.last_changed, val))
             except (ValueError, TypeError):
                 continue

coordinator/flow_calculator.py

@@ -172,9 +172,18 @@ def calculate_ev_budget(self, power: PowerReadings,
         1. Grid export (power going unused to grid)
         2. Redirectable battery charge (slow battery charging to free power for EV)
         3. Active battery discharge (handled separately in coordinator for battery-assist mode)
+
+        Semantics: the returned value is the SETPOINT sent to the charger (total watts
+        the charger is allowed to draw), NOT an increment on top of current consumption.
+        When the EV is already charging at ev_power W and grid_export_power W is going to
+        the grid unused, the new setpoint is ev_power + grid_export_power — this tells the
+        charger to absorb all the surplus. The charger adjusts its draw from ev_power to
+        the new setpoint, naturally consuming the exported surplus without importing. (#229)
         """
         # Source 1: Grid export — always redirectable
         if power.ev_power > 0:
+            # EV already charging: new setpoint = current draw + unused grid export
+            # This is a SETPOINT (target total watts), not a delta to add to current draw.
             base = power.ev_power + power.grid_export_power
         else:
             base = power.grid_export_power
@@ -203,9 +212,11 @@ def _calculate_battery_redirect(self, battery_charge_w: float,
         if forecast_remaining_kwh > 0:
             # Forecast available: redirect proportional to excess forecast
             if forecast_remaining_kwh >= battery_need_kwh and battery_need_kwh > 0:
-                # Forecast covers battery — redirect proportionally
+                # Forecast covers battery — redirect proportionally.
+                # Use max(0.05, ratio) to always redirect at least 5% at the
+                # exact boundary (forecast == battery_need gives ratio=0 without this).
                 ratio = min(1.0, 1.0 - battery_need_kwh / forecast_remaining_kwh)
-                return battery_charge_w * ratio
+                return battery_charge_w * max(0.05, ratio)
             elif battery_need_kwh <= 0.5:
                 # Battery nearly full — redirect all
                 return battery_charge_w
@@ -221,19 +232,24 @@ def _calculate_battery_redirect(self, battery_charge_w: float,
     def calculate_available_power(self, power: PowerReadings) -> float:
         """Calculate power available for EV charging.
 
-        Available = Solar - Home - Battery Charge
-        Grid export is already a consequence of this surplus, not additive.
+        Available = Solar - Home - Battery Charge + Battery Discharge (when assisting)
+        Grid export is already a consequence of surplus, not additive.
+        Battery discharge is included when the battery is actively discharging
+        to assist loads — that power is available for the EV as well.
         """
         excess = (
             power.solar_power
             - power.home_consumption_power
             - power.battery_charge_power
         )
+        available = max(0, excess)
 
-        # Don't report more than solar production
-        available = min(power.solar_power, max(0, excess))
+        # Include battery discharge as available when battery is actively discharging
+        if power.battery_discharge_power > 0:
+            available += power.battery_discharge_power
 
-        return round(available, 0)
+        # Cap at solar + battery discharge (can't report more than combined sources)
+        return round(min(available, power.solar_power + power.battery_discharge_power), 0)
 
     def calculate_charging_current(
         self, available_power: float, voltage: float = 230, phases: int = 3

coordinator/forecast_tracker.py

@@ -62,6 +62,38 @@ def __init__(self):
         self._today_date: Optional[str] = None
         self._correction_factor: float = 1.0
         self._weather_today: str = "unknown"
+        self._hass: Any = None
+
+    def set_hass(self, hass: Any) -> None:
+        """Set Home Assistant instance for reading sun.sun entity."""
+        self._hass = hass
+
+    def _get_sun_hours(self) -> tuple[float, float]:
+        """Get sunrise/sunset hours from sun.sun entity, fallback to defaults.
+
+        Returns (sunrise_hour, sunset_hour) as fractional hours (e.g. 6.5 = 6:30).
+        Falls back to module-level constants when sun.sun is unavailable (polar regions
+        or HA startup). This prevents hardcoded 6/20 from being wrong in polar areas.
+        """
+        try:
+            if self._hass is not None:
+                sun = self._hass.states.get("sun.sun")
+                if sun and sun.attributes:
+                    rise_str = sun.attributes.get("next_rising", "")
+                    sett_str = sun.attributes.get("next_setting", "")
+                    if rise_str and sett_str:
+                        rise = datetime.fromisoformat(rise_str.replace("Z", "+00:00"))
+                        sett = datetime.fromisoformat(sett_str.replace("Z", "+00:00"))
+                        # Convert to local time hours
+                        local_rise = rise.astimezone(dt_util.DEFAULT_TIME_ZONE)
+                        local_sett = sett.astimezone(dt_util.DEFAULT_TIME_ZONE)
+                        return (
+                            local_rise.hour + local_rise.minute / 60.0,
+                            local_sett.hour + local_sett.minute / 60.0,
+                        )
+        except Exception:
+            pass
+        return float(SUNRISE_HOUR), float(SUNSET_HOUR)
 
     def update(
         self,
@@ -288,23 +320,46 @@ def _solar_curve_fraction(solar_hours: float) -> float:
         # = (1 - cos(π·t/T)) / 2
         return (1 - math.cos(math.pi * solar_hours / DAYLIGHT_HOURS)) / 2
 
+    @staticmethod
+    def _solar_curve_fraction_dynamic(solar_hours: float, daylight_hours: float) -> float:
+        """Expected fraction of daily solar using the actual day length.
+
+        Same sine-curve model as _solar_curve_fraction but uses the real
+        daylight_hours derived from sun.sun, so the curve is correct in
+        polar regions where day length differs significantly from 14h.
+        """
+        import math
+        if solar_hours <= 0:
+            return 0.0
+        if solar_hours >= daylight_hours:
+            return 1.0
+        return (1 - math.cos(math.pi * solar_hours / daylight_hours)) / 2
+
     def _calculate_dampening_factor(self) -> float:
-        """Calculate the dampening factor from live data + history."""
+        """Calculate the dampening factor from live data + history.
+
+        Uses actual sunrise/sunset from sun.sun entity so the daylight window
+        is correct in polar regions. Falls back to hardcoded defaults when
+        sun.sun is unavailable (HA startup, polar night).
+        """
         now = dt_util.now()
         hour = now.hour + now.minute / 60.0
 
+        sunrise_hour, sunset_hour = self._get_sun_hours()
+        daylight_hours = max(1.0, sunset_hour - sunrise_hour)
+
         # Outside daylight hours: use historical correction only
-        if hour < SUNRISE_HOUR or hour > SUNSET_HOUR + 1:
+        if hour < sunrise_hour or hour > sunset_hour + 1:
             return self._correction_factor
 
         if self._today_forecast < MIN_FORECAST_KWH:
             return self._correction_factor
 
         # How many solar hours have elapsed
-        solar_hours = max(0, hour - SUNRISE_HOUR)
+        solar_hours = max(0, hour - sunrise_hour)
 
         # Expected fraction using sine-curve model (not linear)
-        expected_fraction = self._solar_curve_fraction(solar_hours)
+        expected_fraction = self._solar_curve_fraction_dynamic(solar_hours, daylight_hours)
         expected_so_far = self._today_forecast * expected_fraction
 
         # Too early to judge — not enough expected production yet