Fix/timed export restore mode safety (#27)

* Guard against GRID_EXPORT as timed-export restore mode (#26)

If the inverter is already in GRID_EXPORT when a new timed export starts
(e.g. due to a stale duplicate scheduler instance), saving GRID_EXPORT as
the restore mode would leave the inverter exporting indefinitely with no
SOC floor protection after the timed window ends. Extend the existing
TOU→SELF_POWERED redirect to also cover GRID_EXPORT→SELF_POWERED.

* Add high_soc_export_set flag to prevent mid-period safety export oscillation (#27)

The mid-period high-SOC safety export had no one-shot guard — unlike the
clipping check (gated by clipping_export_set), it evaluated every tick.
Once an export ended at the SOC floor, solar would recharge past the 50%
trigger threshold and it would fire again after the 15-minute cooldown,
causing repeated export/restore cycles within the same period.

Add high_soc_export_set (same pattern as clipping_export_set) to
DayStateEntry. Once a mid-period high-SOC export fires, the flag prevents
re-triggering for the rest of that period. Auto-extension in
maybe_restore_timed_grid_export handles continuous strong solar during the
active window.

* Set 10% gap for mid-period high-SOC safety export (trigger 55%, floor 45%) (#27)

Raise trigger threshold from 50% to 55% and use DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT
(45%) as the SOC floor directly, replacing the headroom-target-based floor that
was collapsing the gap to zero for Green days (max(45, 50) = 50%).

Result: export only fires when battery is above 55%, stops at 45%, giving a
10% band of guaranteed discharge per export window.

Author: deadl0ck

config/settings.py

@@ -219,8 +219,9 @@
 MORNING_HIGH_SOC_PROTECTION_ENABLED = True
 # SOC threshold for the mid-period high-SOC safety export check (combined with solar).
 # When SOC >= this AND solar >= MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW, export is triggered.
-# 50% (12 kWh) matches HEADROOM_TARGET_KWH: above this the battery cannot absorb a full-day Green surplus without clipping.
-MORNING_HIGH_SOC_THRESHOLD_PERCENT = 50.0
+# 55% gives a 10% gap above the 45% SOC floor (DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT),
+# ensuring each export creates meaningful headroom before stopping.
+MORNING_HIGH_SOC_THRESHOLD_PERCENT = 55.0
 # Solar generation threshold (kW) for mid-period high-SOC safety export.
 # Only triggers when live solar is this strong and SOC >= MORNING_HIGH_SOC_THRESHOLD_PERCENT.
 MID_PERIOD_SAFETY_SOLAR_TRIGGER_KW = round(SOLAR_PV_KW * 0.39, 2)  # ~39% of array capacity

logic/afternoon.py

@@ -124,6 +124,7 @@ async def handle_afternoon_period(ctx: PeriodHandlerContext) -> bool:
     # --- Mid-period high-SOC safety export check ---
     if (
         s["start_set"]
+        and not s["high_soc_export_set"]
         and not timed_export_override["active"]
         and now_utc >= period_start
         and (period_end_utc is None or now_utc < period_end_utc)
@@ -168,17 +169,14 @@ async def handle_afternoon_period(ctx: PeriodHandlerContext) -> bool:
                     mode=SIGEN_MODES["GRID_EXPORT"], reason=mid_period_reason,
                     outcome="mid-period high-SOC safety export triggered",
                 )
-                mid_period_headroom_target_soc = max(
-                    DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
-                    100.0 - mid_period_headroom_target_kwh / BATTERY_KWH * 100.0,
-                )
                 mid_period_override_started = await start_timed_grid_export(
                     period=PERIOD, reason=mid_period_reason,
                     duration_minutes=mid_period_duration_minutes,
                     now_utc=now_utc, battery_soc=mid_period_soc, is_clipping_export=True,
-                    export_soc_floor=mid_period_headroom_target_soc,
+                    export_soc_floor=DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
                 )
                 if mid_period_override_started:
+                    s["high_soc_export_set"] = True
                     return True
 
     # --- Pre-period export check ---

logic/evening.py

@@ -198,6 +198,7 @@ async def handle_evening_period(ctx: PeriodHandlerContext) -> bool:
     # --- Mid-period high-SOC safety export check ---
     if (
         s["start_set"]
+        and not s["high_soc_export_set"]
         and not timed_export_override["active"]
         and now_utc >= period_start
         and (period_end_utc is None or now_utc < period_end_utc)
@@ -247,6 +248,7 @@ async def handle_evening_period(ctx: PeriodHandlerContext) -> bool:
                     export_soc_floor=DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
                 )
                 if mid_period_override_started:
+                    s["high_soc_export_set"] = True
                     return True
 
     # --- Pre-period export check ---

logic/morning.py

@@ -124,6 +124,7 @@ async def handle_morning_period(ctx: PeriodHandlerContext) -> bool:
     # --- Mid-period high-SOC safety export check ---
     if (
         s["start_set"]
+        and not s["high_soc_export_set"]
         and not timed_export_override["active"]
         and now_utc >= period_start
         and (period_end_utc is None or now_utc < period_end_utc)
@@ -168,17 +169,14 @@ async def handle_morning_period(ctx: PeriodHandlerContext) -> bool:
                     mode=SIGEN_MODES["GRID_EXPORT"], reason=mid_period_reason,
                     outcome="mid-period high-SOC safety export triggered",
                 )
-                mid_period_headroom_target_soc = max(
-                    DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
-                    100.0 - mid_period_headroom_target_kwh / BATTERY_KWH * 100.0,
-                )
                 mid_period_override_started = await start_timed_grid_export(
                     period=PERIOD, reason=mid_period_reason,
                     duration_minutes=mid_period_duration_minutes,
                     now_utc=now_utc, battery_soc=mid_period_soc, is_clipping_export=True,
-                    export_soc_floor=mid_period_headroom_target_soc,
+                    export_soc_floor=DAYTIME_TIMED_EXPORT_MIN_SOC_PERCENT,
                 )
                 if mid_period_override_started:
+                    s["high_soc_export_set"] = True
                     return True
 
     # --- Pre-period export check ---

logic/scheduler_operations.py

@@ -104,13 +104,13 @@ async def refresh_daily_data(
 
     if reset_day_state:
         state.day_state = {
-            p: {"pre_set": False, "start_set": False, "clipping_export_set": False}
+            p: {"pre_set": False, "start_set": False, "clipping_export_set": False, "high_soc_export_set": False}
             for p in daytime_periods
         }
     else:
         for period in daytime_periods:
             state.day_state.setdefault(
-                period, {"pre_set": False, "start_set": False, "clipping_export_set": False}
+                period, {"pre_set": False, "start_set": False, "clipping_export_set": False, "high_soc_export_set": False}
             )
 
     state.last_forecast_refresh_utc = datetime.now(timezone.utc)

logic/scheduler_state.py

@@ -20,11 +20,15 @@ class DayStateEntry(TypedDict):
         pre_set: True once the pre-period headroom/export check has been applied.
         start_set: True once the period-start mode decision has been applied.
         clipping_export_set: True once a live clipping-risk export has been started.
+        high_soc_export_set: True once a mid-period high-SOC safety export has fired.
+            Prevents repeated exports within the same period after solar recharges
+            the battery above the trigger threshold.
     """
 
     pre_set: bool
     start_set: bool
     clipping_export_set: bool
+    high_soc_export_set: bool
 
 
 class NightState(TypedDict):

logic/timed_export.py

@@ -301,19 +301,22 @@ async def start_timed_grid_export(
                     current_mode_raw,
                 )
                 return False
-            # TOU is a night-only charging mode and should never be the restore
-            # target after a timed export:
-            #   - During cheap-rate: restoring to TOU would let the inverter
-            #     recharge from the grid, immediately undoing any headroom just
-            #     created by the export.
-            #   - After cheap-rate: TOU left over from an overnight schedule
-            #     would leave the inverter in the wrong mode for the rest of
-            #     the day.
-            # In both cases, restore to SELF_POWERED instead.
-            if restore_mode == SIGEN_MODES["TOU"]:
+            # Neither TOU nor GRID_EXPORT should ever be the restore target:
+            #   - TOU is a night-only charging mode; restoring to it during or
+            #     after cheap-rate would either recharge the battery from the
+            #     grid (undoing headroom) or leave the inverter in the wrong
+            #     daytime mode.
+            #   - GRID_EXPORT as a restore target means the inverter was already
+            #     in export mode when this export started (e.g. a stale state or
+            #     duplicate scheduler instance). Restoring to GRID_EXPORT would
+            #     leave the inverter exporting indefinitely with no SOC floor
+            #     protection once the timed window ends.
+            # In both cases, fall back to SELF_POWERED.
+            if restore_mode in (SIGEN_MODES["TOU"], SIGEN_MODES["GRID_EXPORT"]):
                 logger.info(
-                    "[TIMED EXPORT] Current mode is TOU — "
-                    "will restore to SELF_POWERED instead to preserve headroom."
+                    "[TIMED EXPORT] Current mode is %s — "
+                    "will restore to SELF_POWERED instead.",
+                    restore_label,
                 )
                 restore_mode = SIGEN_MODES["SELF_POWERED"]
             restore_label = str(mode_names.get(restore_mode, restore_mode))

tests/test_period_handler_ticks.py

@@ -40,12 +40,14 @@ def _make_period_state(
     pre_set: bool = False,
     start_set: bool = False,
     clipping_export_set: bool = False,
+    high_soc_export_set: bool = False,
 ) -> DayStateEntry:
     """Return a fresh DayStateEntry with the given flag values."""
     return DayStateEntry(
         pre_set=pre_set,
         start_set=start_set,
         clipping_export_set=clipping_export_set,
+        high_soc_export_set=high_soc_export_set,
     )
 
 
@@ -167,6 +169,11 @@ def test_clipping_export_set_false_initially(self):
         entry = _make_period_state()
         assert entry["clipping_export_set"] is False
 
+    def test_high_soc_export_set_false_initially(self):
+        """A freshly created DayStateEntry has high_soc_export_set=False."""
+        entry = _make_period_state()
+        assert entry["high_soc_export_set"] is False
+
 
 # ---------------------------------------------------------------------------
 # Pre-period tests