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/config.yaml

@@ -163,6 +163,37 @@ options:
   peak_forecast_entity: ""
   peak_cap_w: 3500
 
+  # --- SAFETY-24: the energy backstop under SAFETY-07's forced discharge -----
+  # The peak guard can COMMAND a discharge to hold a billed quarter under
+  # peak_cap_w. Until this card it was bounded from below by nothing but the
+  # pack's own BMS cut-out - a real floor, but the PACK's protection rather than
+  # the OPERATOR's. On the 2026-08-20 replay the guard asks for 878 Wh in a day.
+  #
+  # peak_soc_floor is the percent below which that discharge is not sized. When
+  # it binds the guard reports FLOOR-LIMITED, keeps charging blocked (a 0 W
+  # floor), and the add-on raises ONE notification saying the quarter will be
+  # exceeded - failing to shave is never silent, because the euro figure is the
+  # whole point of the guard.
+  #
+  # ⚠️ THIS IS NOT maintenance_soc_floor AND MUST NOT BE MERGED WITH IT.
+  # maintenance_soc_floor is the DRAIN TARGET of the monthly recalibration: the
+  # depth the cycle deliberately goes to, once a month, on purpose. This is the
+  # depth a money-saving discharge may never reach on any day. The right values
+  # differ, and sharing one key would couple two features that want to move
+  # independently.
+  #
+  # ⚠️ 20 IS DERIVED, NOT PICKED. The reference pack is 13.8 kWh usable and the
+  # worst modelled guard day is 878 Wh, i.e. 6.4 % - so 10 points above the
+  # pack's own cut-out leaves the guard ~1.6 of its worst observed days of room
+  # and still never reaches the BMS.
+  peak_soc_floor: 20
+  # The pack's OWN cut-out percent - what the BMS enforces whatever is set
+  # above. Register 0x0560 reads 10 on the reference GW5000S-BP, consistent with
+  # DoD 90. It is here so validate.py can REFUSE a peak_soc_floor at or below
+  # it: such a floor can never bind, the BMS wins, and the status page would
+  # report an energy backstop that does not exist.
+  bms_soc_floor: 10
+
   # ⚠️ THE OLD PRICE PATH, AND IT IS NOT DEAD YET. These two entities are the
   # add-on delegating the whole price question to Home Assistant: main.py reads
   # both and derives ONE BOOLEAN, `cheap = now <= avg`, which is consumed by
@@ -311,6 +342,12 @@ schema:
 
   peak_forecast_entity: str?
   peak_cap_w: int(500,15000)
+  # SAFETY-24. No "off" value: a guard that can command a discharge does not get
+  # a supported way to have no energy bound at all. The ranges OVERLAP on
+  # purpose - the schema cannot express "above bms_soc_floor", so validate.py
+  # rule 8 is what refuses the pair, with a message naming both numbers.
+  peak_soc_floor: int(5,60)
+  bms_soc_floor: int(0,50)
   price_now_entity: str?
   price_avg_entity: str?