SAFETY-24: an energy floor under the peak guard's forced discharge

SAFETY-07 can command a discharge to hold a billed quarter down, and
nothing below it consulted the state of charge. On the 2026-08-20 replay
it asks for 878 Wh in a day. Relying on the BMS is not absurd - it is a
real floor and it works - but it is the pack's protection rather than the
operator's, and a month of aggressive quarters leaves the battery
repeatedly at that cut-out with no EMS-side record of why. The first
symptom is a pack never available when wanted, which is indistinguishable
from the SoC drift MAINT-01 exists to correct.

decide() now takes soc and soc_floor, both required and neither
defaulted, and discharge_permitted() is the one place the question is
answered. Above the floor nothing changes. At or below it the guard files
a 0 W floor instead of a sized one - one-directional, so charging stays
blocked and no discharge is capped - and reports floor_limited with the
reason it bound. It is not a trip: every stop in 11.2's table still
outranks the claim, and the floor is never negative, so 9.1's asymmetry
survives as a property of the object (0 negative floors over 1296 swept
combinations, SoC included).

The SoC is graded only after `wanted > 0` is established, so it is never
evaluated where it governs nothing. An unreadable SoC is floor-limited,
not a full battery - a full battery is exactly the value that would
disarm the floor, and this project shipped that defaulting once already.

Failing to shave is not silent: one notification per episode
(goodwe_peak_soc_floor), distinct from the saturation alarm because the
two ask for opposite operator actions, plus its own status row and an
action-log line.

Verified by replay. The 2026-08-20 capture is driven against a modelled
pack sized from the day's own measured appetite, so it genuinely
exhausts: without the floor it reaches the BMS cut-out and holds there
for 1227 guard cycles; with it the pack stops at 20.0 % and never touches
the BMS. The energy withheld equals the energy between the two floors to
within one cycle at the rail. The honest half is reported too - the worst
quarter goes 4338 W -> 5030 W, because a floor-limited guard shaves less
on purpose.

Two new options, mirrored once in peakguard.PEAK_OPTION_DEFAULTS
(TARIFF-02's pattern), imported by validate.py and main.py rather than
typed as literals and pinned to config.yaml by a check that reads the
file - so CFG-03 still tracks three places. validate.py rule 8 refuses
peak_soc_floor <= bms_soc_floor at startup, in CFG-01/MAINT-04's manner.
maintenance_soc_floor is deliberately not reused and not renamed: it is a
drain target, not a spend limit, and the rename is recorded as a decision
to revisit if a third floor appears.

Eleven mutations of the shipped source were run against the checks; all
eleven go red and there are no survivors.

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

goodwe_controller/app/main.py

@@ -199,14 +199,25 @@ class Controller:
         # the action log and the notification fire on transitions rather than
         # once per cycle for a quarter of an hour.
         #
-        # ⚠️ NO CONFIG OF ITS OWN, for the reason the clamp watchdog gives ~90
-        # lines up and TARIFF-01 repeats: the ceiling is `peak_cap_w`, already
-        # shipped and already validated, and every other term is read off
-        # something the arbiter or the averager already owns. CFG-03 still
-        # tracks three places, not four.
+        # ⚠️ THE CEILING HAS NO CONFIG OF ITS OWN, for the reason the clamp
+        # watchdog gives ~90 lines up and TARIFF-01 repeats: it is `peak_cap_w`,
+        # already shipped and already validated, and every other term of the
+        # projection is read off something the arbiter or the averager already
+        # owns.
+        #
+        # ⚠️ SAFETY-24'S FLOOR DOES HAVE ONE, AND IT COULD NOT NOT HAVE. How far
+        # down the guard may spend the pack for money is a number only the site
+        # knows, and refusing one set below the pack's own cut-out means knowing
+        # that cut-out too. So this card adds exactly two keys and reads their
+        # defaults from `peakguard.PEAK_OPTION_DEFAULTS` - TARIFF-02's mirror
+        # pattern - rather than typing literals here. THAT is what keeps CFG-03
+        # at three places: the divergence validate.py's rule 6 documents
+        # (`maintenance_charge_w` 2000 there, 2500 here) is exactly what a
+        # literal in this file would repeat.
         self.peak_guard = None
         self._peak_engaged = False
         self._peak_saturated = False
+        self._peak_floor_limited = False
         self._maint_shape_suspended = False
         # Set by amain() once the transport is built, so the status page can show
         # what only the transport knows (homewizard_local's unchanged_s). Stays
@@ -494,6 +505,17 @@ class Controller:
             cap_w=float(self.o.get("peak_cap_w", 3500)),
             reading=self.peak.peak(now),
             achievable_w=min(max_w, abs(float(dev_top))),
+            # ⚠️ SAFETY-24. `self.soc` IS THE MEASURED READING AND MAY BE None,
+            # and it is handed over as None rather than defaulted here. An early
+            # draft of the stage-5 loop read SoC as `| float(100)` and thereby
+            # invented a full battery (NOTES.md 4.4b); a full battery is
+            # precisely the value that disarms this floor. decide() treats None
+            # as floor-limited, which is the direction that costs a shave rather
+            # than the pack.
+            soc=self.soc,
+            soc_floor=float(self.o.get(
+                "peak_soc_floor",
+                peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])),
             max_hold_s=self.p1.averager.max_hold_s,
             frozen=looks_frozen(getattr(self.p1_source, "unchanged_s", None),
                                 standing, max_w, self.freeze_wd.cfg),
@@ -682,6 +704,16 @@ class Controller:
         # method assigned above and nothing since has touched.
         await self.check_peak_saturated()
 
+        # --- SAFETY-24's alarm, and it is the OTHER way the money gets spent --
+        # Same boundary argument as check_peak_saturated(): it grades
+        # `self.peak_guard`, which cycle() assigned above and nothing since has
+        # touched. Kept as its own method rather than folded into that one,
+        # because the two states are mutually exclusive and want OPPOSITE
+        # operator actions - saturation says "shed load, the inverter is already
+        # flat out"; this says "the pack is at its floor and this quarter is not
+        # being shaved at all".
+        await self.check_peak_floor_limited()
+
         # --- TARIFF-01, and it is LAST on purpose -----------------------------
         # Banking a quarter is bookkeeping about a moment that has already
         # happened; a slow SD card must never sit between the meter and the
@@ -826,6 +858,70 @@ class Controller:
                 f"thing that changes the bill."),
         })
 
+    async def check_peak_floor_limited(self) -> None:
+        """SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving.
+
+        ⚠️ FAILING TO SHAVE MUST NOT BE SILENT, AND THAT IS THE WHOLE POINT.
+        The guard exists for one euro figure - the capaciteitstarief bills the
+        month's single worst quarter - so a cycle in which it CHOSE not to shave
+        is a cycle in which money is being spent on purpose. Under-shaving
+        quietly would leave the operator with a bill and a status page full of
+        green.
+
+        The distinction from check_peak_saturated() is the operator's action,
+        which is why these are two notifications and not one:
+
+          saturated      the guard asked for everything the inverter has and it
+                         was not enough. SHED LOAD - the controller has already
+                         done all it can, and it is still discharging.
+          floor-limited  the guard asked for NOTHING, because the pack is at or
+                         under the EMS floor, or its SoC could not be read.
+                         Nothing is being discharged for this quarter at all.
+
+        They cannot both be true: peakguard.decide()'s floor-limited branch
+        returns before the `achievable_w` clamp that sets `saturated`.
+
+        Edge-triggered, and de-asserting arms it again - FreezeWatchdog's shape,
+        for FreezeWatchdog's reason: one notification per episode, not one per
+        cycle for a quarter of an hour.
+        """
+        g = self.peak_guard
+        limited = bool(g is not None and g.floor_limited)
+        was, self._peak_floor_limited = self._peak_floor_limited, limited
+        if not limited or was:
+            return
+        # No prefix: `reason` already opens with PEAK GUARD FLOOR-LIMITED, and
+        # a second copy is the kind of stutter that makes a 40-line action log
+        # read like boilerplate. The saturated path needs its prefix because its
+        # reason carries the word in the middle of a sentence, not at the front.
+        self.log_event(g.reason)
+        _LOG.error(
+            "SAFETY-24 - %s. The controller is STILL RUNNING and charging is "
+            "still blocked, but it is not discharging to hold this quarter, so "
+            "the quarter will set or raise the month's billed capacity peak. "
+            "Shed load, or lower peak_soc_floor if this pack can afford it.",
+            g.reason)
+        # A fixed notification_id, and a DIFFERENT one from every other alarm
+        # here - check_meter_frozen() gives the reasoning. A battery at its
+        # energy floor is not a saturated inverter and is not a frozen meter,
+        # and an operator who has to dismiss three identical-looking cards
+        # learns to dismiss the one that mattered.
+        await self.hass.call("persistent_notification", "create", {
+            "notification_id": "goodwe_peak_soc_floor",
+            "title": "GoodWe: the capacity-peak guard has run out of battery",
+            "message": (
+                f"{g.reason}.\n\nTHIS QUARTER WILL GO OVER THE "
+                f"{g.ceiling_w:.0f} W ceiling and will set or raise the "
+                f"month's billed capaciteitstarief peak, because the peak guard "
+                f"is not allowed to discharge any further: {g.soc_floor_reason}."
+                f" This is not a controller fault - it is the EMS-side energy "
+                f"floor (peak_soc_floor) doing what it is set to do, and it sits "
+                f"deliberately above the pack's own BMS cut-out. Charging stays "
+                f"blocked. Shedding load is the only thing that changes the bill "
+                f"now; if this pack can afford a deeper discharge, lower "
+                f"peak_soc_floor."),
+        })
+
     async def check_meter_frozen(self) -> None:
         """SAFETY-18. Alarm on a meter that answers forever without changing.
 
@@ -1116,6 +1212,13 @@ class Controller:
             elif _pg.saturated:
                 out.append({"ok": False, "warn": False,
                             "text": "PEAK GUARD SATURATED - " + _pg.reason})
+            elif _pg.floor_limited:
+                # SAFETY-24. NOT ok, like saturation: in both states the money
+                # is going to be spent and a human is the only actuator left. A
+                # separate row from saturation because the two ask for opposite
+                # things - see check_peak_floor_limited().
+                out.append({"ok": False, "warn": False,
+                            "text": _pg.explain()})
             elif _pg.blind:
                 out.append({"ok": False, "warn": True, "text": _pg.explain()})
             else: