MAINT-20 part 1 review: restore three lost lines, rewrap ragged comments

Comment, docstring and DECISIONS only (same-code script OK; python -OO
bytecode now identical for all six files).
- peakguard.charge_room_w: one-line docstring + SAFETY-125 pointer (cut whole).
- peakguard.shaping_suspended: keep 'the one place this conjunction is
  written; do not inline it'.
- price_forecast module note: an hour with no price and no yesterday is left
  out, never filled (test_price.py 14d cites the module note for it).
- Refill comment blocks the cut left ragged; DECISIONS pointers on one line.
- FCST-04 note: _yesterday_of(), not _previous_day(); FCST-03 note: the 49
  stronger cases are why the rule is a real change.

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

.gitea/ci/run-tests.sh

@@ -0,0 +1,125 @@
+#!/bin/sh
+# CI-15: run the add-on's test_*.py files, in parallel, inside the CI container.
+# Called by the step "the add-on's own tests" of .gitea/workflows/checks.yml as
+#   sh -eu /w/goodwe-addon/.gitea/ci/run-tests.sh
+# and runnable the same way from a clone (see TESTS_DIR below).
+#
+# WHY: the serial loop ran past the runner's 60-minute limit (SAFETY-125: 85 files,
+# 3 557 s of test time, run 1430 cut off at file 84). The host has 12 cores.
+#
+# SHAPE
+#   1. A parallel batch: JOBS files at a time (xargs -P), longest first.
+#   2. THEN the serial group, one at a time, after the batch has finished, so
+#      each runs on a machine with nothing else of ours on it.
+#   Every file writes to its own $RUN_DIR/<file>.out (there is no shared output
+#   file) and prints its result as ONE block under a lock, so the PASS/FAIL
+#   lines and the `CI: ` / tail -40 text of two files never interleave.
+#
+# THE FILE LIST IS STILL DERIVED FROM THE TREE (see checks.yml). The two typed
+# lists below only SORT or SET ASIDE files that exist; a new test_*.py that is
+# in neither list is run, in the parallel batch. A name that no longer exists
+# in a list is harmless. Nothing can make a file silently not run.
+#
+# SERIAL GROUP: files whose assertions depend on the wall clock, so CPU load
+# from siblings could flip them. Name and reason, one each:
+#   test_loop.py    drives the real run_control() against a real wall-clock
+#                   floor (~93 s on purpose); worst inter-cycle gap 3.0 s
+#                   against a 4.5 s bound (TEST-30, CI-06).
+#   test_freeze.py  part 3 runs the real sim/hwsim.py over a transport with a
+#                   16 s window, a 10 s hold and an alarm measured at 11.0 s:
+#                   one poll of margin, and "failed 1 run in 3" on the rig
+#                   transport (TEST-30, CI-06).
+#   test_safety87.py  builds a controller (CH65) whose meter reading is stamped
+#                   on the REAL clock, and section 8 asks its status page,
+#                   which says "Not ready - Meter: no reading for N seconds,
+#                   limit 30 seconds" once N passes 30. Measured by CI-15: N is
+#                   about half the file's run time (N = 45 s in a 94 s run, 48 s
+#                   in a 103 s run). The file takes ~25 s idle and took 45 s in
+#                   CI's first parallel run, so N was ~20 s of the 30. It FAILED
+#                   alone under --cpus 0.15 (94 s) and in a loaded parallel run
+#                   (103 s). No test file is changed here, so it runs alone.
+# Add a file here only with a measured reason, and say it in this list.
+SERIAL="test_loop.py test_freeze.py test_safety87.py"
+#
+# LONGEST FIRST (SAFETY-125's CI run, job 2580; then a local parallel run, seconds:
+# modes_p4 758, safety126 634 (SAFETY-126, local, one core), safety125 508 on hotfix-0.19.2 only, modes_p3 364, safety119 328,
+# price_run_fixes 184, safety90 160, safety103 134, safety94 114, peakguard 113,
+# opt20 102, safety97 101, safety81 100). With JOBS workers pulling from one
+# queue, starting the longest files first keeps the tail short: the batch takes
+# about as long as the longest file. A sort order, not a selection.
+HEAVY="test_modes_p4.py test_safety126.py test_safety125.py test_modes_p3.py test_safety119.py test_price_run_fixes.py test_safety90.py test_safety103.py test_safety94.py test_peakguard.py test_opt20.py test_safety97.py test_safety81.py"
+#
+JOBS=${CI_JOBS:-6}
+cd "${TESTS_DIR:-/w/goodwe-addon/goodwe_controller}"
+
+# one FILE: run it, keep its output in its own file, print its block whole.
+if [ "${1:-}" = "--one" ]; then
+  f=$2
+  o="$RUN_DIR/$f.out"
+  start=$(date +%s)
+  if python3 "$f" > "$o" 2>&1; then rc=0; else rc=1; fi
+  secs=$(( $(date +%s) - start ))
+  {
+    if [ $rc = 0 ]; then
+      echo "PASS  $f  (${secs}s)"
+      grep "^CI: " "$o" || true
+    else
+      echo "FAIL  $f  (${secs}s)"
+      tail -40 "$o"
+    fi
+  } > "$RUN_DIR/$f.blk"
+  echo $rc > "$RUN_DIR/$f.rc"
+  flock "$RUN_DIR/print.lock" cat "$RUN_DIR/$f.blk"
+  exit 0
+fi
+
+set -- test_*.py
+if [ "$1" = "test_*.py" ]; then
+  echo "NO test_*.py FOUND - the mount is empty or the layout moved. NOTHING has been checked."
+  exit 1
+fi
+echo "$# test file(s) to run: $JOBS at a time, then the serial group"
+
+RUN_DIR=$(mktemp -d /tmp/ci-tests.XXXXXX)
+export RUN_DIR
+: > "$RUN_DIR/par"
+: > "$RUN_DIR/ser"
+for f in $HEAVY; do
+  case " $SERIAL " in *" $f "*) continue ;; esac
+  if [ -f "$f" ]; then echo "$f" >> "$RUN_DIR/par"; fi
+done
+for f in "$@"; do
+  case " $SERIAL $HEAVY " in *" $f "*) continue ;; esac
+  echo "$f" >> "$RUN_DIR/par"
+done
+for f in $SERIAL; do
+  if [ -f "$f" ]; then echo "$f" >> "$RUN_DIR/ser"; fi
+done
+echo "parallel: $(wc -l < "$RUN_DIR/par") file(s); serial: $(wc -l < "$RUN_DIR/ser") file(s)"
+
+t0=$(date +%s)
+rc=0
+# `exit 0` in the worker: a failing FILE is recorded in its .rc, so a non-zero
+# from xargs itself means the machinery broke, which is a failure too.
+xargs -n 1 -P "$JOBS" sh -eu "$0" --one < "$RUN_DIR/par" || rc=1
+echo "parallel batch done in $(( $(date +%s) - t0 ))s; serial group next"
+while read -r f; do
+  sh -eu "$0" --one "$f" || rc=1
+done < "$RUN_DIR/ser"
+
+# Every file that was meant to run has a verdict, and every verdict is PASS. A
+# worker that died before writing its .rc leaves no file, which counts as a fail.
+ran=0
+bad=0
+for f in "$@"; do
+  ran=$((ran + 1))
+  if [ ! -f "$RUN_DIR/$f.rc" ]; then
+    echo "FAIL  $f  (no result: the run never reported)"
+    bad=$((bad + 1))
+  elif [ "$(cat "$RUN_DIR/$f.rc")" != 0 ]; then
+    bad=$((bad + 1))
+  fi
+done
+echo "$ran file(s), $bad failed, $(( $(date +%s) - t0 ))s wall"
+if [ "$bad" = 0 ] && [ "$rc" = 0 ]; then exit 0; fi
+exit 1

.gitea/workflows/checks.yml

@@ -209,7 +209,7 @@ on:
 jobs:
   unit:
     runs-on: [self-hosted, goodwe-rig]
-    timeout-minutes: 70   # ~4 to run; the rest is queueing for the single slot
+    timeout-minutes: 40   # ~15 to run (CI-15: 6 files at a time; the serial suite was ~60 and hit the runner cap); the rest is margin for a busy host
     env:
       # ⚠️ UNDER /home/homelab, NOT $GITHUB_WORKSPACE (ENV-01, and re-measured
       # during CI-01). act's workspace is `/root/.cache/act/<id>/hostexecutor`, a
@@ -534,6 +534,19 @@ jobs:
       # shorter timeout - a 60 s limit was tried during CI-01 and reported
       # exactly the false hang the docstring predicts.
       #
+      # ⚠️ CI-15: THE FILES RUN SIX AT A TIME, NOT ONE AFTER ANOTHER. The serial
+      # loop summed 3 557 s on SAFETY-125's run (job 2580) and ran past the
+      # runner's 60-minute cap. The loop now lives in .gitea/ci/run-tests.sh (it
+      # comes from the merged tree, like the Dockerfile), so the same script runs
+      # locally and here. It runs the longest files first, then the files whose
+      # assertions depend on the wall clock - test_loop.py and test_freeze.py
+      # (TEST-30 / CI-06) and test_safety87.py (CI-15) - ALONE, after the
+      # parallel batch, so no sibling can steal their CPU. The reasons are in
+      # the script. Its output stays one
+      # PASS/FAIL block per file, in a file per file (never one shared /tmp/out).
+      # A file that is not in the script's two typed lists still runs, in the
+      # parallel batch: the list is a sort order, not a selection.
+      #
       # test_freeze.py part 3 runs against the real `sim/hwsim.py` from the
       # checkout above; GOODWE_REQUIRE_HWSIM=1 makes it fail rather than use its
       # stub (CI-12). Lines a test prints with a `CI: ` prefix are echoed on PASS.
@@ -552,28 +565,7 @@ jobs:
       - name: the add-on's own tests
         run: |
           set -eu
-          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -e GOODWE_REQUIRE_HWSIM=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
-            cd /w/goodwe-addon/goodwe_controller
-            set -- test_*.py
-            if [ "$1" = "test_*.py" ]; then
-              echo "NO test_*.py FOUND - the mount is empty or the layout moved. NOTHING has been checked."
-              exit 1
-            fi
-            echo "$# test file(s) to run"
-            rc=0
-            for f in "$@"; do
-              start=$(date +%s)
-              if python3 "$f" > /tmp/out 2>&1; then
-                echo "PASS  $f  ($(( $(date +%s) - start ))s)"
-                grep "^CI: " /tmp/out || true
-              else
-                echo "FAIL  $f  ($(( $(date +%s) - start ))s)"
-                tail -40 /tmp/out
-                rc=1
-              fi
-            done
-            exit $rc
-          '
+          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -e GOODWE_REQUIRE_HWSIM=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu /w/goodwe-addon/.gitea/ci/run-tests.sh
 
       - name: clean up
         if: always()

README.md

@@ -107,7 +107,7 @@ on real hardware, and the comments in `control.py` say which.
 
 ### CI and the infra pin
 
-CI (`.gitea/workflows/checks.yml`) runs every `test_*.py`, with `admin/goodwe` checked out next to this repo at the commit in `.gitea/infra-pin`, so `test_freeze.py` grades against the real `sim/hwsim.py`. If that checkout fails, the job fails. The local stub is used only in local runs, and it prints `STUB USED` when it is.
+CI (`.gitea/workflows/checks.yml`) runs every `test_*.py` (six at a time, the wall-clock ones alone afterwards: `.gitea/ci/run-tests.sh`), with `admin/goodwe` checked out next to this repo at the commit in `.gitea/infra-pin`, so `test_freeze.py` grades against the real `sim/hwsim.py`. If that checkout fails, the job fails. The local stub is used only in local runs, and it prints `STUB USED` when it is.
 The pin tracks `admin/goodwe` **release/1.0**, not master. Two non-required checks go red when release/1.0 has moved past the pin: `infra-pin / fresh` here, on any add-on PR or push to release/1.0, and `addon-pin / fresh` in `admin/goodwe`, on every push to its release/1.0. Nothing re-runs `addon-pin` after a bump, so it stays red on that admin/goodwe commit; `infra-pin / fresh` green on the bump is the all-clear.
 **Bump the pin** whenever either is red. Set `.gitea/infra-pin` to the new release/1.0 SHA (`git ls-remote <gitea>/admin/goodwe.git refs/heads/release/1.0`) in a PR, and let `checks / unit` grade the tests against it. CI reads `admin/goodwe` with the Actions secret `INFRA_READ_TOKEN`.
 

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,65 @@
 # Changelog
 
+## 0.19.2
+
+### Not in a release yet
+
+- The night grid charge no longer raises "Battery stopped limiting the peak" when the 15-minute period stays on the aim. A steadily rising load now alarms a little later, and with a peak margin of 0 a period can end up to 10 W over the limit without this alarm ([[SAFETY-126]]).
+- A night grid charge for *Leftover solar* no longer stops at 03:00 when the solar forecast sensors went quiet in the evening. The evening's figure is used until 06:00, and a charge that has started goes on to its level ([[OPT-34]]).
+
+**A patch bump: two fixes, one for charging from the grid under the peak limit and one for the night charge of Leftover solar, and no option changes.**
+No option was added, removed or renamed, and no default changed (86 options).
+**Existing installs need no option change:** options that start 0.19.1 also
+start 0.19.2. The change below applies with one inverter or two.
+
+**Charging from the grid now stays under this month's peak.** A late meter reading near a period's end could push a grid charge to full power. That could take the 15-minute period over the peak. Now the charge is cut back, with one inverter too. The peak guard line no longer says "under" when the period would go over the limit.
+
+Contents of this release, in merge order since 0.19.1 (`2932f3a`):
+
+| | |
+|---|---|
+| `SAFETY-125` | A grid charge (a battery mode's cheap run, price trading or the maintenance charge, with one inverter or two) counts the seconds since a late meter reading at that reading, so it is cut back near the end of a 15-minute period instead of going back to full power. With one inverter the maintenance charge is now held to the room left in the period, as with two, so the peak guard no longer steps in and gives power at the period's end. Over the limit at the current rate, the peak guard row and the month peak line say so, and that the grid charge is cut back ([[SAFETY-125]]). |
+
+### Known issues
+
+The list under `## 0.19.0` below still applies. The SAFETY-99 line there now
+covers the guard's discharge only, not a grid charge.
+
+### If you are crossing from a version older than 0.10.0
+
+`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the
+withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the
+bare options (`jq '.data.options'`) first.
+
+## 0.19.1
+
+**A patch bump: two fixes for battery modes, and no option changes.**
+No option was added, removed or renamed, and no default changed (86 options).
+**Existing installs need no option change:** options that start 0.19.0 also
+start 0.19.1. The changes below apply with one inverter or two.
+
+**Battery modes now see a day/night or fixed tariff.** With battery modes on, a day/night or fixed tariff and no price service, the batteries never got the prices: "Cheap hours" never charged from the grid at the cheap rate, and the Batteries screen said "No prices". They get them now, with no price service and no internet call added.
+
+**A solar forecast now counts for the price gap.** With battery modes on and a solar forecast read, a price mode needs a gap of at least *Battery cycle cost*, not 1.5 times that. Without a forecast it is still 1.5 times. A day/night gap of 0.08 now works at a cycle cost of 0.07 or less.
+
+Contents of this release, in merge order since 0.19.0 (`793a676`):
+
+| | |
+|---|---|
+| `TARIFF-24` | With battery modes on, the add-on now also resolves the tariff when no price service and no price trading are set, so a day/night or fixed tariff gives the batteries their price runs ([[TARIFF-24]]). With battery modes on and a solar forecast read, the price gap a mode needs is *Battery cycle cost* (widened only for a real-time feed), not 1.5 times that; Home and the Batteries screen use the same rule ([[AUDIT-02]] F1). |
+
+### Known issues
+
+The list under `## 0.19.0` below still applies.
+
+### If you are crossing from a version older than 0.10.0
+
+`## 0.10.0` below can refuse an old config: `slew_w` above its limit, and the
+withdrawn `price_provider` ids `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. Read it before you update. Run `tools/predeploy_check.py` with the
+bare options (`jq '.data.options'`) first.
+
 ## 0.19.0
 
 **A minor bump: price trading behaves differently, plus a fix for a false warning, the Home price chart in 15-minute bars, more Dutch text and EMS-port wording, and no option changes.**

goodwe_controller/DECISIONS/FCST-03-the-hours-not-yet-published.md

@@ -0,0 +1,109 @@
+# FCST-03 - the hours the feed has not published, and what may not rest on them
+
+**Status: SHIPPED.** Tests: `test_price_forecast.py`, `test_price_history.py`.
+Written down by MAINT-20 from the long module comment of `app/price_forecast.py`.
+Follows specs.md 8.3: "Day-ahead prices arrive once daily. Until they do, unknown
+hours use yesterday's profile and are flagged `provisional: true`, and no
+irreversible action may be taken on a provisional price. Real-time / imbalance
+products are treated as high-volatility: arbitrage thresholds widen." This module
+owns the first two; the widening is in price.py (`Uncertainty`, `widen_factor`,
+`required_spread`), spent by `static_tariff.TariffPlan.arbitrage()` as one more
+refusal on its existing ladder. Persistence of yesterday: [[FCST-04]].
+
+## The flag is never passed through
+
+A carried point and a published one are the same three floats and a bool.
+`PricePoint(..., provisional=y.provisional)` copies yesterday's `False` onto
+today's guess: stale data presented as current (SAFETY-18's defect one layer up).
+So:
+
+- `_carried()` has no parameter for the flag; `provisional=True` is a literal in
+  one place.
+- A published point is passed through by identity (`filled.points[i] is
+  fetched.points[j]`, checked by the test), never copied.
+- `_audit()` re-derives the expected flag for every emitted point from the hours
+  the feed published and raises on a mismatch. It never corrects (a module that
+  quietly fixes its own provenance cannot be trusted).
+- test_price_forecast.py walks this file's AST and fails if any `PricePoint(...)`
+  passes anything but a literal for `provisional`.
+
+"Published" does not mean "firm": 9.3 carries `provisional` per point because a
+real-time product's current-interval print is published AND provisional, so the
+audit's rule for a published point is "whatever the feed said". No shipped
+plugin emits one since [[TARIFF-07]]; the rule is a property of the format and
+weakening it would let the first imbalance feed arrive mispriced and flagged firm.
+
+## The audit is a provenance check, not a completeness check (FCST-05)
+
+Rules: a PUBLISHED point must be one of `published[u]` by identity and be
+emitted once, with the feed's own flag; a CARRIED point's hour must not be in
+`published` at all, flag exactly True, and no second point in that hour. This
+replaced FCST-03's "at most one point per hour" count, which cannot express a
+quarter-hourly feed. FCST-04 claimed two strengthenings; both were false: a
+differential over every published mask on 3 hours crossed with every output of
+length 0-3 found zero divergence either way (OLD raised/NEW accepted 0, OLD
+accepted/NEW raised 0). The one real change is the intended relaxation (several
+distinct published points per hour).
+
+The audit does not check completeness: fed the decimation defect (four points in
+an hour, only the last emitted), two of four, or an empty output, it accepts.
+What stops decimation is the point COUNT and IDENTITY checks in the two test
+files. It cannot be made complete from its arguments: `published` is over the
+whole unwindowed read while the fill emits `[since, until)`, so a published point
+outside the window is legitimately absent. FCST-05 built "every published point
+is emitted" (+162 B) and it took the 1 h, 12 h and 48 h horizon checks red on a
+healthy feed (a real change: the differential scored it 49 cases stronger),
+so the rule as stated is wrong, and
+asserting a completeness the instrument lacks is MUTATION.md habit 16's defect.
+
+## The fill keys on the wall clock
+
+For each whole hour of the horizon the feed has not published, take yesterday's
+value for the SAME BRUSSELS WALL-CLOCK HOUR, not `t - 86400 s`: a 23-hour day has
+no 02:00 and a 25-hour day has two, so a fixed 24 h shifts every carried hour
+across a transition. On a 25-hour day both 02:00s are filled from yesterday's
+single 02:00 (both guesses, both flagged); if yesterday was a 25-hour day, the
+first of its two 02:00 points is used. An hour with no published price and no
+yesterday value is left out, not filled with a neighbour, mean or zero: 11.4
+applies (`Absence`, then the static profile). If nothing can be produced the
+result is `no_data`, not an empty series.
+
+A sub-hourly feed is not decimated: the hourly walk decides which hours need
+filling, never what a published hour may hold. Belgian day-ahead settles per
+quarter since 2025-10-01 (96 points a day), so every published point in the
+window is passed through and a carried one is added only for an hour with no
+published coverage. `{_utc_hour(p.start): p for p in r.points}` reads ordinary
+and keeps the last point of each hour; FCST-04's first caller shipped it, the
+series came out 15 points long, the spread fell from 0.143 to 0.014 EUR/kWh and
+the cheapest "hour" became a `:45` point. `_published_by_hour()` holds a tuple
+per hour for that reason.
+
+The window is whole hours at both ends: `since` floored (the current hour is
+still tradeable) and `until` floored too; with `until` compared raw a 48 h horizon
+asked at 08:17 emitted 49 hours. `yesterday` has no default (a missing yesterday
+and a useless one must not look alike). The fill is idempotent and re-runnable
+(5.4 late publication, 14-16 h CET): published hours win, and the series is
+rebuilt, not patched. TARIFF-11 log line: carried HOURS, total hours and
+published POINTS are three different quantities (a quarter-hourly feed made it
+read "33 of 141 hours" for 48 h).
+
+## AC2: the irreversible-action gate
+
+An irreversible action is a value, `Irreversible`, carrying the hours it commits.
+`price_permits()` looks at exactly those hours and answers with a `Gate` carrying
+evidence on the permitting arm and a reason on the blocking one (the `_Outcome`
+shape). It blocks when the read observed nothing (11.4), an hour has no price, or
+an hour is provisional, and names the hour. The maintenance drain's window is
+derived from `maintenance.DRAIN_TIMEOUT_MIN` / `CHARGE_TIMEOUT_MIN`, so the gate
+and the phase machine cannot drift. `_window_hours()` is separate so the gate and
+its caller agree on "the hours it commits".
+
+What is NOT gated matters more: the maintenance cycle is a calendar obligation
+(12.2: a cycle that silently never fires looks like one not yet due), and a site
+with `price_provider: off` (the default) has no series. Routing every start
+through a gate that blocks on `no_data` would stop the monthly cycle on every
+default install. So `begin_phase()` is the entry point for a start JUSTIFIED BY A
+PRICE; main.py's calendar path is untouched, and OPT-04 / MAINT-05 own which a
+site runs. Reversible actions (self-consumption modulation, the loop) are not
+gated: 6 says absent machinery must not disable the loop. Read this before wiring
+`begin_phase()` in.

goodwe_controller/DECISIONS/FCST-04-the-day-that-is-carried.md

@@ -188,3 +188,64 @@ still raises; so does the same published point emitted twice; and a carried
 point sharing an hour with a real print now raises too, which the count never
 looked at. Each of those three is driven by its own mutation in
 `test_price_forecast.py`.
+
+## 5. Store details (moved here from `app/price_history.py` by MAINT-20)
+
+**Why a file, and which one.** FCST-03 shipped the fill with no caller, so no
+series ever contained a carried point. Without a yesterday that survives a
+restart, the mornings after an operator touched something spend the whole
+window on the truncated series. The cache is `/data/price_history.json`, not
+`/data/state.json`: `Store.set()` rewrites the whole of state.json on each
+write, and the refresh runs every `TARIFF_REFRESH_S` (1800 s), so 48 extra
+rewrites a day would go through the file whose corruption reads as "no
+maintenance ever ran". Separate file, separate blast radius. The directory is
+not created (`tariff.PeakStore`'s rule): `/data` is always mounted, so a
+`makedirs` could only succeed where the durable volume is missing and build a
+cache on the ephemeral layer. "Cannot persist" is one question asked after the
+attempt: see [[FCST-06]]; `self._days` never holds a point the file does not.
+
+**Brussels date, not UTC.** 23:30 UTC in July is already tomorrow in Belgium.
+`_yesterday_of()` subtracts on the local `date`, not the instant: the old
+`brussels(stamp) - timedelta(days=1)` took 24 absolute hours and, at
+2026-03-30T00:30+02:00, returned 2026-03-28 (a two-day-old profile flagged as
+yesterday's). Rows are keyed by instant, not local hour, so the two 02:00s of
+the 25-hour October day both survive and `fill_from_yesterday()`'s own rule is
+the only collapsing rule. The merge key is the validated instant; the old
+string key merged by spelling and sorted the `+01:00` 02:00 before the `+02:00`.
+`KEEP_DAYS` is a sort-order cap, not a horizon: nothing is deleted by arithmetic
+against the clock (a jumped clock, WITNESS-03, would otherwise delete everything
+on the one morning the fill is for), and the two dates `yesterday()` can be
+asked for are pinned on top of the cap, which can only retain.
+
+**One validator (FCST-05, MEDIUM).** The read path was defensive about every
+field and the write path trusted `q["start"]` to be hashable and sortable. An
+int, null, dict or list `start` raised `TypeError` out of `carry()` on the day
+being written; `run_tariff_refresh` caught it, so the add-on stayed up and every
+refresh failed for good (the plan retires after `TARIFF_MAX_AGE_S`, arbitrage and
+the cheap window go off, and `_remember()` raised before `_save()`, so no
+self-heal). `_point_of()` is now the one standard for both paths and returns
+`None` rather than raising.
+
+**A broken cache is a short horizon, never a controller that will not start**
+(6: absent machinery must not disable the loop). `PriceHistory(...)` and `.words`
+are unguarded in `Controller.__init__`. Shipped defects, all fixed:
+
+- `_load()` caught `json.JSONDecodeError` and `OSError` only; one non-UTF-8 byte
+  raised `UnicodeDecodeError` (a `ValueError`, not an `OSError`) and the add-on
+  did not start (FCST-05, HIGH). The handler names the `ValueError` family. The
+  schema version is compared with its type (`1.0 == 1` in Python).
+- `{"days": {"2026-01-14": "oops"}}` loaded as healthy and raised
+  `AttributeError` out of `words`, `yesterday()` and `resolve_tariff()`.
+  `_usable_days()` drops such records, and counts (not drops) malformed rows
+  inside a kept record so the store stops reporting health it lacks.
+- `words` printed `f"{d} ({_n_points(rec)} h)"`: points under the hour's name
+  (`'2026-01-13 (96 h)'` for a 24-hour quarter-hourly day, FCST-05 LOW). Both
+  numbers are printed now; only rows that are points are counted. `words` must
+  never raise, `_held()` is total.
+- A failed merge is undone from a deep copy (a one-level copy shares the day
+  records the merge rebinds).
+
+`NO_HISTORY` is a name, not `None`, so `history=` can be required: `None`
+meaning "skip the fill" is how a caller silently gets the truncated horizon.
+`carry()` records first, then fills, so the filled series exists only as a
+return value that the store never sees again (rule 1).

goodwe_controller/DECISIONS/OPT-27-last-fresh-forecast-for-the-night.md

@@ -0,0 +1,46 @@
+# OPT-27 - the night plan keeps the last fresh forecast
+
+**Status: done on `release/1.0`, not released.** Tests: `test_opt27.py`.
+
+**The defect.** A today sensor is stale after 3 h (`FRESH_S`) or when it is from
+before local midnight. Forecast.Solar stops updating in the evening, so at night
+every Forecast.Solar site had no forecast: a price mode's night cheap run needed
+1.5x the cycle cost (TARIFF-24 round 2) and Leftover solar planned nothing.
+Separately, one missed poll (`unavailable`) dropped the forecast at once.
+
+**Where: `solarfc`, not the plan.** The last fresh reading of each sensor is
+kept in `solarfc.Hold` and `read_sum()` uses it when a sensor has none. A hold
+at the plan (`_wx_track`/`weather_held`) can only keep the 1.5x gap off. The
+day plan, Leftover solar's levels, Home and the Forecast tab all read
+`Controller.solar_fc`, so one kept forecast makes control and every screen agree
+(UX-53) with no second rule to keep in step. `weather_held()` is unchanged: it
+still keeps a run under way when a read is lost.
+
+**The rule** (`Hold.stand_in()`). A kept reading is for one day. It covers a
+sensor that is missing or stale, never one with a bad value or unit, and:
+- for up to `FRESH_S` when the sensor is missing: a short outage, any time of day;
+- from the end of the bell (20:00 local, `BELL_TO_H`) until local midnight, if the
+  reading is at most `KEPT_MAX_AGE_S` (12 h) old when used; after midnight the
+  tomorrow figure is today's until the bell starts (06:00), up to 15 h old
+  (OPT-34 changed this from midnight + 3 h);
+- the day it is for: a today figure only on that day, a tomorrow figure as
+  tomorrow until midnight and, if the today sensors are still stale, as today's
+  until 06:00 (all sensors of the sum are needed, as for any sum);
+- until the next fresh reading, which replaces it at once.
+
+So a figure is never used for another day and never older than 12 hours (`KEPT_MAX_AGE_S`), except the morning case above: a 17:05 reading serves until 06:00 (12 h 55 min), a 09:05 reading only until 21:05. Until OPT-34 the figure ended at 03:00, and a charge under way lost its level there; OPT-34 closes that limit.
+Daytime is as before: a sensor that stopped is stale after 3 h, and no forecast
+all day is still no forecast (the night run still needs 1.5x).
+
+**Where it is stored.** The controller's store, key `solar_fc_hold`, so an
+evening restart keeps it. It is written when a reading's figure changes or
+every 15 min (`SAVE_EVERY_S`), not on every poll. A damaged entry is dropped.
+
+**The screens.** `Forecast.kept` is true when a reading older than `FRESH_S` is
+in use; the forecast line then reads "Solar forecast read 17:05, kept for
+tonight." (`home_words.solar.kept`, EN and NL). The event log says
+"read, kept from 17:05".
+
+**Not changed.** Control with modes off: it does not use the forecast. The
+screens still show the line, so it says "kept", not "used for the plan". A
+forecast that stays fresh. The hold does not look at the weather, only at the clock and the day.

goodwe_controller/DECISIONS/OPT-34-the-night-charge-keeps-its-level.md

@@ -0,0 +1,62 @@
+# OPT-34 - the night charge keeps its level when the kept forecast ends
+
+**Status: done on `release/1.0`, not released.** Tests: `test_opt34.py`.
+
+**The defect** (OPT-27 rig test, F-1). The kept evening figure ended at midnight + 3 h.
+With the sensors silent from 17:05 the Leftover solar battery's level went with
+it in the middle of the charge: A ended at 49.8 % against 79.9 % with a fresh
+figure. Whether Forecast.Solar refreshes after midnight on a live site is not
+known, so the add-on does not depend on it.
+
+**The rule.**
+1. *A charge under way keeps its level* (`Controller._latch_charge()`). While
+   there is a forecast (fresh or kept), each battery that charges from the grid in the
+   cheap run takes its planned level into a latch (store key `night_charge_latch`).
+   With no forecast, `plan_targets()` gives the latched level, and the wide
+   no-forecast gap does not refuse the next slice of the run (`weather_held()`,
+   as TARIFF-24 does for the run under way). While a
+   forecast is there the latch follows the plan, up or down as a fresh figure moves
+   it. It lasts through every cheap run on and one price slot after the last, and it
+   ends at once when its end time passes, whatever the run state (it is also
+   ignored at a restart if it has ended). A battery that is switched off or
+   changed to another mode leaves it.
+   *Night bound (manager's call, 2026-10-31):* a run carries the latch on only if
+   it starts by the bell start (06:00 local) after the latch began; that run
+   finishes, plus one slot. Chosen over a fixed 12 h because the night tariff
+   (22:00-07:00) needs the 06:00-07:00 slice and 12 h from a late start would
+   reach into the day. With dynamic prices a chain of cheap slots cannot carry a
+   night's level into the next day.
+2. *The evening's tomorrow figure is today's until the bell starts*, 06:00 local
+   (`BELL_FROM_H`, `solarfc._bell_start()`), not until midnight + 3 h.
+   Nothing has been produced yet, so it is still the whole day.
+3. *Up to 15 h old for that case only* (`KEPT_MORNING_MAX_AGE_S`): a 17:05
+   reading is 12 h 55 min old at 06:00. It must have been at most 12 h old at
+   midnight, so a 09:05 reading, unusable since 21:05, does not come back for five
+   minutes after midnight. Same-day figures and the daytime rule keep 12 h and 3 h.
+4. A fresh figure replaces the kept one at once, as before.
+
+**Step 1 alone is enough for the owner's shape, steps 2-3 are still needed.**
+With the window put back to midnight + 3 h the owner's night still ends as a
+fresh figure ends it (A 86.9 %, B 95.0 %), because the charge had started at
+22:00. But a charge that has not started by 03:00 (the price dips at 04:00, or
+the headroom is taken) has no level to latch: A ends at 38 % against 78 %. The
+plan, the screens and a restart also need the figure itself.
+
+**Screens.** "Solar forecast read {at}, kept for tonight." is still true until
+06:00 and unchanged. After the figure ends, with a charge still going on: "No
+solar forecast now. The charge under way goes on to its planned level." /
+"Nu geen zonneprognose. De lopende lading gaat door tot het geplande niveau."
+(`home_words.solar.latched`, only while a cheap run is on and a latched battery is below its level).
+
+**Not used.** A figure over 15 h old; a morning figure at night (12 h); a figure
+for another day; a bad value or unit; and no latch for a charge that has not
+started, for a battery that is not charging, or after the cheap runs have ended
+(plus one slot).
+
+**Not changed.** Charge sizing, the peak guard, Cheap hours, modes off, arbitrage.
+A fresh figure that LOWERS the level during a charge still lowers it, as before.
+
+**Mutants** (all red in `test_opt34.py`): no latch; window back to midnight + 3 h;
+15 h without a limit; no "usable at midnight" rule; the latch without the narrow
+gap, without its save, or not kept through the next run; the window 6 h after
+midnight instead of 06:00 local (DST); 15 h cut to 12 h; the new screen line off or shown without a cheap run; no expiry check; no pruning of a changed mode; no night bound; a left-the-plan battery keeping its level.

goodwe_controller/DECISIONS/SAFETY-07-peak-guard.md

@@ -0,0 +1,166 @@
+# SAFETY-07 - the quarter-peak projection guard (with SAFETY-24 and CFG-03)
+
+**Status: SHIPPED.** Tests: `test_peakguard.py`. Written down by MAINT-20 from
+the long module comment in `app/peakguard.py`, so the module can stay short.
+Later changes have their own notes: [[SAFETY-25]], [[SAFETY-32]], [[SAFETY-45]],
+[[SAFETY-79]], [[SAFETY-81]], [[SAFETY-87]], [[SAFETY-90]], [[SAFETY-125]],
+[[SAFETY-126]].
+
+## The hazard
+
+The capacity tariff bills the month's single worst 15-minute average offtake,
+with no averaging and no forgiveness. specs.md:583 records one 4998 W quarter
+that moved a monthly peak from 4832 W to 5013 W and billed the whole month at
+it. SAFETY-18 alarms on a frozen meter (`meter_freeze_s`, 300 s) but a frozen
+meter can rail the command in 75 s (freeze.py's table, `max_w: 5000`, meter at
+3000 W or more), against a 900 s quarter. The guard is the cap on that. It
+reads freeze.py's `looks_frozen()`; it is not a second freeze detector.
+
+## The mechanism: one `lo` limit at `P_PEAK`
+
+specs.md 10.1 row 2 wants pre-emptive discharge near the limit and a hard clamp
+on charging above it; 9.1 says discharge and export are never capped by the
+peak guard. A lower bound on the setpoint is the only shape that does both: a
+floor cannot stop the loop discharging harder (so 9.1 holds by structure), it
+clamps charging when above the standing charge, and it forces discharge when
+above zero.
+
+- `P_PEAK` (50) is above `P_LOOP` (10) and below `P_MAINTENANCE` (60) and
+  `P_SAFETY` (100). arbiter clause 2 applies only limits at or above the
+  winning set's priority, so a P_SAFETY 0 W stop is not pulled off zero.
+- A limit does not out-vote another limit: clause 2 takes the most restrictive
+  with no priority between limits. The floor (`lo >= 0`) and the maintenance
+  charge-only shaping (`hi <= 0`) therefore resolve to `lo > hi`, a
+  contradiction, which the arbiter answers with 0 W (battery parked in the
+  worst quarter). The rule for two crossing limits is suppression, not
+  priority: main.py drops the shaping while the guard is engaged
+  (`shaping_suspended()`). The floor is clamped to `achievable_w` to close the
+  only other crossing pair (the P_SAFETY rating bounds).
+- Arbitrage arrives as a SET below `P_PEAK`, so clause 2 binds it with this
+  floor without any edit here (9.1: peak shaving outranks arbitrage).
+
+## The floor is derived
+
+With `projected = (acc + held * remaining) / 900`, the watts that must come off
+the meter are `excess_w = 900 * (projected - ceiling) / remaining`, and the
+floor is `floor_w = batt_w + excess_w`.
+
+1. The claim is filed while the floor is positive, not while the excess is.
+   `excess` falls to zero as soon as the battery is already removing it, and a
+   guard that released there handed the actuator back and re-engaged next
+   cycle. The first cut did that on 2026-08-20's billed quarter: 17
+   engage/release cycles in 900 s, and the quarter still ended 49 W over.
+   Thresholding `batt_w + excess` (the offtake with the battery at zero, less
+   the level the quarter can afford) decays continuously, so there is no
+   hysteresis constant. 10.2: an EMS that oscillates is worse than none.
+2. The gain 900/remaining is 1.0 at the start of a quarter and grows. The guard
+   is gentlest when its evidence is weakest. No minimum-evidence threshold was
+   added: it would delay the guard on a sustained rail from second zero.
+3. `batt_w` is the measured battery power, not the command. The bill is what
+   flowed, and a floor built on the command winds up to the rail when the
+   inverter cannot follow; one built on the measurement stops rising when
+   delivery does.
+
+## The ceiling
+
+`ceiling_w = max(peak_cap_w, the month's banked peak)`. Once a month's peak
+stands at 5013 W, holding later quarters to 3500 W buys nothing. Only an
+`OBSERVED` reading may raise it; `NO_RECORD` and `NOT_OBSERVED` leave it at
+`peak_cap_w`, so a peak store that cannot be read makes the guard stricter,
+never looser. That is also why the guard does not use `headroom_w()`: a peak
+read as 0 W returns full headroom, which is a guard that is not there.
+SAFETY-79 aims `peak_margin_w` under the ceiling; the ceiling stays the real
+limit for reports and the bill.
+
+## Blindness comes first
+
+The projection is graded only if the quantity under it was measured. Three
+ways it was not, checked before grading:
+
+- No open block: a fresh averager answers an all-zero `Projection`, which sits
+  under every ceiling. That is "no quarter", not "the quarter is fine".
+- Coverage: a meter gap longer than `max_hold_s` leaves seconds the averager
+  does not accumulate (holding a dead meter's value forward is how a fabricated
+  peak gets onto a permanent record), so the projection reads low. The
+  threshold is `max_hold_s`, not a new number. SAFETY-90 fills gaps once
+  readings return.
+- Frozen: samples keep arriving, coverage is perfect and the projection is a
+  confident zero while the real meter is at the rail.
+
+The blind action is `floor_w = 0.0`: no importing while the billed quantity
+cannot be observed. It is one-directional (forbidding charge only lowers
+offtake), so a false blindness costs a charge and never pack energy.
+
+## Why it trips where SAFETY-18 only notifies
+
+The healthy-day false-engagement rate is zero (2026-08-23, 95 quarters;
+test_peakguard.py re-measures it from the committed capture). The action is
+level-triggered and unlatched: it is re-derived each cycle and releases when the
+projection drops, so a false engagement costs one cycle, not a parked battery.
+It is a limit, so every safety stop outranks it. It is the only guard whose
+trigger is the billed quantity itself.
+
+## Saturation is reported, not alarmed as a bug
+
+10.3 treats an out-of-range setpoint as a bug (SAFETY-03). A peak floor above
+the inverter rating is not: it is a 5900 W house on a 5000 W inverter (2026-08-20
+15:45). The floor is clamped to `achievable_w`, the decision carries
+`saturated`, and main.py raises one notification.
+
+## SAFETY-24: the energy backstop the guard shipped without
+
+The graded branch can force discharge (878 Wh in a day on the 2026-08-20 replay)
+and nothing below it consulted the state of charge; the BMS was the only
+backstop, which protects the pack and not the operator. `decide()` now takes
+`soc` and `soc_floor` and `discharge_permitted()` answers.
+
+1. Not a trip. When it binds, the guard stops asking for more discharge and
+   commands nothing; every stop in 11.2 still outranks it.
+2. The action is `floor_w = 0.0` (forbids charging, forbids nothing else). A
+   `lo` limit cannot cap discharge, and a negative floor would destroy that.
+   The loop is not bounded: self-consumption may still drain the pack past the
+   floor. [[SAFETY-25]] measured it (2026-08-20, 19:00-22:00 UTC, 830 W mean:
+   the pack ends at the BMS floor, 10.0 %, whatever `peak_soc_floor` is) and the
+   owner decided on 2026-09-02 that the BMS stays the only backstop for
+   demand-driven discharge, a loop-side reserve being deferred to ALLOC-01.
+3. Graded only after `wanted > 0`, where a forced discharge is asked for.
+4. An unreadable SoC is not a full battery. `soc=None` and `soc_floor=None` are
+   floor-limited. Both arguments are required keyword-only, no default (TEST-14).
+5. Failing to shave is not silent: `floor_limited=True` and one notification.
+   It excludes `saturated`, since it asks for nothing.
+
+The action log says "the peak reserve", not "the SoC floor": `peak_soc_floor`
+(“Peak reserve”) bounds this guard only, and the wider words would contradict
+a loop that is draining the pack at that moment.
+
+## CFG-03: two options, mirrored once
+
+- `peak_soc_floor` is the EMS floor, not `maintenance_soc_floor` (the monthly
+  recalibration's drain target); sharing a key would couple features whose
+  right values differ. Default 20: the reference pack is 300 Ah at 51.2 V,
+  DoD 90, 13.8 kWh usable; the replay's 878 Wh is 6.4 %; a floor 10 points above
+  the 10 % cut-out leaves about 1.6 worst days of room.
+- `bms_soc_floor` is the pack's own cut-out (register 0x0560, 10 on the
+  reference unit). It exists so validate.py rule 8 can refuse a
+  `peak_soc_floor` at or below it.
+- Both defaults live once in `PEAK_OPTION_DEFAULTS` (TARIFF-02's pattern),
+  imported by validate.py and main.py and pinned to config.yaml by the test.
+  The module reads no option itself.
+- `maintenance_soc_floor` is the ambiguous name of the two. Decision: keep it,
+  carry the distinction in DOCS.md; revisit if a third floor appears.
+- SAFETY-07 itself added no option: `peak_cap_w` was already validated
+  `int(500,15000)`, and 14's `capacity_peak_limit_kw` stays declined (a kW key
+  beside a W key is the mismatch trap).
+
+## Per-pack floors (SAFETY-32) and phases
+
+`bms_soc_floor` became a roster key; `pack_floor_pct()` conjoins it with the
+site's EMS floor, and rule 8 names the unit it refuses. `peak_soc_floor` stayed
+one number for the site, so with cut-outs of 10 and 18 the operator sets it
+above 18; the per-pack EMS floor is the open question in [[SAFETY-32]]. The
+`min()` over measured SoC (`Controller.pack_floor_soc`) is still right for the
+site verdict; `pack_permissions()` is the per-pack answer.
+
+Nothing here reads a per-phase quantity: the sum/max/net choice is an open
+owner question, defaulted to NET inside `billed_w()`, so this file does not
+change whichever way it is answered.

goodwe_controller/DECISIONS/SAFETY-125-grid-charge-under-the-month-peak.md

@@ -0,0 +1,10 @@
+# SAFETY-125 - a grid charge under the month peak
+
+**Status: FIXED in 0.19.2 (hotfix from 0.19.1).** Tests: `test_safety125.py`.
+
+A grid charge is sized by `peakguard.charge_room_w()`, the guard's headroom
+with the seconds since a late meter reading counted at that reading (the
+projection leaves them out, SAFETY-99, the bill does not), and the guard's own
+floor is unchanged. At N=1 the maintenance charge is now sized too (owner
+2026-10-29; SAFETY-84 had left it out). Evidence (repro on 0.19.1, sweep,
+digests): the SAFETY-125 pull request.

goodwe_controller/DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md

@@ -0,0 +1,47 @@
+# SAFETY-126 - a landing error on the aim is not an overrun
+
+**Status: FIXED on release/1.0 (after 0.19.2).** Tests: `test_safety126.py`.
+
+**Cause.** A grid charge under the peak limit is sized to land the 15-minute
+period on the aim (SAFETY-125), so the period ends 0-7 W over it. In the last
+second `peakguard.excess_w()` multiplies that by 900 / remaining (3 000 at
+0.3 s left, 90 000 at 0.01 s), so `decide()` wants tens of kW
+(`wanted > 0`, peakguard.py `decide()`). With every battery under the peak
+reserve that is floor-limited at 0 W, and `check_peak_floor_limited()`
+alarmed on it at once: SAFETY-87 graded only the case where another battery
+could give. With one battery able, the guard asked it for its rating for that
+cycle and the Batteries "Why" said "The peak limit needs power". The
+add-on's own charge is not the cause: `wanted` already counts it as
+stoppable.
+
+**Rule.** Each cycle the guard wants power, `Controller._peak_landing()`
+asks `peakguard.misses_aim()`: with the batteries at 0 W from now on, does
+the period end more than `ALARM_MISS_W` (10 W) over the aim? This is
+`load_too_high()` with nothing to give, without `decide()`'s gain. If not, and
+no real miss was seen since the guard took hold, the decision is
+`within_aim`. Such a decision raises no reserve alarm (ERROR,
+notification, red row), no red "Load too high" row, no "Why" peak and
+no "Battery stopped limiting the peak" event hint. The claim, the floor and the
+commands are unchanged.
+
+**Still alarms.** House load the batteries cannot cover under the reserve:
+the period would end over the aim with the batteries at 0 W. A step load
+alarms on the same cycle as before. SAFETY-87's case and SAFETY-81's 'Load too
+high' notification are unchanged.
+
+**What the 10 W tolerance costs** (review, owner accepted 2026-10-31):
+- A steadily rising load alarms a little later, once the projected miss passes
+  10 W (3 000 -> 4 000 W over 45 min: 56 s later). With the default 50 W
+  margin the alarm still comes before the limit.
+- With `peak_margin_w` 0, a period can end up to 10 W over the limit without
+  this alarm, the tolerance 'Load too high' already accepts (SAFETY-81).
+
+`misses_aim()` takes the house as meter plus batteries, so an export nets
+off (`decide()`'s projection counts offtake only). A re-alarm while the loop's
+draw on held batteries covers the house is gone too (test_safety126.py part 2,
+modes off: 2 notifications, was 4).
+
+**Not changed.** The one-cycle floor itself: at a period's last instant the
+guard still asks an able battery for its rating, or stops a charge, for a
+landing error. That is control, outside the alarm path. Raise a card if it
+should go.

goodwe_controller/DECISIONS/SAFETY-84-charge-at-two.md

@@ -39,7 +39,8 @@ was fine.
 **Not changed.**
 - At N=1 the charge is not sized to the headroom: the guard still suspends it
   and the battery gives until the quarter is safe. The same sizing would fit
-  there; that is an owner question, not this fix.
+  there; that is an owner question, not this fix. (SAFETY-125, 0.19.2: the
+  owner said yes, and N=1 is sized the same way.)
 - Outside a cheap window (`hi = 0`, solar only) nothing is filed, at any N.
 - A HOLD (later fixed by [[SAFETY-86]]) and the "Battery is not keeping up"
   alarm (SAFETY-85) are untouched. In the identity runs that alarm's log line

goodwe_controller/DECISIONS/TARIFF-02-price-provider-plugins.md

@@ -0,0 +1,273 @@
+# TARIFF-02 - price provider plugins, and the canonical shape (with later additions)
+
+**Status: SHIPPED.** Tests: `test_price.py`, `test_price_service.py`. Written
+down by MAINT-20 from the long comments of `app/price.py` so the module can stay
+short. Related: [[TARIFF-07]], [[TARIFF-09]], [[TARIFF-10]], [[TARIFF-14]],
+[[TARIFF-15]], [[PRICE-01]].
+
+## Where it lives
+
+specs.md 2.2 puts this at `ems/ingest/prices/`; that layout is not being built.
+Owner decision 2026-08-30: everything ships in `goodwe_controller/app/`. The
+behaviour in specs.md 9.3 / 8.3 / 11.4 is unchanged and authoritative.
+
+## The canonical format (9.3)
+
+`{"prices": [{"start": "2026-01-15T00:00:00+01:00", "eur_per_kwh": 0.1834,
+"provisional": false}]}`. `start` is tz-aware at the Brussels offset for that
+instant, the price is EUR/kWh and all-in, `provisional` is per point (8.3: no
+irreversible action on a provisional price). Three fields; a fourth would change
+the wire format every store, fixture and captured body is written against.
+
+## Three rules the module is shaped by
+
+1. **Double-counting markup is refused, given a correct declaration.** A plugin
+   returns `RawPoint`s with the figure its source published and declares in
+   `capabilities().sources` which of {ENERGY, MARKUP, TAXES} it already holds.
+   `assemble()` (framework only) adds the complement from `price_markup_eur_kwh`
+   / `price_taxes_eur_kwh`. A plugin cannot reach those two numbers by any route:
+   `PluginOptions` raises `FrameworkOption`, and review of PR #16 wrote a
+   double-counting plugin three more ways (`opts._o`, `price_option()`, and the
+   public `PRICE_OPTION_DEFAULTS`), so `register()` also refuses any plugin
+   whose own code mentions a framework key (`code_leaks()`). The guarantee is
+   exactly this: the complement is added once *given a correct `sources`*. A
+   plugin declaring `{ENERGY}` for an all-in feed comes out one markup high and
+   no code can catch that. test_price.py checks that a plugin's docstring lines
+   (`SOURCES:` / `The framework ADDS:`) agree with its declaration, not that
+   either is true. `code_leaks()` strips docstrings before searching (they must
+   name the components) and fails open on missing source (a frozen build must
+   still start; CI asserts source is found for every shipped plugin).
+2. **The product type is declared, not inferred from the id.** `capabilities().
+   product` is a `PriceProduct`, rides on the series, and `volatility_regime()`
+   reads it (8.3: real-time products widen thresholds). A plugin id appears only
+   in `PROVIDERS`, `RETIRED_PROVIDERS` and its own class (AC2). No shipped plugin
+   declares `REALTIME` since [[TARIFF-07]]; `_WIDE`, `Uncertainty.REALTIME_PRODUCT`
+   and `WIDEN_FACTOR`'s 2.5 are kept, and test_price.py section 10 declares
+   REALTIME from a class outside this file to keep them live.
+3. **"No price data" is a type, not an empty list.** 11.4: no data means static
+   profile, provisional plan, no arbitrage; all-zero prices mean arbitrage is
+   merely pointless. `PriceRead.series()` refuses an empty list;
+   `PriceRead.no_data(reason)` carries `.reason` and nothing else, so
+   `min(read.points)`, `for p in read.points` and `.get("points", [])` raise
+   `Absence`; `.match(*, series, no_data)` takes both handlers as required
+   keywords. Same shape as `sim/riglock.py` after TEST-04 (read its `Absence`
+   block before changing this). Two ways past it survive and are not worth code:
+   `vars(read).get("points", [])`, and `bool(read)` being True for both
+   variants (a falsy `no_data` would turn `if read:` into a guard by accident;
+   use `.match`).
+
+## Timezone without `zoneinfo`
+
+The Alpine image has no `tzdata`, so `ZoneInfo("Europe/Brussels")` would raise
+on the client's Pi. Every instant is UTC and rendered at its fixed offset, so
+the October 02:00-03:00 hour that happens twice is two instants (`02:00+02:00`
+and `02:00+01:00`); a naive-local-hour key or a 24-slot array is wrong on both
+transition days (test_price.py counts points on both 2026 transitions). The EU
+rule: CEST from 01:00 UTC on the last Sunday of March to 01:00 UTC on the last
+Sunday of October. Review of PR #16 matched it against `zoneinfo` over 149 040
+hourly instants 2020-2036 with zero mismatches. Residual risk is political (EU
+abolishes the change): one edit in `brussels_offset()`.
+
+## The feed range (TARIFF-09)
+
+`generic_dayahead.fetch()` used to ignore `since`/`until` and request the bare
+URL, so the feed answered ONE Brussels day and 8.3 dropped everything past today
+as provisional: at 09:00 over a 48 h horizon 15 firm and 33 carried, at 23:00 1
+firm and 47 carried. `feed_days()` returns the Brussels calendar days (first,
+last, both inclusive; the API takes dates) that the half-open `[since, until)`
+touches: Brussels, never UTC (22:30 UTC in summer is already tomorrow); `until`
+exclusive, so local midnight belongs to the day before; an empty or inverted
+window collapses to one day. `api.energy-charts.info` capture:
+`scenarios/energy-charts-be-price-2026-09-09_2026-09-10-twoday.json`.
+`dated_feed_url()` refuses a base that already has a query string (appending
+would give `?bzn=BE?bzn=BE&start=...`). An operator's `price_feed_url` override
+is used verbatim and loses the range, on purpose: rewriting an operator's URL
+reorders and re-escapes it, and both providers declare a second host
+(`web-api.tp.entsoe.eu`) whose parameters are not `start`/`end`. The cost is
+logged at fetch time, naming the horizon consequence. The URL rule is shared by
+`generic_dayahead` and `custom_formula` (TARIFF-15), taking `plugin_id` as an
+argument so AC2 holds. The "range is used" promise is not mechanically enforced
+(a rule would be satisfied by an invented parameter name); test_price.py pins
+which plugins consume the range as a literal roster.
+
+## Absence and the covering window
+
+See [[TARIFF-14]] for the cover table: a point covers from its own start to the
+next point's start, never more than an hour; the last point gets the span of the
+one before; sorted at construction. `covers()` delegates to `at()` (a second copy
+of the rule is a second place to be wrong); `window_points()` grades only the
+`start` against `[since, until)` and is not a coverage query. `at()` is a linear
+scan over about 192 entries on the 30 s path; a bisect is not worth a second
+way to be wrong. A duplicated start (not reachable through `load_prices()`)
+gives the earlier entry a zero-width window.
+
+## Taxes components (TARIFF-18)
+
+`price_taxes_eur_kwh`'s default (0.06 before) is the sum of
+`FLEMISH_TAXES_COMPONENTS_EUR_KWH`, each row one line of the Eneco residential
+card for Flanders, September 2026, including 6 % VAT, in EUR/kWh;
+test_price.py section 1b re-adds them. It is per DSO: the distribution row runs
+5,28 c (Midden-Vlaanderen) to 6,70 c (West), so the all-in Flemish total runs
+about 0.117 to 0.131; a site outside Antwerpen types its own. The default sits
+near the low end on purpose: the scalar cancels in `max - min`, and its one
+decision is the 17 negative-price guard in arbitrage.py, which tests the
+absolute all-in sell price. Too high carries a genuinely negative hour above
+zero (export into paid-for disposal); too low only declines a trade that would
+have paid. `energiebijdrage` is a row of zero: from 1 August 2026 it is merged
+into the bijzondere accijns, and the zero row makes the double-count a visible
+decision. Moving a shipped default changes which configs start: TARIFF-17's rung
+in validate.py refuses `price_taxes_profile` together with a non-default scalar,
+comparing against the default (the Supervisor merges every schema key into the
+stored blob, 70 of 71 keys on the reference install, CHANGELOG 0.9.0), so a
+superseded shipped default (0.06) must still read as untouched, and the rung's
+sentence names both figures.
+
+## One in-code mirror of option defaults (CFG-03)
+
+Option defaults live in config.yaml's `options:` and `schema:` and main.py's
+`.get()` fallbacks. `PRICE_OPTION_DEFAULTS` is the single in-code mirror for the
+price options: validate.py imports it, main.py has no `o.get("price_...", X)`
+fallbacks, no dataclass carries a copy, and test_price.py section 1 reads
+config.yaml and asserts equality key for key. `static_profile` (TARIFF-03),
+`price_taxes_profile` (TARIFF-17), `price_formula` (TARIFF-15),
+`price_export_formula` (TARIFF-16) and the OPT-04 keys live there for the same
+reason, not in their own modules (a second dict would be a fourth location).
+Details:
+
+- The tables / formulas are in `FRAMEWORK_KEYS`: a plugin reading one could add
+  taxes a second time per hour, or fold an injection curve into a consumption
+  price. `BANNED_IN_PLUGIN_CODE` derives from that set.
+- `arbitrage_soc_floor` / `arbitrage_soc_ceiling` are not the maintenance keys
+  (a balancing cycle is not a trading reserve).
+- `cycle_cost_threshold_eur` is 0.10 because 10.1's name says so, not because it
+  makes anything trade: on Belgian day/night numbers the static spread is about
+  0.08, so a static-tariff site does not trade at this default (test_arbitrage.py
+  section 7). Whether 0.10, or FCST-03's 2.5 / 1.5, is right is an owner
+  decision.
+- `price_service_token` is a secret (`SECRET_OPTIONS`); `scrub()` removes secret
+  values from any text built from an error.
+
+## Widening (FCST-03)
+
+One path, a set of active uncertainty sources (real-time product 8.3, no weather
+data 11.4). The combination rule is `max`, not a product (2.5 x 1.5 would give a
+threshold nothing on a Belgian tariff clears). The factors are policy defaults,
+not derived (no arbitrage ever ran); they differ so `max`, `sum` and `product`
+are distinguishable in a check. `widen_factor()` refuses a string (a silent 1.0
+would report a widening that is not applied).
+
+## Injection price (AC4, TARIFF-16)
+
+`export_price_eur_kwh()` is a separate scalar. It was said to be so because
+nothing dynamic exists to route; that was false (Eneco publishes `0,1 x BELPEX-H
+- 1,188`, ENGIE `(B x eSpot_15) - A`). The true reason: an injection curve has
+its own coefficients and VAT treatment (injection is VAT-exempt, consumption is
+6 %). TARIFF-16 added `price_export_formula`, read by `export_formula()` through
+the same parser as the consumption leg (`parse_export_formula()` is
+`parse_price_formula()` with its option name moved). `export_price_at()` falls
+through to the scalar and ignores the index, correctly. A negative answer is a
+real answer (Eneco's formula is below zero for any index under 11,88 EUR/MWh);
+nothing floors it. Nothing under `app/` calls either reader to take a decision:
+arbitrage prices the sell side as displaced import. A malformed leg is refused at
+startup by validate.py; `taxes_profile()` and `export_formula()` still handle it
+loudly at run time. `static_tariff` is imported lazily in `taxes_profile()`
+because it imports this module at module scope.
+
+## Taxes at each point's own instant (TARIFF-17)
+
+`taxes_at()` takes a scalar or a period table (duck-typed on `price_at`, because
+price.py must not import static_tariff.py). A non-flat component matters: ORES
+bills `dag 13,27 / nacht 7,39` c, a 5,88 c gap coinciding with the cheap spot
+hours, and flattening it understates the spread. `assemble()` must evaluate it
+per point; hoisting the lookup out of the loop collapses the feature back into a
+level (test_price.py section 24 grades which hour is cheapest, since a
+spread-magnitude assertion passes on the hoisted version). On a scalar, `0.0 +
+markup` is exactly `markup` in IEEE 754, so scalar sites get identical bytes.
+The table wins over the scalar; validate.py refuses configs where both speak.
+
+## Retired providers (TARIFF-07)
+
+`RETIRED_PROVIDERS` exists so `eneco_eddy` and friends are not refused as typos:
+they were shipped, the operator chose them, and every failed fetch fell back
+silently to `static_profile`. No alias to `generic_dayahead`: they published
+retail prices (`B x spot + A`) and it reads wholesale; an alias would invent the
+site's two coefficients (behind the klantenzone login; CREG tariff-card pages
+404, VREG unreachable). Each value is the id-specific half of the refusal (the
+endpoint, what it answered on 2026-09-13, why no replacement can be built);
+validate.py owns the framing. `register()` refuses at import to register a
+retired id again, because `pid in PROVIDERS` going true silences the named
+refusal; re-shipping is a decision recorded by removing it from
+`RETIRED_PROVIDERS` in the same commit. See [[TARIFF-07]].
+
+## Parsers (TARIFF-08)
+
+The only parser is columnar: `https://api.energy-charts.info/price?bzn=BE` gives
+parallel `unix_seconds` / `price` arrays plus `unit`. The earlier row parser read
+`doc["data"]`, a shape no feed ever published, graded by fixtures written from
+the same guess, so every fetch ended `SourceUnavailable` and 11.4 fell back to
+static silently. Two shapes, two functions: a parser that sniffs can decide
+wrong, and a wrong-but-parseable response becomes a price.
+`_points_from_columnar_json()` refuses:
+
+- unequal arrays (`zip()` would truncate the evening peak, and a series missing
+  the expensive hours is traded on while no-data switches arbitrage off);
+- a unit other than the declared one (EUR/kWh under the same keys would be 1000
+  times too small and `MAX_PLAUSIBLE_EUR_KWH` bounds only the large side);
+- naive time: `unix_seconds` are UTC (`fromtimestamp(t, timezone.utc)`).
+  Rendering at the Brussels offset is `assemble()`'s, once, for every plugin.
+
+A `null` price is dropped and logged (the pairing is reliable, the source said
+it published none; `_Series.at()` answers the hole with `Absence`);
+`scenarios/fetch_epex_be.py` dropped 0 nulls in 12 months to 2026-08-31. The
+feed is quarter-hourly since Belgium's 15-minute MTU (2025-10-01); nothing
+assumes either granularity (test_price.py section 2b replays both).
+`_validate_raw()` accepts negative prices (windy-Sunday hours are the year's best
+charging; 17 keeps the regression) and rejects NaN, infinity, an implausible
+magnitude, naive datetimes, and duplicate or out-of-order starts.
+
+## Transport and plugin details
+
+- `check_host()` splits the scheme before parsing the host. The first version
+  stripped `len("https://")`, which on `http://` ate two characters of the host
+  (`pi.energy-charts.info`), so a non-TLS feed failed the allow-list and the check
+  "plain http is refused" passed even with the TLS rule deleted. Found by
+  mutation in review of PR #16.
+- The default transport imports aiohttp lazily so `manual_csv` works with no HTTP
+  stack. With `headers` (price_service only) it answers in the safe words of
+  `status_words()` and follows no redirects (the host is fixed; a redirect would
+  take the token somewhere the allow-list never saw).
+- `manual_csv`: the CSV is all-in (the plugin cannot know what a typed number
+  contains); `load_prices()` warns when markup / taxes are set non-zero under a
+  plugin that sources them. No transport, aiohttp, network or tz database: it is
+  the offline escape hatch and the TEST-01 replay ingest path.
+- `custom_formula` (TARIFF-15) declares `{ENERGY, MARKUP}`, not `ALL_IN`: a
+  card's `Tariefformule` is the energy component only (Eneco tabulates network
+  tariffs separately; ENGIE excludes network, transport, levies, excise), so
+  `ALL_IN` would drop about 12 c/kWh. The risk left is an operator folding
+  network charges into `offset`; the card self-check in custom_formula.py refuses
+  that, and grades the coefficients against the card, not the card against
+  reality. No expression evaluation: the string is settable over HTTP through
+  the ingress config page, so `eval` would be RCE in a root container holding
+  `SUPERVISOR_TOKEN`. It reuses `generic_dayahead`'s feed, URL and parser. It
+  keeps `scale=1.0`, so its `RawPoint`s carry EUR/MWh in a field called
+  `eur_per_kwh`: contained (destructured on the next line, never leaves the
+  method; `_validate_raw()` would refuse an escape).
+- `startup_preview()` is a hook (TARIFF-15), not a line in `load_prices()`: only
+  the plugin knows what went into its arithmetic, and the index beside the
+  all-in figure makes a factor of 1000 obvious. It must not raise into the control
+  path; the id is recorded before the hook runs so a failing preview is not
+  retried every 30 minutes.
+- `load_prices()` returns, never raises, except `FrameworkOption` (a plugin trying
+  to read the markup; turning it into "no price data" would hide the defect).
+- `price_provider_id()` is one spelling of the selected id because the same
+  expression was written at three call sites (TARIFF-10). validate.py keeps its
+  own reader on purpose: it validates the raw blob.
+- `price_provider_selected()` (TARIFF-10): the background refresh used to start
+  only when `arbitrage_enabled` (ships false) was on, so a configured site
+  fetched nothing (40 h soak: zero feed requests, `present: false` on all 802
+  samples). It is not a trading switch: `arbitrage.enabled()` answers that.
+- `price_service` (PRICE-01): `FALLBACKS` and `KEEP_LAST` are empty/False for
+  every earlier plugin, so `price_chain.py` is not used for them.
+  `TOKEN_REFUSED` is the one phrase the fallback chain reads to tell "the owner
+  must act" from "the server is down". `covers` lists complete days only; an hour
+  missing inside a day is a hole, not a free hour.

goodwe_controller/DECISIONS/TARIFF-16-the-injection-leg.md

@@ -0,0 +1,102 @@
+# TARIFF-16 - the injection leg of a dynamic contract (`price_export_formula`)
+
+**Status: SHIPPED.** Tests: `test_price.py` (17 series). Written down by
+MAINT-20 from `app/custom_formula.py` and `app/price.py`. Follows [[TARIFF-15]],
+whose parser it reuses.
+
+## Why a formula, not the scalar
+
+`price.py` modelled injection as one scalar. The market publishes a line a
+scalar cannot hold:
+
+    Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c EUR/kWh
+    ENGIE Dynamic                (B x eSpot_15) - A
+    Aspiravi (non-dynamic)       0,07 x Belpex - 2
+
+1. Its own factor (Eneco 0,102 on consumption, 0,100 on injection; Aspiravi 0,07
+   against about 0,10): not the consumption `B` with a sign flip.
+2. A negative offset (`- 1,188`, `- 2`); `price_markup_eur_kwh: float(0,1)`
+   cannot express one.
+3. VAT-exempt ("Injectietarieven zijn vrijgesteld van btw") against 6 % on
+   consumption: representable only because `vat_pct` is per spec.
+4. It goes negative with no floor: Eneco's is below zero for any BELPEX-H under
+   11,88 EUR/MWh, the hours a PV household exports in. You can be charged to
+   export.
+
+`price_export_formula` is `custom_formula`'s parser with one argument moved
+(`option`, a row of `_LEGS`), as TARIFF-17 did for `parse_static_profile()`. A
+second parser would be a second `_finite()`, unknown-key rule, unit table and
+`to_resolution()`, diverging first on the 23- and 25-hour days. Every earlier
+call site passes no `option` and reads byte-identical sentences. The flat scalar
+`export_price_eur_kwh()` is untouched and still answers when the option is "".
+
+## What it does not affect
+
+`arbitrage.py` does not read the injection price at all (9.3: near-zero Belgian
+injection; it prices the sell side as displaced import), so no trade today turns
+on this number and it is not a wrong-trade fix. It changes what an operator is
+told and what a future export-aware strategy (OPT-06) rests on.
+
+## The card cannot always grade it
+
+Eneco's injection formula is printed with no price beside it. The `card` block
+is required on the consumption leg and optional here (`FormulaSpec.card_graded`
+is how callers ask; `card_discrepancy()` raises on an ungraded spec rather than
+returning 0.0). The self-check runs wherever a printed estimate exists, and
+validate.py says at startup that a leg is ungraded. Inventing an estimate would
+grade the arithmetic against itself (MUTATION.md habit 4).
+
+## `implausible_injection()`: bounds on the coefficients, not the price
+
+The consumption band (`implausible_all_in()`) cannot be reused: it adds
+`price_taxes_eur_kwh`, a consumption component, and its floor `energy >= 0.02`
+would refuse the real market's negative hours. But that floor catches a whole
+card read 100x too small, which the card check cannot see (it cancels). A band
+spanning zero cannot catch 0.00132 EUR/kWh, so the bound moves onto the
+coefficients, index-free and sign-free:
+
+- pass-through `factor x UNITS[units] / 0.001` (one EUR/MWh is 0.001 EUR/kWh):
+  1.00 for Eneco's injection leg, 0.70 for Aspiravi's; 100x off reads 0.01 or 100;
+- offset magnitude, on the absolute value (1,188 c = 0.01188; a hundredfold error
+  is 1.188 EUR/kWh).
+
+Two rungs can both answer one stimulus, so they are graded on their reasons and
+mutated together (MUTATION.md, TEST-16); test_price.py 17d builds fixtures so
+each is the only one firing. It bounds the shape of the coefficients, never
+their truth.
+
+## The consumption band's asymmetry (`implausible_all_in()`)
+
+The low end is graded on the energy component and the high end on the all-in
+figure. `price_taxes_eur_kwh` ships at 0.11736 (TARIFF-18; 0.06 before), nearly
+six times the low bound, so a card read 100x too small (0.0016 EUR/kWh) is
+carried over the floor by the flat tax addend alone and would pass a band applied
+to the all-in total. Raising the default made the trap wider. The ceiling is on
+the all-in figure because that is what the site is billed. It grades the card's
+own point, not every hour: live EPEX hours may fall outside (a negative hour is
+the best charging opportunity of the year, 17 keeps a regression case). It is
+called from validate.py only, since it reads the framework-owned taxes number.
+
+## Smaller rules
+
+- `CARD_TOLERANCE` is 0.01 in the card's units, the last digit both real cards
+  print (Eneco 15,55 against 15.5471; ENGIE 7,522 against 7.5218). Every error
+  class it exists for is at least two orders of magnitude bigger.
+- The card age warning (about 6 months) is never a refusal: ENGIE freezes a
+  contract's coefficients, so an old card can be exactly right.
+- `units` is required with no default (a default is the factor-1000 class).
+  A zero factor is a fixed tariff in a dynamic one's clothes (every spread 0,
+  arbitrage never fires; 14's warning box), so the operator is pointed at the
+  first-class way to say one price. A negative factor inverts the market (charge
+  into the evening peak). `vat_pct: 0` is legitimate (injection is exempt; some
+  cards are quoted VAT-inclusive); the bound exists for the 106 / 1.06 / 6
+  confusion. An unknown key is refused, not ignored, so a user who types "expr"
+  is not priced on the fields they also typed. A non-finite factor would make
+  every price NaN; `True` is an `int` and would price the day at the index.
+- `to_resolution()`: the bucket is a UTC hour, exact for Belgium (CET and CEST
+  are whole-hour offsets, so keying by UTC cannot collide the two 02:00s). It
+  decides how many points are emitted, not how long one covers ([[TARIFF-14]]). An
+  incomplete hour is averaged over what is there, not dropped or zero-filled.
+- The startup preview prints the index that went in beside the price that came
+  out (`61.96 -> 0.13522`): every error this module refuses is invisible on the
+  status page, and a factor of 1000 is one glance there.

goodwe_controller/DECISIONS/TARIFF-24-modes-need-the-tariff-task.md

@@ -0,0 +1,70 @@
+# TARIFF-24 - battery modes need the tariff task
+
+**Status: FIXED in 0.19.1 (hotfix from 0.19.0, owner go 2026-10-28).**
+Follows TARIFF-10 (fetching is not trading). Tests: `test_tariff24.py`.
+
+**The defect.** The control cycle gets prices only from
+`Controller.tariff_plan`, which only `run_tariff_refresh()` stores. `amain()`
+starts that task when `tariff_refresh_wanted(opts)`, which was
+`provider_configured(opts) or arbitrage.enabled(opts)`. Battery modes read the
+plan but were not a term. With battery modes on, a day/night or fixed
+`static_profile`, `price_provider: off` and `arbitrage_enabled: false` (the
+site trade switch is not read with modes on) no task ran. Then
+`fresh_tariff_plan()` was None, `_price_runs()` was None and `mode_runs` was
+None, so Leftover solar and Cheap hours never charged from the grid. The
+Batteries screen said "No prices, so it follows the house" while Home priced
+the day from `static_plan()` itself (`homeview.build_plan()`).
+
+**The fix** (`main.py`, `tariff_refresh_wanted()`). `packmode.enabled(opts)`
+is a third term. The gate stays a widening: nothing that started the task
+before stops. No HTTPS call is added: with `price_provider: off`,
+`resolve_tariff()` is the pure `static_plan()`.
+
+**Not changed.** Modes off, arbitrage off, no feed still starts no task. The
+control law, the price runs and every message are untouched.
+
+**One rule, not two.** Gating on "modes on and a static profile" was
+considered. It saves one arithmetic pass every 30 min on a site with modes on
+and no prices at all, and it adds a second condition that has to track what
+`resolve_tariff()` accepts. With no profile and no feed the plan is `no_data`,
+exactly what the cycle sees without the task.
+
+**UX-55.** Home said "no prices have arrived" (`mode_runs` None) with every
+battery on Solar first. The same cause, and this fix clears it for a site with
+a static profile (`test_tariff24.py` part 5). A site with no profile and no
+feed still has no prices, and Home still says so.
+
+## Round 2 (AUDIT-02 F1): the forecast replaces the "no weather" doubt
+
+**Decided 2026-10-28 (owner), in the same hotfix.** The price gap a mode needs
+was `cycle_cost_threshold_eur` x 1.5 (`Uncertainty.NO_WEATHER`) whether or not
+a solar forecast was read. At the shipped cost 0.10 that is 0.15, so a
+day/night gap (0.08) and many dynamic days never traded, and the screens said
+only "Prices differ too little".
+
+**Why the doubt goes with a forecast.** The widening stands in for not knowing
+the weather. The forecast is that knowledge, and the day plan already trusts it
+for how much to charge. Trusting it for the plan but doubting it for the gap
+was one input judged twice.
+
+**The rule** (`arbitrage.weather_uncertainty()`). With battery modes on and a
+usable forecast (`solar_fc` not None, the day plan's own test) the doubt is
+not added: the gap needed is the cycle cost, widened by the price product only.
+No forecast, or a stale or unusable one: 1.5 x, as before. It is read in four
+places that must agree: the run plan (`_price_runs()`), the charge gate
+(`_mode_roles()`), Home's mirror (`homeview.trade_verdict()`) and the Forecast
+tab's longer cheap run (`dayview.py`, from release/1.0). The forecast
+is read at most every 60 s and the plan key already holds "forecast or not", so
+the gap follows in the cycle the read changes, both ways, with one exception:
+a run planned with a forecast that is under way keeps that gap to its end
+(`Controller.weather_held()`), so a sensor that goes unavailable does not stop
+or restart a Cheap hours charge (a Leftover solar battery still stops: without
+a forecast it has no planned level). The wider gap applies from the next run.
+A run that has started runs to its end: a give run that starts during the hold
+is kept after it (`keep_started()`), with no grid charge or sale.
+
+**Not changed.** Modes off (the site trade) keeps the doubt always. The
+shipped cost 0.10 still needs a gap of 0.10 even with a forecast: a 0.08
+day/night site must set *Battery cycle cost* to 0.08 or less. Showing the two
+numbers on the screens (AUDIT-02 F1 option b) is a separate card.
+

goodwe_controller/DOCS.md

@@ -538,7 +538,7 @@ With battery modes on, these choices replace the *Charging and selling on price*
 
 **Cheap and expensive hours.** They come from the published day-ahead prices, as runs of consecutive 15-minute periods, not a single period.
 - The cheap run is the cheapest stretch long enough to fill the batteries that may charge, at their power.
-- An expensive hour costs at least *Battery cycle cost* (`cycle_cost_threshold_eur`, widened as for trading) more than the cheap run. The batteries hold their power until then.
+- An expensive hour costs more than the cheap run by at least *Battery cycle cost* (`cycle_cost_threshold_eur`) when a solar forecast is read, and by 1.5 times that when none is (a real-time price feed widens it further). The batteries hold their power until then.
 - The sale uses the most expensive stretch inside those hours, and never a period below 0.
 - A carried (not yet published) price is never used. A run that has started runs to its end.
 - With no prices, or too small a gap, every battery follows the house.
@@ -557,6 +557,7 @@ With battery modes on, these choices replace the *Charging and selling on price*
 - The plan is checked every 15 minutes. A planned level moves only by 1 kWh or 10 %, so a wobbling forecast does not flip it.
 - No forecast, one older than 3 hours or from before midnight, or no house use yet: *Leftover solar* takes solar only and *Cheap hours only* fills to the top level. The Batteries screen says so.
 - A battery needs its capacity (`inverters.capacity_kwh`) for a plan.
+- **At night.** Some forecasts stop updating in the evening (Forecast.Solar does). The add-on keeps the last reading of each sensor and uses it for that night's plan: from 20:00 until 06:00, or until a newer reading comes. After midnight the evening's figure for tomorrow is today's, whole, because nothing has been produced yet. A sensor that is missing for up to 3 hours is covered the same way. A figure is never used for another day, and never when it is more than 12 hours old (15 hours after midnight, for a figure that was still in use at midnight). A charge from the grid that has started keeps its level when the forecast ends, and goes on to it; the Batteries screen says so. The Batteries screen says "Solar forecast read 17:05, kept for tonight." With no reading all day, the night run still needs the wider gap.
 
 **What always comes first.**
 - The peak limit, the safety stops and the monthly cycle come before a battery's mode.
@@ -1710,7 +1711,9 @@ DECISIONS/MAINT-13-full-pack-is-complete.md.
 On a capacity-tariff site the maintenance charge is capped by the headroom left
 under `peak_cap_w`, and if the forecast goes over the cap the charge-only clamp
 is dropped so the battery can shave the peak instead. Money outranks the
-maintenance schedule.
+maintenance schedule. With one battery or several, the charge also stays
+within the room left in the 15-minute period, so a late meter reading does
+not let it run at full power.
 
 With two or more batteries, the one being emptied gives its drain rate and the
 others only add power when the house needs more; none charges while it drains
@@ -3455,7 +3458,7 @@ Charging from the grid stays blocked meanwhile. With several inverters the
 notification names the battery at its limit (SAFETY-32), each graded against
 its own cut-out level. That battery is held (weight 0 while the site gives)
 and the guard's need goes to the others, up to their rating; the alarm fires
-only if they miss the limit at full power for `ALARM_HOLD_S` (SAFETY-87). ⚠️ **The reserve binds the peak guard only
+only if they miss the limit at full power for `ALARM_HOLD_S` (SAFETY-87). With no battery able to give it fires at once, but only if the period would end more than 10 W over the aim with the batteries at 0 W. A grid charge the add-on runs counts as one it can stop, and the last second's landing error on the aim is not an alarm. A steadily rising load therefore alarms a little later. With `peak_margin_w` 0 a period can end up to 10 W over the limit without this alarm, as for “Load too high” (SAFETY-126). ⚠️ **The reserve binds the peak guard only
 (SAFETY-25).** Self-consumption has no such floor. See *What `peak_soc_floor`
 does not protect*.
 
@@ -3614,7 +3617,7 @@ for a new install*.
 | Meter reading may be stuck | See *Meter reading may be stuck* under Notifications. |
 | Month peak | This month's highest 15-minute average, when it happened, and how close it is to your peak limit. Amber from 80 %. |
 | 15-minute periods measured this month | How many 15-minute periods the add-on has measured and saved this month. |
-| Peak guard, Load too high for battery, Battery at its peak reserve | What the add-on does to keep your peak down. *Idle, heading for …* is where this 15-minute period is heading. *Waiting for meter readings* after a restart means the battery does not charge until the add-on can measure the period again. A red peak row is an alarm while control keeps running, so the banner shows its title without *Not ready*. |
+| Peak guard, Load too high for battery, Battery at its peak reserve | What the add-on does to keep your peak down. *Idle, heading for …* is where this 15-minute period is heading. *At this rate … over …* means it would go over at the current rate. With *grid charge limited*, a charge from the grid is cut back so it does not. *Waiting for meter readings* after a restart means the battery does not charge until the add-on can measure the period again. A red peak row is an alarm while control keeps running, so the banner shows its title without *Not ready*. |
 | Battery level, Battery power, Grid power | The reading of that entity. *No usable reading* means the entity is missing, or its reading is too old. Check it in Developer Tools before replacing it. |
 | Inverter control | Whether the inverter can be controlled, and how much it can charge and give. |
 | *name*: battery power reading stopped changing | The reading did not change while the add-on asked for a change. It may be stuck, or the battery may be refusing. The add-on sets the inverters to 0 W until it changes. |

goodwe_controller/app/arbitrage.py

@@ -147,7 +147,7 @@ from dataclasses import dataclass
 from datetime import datetime
 
 from .arbiter import ACTUATOR_SITE, P_ARBITRAGE, Claim
-from .price import Absence, price_option
+from .price import Absence, Uncertainty, price_option
 
 _LOG = logging.getLogger("goodwe.arbitrage")
 
@@ -267,6 +267,21 @@ def threshold_eur_kwh(opts: dict) -> float:
     return v
 
 
+def weather_uncertainty(modes_on: bool, solar_fc, held: bool = False) -> frozenset:
+    """The "no weather" doubt (x1.5) a trade must clear. TARIFF-24.
+
+    Battery modes read a solar forecast; with one read (`solar_fc` not None) the
+    doubt is gone, and `held` (a run planned with a forecast is under way, see
+    `Controller.weather_held()`) keeps it gone until that run ends. Everything
+    else, and the modes without a forecast, keep it. One rule for the run plan,
+    the charge gate and Home's mirror. See
+    DECISIONS/TARIFF-24-modes-need-the-tariff-task.md.
+    """
+    if modes_on and (solar_fc is not None or held):
+        return frozenset()
+    return frozenset({Uncertainty.NO_WEATHER})
+
+
 def soc_bounds(opts: dict) -> tuple:
     """(floor, ceiling) in percent. The reserve arbitrage may not spend."""
     return (float(price_option(opts, "arbitrage_soc_floor")),

goodwe_controller/app/custom_formula.py

@@ -1,174 +1,18 @@
 """TARIFF-15 - the customer's own tariff card, as two fixed coefficients.
 
-WHAT THIS IS FOR, in one sentence: a Belgian dynamic contract prices energy as
-`B x index + A` with coefficients that exist in exactly one place - the tariff
-card in the customer's klantenzone - so the customer types those two numbers
-and the add-on does every unit conversion and the VAT multiplication itself.
+A Belgian dynamic contract prices energy as `B x index + A` with coefficients
+that exist only on the customer's card. The customer types those two numbers;
+the add-on does every unit conversion and the VAT multiplication. Fixed
+coefficients, no expression evaluation of any kind (the string is settable over
+HTTP, and an expression cannot be graded against the card). An unknown key is
+refused, never ignored. validate.py refuses to start unless the formula
+reproduces the card's printed estimate within CARD_TOLERANCE: that grades the
+coefficients against the card, not the card against reality.
 
-WHY A FORMULA AND NOT FOURTEEN MORE PLUGINS (§9.2, TARIFF-07)
-=============================================================
-There is NO machine-readable source of Belgian tariff coefficients anywhere.
-CREG's consumer tariff-card pages 404, CREG Scan is a JS-only wizard, the
-annual report carries the supplier list and no per-product coefficients, and
-VREG was unreachable. Every coefficient found in research came off a supplier's
-own PDF, one of them image-only. So there is nothing to scrape and a
-per-supplier plugin would have no source for its numbers - fourteen plugins
-would be fourteen copies of the same invention, which is the defect TARIFF-07
-withdrew three plugins for. THE CUSTOMER IS THE ONLY PARTY WHO CAN SEE THEIR
-OWN COEFFICIENTS, and the card they read them from is the only artefact that
-can grade them.
-
-THE SHAPE IS THE MARKET'S PUBLISHED ARITHMETIC, NOT OUR APPROXIMATION
-====================================================================
-Both suppliers whose 2026 cards were readable print the formula, the reference
-index they assumed AND the resulting price, so the arithmetic below is
-reproducible against something they published rather than against our own
-guess:
-
-    Eneco   (0.102 x 133.9905 + 1.00) x 1.06 = 15.5471   card prints  15,55
-    ENGIE   (0.100 x  61.96   + 0.90) x 1.06 =  7.5218   card prints   7,522
-
-Two independent suppliers, reproduced to the last printed digit, in
-c EUR/kWh. test_price.py section 13 runs both through the SHIPPED code.
-
-⚠️ THE DOUBLE-COUNTING MECHANISM, AND WHY THIS DESIGN IS SAFE AT ALL
-====================================================================
-This provider declares `sources = {ENERGY, MARKUP}` and NOT `ALL_IN`. A Belgian
-card's `Tariefformule` line is THE ENERGY COMPONENT ONLY: Eneco puts network
-tariffs in one table and levies in a second, and ENGIE states in so many words
-that the formula "does not include fixed network/distribution costs, transport,
-grid levies, or excise duties". Declaring ALL_IN would lie on behalf of every
-user who typed what their card says, and would silently drop ~12 c EUR/kWh.
-
-price.py already mechanises that a PLUGIN cannot double-count (`PluginOptions`,
-`FRAMEWORK_KEYS`, `code_leaks()`). This provider introduces a risk none of those
-can see, because it is not in the code: THE OPERATOR double-counting, by folding
-their network charges into `offset` while `price_taxes_eur_kwh` carries them as
-well. `code_leaks()` scans code. This is config.
-
-So the card is the grader:
-
-    At startup validate.py computes
-    `(factor x card.index_eur_per_mwh + offset) x (1 + vat_pct/100)` and
-    REFUSES TO START unless it equals `card.expect_incl_vat` to within
-    CARD_TOLERANCE, naming the discrepancy.
-
-An `offset` inflated by network charges CANNOT PASS: the card's printed estimate
-is by construction the energy component alone, so adding ~12 c EUR/kWh moves
-15.55 to ~27 and the add-on refuses. The same check catches VAT omitted, VAT
-applied twice, a transposed digit, and a UNIT MISMATCH BETWEEN THE TWO SIDES -
-coefficients read off the formula line while the expected price is typed in
-another convention, which is the factor-10/100/1000 class as it actually
-happens.
-
-⚠️ THE ONE UNIT ERROR THE CARD CHECK CANNOT SEE IS THE ONE APPLIED TO BOTH
-SIDES AT ONCE, and saying so is the difference between a guard and a slogan:
-scaling the coefficients AND the expected price by the same 100 cancels out of
-a comparison between them. That is what `implausible_all_in()` is for, and it
-is a SEPARATE refusal on a SEPARATE quantity - the card's own point, all-in,
-against the band a Belgian retail tariff can occupy.
-
-⚠️ AND THE LIMIT, IN THE SAME BREATH AS THE CLAIM, exactly as price.py's trap 1
-states its own: THE CHECK GRADES THE COEFFICIENTS AGAINST THE CARD, NOT THE CARD
-AGAINST REALITY. A consistent-but-wrong pair - both numbers copied off the wrong
-product, or off last year's card - reproduces its own printed price perfectly
-and passes. Nothing here or anywhere else can catch that; what is mechanised is
-that the two coefficients and the printed estimate AGREE, which is the whole of
-the unit/VAT/decimal-point class and none of the "wrong contract" class.
-
-⚠️ FIXED COEFFICIENTS. NO EXPRESSION EVALUATION OF ANY KIND.
-============================================================
-All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
-`B x index + A`, so an expression buys nothing the market needs. Against that:
-
-  * the add-on serves `POST config/save` -> `POST /addons/self/options` on its
-    own ingress page, so this string is SETTABLE OVER HTTP. `eval` on it is
-    remote code execution in a root container holding SUPERVISOR_TOKEN, with
-    `homeassistant_api` and `hassio_api`, driving an inverter over RS485.
-    (`eval(s, {"__builtins__": {}})` is not a sandbox and never was.)
-  * ⚠️ AND THE DECIDING ARGUMENT IS NOT SECURITY - AN EXPRESSION IS
-    UNVERIFIABLE. Two coefficients can be graded against the card's printed
-    estimate. An arbitrary expression cannot be graded against anything, so it
-    makes the invisible-wrong-coefficient problem STRICTLY WORSE, which is the
-    exact failure this provider exists to prevent.
-
-Future shapes become NAMED FIELDS - `clamp_lo`, `factor_negative`,
-`offset_bands` - each individually refusable and each individually gradeable
-against a card. Never a grammar. `parse_price_formula()` therefore REFUSES AN
-UNKNOWN KEY rather than ignoring it, so a user who types `"expr"` is told it
-does not exist instead of being silently priced on the fields they also typed.
-test_price.py section 13f walks this module's AST and fails if `eval`, `exec`,
-`compile`, `__import__` or `literal_eval` ever appears in it.
-
-WHERE THE NUMBERS COME FROM AND WHERE THEY GO
-=============================================
-`index` names the reference series. `epex_be` is the EPEX BE day-ahead curve in
-EUR/MWh, which is what `generic_dayahead` already fetches - same feed, same
-`brussels_date_range()` request, same columnar parser, same declared egress
-hosts. No new parser and no new failure mode.
-
-`resolution` says which series the contract is written against:
-
-  * `quarter_hourly` - the 96 points the feed publishes since Belgium's
-    15-minute MTU (2025-10-01), emitted as they are;
-  * `hourly`         - the four quarters of each hour averaged into one point.
-
-⚠️ NEITHER IS AN HOURLY ASSUMPTION IN `_Series.at()`'s SENSE (TARIFF-14). The
-hourly option changes how many POINTS are emitted and their spacing; the window
-each point covers is still derived from its neighbours by `_cover_table()`, and
-nothing here tells anything downstream how long a point lasts. A feed that is
-already hourly averages one member per hour, which is the identity - so the
-option cannot silently assume the granularity it was handed.
-
-`units` is NOT bureaucracy. Two suppliers publish the same shape in different
-units and the market aggregator prints both conventions in one column, so the
-add-on has to be told which one the card is in - and the unit conversion is the
-add-on's job precisely because it is one of the two steps that silently costs a
-factor of 10, 100 or 1000. The other is VAT, which is also the add-on's.
-
-TARIFF-16 - THE SECOND LEG, AND WHY IT IS THIS PARSER AND NOT A SECOND ONE
-==========================================================================
-A Belgian dynamic contract has TWO published lines, not one, and the second is
-what the site is PAID for export:
-
-    Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c EUR/kWh
-    ENGIE Dynamic                (B x eSpot_15) - A
-    Aspiravi (non-dynamic)       0,07 x Belpex - 2
-
-Same `B x index + A` shape - which is why `price_export_formula` is this
-module's parser with ONE argument moved (`option`), exactly as TARIFF-17 made
-`parse_static_profile()`'s option name a parameter rather than forking the
-period grammar. What differs between the two legs is FOUR numbers and a
-handful of sentences, and all of them are rows of `_LEGS`:
-
-  * its OWN factor - Eneco 0,102 on consumption against 0,100 on injection,
-    Aspiravi 0,07 against ~0,10. NOT the consumption `B` with a sign flip;
-  * a NEGATIVE offset, which `factor`/`offset` already allow and which
-    `price_markup_eur_kwh: float(0,1)` cannot express at all;
-  * `vat_pct: 0` - "Injectietarieven zijn vrijgesteld van btw" - against 6 on
-    consumption, which is a SIX PERCENT ASYMMETRY between the buy leg and the
-    sell leg and is representable only because `vat_pct` is PER SPEC;
-  * a price that goes BELOW ZERO with no floor, in the hours a PV household
-    exports. `implausible_injection()` is the band that accepts that and still
-    refuses an implausible one; `implausible_all_in()` is NOT it, and its
-    docstring says why.
-
-⚠️ AND THE CARD CANNOT ALWAYS GRADE IT. Eneco's injection formula is printed
-with NO price beside it, so on that card there is nothing to reproduce. The
-`card` block is therefore OPTIONAL on this leg and REQUIRED on the other, the
-self-check runs wherever there is a printed estimate, and validate.py says at
-startup when a leg is ungraded. Inventing an estimate to grade against would
-be grading arithmetic against itself, which is the defect MUTATION.md habit 4
-is about; TARIFF-15 demonstrated two tariffs end to end rather than three for
-the same reason.
-
-⚠️ NOTHING TRADES ON THIS TODAY, AND SAYING SO IS PART OF SHIPPING IT.
-`arbitrage.py` does not read `export_price_eur_kwh` at all - its own comment
-says so, citing §9.3's near-zero Belgian injection price - and both hours it
-compares are all-in CONSUMPTION prices. So this is not a wrong-trade defect
-and must not be described as one. What it changes is what an operator is told,
-and what a future export-aware strategy would rest on.
-"""
+The provider declares `{ENERGY, MARKUP}`, never `ALL_IN` (a card's formula is
+the energy component only). TARIFF-16 added the injection leg through this same
+parser. DECISIONS/TARIFF-15-the-card-is-the-grader.md and
+DECISIONS/TARIFF-16-the-injection-leg.md."""
 
 import json
 import math
@@ -183,13 +27,11 @@ class FormulaInvalid(Exception):
     validate.py at startup - never at 03:00 on a fetch."""
 
 
-# --------------------------------------------------------------------------- #
-# The enumerations. Every one of these is a CLOSED set, and that is the point:
-# an unknown value is refused by name rather than guessed at.
-# --------------------------------------------------------------------------- #
+# The enumerations. Each is a CLOSED set: an unknown value is refused by name,
+# not guessed.
 
-# unit -> how many EUR/kWh one of it is. ⚠️ THE WHOLE FACTOR-1000 CLASS LIVES
-# HERE, so the table is tiny, explicit, and has no "default".
+# unit -> EUR/kWh per one of it. The whole factor-1000 class lives here: tiny,
+# explicit, no default.
 UNITS: dict = {
     "c_eur_per_kwh": 0.01,      # eurocent per kWh - Eneco and ENGIE print this
     "eur_per_kwh": 1.0,         # some aggregators print this
@@ -198,54 +40,41 @@ UNITS: dict = {
 
 RESOLUTIONS: tuple = ("hourly", "quarter_hourly")
 
-# index id -> the human name of the series it refers to. One entry today; a
-# second index is a new row here plus a fetch path, not a new grammar.
+# index id -> the series it names. A second index is a new row here plus a
+# fetch path.
 INDEXES: dict = {
     "epex_be": "Belgian day-ahead price, EUR/MWh",
 }
 
-# ⚠️ 0.01 IN THE CARD'S OWN UNITS, WHICH IS THE LAST DIGIT BOTH REAL CARDS
-# PRINT. Eneco prints 15,55 against a computed 15.5471 (0.0029 out) and ENGIE
-# prints 7,522 against a computed 7.5218 (0.0002 out), so the tolerance has to
-# absorb the card's own rounding and nothing more. Every error class this check
-# exists for - a factor of 10, of 100, of 1000, a missing or doubled 1.06, a
-# transposed digit, ~12 c EUR/kWh of network charge folded into `offset` - is
-# at least two orders of magnitude bigger than this.
+# 0.01 in the card's own units, the last digit both real cards print (Eneco
+# 15,55 vs 15.5471; ENGIE 7,522 vs 7.5218): the card's rounding and nothing
+# more. DECISIONS/TARIFF-16-the-injection-leg.md.
 CARD_TOLERANCE = 0.01
 
-# The all-in plausibility band, EUR/kWh. `MAX_PLAUSIBLE_EUR_KWH` in price.py
-# bounds only prices that are too LARGE; this is the other end, and it is the
-# one the factor-1000 error falls off.
+# The all-in plausibility band, EUR/kWh: the low end, where a factor-1000 error
+# falls off.
 PLAUSIBLE_LO_EUR_KWH = 0.02
 PLAUSIBLE_HI_EUR_KWH = 1.00
 
-# ~6 months. ⚠️ A WARNING, NEVER A REFUSAL: ENGIE freezes a contract's
-# coefficients for its duration, so a card two years old can be exactly right
-# and a site refused over one would be a site that cannot start.
+# ~6 months. A WARNING, never a refusal: ENGIE freezes a contract's
+# coefficients.
 CARD_STALE_DAYS = 183
 
 _CARD_KEYS = ("month", "index_eur_per_mwh", "expect_incl_vat")
 _TOP_KEYS = ("index", "resolution", "factor", "offset", "units", "vat_pct",
              "card")
 
-# --------------------------------------------------------------------------- #
 # TARIFF-16 - the SECOND leg, and the one parameter that carries it
-# --------------------------------------------------------------------------- #
 
 EXPORT_FORMULA_OPTION = "price_export_formula"
 
-# ⚠️ THE PASS-THROUGH FRACTION, WHICH IS WHY THE NEXT TWO BOUNDS CAN BE
-# INDEX-FREE. One EUR/MWh IS 0.001 EUR/kWh, so `factor x UNITS[units] / 0.001`
-# is the dimensionless share of the wholesale price the contract passes
-# through - 1.00 for Eneco's injection leg (0,100 c EUR/kWh per EUR/MWh), 0.70
-# for Aspiravi's (0,07). A coefficient typed a hundred times too small or too
-# large moves this by a hundred, whatever the index and whatever the sign of
-# the price.
+# The pass-through fraction, `factor x UNITS[units] / 0.001`: index-free and
+# sign-free, so a coefficient typed 100x off moves it by 100 whatever the
+# price.
 EUR_KWH_PER_EUR_MWH = 0.001
 
-# The two plausibility bounds for an INJECTION leg. ⚠️ NEITHER LOOKS AT THE
-# SIGN OF THE PRICE, AND THAT IS THE WHOLE POINT - see
-# `implausible_injection()`.
+# The two plausibility bounds for an INJECTION leg; neither looks at the sign
+# of the price.
 PASSTHROUGH_LO = 0.10       # 10% of the wholesale price
 PASSTHROUGH_HI = 10.0       # 1000% of it
 INJECTION_OFFSET_MAX_EUR_KWH = 0.20
@@ -254,18 +83,8 @@ INJECTION_OFFSET_MAX_EUR_KWH = 0.20
 @dataclass(frozen=True)
 class _Leg:
     """What ONE option's coefficients price, as sentences its refusals read.
-
-    ⚠️ TARIFF-16 MADE `option` A PARAMETER RATHER THAN FORKING THE PARSER,
-    exactly as TARIFF-17 made `option`/`means` parameters of
-    `parse_static_profile()` rather than forking the period grammar. A second
-    copy of this parser would be a second `_finite()`, a second unknown-key
-    rule, a second unit table and a second `to_resolution()` - and the two
-    would diverge first on the 23- and 25-hour days, where nobody looks.
-    Everything that differs between the consumption leg and the injection leg
-    is a STRING in this table; the arithmetic, the enumerations, the card
-    comparison and the resolution rule are ONE implementation with one set of
-    checks over it.
-    """
+    `option` is a parameter, not a fork of the parser (TARIFF-16, as TARIFF-17 did
+    for `parse_static_profile()`)."""
 
     option: str
     what: str            # "consumption" / "injection", for a sentence
@@ -316,12 +135,8 @@ _LEGS = {
 
 @dataclass(frozen=True)
 class FormulaSpec:
-    """One contract's published arithmetic. SEVEN numbers and no code.
-
-    ⚠️ EVERY FIELD IS A FIXED, NAMED SCALAR. There is deliberately no field
-    that holds an expression, a callable, a lambda or a template, and there is
-    no place to put one: `parse_price_formula()` refuses an unrecognised key.
-    """
+    """One contract's published arithmetic: SEVEN numbers and no code. Every field is
+    a fixed named scalar; `parse_price_formula()` refuses an unrecognised key."""
 
     index: str
     resolution: str
@@ -332,8 +147,8 @@ class FormulaSpec:
     card_month: str = ""            # "YYYY-MM", as the card is dated
     card_index_eur_per_mwh: float = None
     card_expect_incl_vat: float = None   # in `units`, as the card prints it
-    # TARIFF-16. Which OPTION this spec was read from, so a refusal, a log line
-    # and `card_graded` name the leg the operator actually typed.
+    # TARIFF-16. Which OPTION this spec was read from, so refusals name the leg
+    # typed.
     option: str = "price_formula"
 
     @property
@@ -342,24 +157,14 @@ class FormulaSpec:
 
     @property
     def card_graded(self) -> bool:
-        """Is there a printed estimate to grade these coefficients against?
-
-        ⚠️ FALSE IS A REAL, SHIPPED STATE ON THE INJECTION LEG and is reported
-        rather than defaulted: Eneco's injection formula is printed with no
-        price beside it. Never False on `price_formula`, where `_card()`
-        refuses an absent block.
-        """
+        """Is there a printed estimate to grade these coefficients against? False is a
+        real state on the injection leg (Eneco prints none); never False on `price_formula`."""
         return self.card_expect_incl_vat is not None
 
     @property
     def passthrough(self) -> float:
-        """The dimensionless share of the wholesale price this passes through.
-
-        `factor x UNITS[units] / 0.001`. 1.00 for Eneco's injection leg, 0.70
-        for Aspiravi's. ⚠️ INDEX-FREE AND SIGN-FREE, which is what lets
-        `implausible_injection()` bound a leg whose price legitimately goes
-        below zero.
-        """
+        """The dimensionless share of the wholesale price this passes through. Index-free
+        and sign-free, which lets `implausible_injection()` bound a leg that goes negative."""
         return self.factor * self.unit_to_eur_kwh / EUR_KWH_PER_EUR_MWH
 
     @property
@@ -368,46 +173,27 @@ class FormulaSpec:
         return self.offset * self.unit_to_eur_kwh
 
 
-# --------------------------------------------------------------------------- #
 # The arithmetic. Two functions, and the SECOND one is the contract.
-# --------------------------------------------------------------------------- #
 
 def in_card_units(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
-    """`(factor x index + offset) x (1 + vat_pct/100)`, in the card's units.
-
-    This is the line the card prints, spelled exactly as the card spells it,
-    and it is the only place the coefficients are combined. The card
-    self-check and the price path both go through here, so a mutation to it
-    cannot move the price without also moving the self-check.
-    """
+    """`(factor x index + offset) x (1 + vat_pct/100)`, in the card's units: the line
+    the card prints. The only place the coefficients are combined, so the card
+    check and the price path cannot diverge."""
     return ((spec.factor * float(index_eur_per_mwh) + spec.offset)
             * (1.0 + spec.vat_pct / 100.0))
 
 
 def price_eur_kwh(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
-    """The energy+markup price for one index value, in EUR/kWh.
-
-    ⚠️ THE UNIT CONVERSION IS THE ADD-ON'S JOB AND IT HAPPENS HERE, ONCE. The
-    user types what their card prints, in the card's own units; every step
-    from there to EUR/kWh is code, because those steps are exactly the ones
-    that silently cost a factor of 10, 100 or 1000 when a human does them.
-    """
+    """The energy+markup price for one index value, in EUR/kWh. The unit conversion
+    happens here, once: those steps are the ones that cost a factor of 10, 100 or 1000."""
     return in_card_units(spec, index_eur_per_mwh) * spec.unit_to_eur_kwh
 
 
 def card_discrepancy(spec: FormulaSpec) -> float:
-    """How far the coefficients land from the card's own printed estimate.
-
-    In the card's units, signed: positive means the formula computes MORE than
-    the card prints, which is the direction an `offset` carrying network
-    charges moves it.
-
-    ⚠️ RAISES ON A SPEC WITH NO CARD RATHER THAN RETURNING 0.0 (TARIFF-16). An
-    ungraded injection leg has no printed estimate, and a discrepancy of zero
-    is exactly what "the coefficients reproduce the card" looks like - so a
-    silent zero here would report the strongest possible result for the one
-    state in which nothing was compared at all.
-    """
+    """How far the coefficients land from the card's printed estimate, in the card's
+    units, signed: positive means MORE than the card prints (the direction an
+    `offset` carrying network charges moves it). Raises on a spec with no card
+    rather than returning 0.0 (TARIFF-16)."""
     if not spec.card_graded:
         raise FormulaInvalid(
             f"{spec.option} has no card block, so there is no printed "
@@ -417,18 +203,10 @@ def card_discrepancy(spec: FormulaSpec) -> float:
         - spec.card_expect_incl_vat
 
 
-# --------------------------------------------------------------------------- #
 # Reading the option
-# --------------------------------------------------------------------------- #
 
 def _finite(value, field: str, option: str = "price_formula") -> float:
-    """A real, finite number - or a refusal naming the field.
-
-    ⚠️ SAME CLASS AS `_validate_raw()`'s NaN RULE, one layer earlier. A NaN
-    factor makes every price NaN, every comparison False, and an arbitrage
-    strategy that silently never fires; `True` is an `int` in Python and would
-    price the whole day at the index.
-    """
+    """A real, finite number, or a refusal naming the field (NaN would price every hour NaN; `True` is an `int`)."""
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         raise FormulaInvalid(
             f"{option}.{field} is {value!r}, which is not a number. Write a "
@@ -441,15 +219,9 @@ def _finite(value, field: str, option: str = "price_formula") -> float:
 
 
 def _card(raw, leg: _Leg = None) -> tuple:
-    """The `card` block: the estimate the coefficients are graded against.
-
-    ⚠️ REQUIRED ON THE CONSUMPTION LEG AND OPTIONAL ON THE INJECTION ONE, and
-    the asymmetry is a fact about the CARDS rather than a relaxed rule. See
-    `_LEGS[EXPORT_FORMULA_OPTION].card_note`: Eneco's injection formula is
-    printed with no price beside it, so on that card there is nothing to grade
-    against. `("", None, None)` is the ungraded answer and
-    `FormulaSpec.card_graded` is how every caller asks.
-    """
+    """The `card` block: the estimate the coefficients are graded against. Required on
+    the consumption leg, optional on the injection one because Eneco prints none
+    (`("", None, None)`; `FormulaSpec.card_graded`)."""
     if leg is None:
         leg = _LEGS["price_formula"]
     if raw is None:
@@ -491,31 +263,8 @@ def _month_date(month: str):
 
 
 def parse_price_formula(value, *, option: str = "price_formula"):
-    """`price_formula` -> a `FormulaSpec`, or None when unset.
-
-    ⚠️ `option` IS TARIFF-16'S WHOLE REUSE, and it is TARIFF-17's move. It
-    selects a row of `_LEGS` and nothing else: the enumerations, the
-    arithmetic, `to_resolution()`, the unknown-key rule and the card
-    comparison are shared, and every pre-existing call site - which passes no
-    `option` at all - lands on the consumption row and reads byte-identical
-    sentences. `parse_export_formula()` is a two-line wrapper, not a fork.
-
-    Accepts what the option can actually arrive as, exactly as
-    `parse_static_profile()` does:
-
-      * `None` / `""` / `"null"`   - unset.
-      * a JSON string              - what config.yaml's flat `str?` option
-                                     carries on a Supervisor install.
-      * a dict                     - already parsed, from a future nested
-                                     schema, from sim/inject.py, or a check.
-
-    Raises `FormulaInvalid`; never returns a half-built spec.
-
-    ⚠️ THE CARD SELF-CHECK IS PART OF PARSING, not a separate step a caller
-    may forget. Both callers - validate.py's startup gate and the plugin's own
-    fetch - go through this one function, so there is no route to a price that
-    has not been graded against the card.
-    """
+    """`price_formula` -> a `FormulaSpec`, or None when unset. `option` selects a row of
+    `_LEGS`; everything else is shared, so `parse_export_formula()` is a wrapper."""
     leg = _LEGS[option]
     if value is None:
         return None
@@ -534,12 +283,8 @@ def parse_price_formula(value, *, option: str = "price_formula"):
             f"{option} is {type(value).__name__}, not a JSON object with "
             f"{', '.join(_TOP_KEYS)}.")
 
-    # ⚠️ AN UNKNOWN KEY IS REFUSED, NOT IGNORED, AND THIS IS THE HALF THAT
-    # KEEPS THE "NEVER A GRAMMAR" PROMISE HONEST. A future shape is a NAMED
-    # field - clamp_lo, factor_negative, offset_bands - added here and
-    # refusable on its own. Ignoring unknown keys would mean a user who typed
-    # "expr" or "formula" gets priced on the fields they also typed, with the
-    # one they believed in dropped in silence.
+    # An unknown key is refused, not ignored: a future shape is a NAMED field,
+    # never a grammar.
     unknown = sorted(set(value) - set(_TOP_KEYS))
     if unknown:
         raise FormulaInvalid(
@@ -559,10 +304,8 @@ def parse_price_formula(value, *, option: str = "price_formula"):
             f"{option}.resolution is {value.get('resolution')!r}. Choose one "
             f"of {list(RESOLUTIONS)}, as your tariff card says.")
 
-    # ⚠️ `units` IS REQUIRED AND HAS NO DEFAULT. A default here would be the
-    # factor-1000 class with a friendly face: the add-on would silently assume
-    # a convention the card never stated, and the card self-check would then
-    # be graded in units nobody chose.
+    # `units` is required with no default: a default is the factor-1000 class
+    # with a friendly face.
     units = str(value.get("units", "") or "").strip()
     if units not in UNITS:
         raise FormulaInvalid(
@@ -573,29 +316,22 @@ def parse_price_formula(value, *, option: str = "price_formula"):
     offset = _finite(value.get("offset"), "offset", option)
     vat_pct = _finite(value.get("vat_pct"), "vat_pct", option)
 
-    # ⚠️ ZERO IS NOT "NO INDEXATION", IT IS A FIXED TARIFF WEARING A DYNAMIC
-    # ONE'S CLOTHES. Every hour comes out at the same price, so every spread is
-    # 0, arbitrage can never clear any threshold, and a strategy that never
-    # fires is indistinguishable from one that is switched off (§14's warning
-    # box). The add-on already has a first-class way to say "one price": point
-    # the operator at it rather than let them build it by accident.
+    # Zero is a fixed tariff in a dynamic one's clothes (arbitrage never
+    # fires); point the operator at the first-class fixed price.
     if factor == 0.0:
         raise FormulaInvalid(
             f"{option}.factor is 0, so every hour gets the same {leg.what} "
             f"price{leg.zero_factor}. For one flat price, {leg.flat}.")
 
-    # ⚠️ A NEGATIVE FACTOR INVERTS THE MARKET, and the direction is the danger:
-    # the dearest hour becomes the cheapest one, so the battery is told to
-    # charge into the evening peak and to discharge at 03:00. That is not a
-    # mispriced site, it is a site actively trading against itself.
+    # A negative factor inverts the market: charge into the evening peak,
+    # discharge at 03:00.
     if factor < 0.0:
         raise FormulaInvalid(
             f"{option}.factor is {factor:g}, which turns the market upside "
             f"down. {leg.neg_factor}.")
 
-    # ⚠️ 0 IS LEGITIMATE AND MUST STAY SO: injection is VAT-exempt in Belgium,
-    # and some cards are already quoted VAT-inclusive. The bound exists for the
-    # 106 / 1.06 / 6 confusion, not to make VAT compulsory.
+    # 0 is legitimate (injection is VAT-exempt; some cards are VAT-inclusive);
+    # the bound is for the 106 / 1.06 / 6 confusion.
     if not 0.0 <= vat_pct <= 30.0:
         raise FormulaInvalid(
             f"{option}.vat_pct is {vat_pct:g}. Write a percentage between 0 "
@@ -607,13 +343,9 @@ def parse_price_formula(value, *, option: str = "price_formula"):
                        card_month=month, card_index_eur_per_mwh=card_index,
                        card_expect_incl_vat=card_expect, option=option)
 
-    # ⚠️ THE CARD SELF-CHECK STILL RUNS WHEREVER THERE IS A CARD TO RUN IT
-    # AGAINST, on either leg, with the same tolerance. What TARIFF-16 adds is
-    # the honest answer for the leg where the card prints no estimate: NOT a
-    # weakened comparison and NOT an estimate computed here, but two bounds on
-    # the COEFFICIENTS that need no printed price - see
-    # `implausible_injection()` - and a startup line saying the leg is
-    # ungraded.
+    # The card self-check still runs wherever there is a card, with the same
+    # tolerance. Where the card prints no estimate, `implausible_injection()`
+    # bounds the coefficients and a startup line says the leg is ungraded.
     if spec.card_graded:
         delta = card_discrepancy(spec)
         if abs(delta) > CARD_TOLERANCE:
@@ -626,60 +358,15 @@ def parse_price_formula(value, *, option: str = "price_formula"):
 
 
 def parse_export_formula(value):
-    """`price_export_formula` -> the INJECTION leg's `FormulaSpec`, or None.
-
-    TARIFF-16. THE DEFECT THIS EXISTS TO CLOSE: `price.py` modelled injection
-    as ONE scalar, and the market publishes a line with four properties a
-    scalar cannot hold. Verbatim off the cards:
-
-        Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c EUR/kWh
-            "Het injectietarief is dynamisch en kan per uur wijzigen"
-            - identical on the January and the September 2026 cards
-        ENGIE Dynamic                (B x eSpot_15) - A       c EUR/kWh
-        Aspiravi (non-dynamic)       0,07 x Belpex - 2
-
-      1. ITS OWN FACTOR. Eneco uses 0,102 on consumption and 0,100 on
-         injection; Aspiravi 0,07 against ~0,10 on its consumption leg. It is
-         NOT the consumption `B` with a sign flip.
-      2. A NEGATIVE OFFSET - `- 1,188`, `- 2`. Note that
-         `price_markup_eur_kwh: float(0,1)` cannot express a negative markup
-         at all, so the offset has no home on the consumption side either.
-      3. VAT-EXEMPT. "Injectietarieven zijn vrijgesteld van btw", while
-         consumption is at 6% - a SIX PERCENT ASYMMETRY between the buy leg
-         and the sell leg, which a single scalar cannot even state.
-      4. IT GOES NEGATIVE, WITH NO FLOOR. Eneco's injection price is negative
-         for any BELPEX-H below 11,88 EUR/MWh, and a PV household exports
-         precisely in the hours most likely to be negative. You can be charged
-         to export.
-
-    ⚠️ AND WHAT THIS DOES **NOT** AFFECT TODAY, SAID HERE SO NOBODY READS THE
-    ABOVE AS A TRADING BUG. `arbitrage.py` does not read
-    `export_price_eur_kwh` at all - its own comment says so, and gives §9.3's
-    near-zero Belgian injection price as the reason the economically sound
-    trade on this market is charge-cheap-to-displace-expensive-IMPORT. Both
-    hours it compares are all-in CONSUMPTION prices. So no trade the add-on
-    takes today is decided by this number, and this card is not a correction
-    of a wrong trade. What it changes is what an operator is told, and what
-    any future export-aware strategy would rest on: OPT-06 and any export
-    logic would otherwise inherit a scalar that cannot represent the market,
-    and the 6% VAT asymmetry would be invisible in the arithmetic.
-
-    ⚠️ THE SCALAR IS NOT REPLACED. `export_price_eur_kwh()` is untouched and
-    still answers for every site with a flat injection price, which is every
-    site that exists today; this option ships "". That is `price.py`'s own
-    prediction coming true rather than a new design - "when it does land, an
-    injection curve gets a `PriceProvider` of its own and this scalar becomes
-    its FIXED-product default; the seam is already the right shape for that."
-    """
+    """`price_export_formula` -> the INJECTION leg's `FormulaSpec`, or None (TARIFF-16).
+    Same parser with `option` moved; the flat `export_price_eur_kwh()` still answers
+    when unset. Nothing trades on it today. DECISIONS/TARIFF-16-the-injection-leg.md."""
     return parse_price_formula(value, option=EXPORT_FORMULA_OPTION)
 
 
 def card_refusal(spec: FormulaSpec, delta: float) -> str:
-    """The sentence an operator reads when their formula misses its own card.
-
-    It names both numbers and what to check. The usual causes are in DOCS.md,
-    because each of these errors looks like a working tariff on the status page.
-    """
+    """The sentence an operator reads when their formula misses its own card: both
+    numbers and what to check (causes are in DOCS.md)."""
     got = in_card_units(spec, spec.card_index_eur_per_mwh)
     leg = _LEGS[spec.option]
     return (
@@ -688,53 +375,14 @@ def card_refusal(spec: FormulaSpec, delta: float) -> str:
         f"{spec.card_expect_incl_vat:g}. Check {leg.card_causes}.")
 
 
-# --------------------------------------------------------------------------- #
 # The two questions the PLUGIN cannot ask, because they need framework numbers
-# --------------------------------------------------------------------------- #
 
 def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
-    """The card's own point, if its LEVEL cannot be a Belgian retail price.
-
-    Returns a refusal sentence or None. ⚠️ CALLED FROM validate.py AND FROM
-    NOWHERE ELSE, because it reads a FRAMEWORK-owned number: a plugin that
-    could see `taxes` could add it a second time, which is price.py's trap 1.
-
-    ⚠️ THE LOW END IS GRADED ON THE ENERGY COMPONENT AND THE HIGH END ON THE
-    ALL-IN FIGURE, AND THAT ASYMMETRY IS THE CHECK RATHER THAN AN OVERSIGHT.
-    `price_taxes_eur_kwh` ships at 0.11736 (TARIFF-18; it was 0.06 before, and
-    the argument was already decisive at that figure), which is nearly SIX
-    times the low bound - so a card read a HUNDRED times too small comes out at
-    0.0016 EUR/kWh of energy, is carried over the floor by the flat tax addend
-    alone, and passes a band applied to the all-in total. The hundredfold error
-    is precisely what this exists to catch, so the floor is applied where it
-    can still see it. ⚠️ Raising the default made this trap WIDER, not
-    narrower: the addend that does the carrying got bigger. The ceiling is
-    applied to the all-in figure because that is the number the site is really
-    billed at, and taxes only push it up.
-
-    ⚠️ AND THE LIMIT, WITH THE CLAIM. This grades the CARD'S OWN POINT - one
-    price, at the monthly index the card assumed - and not every hour of every
-    day. A live EPEX hour can and should fall outside this band (a negative
-    hour is the best charging opportunity of the year, and §17 keeps a
-    regression case for it), so the band is deliberately NOT applied to the
-    fetched series. What it catches is a formula whose whole LEVEL is wrong,
-    which is the factor-of-1000 class arriving from the end
-    `MAX_PLAUSIBLE_EUR_KWH` does not bound.
-
-    ⚠️ AND IT IS THE CONSUMPTION LEG'S BAND ONLY - TARIFF-16 DELIBERATELY DID
-    NOT POINT IT AT THE INJECTION LEG. Two reasons, and the second is an
-    acceptance criterion rather than a preference:
-
-      * it adds `taxes_eur_kwh`, and `price_taxes_eur_kwh` is a CONSUMPTION
-        component. Nothing is added to what a site is PAID for export, so the
-        `all_in` half would be adding a number the injection leg never carries;
-      * its floor is `energy >= 0.02 EUR/kWh`, and a REAL Eneco injection price
-        is negative for any BELPEX-H below 11,88 EUR/MWh - the hours a PV
-        household actually exports in. Applied to injection this floor would
-        refuse the market, and refuse it hardest in the hours where knowing the
-        number matters most. `implausible_injection()` is the injection band
-        and it is deliberately NOT this function with a lower floor.
-    """
+    """The card's own point, if its LEVEL cannot be a Belgian retail price. Refusal
+    sentence or None. Called from validate.py only (it reads the framework-owned
+    taxes). The low end is graded on the energy component and the high end on the
+    all-in figure; the consumption leg's band only. It grades the card's own point,
+    not the fetched series. DECISIONS/TARIFF-16-the-injection-leg.md."""
     energy = price_eur_kwh(spec, spec.card_index_eur_per_mwh)
     all_in = energy + float(taxes_eur_kwh)
     if energy >= PLAUSIBLE_LO_EUR_KWH and all_in <= PLAUSIBLE_HI_EUR_KWH:
@@ -747,49 +395,10 @@ def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
 
 
 def implausible_injection(spec: FormulaSpec):
-    """The INJECTION leg's plausibility band. Returns a refusal or None.
-
-    ⚠️ A NEGATIVE INJECTION PRICE IS ACCEPTED, NOT REFUSED, AND NEITHER RUNG
-    BELOW LOOKS AT THE SIGN OR THE LEVEL OF A PRICE. Eneco's published line
-    `0,1 x BELPEX-H - 1,188` is negative for any BELPEX-H under 11,88 EUR/MWh;
-    those are the midday hours a PV household exports in, so a band with a
-    floor above zero - which is what `implausible_all_in()` has, for the
-    consumption leg's own good reasons - would refuse the real market and
-    would hide it in exactly the hours it costs money. You CAN be charged to
-    export. The add-on says so rather than declining to represent it.
-
-    THE PROBLEM THAT LEAVES, STATED BEFORE THE SOLUTION. The consumption
-    floor was not decoration: it is what catches a whole card read a hundred
-    times too small, the one unit error the card self-check cannot see because
-    it cancels out of a comparison between the two sides. A band that spans
-    zero cannot catch it - 0.00132 EUR/kWh is inside any interval that
-    contains -0.03. So the bound moves OFF the price and ONTO the
-    coefficients, where it is index-free and sign-free:
-
-      * PASS-THROUGH. `factor x UNITS[units] / 0.001` is the dimensionless
-        share of the wholesale price the contract passes through, because one
-        EUR/MWh IS 0.001 EUR/kWh. Eneco's injection leg is 1.00 and Aspiravi's
-        is 0.70. A factor typed 100x too small reads 0.01 and 100x too large
-        reads 100, whatever the index and whatever the sign of the result.
-      * OFFSET MAGNITUDE. Eneco's is 1,188 c EUR/kWh = 0.01188 EUR/kWh and
-        Aspiravi's is 2 c = 0.02. A hundredfold error is 1.188 EUR/kWh, which
-        is not an injection tariff in any direction. The bound is on the
-        ABSOLUTE value, so a negative offset of a believable size passes and
-        that is the normal case on this leg.
-
-    ⚠️ TWO RUNGS THAT CAN BOTH ANSWER ONE STIMULUS, SO THEY ARE GRADED ON
-    THEIR REASONS AND MUTATED TOGETHER (MUTATION.md, TEST-16). A whole card
-    read 100x too large trips both. The fixtures in test_price.py 17d are
-    built so that each rung is the ONLY one that fires on its own stimulus.
-
-    ⚠️ AND WHAT THIS CANNOT SEE, WITH THE CLAIM (habit 13). It bounds the
-    SHAPE of the coefficients, never their truth: a contract really written
-    against a different index, or last year's coefficients, passes both rungs
-    and reproduces any card typed beside them. Where a card DOES print an
-    estimate the self-check grades the pair against it; where it does not -
-    which is Eneco's injection line - these two bounds are the whole of what
-    is mechanised, and validate.py says so at startup.
-    """
+    """The INJECTION leg's plausibility band. Refusal or None. A negative price is
+    accepted; the bounds are on the coefficients (pass-through and offset
+    magnitude), since a band spanning zero cannot catch a card 100x too small. It
+    bounds the shape, not the truth. DECISIONS/TARIFF-16-the-injection-leg.md."""
     if not PASSTHROUGH_LO <= spec.passthrough <= PASSTHROUGH_HI:
         return (
             f"{spec.option}.factor passes through {spec.passthrough:.4g}x the "
@@ -806,10 +415,7 @@ def implausible_injection(spec: FormulaSpec):
 
 
 def stale_card(spec: FormulaSpec, today=None):
-    """A warning when the card is older than ~6 months, or None. NEVER a
-    refusal: ENGIE freezes a contract's coefficients for its duration, so an
-    old card can be exactly right and refusing one would stop the add-on on a
-    correctly configured site."""
+    """A warning when the card is older than ~6 months, or None. Never a refusal (ENGIE freezes coefficients)."""
     dated = _month_date(spec.card_month)
     now = today or datetime.now(timezone.utc).date()
     if dated is None or (now - dated).days <= CARD_STALE_DAYS:
@@ -820,36 +426,14 @@ def stale_card(spec: FormulaSpec, today=None):
         f"contract changed since, copy the new figures from your supplier.")
 
 
-# --------------------------------------------------------------------------- #
 # Resolution
-# --------------------------------------------------------------------------- #
 
 def to_resolution(pairs, resolution: str) -> list:
     """`[(instant, index EUR/MWh)]` -> the series the CONTRACT is written on.
-
-    `quarter_hourly` hands the feed's own points back, ascending.
-    `hourly` averages each hour's members into one point AT THE TOP OF THE
-    HOUR.
-
-    ⚠️ THE BUCKET IS A UTC HOUR AND THAT IS EXACT FOR BELGIUM, not an
-    approximation: CET and CEST are both WHOLE-hour offsets, so a Brussels hour
-    and a UTC hour start at the same instant on every day of the year including
-    both transition days. Keying by a naive local hour is what collides the two
-    02:00s in October; keying by the UTC instant cannot.
-
-    ⚠️ AND THIS IS NOT `_Series.at()`'s HOURLY ASSUMPTION COMING BACK
-    (TARIFF-14). It decides how many points are EMITTED, not how long one
-    covers - the coverage window is still derived from the neighbours in
-    `_cover_table()`. A feed that already publishes hourly points averages one
-    member per hour, i.e. the identity, so this cannot silently assume the
-    granularity it was handed.
-
-    ⚠️ AN INCOMPLETE HOUR IS AVERAGED OVER WHAT IS THERE rather than dropped or
-    zero-filled. A horizon that starts at 09:20 has two quarters in its first
-    hour; their mean is the best statement available about that hour, and
-    dropping it would leave a hole `at()` answers with `Absence` for an hour
-    the feed did publish.
-    """
+    `quarter_hourly` returns the feed's points, `hourly` averages each UTC hour
+    (exact for Belgium: whole-hour offsets) at the top of the hour. An incomplete
+    hour is averaged over what is there. It sets how many points are emitted, not
+    how long one covers (TARIFF-14)."""
     ordered = sorted(pairs, key=lambda r: r[0].astimezone(timezone.utc))
     if resolution == "quarter_hourly":
         return list(ordered)
@@ -863,28 +447,16 @@ def to_resolution(pairs, resolution: str) -> list:
     return [(k, sum(v) / len(v)) for k, v in sorted(buckets.items())]
 
 
-# --------------------------------------------------------------------------- #
 # The startup preview
-# --------------------------------------------------------------------------- #
 
 PREVIEW_HOURS = 24
 PREVIEW_MAX_ROWS = 24
 
 
 def preview_lines(spec: FormulaSpec, rows) -> list:
-    """`[(instant, index EUR/MWh, all-in EUR/kWh)]` -> lines for the log.
-
-    THE DEFECT THIS EXISTS TO MAKE VISIBLE: every error this module refuses is
-    one the operator cannot see from the status page, and the two numbers that
-    would have shown it - the index that went IN and the price that came OUT -
-    are never printed beside each other anywhere else. A factor of 1000 is
-    obvious in one line of `61.96 -> 0.13522` and invisible in a plan.
-
-    ⚠️ IT PRINTS A BOUNDED NUMBER OF ROWS AND SAYS SO. At `quarter_hourly` the
-    next 24 h is 96 points; the cap is a row COUNT rather than "every fourth
-    point", because sampling every fourth point would assume the granularity
-    TARIFF-14 spent a card removing the assumption of.
-    """
+    """`[(instant, index EUR/MWh, all-in EUR/kWh)]` -> lines for the log: the index
+    that went IN beside the price that came OUT. Prints a bounded row COUNT, not
+    every fourth point (that would assume the granularity)."""
     if not rows:
         return []
     shown = rows[:PREVIEW_MAX_ROWS]

goodwe_controller/app/dayview.py

@@ -23,7 +23,7 @@ from . import arbitrage, dayplan, homeview as hv, modetrade, priceruns
 from . import solarfc
 from .daycurve import Batt, curve
 from .packmode import SOLAR_FIRST
-from .price import Uncertainty, brussels, required_spread, uncertainty_of
+from .price import brussels, required_spread, uncertainty_of
 
 BLOCKS = ("grid", "give", "cycle")      # the kinds a battery's blocks carry
 LEVEL_DP = 1                            # the tab shows a level to 0.1 %
@@ -204,9 +204,12 @@ def _levels(c, est, fc, trust, now, end, runs, floor, ceil, notes_b, shadow,
     end_t = None
     if plan_on and cheap is not None and rp.charge_useful() \
             and n0 <= cheap.start < n1 and plan is not None:
+        # The gap control's run plan needs (TARIFF-24): no x1.5 with a
+        # forecast read.
         required = required_spread(
             arbitrage.threshold_eur_kwh(c.o),
-            uncertainty_of(plan.read.product) | {Uncertainty.NO_WEATHER})
+            uncertainty_of(plan.read.product)
+            | arbitrage.weather_uncertainty(True, c.solar_fc))
         end_t = cheap.end
         for _ in range(24):
             ext = dataclasses.replace(rp, cheap=priceruns.Run(
@@ -368,7 +371,8 @@ def _day(c, k, d0, d1, now, fc, house, trust, levels, blocks, rows, shadow,
     if fc is not None:
         if k == 0:
             line = hv.line_solar(fc.today.kwh, fc.today.kwh * trust,
-                                 hv.hhmm(fc.at))
+                                 hv.hhmm(fc.at),
+                                 kept=getattr(fc, "kept", False))
         elif fc.tomorrow is not None:
             line = hv.day_note("tomorrow_total",
                                kwh=hv._kwh(fc.tomorrow.kwh),

goodwe_controller/app/homeview.py

@@ -24,7 +24,7 @@ from .dayplan import EFF
 from .maintenance import CHARGE as M_CHARGE, DRAIN as M_DRAIN, HOLD as M_HOLD
 from .maintenance import IDLE as M_IDLE, next_slot_start
 from .packmode import CHEAP_HOURS, GRID_CHARGE_MODES, LEFTOVER_SOLAR, SOLAR_FIRST
-from .price import Absence, Uncertainty, brussels, _cover_table
+from .price import Absence, brussels, _cover_table
 from .static_tariff import static_plan
 from .tariff import BILLING_TZ
 from .uimodel import REGION_PRESETS, options_to_ui
@@ -280,7 +280,11 @@ def trade_verdict(c, plan, now):
         return None, "no_prices"
     verdict = plan.arbitrage(peak_guard_active=guard,
                              min_spread_eur_kwh=arbitrage.threshold_eur_kwh(c.o),
-                             uncertainty=frozenset({Uncertainty.NO_WEATHER}),
+                             uncertainty=arbitrage.weather_uncertainty(
+                                 bool(getattr(c, "modes_on", False)),
+                                 getattr(c, "solar_fc", None),
+                                 bool(getattr(c, "weather_held",
+                                              lambda _n: False)(now))),
                              now=now)
     return verdict.match(
         allowed=lambda v: (v, "allowed"),
@@ -531,15 +535,29 @@ def plan_cover(c, name):
     return targets[name], max(0.0, top - floor) / 100.0 * cap * EFF
 
 
+def _latched_below(c) -> bool:
+    """OPT-34: no forecast, but a cheap run is on and a battery is still below
+    the level its night charge keeps (`Controller.plan_targets()`), so control
+    goes on charging."""
+    rp = getattr(c, "mode_runs", None)
+    if rp is None or rp.cheap is None or not rp.cheap.holds(
+            datetime.now(timezone.utc)):
+        return False
+    targets = getattr(c, "plan_targets", lambda: None)() or {}
+    return any(inv.soc is not None and inv.name in targets
+               and inv.soc < targets[inv.name] for inv in c.inverters)
+
+
 def plan_state(c):
     """P4: `"plan"` (a day plan is made), `"learning"` (no house profile
-    yet), `"no_forecast"` (set but missing or stale), or None (not set, or
-    battery modes off)."""
+    yet), `"no_forecast"` (set but missing or stale), `"latched"` (OPT-34:
+    the same, but a night charge under way is still going on to its level),
+    or None (not set, or battery modes off)."""
     if not getattr(c, "modes_on", False) or \
             getattr(c, "fc_entity", None) is None:
         return None
     if getattr(c, "solar_fc", None) is None:
-        return "no_forecast"
+        return "latched" if _latched_below(c) else "no_forecast"
     hp = getattr(c, "house_profile", None)
     if hp is not None and not hp.ready():
         return "learning"
@@ -560,11 +578,12 @@ def solar_block(c, now):
         out.update(fc_kwh=round(fc.today.kwh, 1),
                    count_kwh=round(fc.today.kwh * trust, 1),
                    updated=hhmm(fc.at))
-    if st in ("no_forecast", "learning"):
+    if st in ("no_forecast", "learning", "latched"):
         out["line"] = _t("solar." + st)
     elif fc is not None:
         out["line"] = line_solar(fc.today.kwh, out["count_kwh"],
-                                 out["updated"])
+                                 out["updated"],
+                                 kept=getattr(fc, "kept", False))
         dp = getattr(c, "day_plan", None)
         if st == "plan" and dp is not None and dp.uncovered_kwh >= MIN_KWH:
             out["line"] += " " + line_uncovered(dp.uncovered_kwh)
@@ -813,9 +832,11 @@ def refusing(c, inv) -> int:
 def peak_engaged(c) -> bool:
     """The peak guard asks the batteries for power this cycle. Not when it is
     blind or floor-limited: those are engaged with a 0 W floor (no charging
-    only), so no battery gives power for it."""
+    only), so no battery gives power for it. Nor when the quarter ends on
+    the aim anyway (SAFETY-126, `within_aim`)."""
     pg = getattr(c, "peak_guard", None)
-    return bool(pg is not None and pg.engaged and (pg.floor_w or 0.0) > 0.0)
+    return bool(pg is not None and pg.engaged and (pg.floor_w or 0.0) > 0.0
+                and not pg.within_aim)
 
 
 def battery_rows(c, shadow, running, held=False):
@@ -1058,7 +1079,8 @@ def month_peak(c, now):
         ceiling = pg.ceiling_w or limit_w
     out["line"] = line_period(out["period_w"], ceiling, c.shadow,
                               unmeasured=getattr(c, "peak_unmeasured_s", 0.0)
-                              > 0.0)
+                              > 0.0,
+                              cut=getattr(c, "room_charge", False))
     return out
 
 
@@ -1441,7 +1463,11 @@ def day_note(key, **values) -> str:
     return _t("day." + key, **values)
 
 
-def line_solar(fc_kwh, count_kwh, at) -> str:
+def line_solar(fc_kwh, count_kwh, at, kept=False) -> str:
+    """The forecast line. OPT-27: a reading kept past three hours (the
+    evening's, used at night) says so instead of "Updated"."""
+    if kept:
+        return _t("solar.kept", at=at)
     return _t("solar.line", kwh=_kwh(fc_kwh), count=_kwh(count_kwh), at=at)
 
 
@@ -1504,13 +1530,19 @@ def line_peak_not_covered() -> str:
     return _t("peak_not_covered")
 
 
-def line_period(period_w, limit_w, shadow, unmeasured=False) -> str:
+def line_period(period_w, limit_w, shadow, unmeasured=False,
+                cut=False) -> str:
     step = _w(shadow, "step_in", kw=_kw(limit_w))
     if unmeasured:
         # SAFETY-90: the add-on started during this period.
         return _t("period_unmeasured") + " " + step
     if period_w is None:
         return step
+    if period_w > limit_w:
+        # SAFETY-125: the figure is the current rate, and a grid charge is
+        # what gets cut back.
+        return _t("period_over", kw=_kw(period_w)) + " " + (
+            _w(shadow, "charge_cut", kw=_kw(limit_w)) if cut else step)
     return _t("period", kw=_kw(period_w)) + " " + step
 
 
@@ -1584,6 +1616,8 @@ def _samples() -> list:
                 ("plan", line_period(1240, 3500, sh)),
                 ("plan", line_period(None, 3500, sh)),
                 ("plan", line_period(1240, 3500, sh, unmeasured=True)),
+                ("plan", line_period(5814, 5413, sh)),
+                ("plan", line_period(5814, 5413, sh, cut=True)),
                 ("plan", control_text(True, sh)),
                 ("plan", control_text(False, sh))]
     out += [("plan", run_grid_why(0.1412)), ("plan", run_grid_amount(1.23)),
@@ -1622,7 +1656,8 @@ def _samples() -> list:
                                kwh="9.4 kWh")) for k in words["why"]]
     out += [("plan", today_words(k)) for k in words["today"]]
     out += [("plan", line_solar(9.2, 6.4, "10:15")),
-            ("plan", _t("solar.no_forecast")), ("plan", _t("solar.learning"))]
+            ("plan", _t("solar.no_forecast")), ("plan", _t("solar.learning")),
+            ("plan", _t("solar.latched"))]
     out += [("plan", day_note(k, pct=70, name="Battery A", at="08:15",
                               kwh="9.2 kWh", count="6.4 kWh"))
             for k in words["day"]]

goodwe_controller/app/main.py

@@ -175,57 +175,17 @@ TARIFF_MAX_AGE_S = 3 * TARIFF_REFRESH_S
 
 
 def tariff_refresh_wanted(opts: dict) -> bool:
-    """TARIFF-10. Does this install need the background tariff refresh at all?
+    """Does this install need the background tariff refresh? (TARIFF-10, TARIFF-24)
 
-    THE DEFECT THIS PREVENTS, and it shipped: the gate below used to be
-    `arbitrage.enabled(opts)` alone. That option defaults to `false`, and
-    `run_tariff_refresh` is the only caller of `resolve_tariff()`, which is the
-    only caller of `price_history.carry()` - so on a shipped install with a
-    provider configured NOTHING was ever fetched, no plan was ever resolved,
-    `/data/price_history.json` was never created, the *Price history* row read
-    `empty` forever, and TARIFF-09's short-horizon warning could not fire
-    because there was no fetch to warn about. Measured over a 40 h soak of two
-    instances side by side: zero feed requests and `present: false` across all
-    802 samples on the shipped default, against a resolved plan from the same
-    feed on the instance with arbitrage armed. ⚠️ AND `DOCS.md` HAS
-    DESCRIBED THE BEHAVIOUR BELOW SINCE THE COMMIT THAT WROTE THE GATE:
-    OPT-04 (bdd7f18) added the refresh task, the `arbitrage.enabled()` guard on
-    it, and the sentence saying a configured provider still fetches, all in one
-    change. config.yaml has said it since TARIFF-02 (852fc7c).
-
-    Two terms, and they answer two different questions:
-
-      provider_configured(opts) -> "the operator asked for a price feed", so
-                                   fetch it, validate it and record the day
-                                   (§8.3). This is the term TARIFF-10 ADDS.
-      arbitrage.enabled(opts)   -> "the operator armed trading". This term is
-                                   what the gate USED to be, kept verbatim.
-
-    ⚠️ IT IS AN `or`, SO THE GATE IS A STRICT WIDENING. Every configuration
-    that started this task before still starts it; none that did not start it
-    stops anything. That matters because the second term is not redundant:
-    `price_provider: off` + a `static_profile` + `arbitrage_enabled: true` is a
-    configuration validate.py explicitly ACCEPTS, and it trades - measured, at
-    `cycle_cost_threshold_eur: 0.05` on a 0.20/0.284 day/night profile,
-    `ARBITRAGE_CHARGE -5000 W`. Dropping that term to make the gate read
-    `provider_configured(opts)` alone would leave `self.tariff_plan` at None on
-    that site forever and `decide()` would answer "no tariff plan has been
-    resolved yet" on every cycle - silently disarming a strategy the UI says is
-    running, which is the exact failure validate.py's OPT-04 rules exist to
-    refuse.
-
-    ⚠️ AND NO CONFIGURATION ACQUIRES A PERIODIC HTTPS CALL FROM THIS TICKET.
-    With `price_provider` off, `resolve_tariff()` returns `static_plan()` - pure
-    arithmetic, no socket - so the second term starts a task that fetches
-    nothing. The true shipped default (no provider, no arbitrage) starts no
-    task at all. What is fetched is decided by the FIRST term only.
-
-    ⚠️ THIS IS NOT A TRADING SWITCH. It decides whether prices are LOOKED UP.
-    Whether they move energy is `arbitrage.enabled()` at the one call site in
-    `cycle()`, and TARIFF-10 did not touch it: `arbitrage_enabled: false` still
-    means no trade, ever, on any configuration.
+    Yes with a price feed, with trading on price armed, or with battery modes
+    on: the modes read `self.tariff_plan` for their price runs. With
+    `price_provider` off the refresh is pure arithmetic on `static_profile`, so
+    no term here adds an HTTPS call. It decides whether prices are looked up,
+    never whether energy moves. See DECISIONS/TARIFF-10-fetching-is-not-trading.md
+    and DECISIONS/TARIFF-24-modes-need-the-tariff-task.md.
     """
-    return provider_configured(opts) or arbitrage.enabled(opts)
+    return (provider_configured(opts) or arbitrage.enabled(opts)
+            or packmode.enabled(opts))
 
 
 def load_options() -> dict:
@@ -248,9 +208,44 @@ EDGE_HOLD_S = _ctl.PLANT_SETTLE_S
 # OPT-11 P4: the store key of the house profile (dayplan.HouseProfile), and
 # how often the forecast sensors are read (they change hourly at most).
 HOUSE_PROFILE_KEY = "house_profile"
+# OPT-27: the forecast sensors' last fresh readings (`solarfc.Hold`), so an
+# evening restart keeps the figure the night plan uses.
+FC_HOLD_KEY = "solar_fc_hold"
+# OPT-34: the level of a night grid charge that has started, so it does not
+# drop when the forecast goes (`Controller._latch_charge()`).
+CHARGE_LATCH_KEY = "night_charge_latch"
+# OPT-34: a latch outlives the cheap run it was last used in by one price
+# slot, because the next run is planned at the slot edge, in the cycle after
+# the old one ended.
+CHARGE_LATCH_GRACE_S = 900.0
 FORECAST_READ_S = 60.0
 
 
+def _load_latch(data, now=None):
+    """`(until, {name: level %}, born)` from the store, or None if it is not a
+    well-formed latch or has ended (OPT-34)."""
+    try:
+        until = datetime.fromisoformat(data["until"])
+        born = datetime.fromisoformat(data.get("born") or data["until"])
+        levels = {str(n): float(v) for n, v in data["levels"].items()}
+    except (TypeError, KeyError, ValueError, AttributeError):
+        return None
+    if until.tzinfo is None or born.tzinfo is None or not levels or not all(
+            math.isfinite(v) and 0.0 <= v <= 100.0 for v in levels.values()):
+        return None
+    if now is not None and now >= until:
+        return None
+    return until, levels, born
+
+
+def _night_limit(born):
+    """OPT-34: a run that starts after this cannot carry the latch on: the
+    first bell start (`solarfc.BELL_FROM_H`, local) after `born`."""
+    d0, d1 = solarfc._bounds(born)
+    bell = solarfc._bell_start(d0)
+    return bell if bell > born else solarfc._bell_start(d1)
+
+
 def why_raised(resolution, claims) -> bool:
     """F2 (OPT-11 P1 test): did the limit that bound the site target push it
     ABOVE what the winner asked (the peak floor asking for more power)? Then
@@ -987,6 +982,9 @@ class Controller:
         # SAFETY-87: the reserve alarm's hold, as SAFETY-81's above.
         self._reserve_batt_prev = None
         self._reserve_high_since = None
+        # SAFETY-126: `_peak_landing()`'s last battery reading and latch.
+        self._land_batt_prev = None
+        self._peak_needed = False
         self._maint_shape_suspended = False
         # OPT-11. Battery modes, off by default so an install that has not
         # turned them on behaves exactly as before (SAFETY-10 section 1). Each
@@ -1001,6 +999,9 @@ class Controller:
         # and whether last tick filed a mode trade (a run edge reseeds).
         self.mode_runs = None
         self._runs_key = None
+        # TARIFF-24: the end of the run that was under way while a forecast
+        # was read; until then losing the forecast does not widen the gap.
+        self._wx_free_to = None
         self.mode_tick = None
         # UX-53: why the trade gate refused a grid charge this tick (`peak`,
         # `not_worth`, `not_covered`), or None when it allowed one. Home reads
@@ -1032,8 +1033,14 @@ class Controller:
         self.solar_fc_why = (solarfc.NOT_SET if self.fc_entity is None
                              else solarfc.MISSING)
         self._fc_read_mono = None
+        self.fc_hold = solarfc.Hold(
+            (getattr(store, "data", None) or {}).get(FC_HOLD_KEY))
         self.day_plan = None
         self._plan_targets = None
+        # OPT-34: `(until, {name: level %})` of a night charge under way.
+        self._charge_latch = _load_latch(
+            (getattr(store, "data", None) or {}).get(CHARGE_LATCH_KEY),
+            datetime.now(timezone.utc))
         self.house_profile = None
         if self.fc_entity is not None:
             self.house_profile = dayplan.HouseProfile(
@@ -1259,6 +1266,8 @@ class Controller:
         # because `self.peak_guard` is a different cycle's decision by the time
         # the status page renders.
         self.arb_headroom_w = None
+        # SAFETY-125: a grid charge sized to the quarter's room this cycle.
+        self.room_charge = False
         # UX-13 P1: today's prices as the Home chart has seen them. Display
         # only; nothing reads it back into a decision.
         self.home_prices = homeview.DayPrices()
@@ -2274,6 +2283,32 @@ class Controller:
                 probing=probing))
         return out
 
+    def _wx_track(self, now) -> None:
+        """TARIFF-24, once per cycle, before the plan: with a forecast read,
+        remember when the run now under way (cheap, give or sell) ends."""
+        if self.solar_fc is None:
+            return
+        rp = self.mode_runs
+        ends = []
+        if rp is not None and rp.on:
+            ends = [r.end for r in (rp.cheap, rp.sell)
+                    if r is not None and r.holds(now)]
+            g = rp.give_at(now)
+            if g is not None:
+                ends.append(g.end)
+        self._wx_free_to = max(ends) if ends else None
+
+    def weather_held(self, now) -> bool:
+        """TARIFF-24: no forecast now, but a run planned with one is under
+        way: it keeps its gap to its end. The wider gap applies from the next
+        run. OPT-34: a night charge that keeps its level (`_latch_charge()`)
+        keeps the gap too, run after run, or the next slice of it would be
+        refused. Pure; Home asks the same (`homeview.trade_verdict()`)."""
+        return self.solar_fc is None and (
+            (self._wx_free_to is not None and now < self._wx_free_to)
+            or (self._charge_latch is not None
+                and now < self._charge_latch[0]))
+
     def _price_runs(self, now, packs, floor_pct, ceiling_pct):
         """The kept run plan, rebuilt at most once per price slot (15 min) or
         when the prices or a battery's choice change; a run under way is
@@ -2287,9 +2322,11 @@ class Controller:
         slot = int(now.timestamp() // 900)
         key = (id(plan), slot, tuple((p.name, p.use, p.mode, p.sell)
                                      for p in packs))
+        held = self.weather_held(now)
         if self.fc_entity is not None:
-            # P4: a forecast arriving or going rebuilds the plan at once.
-            key += (self.solar_fc is None,)
+            # P4: a forecast arriving or going rebuilds the plan at once (and
+            # so does the end of a run that held the gap, TARIFF-24).
+            key += (self.solar_fc is None, held)
         if key != self._runs_key:
             done_c = self._run_done.get("charge", (None, set()))[1]
             done_s = self._run_done.get("sell", (None, set()))[1]
@@ -2298,7 +2335,7 @@ class Controller:
             required = price_required_spread(
                 arbitrage.threshold_eur_kwh(self.o),
                 price_uncertainty_of(plan.read.product)
-                | {Uncertainty.NO_WEATHER})
+                | arbitrage.weather_uncertainty(True, self.solar_fc, held))
             ref = self._ref_cheap
             if ref is not None and now - ref.end > REF_CHEAP_KEEP:
                 ref = self._ref_cheap = None
@@ -2355,11 +2392,73 @@ class Controller:
 
     def plan_targets(self):
         """P4: each battery's planned level, or None (no day plan). Dropped
-        at once when the forecast goes (stale or missing)."""
+        at once when the forecast goes (stale or missing), except the level
+        of a night charge that has started (OPT-34): it keeps that level."""
         if self.solar_fc is None:
-            return None
+            lt = self._charge_latch
+            if lt is None or datetime.now(timezone.utc) >= lt[0]:
+                return None
+            return dict(lt[1])
         return self._plan_targets
 
+    def _latch_charge(self, now, runs, targets, packs=None) -> None:
+        """OPT-34, once per cycle after `modetrade.decide()`. A night grid
+        charge that has started keeps its planned level when the forecast goes
+        mid-charge (the kept figure ends and the sensors are still silent).
+
+        While there is a forecast, fresh or kept, the latch is rebuilt each
+        cycle from the plan: a battery that charges from the grid in the cheap
+        run comes in with its planned level, and stays in it at whatever level
+        the plan gives it, up or down as a fresh figure moves it (also when it
+        has stopped, at a lowered level), until it leaves the plan. While there
+        is none, `plan_targets()` gives the latched levels, so the charge goes
+        on to them, and `weather_held()` keeps the narrow price gap. The latch
+        lasts through every cheap run on and one price slot after the last
+        (`CHARGE_LATCH_GRACE_S`), but a run is carried on only if it starts
+        by the bell start of the night the latch began in (`_night_limit()`;
+        the run under way then finishes). It is dropped when `now` passes its
+        end whatever the run state, and a battery that is off or no longer in
+        a mode with a planned level (`packs`) leaves it. A charge that never
+        started has none."""
+        old = lt = self._charge_latch
+        tick = self.mode_tick
+        run = None if runs is None else runs.cheap
+        in_run = run is not None and run.holds(now)
+        grace = timedelta(seconds=CHARGE_LATCH_GRACE_S)
+        if lt is not None and now >= lt[0]:
+            lt = None
+        if lt is not None and packs is not None:
+            ok = {p.name for p in packs
+                  if p.use and p.mode in packmode.PLAN_CHARGE_MODES}
+            lv = {n: v for n, v in lt[1].items() if n in ok}
+            lt = (lt[0], lv, lt[2]) if lv else None
+        # A run may carry the latch on only if it starts by the night's bell.
+        carry = in_run and (lt is None or run.start <= _night_limit(lt[2]))
+        if in_run and self.solar_fc is not None:
+            # Rebuilt from the plan: a battery already latched follows its
+            # level up or down whatever its role this tick (a fresh figure may
+            # lower it below the SoC), one that left the plan is dropped, and
+            # a new one comes in only while it charges from the grid.
+            tg = targets or {}
+            lv = {n: float(tg[n]) for n in (lt[1] if lt else {}) if n in tg}
+            if tick is not None and tick.action == modetrade.CHARGE:
+                lv.update({n: float(tg[n]) for n, r in tick.roles.items()
+                           if r == modetrade.CHARGE and n in tg})
+            if not lv:
+                lt = None
+            elif lt is None:
+                lt = (run.end + grace, lv, now)
+            else:
+                lt = (max(run.end + grace, lt[0]) if carry else lt[0], lv,
+                      lt[2])
+        elif lt is not None and carry:
+            lt = (max(lt[0], run.end + grace), lt[1], lt[2])
+        if lt != old:
+            self._charge_latch = lt
+            self.store.set(CHARGE_LATCH_KEY, None if lt is None else {
+                "until": lt[0].isoformat(), "levels": lt[1],
+                "born": lt[2].isoformat()})
+
     def _mode_roles(self, now, maint_results):
         """OPT-11 P3: each battery's role and range this tick. Grid charging
         and selling need a fresh plan that `TariffPlan.arbitrage()` allows
@@ -2367,6 +2466,7 @@ class Controller:
         quarter), exactly the gate `arbitrage.decide()` has."""
         floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
         packs = self._mode_packs(maint_results)
+        self._wx_track(now)
         runs = self._price_runs(now, packs, floor_pct, ceiling_pct)
         guard = arbitrage.guard_state(self.peak_guard)
         plan = self.fresh_tariff_plan(now)
@@ -2377,7 +2477,8 @@ class Controller:
             return plan.arbitrage(
                 peak_guard_active=active,
                 min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o),
-                uncertainty=frozenset({Uncertainty.NO_WEATHER}),
+                uncertainty=arbitrage.weather_uncertainty(
+                    True, self.solar_fc, self.weather_held(now)),
                 now=now).match(
                     allowed=lambda _v: True, refused=lambda _v: False)
         if guard is not None and plan is not None and runs is not None:
@@ -2430,6 +2531,7 @@ class Controller:
             blocked=self._charge_blocked_q == quarter,
             done_charge=done_c, done_sell=done_s, targets=targets,
             draining=any(r.phase == DRAIN for r in maint_results or ()))
+        self._latch_charge(now, runs, targets, packs)
         # A charge the guard or the headroom stopped stays off this period.
         # OPT-15: only a MEASURED stop latches; the first unmeasured headroom
         # (None) in a quarter stops this tick only, so a gap cannot cost the
@@ -2993,6 +3095,27 @@ class Controller:
             soc=min(float(p.soc) for p in able),
             soc_floor=peakguard.binding_soc_floor(able, floor))
 
+    def _peak_landing(self, decision):
+        """SAFETY-126: `decision` marked `within_aim` while the guard wants
+        power but the batteries at 0 W would end the quarter within
+        `ALARM_MISS_W` of the aim (`peakguard.misses_aim()`). Once a real miss
+        is seen, the need stands until the guard lets go. The claim and the
+        commands are unchanged; only the alarms and the "Why" read it.
+        DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md."""
+        batt, prev = self.site_batt_w, self._land_batt_prev
+        self._land_batt_prev = batt
+        if not (decision.engaged and decision.blind is None
+                and (decision.wanted_w or 0.0) > 0.0):
+            self._peak_needed = False
+            return decision
+        if batt is not None and prev is not None:
+            batt = min(float(batt), float(prev))
+        self._peak_needed = self._peak_needed or (
+            self._peak_proj is not None and peakguard.misses_aim(
+                self._peak_proj, batt_w=batt, target_w=decision.target_w))
+        return (decision if self._peak_needed
+                else dataclasses.replace(decision, within_aim=True))
+
     def _peak_reserve(self) -> frozenset:
         """SAFETY-87: the batteries that give nothing for the peak this
         cycle: under their reserve while the others carry a peak floor."""
@@ -3250,17 +3373,19 @@ class Controller:
         return floor
 
     def _charge_headroom(self, floor: float, claims) -> float:
-        """SAFETY-84: at N>=2 a cheap-window charge pulls no more than the
-        quarter's headroom under the peak aim (`charge_headroom_w()`), so it
-        yields just enough to the peak guard, and nothing under a site stop
-        (its 0 W would need the other pack to give). N=1 is unchanged."""
-        if len(self.inverters) < 2:
-            return floor
-        if any(c.kind == SET and c.actuator == ACTUATOR_SITE
-               and c.priority > P_MAINT_SHAPE for c in claims):
+        """SAFETY-84: a cheap-window charge pulls no more than the quarter's
+        room under the peak aim (`charge_room_w()`), so it yields just enough
+        to the peak guard; at N>=2 nothing under a site stop (its 0 W would
+        need the other pack to give). SAFETY-125: at N=1 too, owner
+        2026-10-29; the stop rule stays N>=2 only."""
+        if len(self.inverters) > 1 and any(
+                c.kind == SET and c.actuator == ACTUATOR_SITE
+                and c.priority > P_MAINT_SHAPE for c in claims):
             return 0.0
-        room = peakguard.charge_headroom_w(self.peak_guard)
-        return floor if room is None else min(floor, room)
+        room = peakguard.charge_room_w(self.peak_guard, self._peak_proj)
+        floor = floor if room is None else min(floor, room)
+        self.room_charge = self.room_charge or floor > 0.0
+        return floor
 
     def _charge_ceiling(self, claims):
         """SAFETY-84: the site `hi` for a cheap-window charge at N>=2, or None.
@@ -3417,17 +3542,25 @@ class Controller:
         now = datetime.now(timezone.utc)
         fc, why, gaps = solarfc.read_sum(
             list(zip(self.fc_entities, states[:n])),
-            list(zip(self.fc_tomorrow_entities, states[n:])), now)
+            list(zip(self.fc_tomorrow_entities, states[n:])), now,
+            hold=self.fc_hold)
+        if self.fc_hold.changed:
+            self.fc_hold.changed = False
+            self.store.set(FC_HOLD_KEY, self.fc_hold.dump())
         # A member is named only in a sum of several; one entity reads as
         # before. Logged once per episode: on a change, never every read.
         gaps = tuple(g for g in gaps if len(
             self.fc_entities if g[0] == "today"
             else self.fc_tomorrow_entities) > 1)
+        was_kept = bool(self.solar_fc is not None and self.solar_fc.kept)
         if (fc is None) != (self.solar_fc is None) \
-                or why != self.solar_fc_why or gaps != self.solar_fc_gaps:
+                or why != self.solar_fc_why or gaps != self.solar_fc_gaps \
+                or bool(fc is not None and fc.kept) != was_kept:
             self.log_event(
-                "solar forecast: " + ("read" if fc is not None else
-                                      f"none ({why})")
+                "solar forecast: " + (
+                    "none (" + str(why) + ")" if fc is None else
+                    f"read, kept from {brussels(fc.at):%H:%M}" if fc.kept
+                    else "read")
                 + "".join(f", {d} {e} not usable ({w})"
                           for d, _i, e, w in gaps),
                 hint=messages.hint(
@@ -4839,6 +4972,7 @@ class Controller:
         if self.peak_guard is not None:
             self.peak_guard = self._peak_on_able(self.peak_guard,
                                                  maint_results)
+            self.peak_guard = self._peak_landing(self.peak_guard)
         # SITE, and peakguard.claim() says so on the object it builds. The
         # quantity is the 15-minute average OFFTAKE AT THE GRID CONNECTION,
         # which is what the capacity tariff bills; there is one quarter-hour
@@ -4863,6 +4997,7 @@ class Controller:
                 self.log_event(_pg.explain(), hint=messages.hint(
                     "peak_off" if not _pg.engaged else
                     "peak_blind" if _pg.blind else
+                    "peak_on" if _pg.within_aim else
                     "peak_reserve" if _pg.floor_limited else
                     "peak_saturated" if _pg.saturated else "peak_on"))
 
@@ -4910,6 +5045,7 @@ class Controller:
         # decision presented as current.
         self.arb, self.arb_at = None, now
         self.arb_headroom_w = None
+        self.room_charge = False
         # OPT-11 P3: with battery modes on, each battery's mode decides who
         # trades (`_mode_roles()`, `_mode_trade()`, below, which read the
         # same headroom), and this site-wide trade is not run.
@@ -4920,7 +5056,9 @@ class Controller:
             # `arbitrage.sized_from_meter()` in `_shadow_settle()`, so the
             # caveat on the recorded watts can never be answered from a
             # different cycle's guard than the watts were.
-            self.arb_headroom_w = peakguard.charge_headroom_w(self.peak_guard)
+            # SAFETY-125: a late meter reading's seconds count, as the bill.
+            self.arb_headroom_w = peakguard.charge_room_w(self.peak_guard,
+                                                          self._peak_proj)
         if site_trade:
             floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
             charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
@@ -4975,6 +5113,7 @@ class Controller:
             arb_claim = arbitrage.claim(self.arb)
             if arb_claim is not None:
                 claims.append(arb_claim)
+            self.room_charge = self.arb.action == arbitrage.CHARGE
             # Edge-logged, for the peak guard's reason: the action log holds 40
             # lines and a trade lasts a whole hour, so a line per cycle would
             # flush the context that explains it. The transition is what an
@@ -5194,6 +5333,8 @@ class Controller:
         mode_trade, trade_was = False, self._mode_trade_was
         if self.modes_on:
             mode_trade = self._mode_trade(claims, now)
+            self.room_charge = self.room_charge or (
+                mode_trade and self.arb.action == arbitrage.CHARGE)
         self._mode_trade_was = mode_trade
         self._charge_track(claims, maint_results)
         _live96 = set(self.live_units())
@@ -6154,6 +6295,9 @@ class Controller:
             limited = self._reserve_short(g)
         else:
             self._reserve_batt_prev = self._reserve_high_since = None
+            # SAFETY-126: nothing can give, so it alarms at once, but only
+            # when the quarter really misses the aim (`_peak_landing()`).
+            limited = limited and not g.within_aim
         was, self._peak_floor_limited = self._peak_floor_limited, limited
         if not limited or was:
             return
@@ -7031,12 +7175,13 @@ class Controller:
             if _pg is None:
                 out.append({"ok": True, "warn": True, "id": "peak_guard",
                             "text": messages.row_peak_guard_waiting()})
-            elif _pg.saturated:
+            elif _pg.saturated and not _pg.within_aim:
                 out.append({"ok": False, "warn": False, "id": "peak_guard",
                             "runs": True,
                             "text": messages.row_peak_saturated(_pg.ceiling_w)})
-            elif _pg.floor_limited and (not (_pg.floor_w or 0.0) > 0.0
-                                        or self._peak_floor_limited):
+            elif _pg.floor_limited and (
+                    not ((_pg.floor_w or 0.0) > 0.0 or _pg.within_aim)
+                    or self._peak_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
@@ -7087,6 +7232,15 @@ class Controller:
                             "text": messages.row_peak_guard_on(
                                 _pg.floor_w or 0.0, _pg.ceiling_w,
                                 shadow=self.shadow)})
+            elif _pg.projected_w is not None:
+                # SAFETY-125: "under" only when it is; over the limit at this
+                # rate, a grid charge is cut back to the quarter's room.
+                out.append({"ok": True, "warn": False, "id": "peak_guard",
+                            "text": messages.row_peak_guard_idle(
+                                _pg.projected_w, _pg.ceiling_w,
+                                month_peak=(_pg.ceiling_from
+                                            == peakguard.CEILING_MONTH_PEAK),
+                                cut=self.room_charge and not self.shadow)})
             else:
                 out.append({"ok": True, "warn": False, "id": "peak_guard",
                             "text": _pg.explain()})
@@ -8080,11 +8234,9 @@ async def amain() -> None:
         # ESP32 heartbeat. A fetch on that path is a supplier's TLS timeout able
         # to push this add-on towards layer 1's 30 s veto. See TARIFF_REFRESH_S.
         #
-        # ⚠️ STARTED WHEN A PROVIDER IS CONFIGURED, *OR* WHEN TRADING IS ARMED
-        # - TARIFF-10, and it used to be the second term alone. `arbitrage_
-        # enabled` ships `false`, so a site that had selected a price feed
-        # fetched nothing at all; the whole argument, the measurement and what
-        # the `or` is protecting are in `tariff_refresh_wanted()` above.
+        # ⚠️ STARTED FOR A PROVIDER, FOR ARMED TRADING OR FOR BATTERY MODES:
+        # see `tariff_refresh_wanted()` above and DECISIONS/TARIFF-10 and
+        # TARIFF-24 for why each term is there.
         #
         # ⚠️ IT DOES NOT ARM ANYTHING. Fetching a price and trading on one are
         # two decisions; this is the first, and `cycle()`'s

goodwe_controller/app/messages.py

@@ -1170,8 +1170,18 @@ def row_periods_measured(n) -> str:
               f"Gemeten kwartieren deze maand: {getoond}")
 
 
-def row_peak_guard_idle(projected_w, limit_w, month_peak: bool) -> str:
-    """The projection first and the limit second (SAFETY-38's ordered pair)."""
+def row_peak_guard_idle(projected_w, limit_w, month_peak: bool,
+                        cut: bool = False) -> str:
+    """The projection first and the limit second (SAFETY-38's ordered pair).
+    SAFETY-125: over the limit at this rate it says so, and `cut` that a
+    grid charge is limited to the room left."""
+    if float(projected_w) > float(limit_w):
+        doing, doet = (("grid charge limited", "laden beperkt") if cut
+                       else ("idle", "in rust"))
+        return Bi(f"Peak guard: {doing}, at this rate {watts(projected_w)}, "
+                  f"over {watts(limit_w)}",
+                  f"Piekbewaking: {doet}, aan dit tempo "
+                  f"{watts(projected_w)}, boven {watts(limit_w)}")
     limit = (f"this month's {watts(limit_w)} peak" if month_peak
              else f"the {watts(limit_w)} peak limit")
     grens = (f"de maandpiek van {watts(limit_w)}" if month_peak
@@ -1563,6 +1573,11 @@ def status_samples() -> list:
         ("row_periods_measured", GREEN, row_periods_measured("unreadable")),
         ("row_peak_guard_idle", GREEN, row_peak_guard_idle(1300, 2500, True)),
         ("row_peak_guard_idle", GREEN, row_peak_guard_idle(1300, 2500, False)),
+        ("row_peak_guard_idle", GREEN, row_peak_guard_idle(5814, 5413, True)),
+        ("row_peak_guard_idle", GREEN, row_peak_guard_idle(5814, 5413, True,
+                                                           cut=True)),
+        ("row_peak_guard_idle", GREEN, row_peak_guard_idle(3814, 3500, False,
+                                                           cut=True)),
         ("row_peak_guard_quiet", GREEN, row_peak_guard_quiet()),
         ("row_peak_guard_unmeasured", AMBER, row_peak_guard_unmeasured()),
         *(("row_peak_guard_blind", AMBER, row_peak_guard_blind(k))

goodwe_controller/app/price_chain.py

@@ -1,27 +1,15 @@
 """PRICE-01 - where the prices come from when the first source does not answer.
 
-A provider that names `FALLBACKS` (app/price.py) is read through this module
-instead of straight from `load_prices()`. The order is fixed:
+A provider that names `FALLBACKS` (app/price.py) is read through here: first the
+provider (the owner's price server), then each id in `FALLBACKS`, then the
+prices the history store kept from the last fetch that worked. A step counts
+only if its answer holds a price for NOW (a server answering 200 with
+yesterday's prices is as useless as one that is down). Other providers never
+come here (`uses_chain()` is False).
 
-    1. the provider itself (the owner's price server)
-    2. each id in its `FALLBACKS` (energy-charts.info)
-    3. the prices the history store kept from the last fetch that worked
-
-A step counts only if its answer holds a price for NOW. A server that answers
-200 with yesterday's prices is as useless to a battery as one that is down, so
-it is skipped, with the same log line.
-
-Every other provider never comes here (`uses_chain()` is False for it), so
-`generic_dayahead`, `manual_csv`, `custom_formula` and `off` take the road they
-always took.
-
-THE GATE. `gate_for()` is the maintenance charge rule for a site on such a
-provider: the current 15-minute price is at or below today's average. It is the
-rule the Home Assistant pair (`price_now_entity`, `price_avg_entity`) gave, read
-from the provider's own prices, so moving a site from the pair to the provider
-does not change WHEN the charge runs. DECISIONS/PRICE-01-own-price-server.md
-says how equal, and where it is not.
-"""
+`gate_for()` is the maintenance charge rule for such a site: the current
+15-minute price is at or below today's average, as the Home Assistant pair gave.
+DECISIONS/PRICE-01-own-price-server.md says how equal, and where it is not."""
 
 import logging
 from dataclasses import dataclass
@@ -74,13 +62,8 @@ class Resolved:
 
 
 class PriceWatch:
-    """Which step the prices come from, and one log line per change of it.
-
-    The line is written when the step CHANGES and not before. Nothing repeats
-    while a source stays down, and nothing is written for a refresh that
-    changes nothing. The reasons (a status code, a timeout) go on a DEBUG line
-    beside it, with the token taken out.
-    """
+    """Which step the prices come from, and one log line per change of it (nothing
+    repeats while a source stays down). Reasons go on a DEBUG line, token removed."""
 
     def __init__(self):
         self.step = None
@@ -123,20 +106,14 @@ async def resolve(opts: dict, since: datetime, until: datetime, transport,
                   history, stamp: datetime, watch: PriceWatch,
                   load) -> Resolved:
     """Walk the chain and return the first step that has a price for `stamp`.
-
-    `load` is the caller's `load_prices`, passed in so that `static_tariff.py`
-    stays the one module that fetches prices. Never raises
-    for a source condition: a read that gets nowhere is a `no_data` whose
-    reason names every step, so the §11.4 row applies exactly as for a single
-    provider that failed.
-    """
+    `load` is the caller's `load_prices`, so static_tariff.py stays the one module
+    that fetches. Never raises for a source condition: `no_data` names every step."""
     pid = provider_id(opts)
     cls = PROVIDERS[pid]
     reasons = []
     for step, sid in enumerate((pid,) + tuple(cls.FALLBACKS)):
-        # A fallback is asked for ITS OWN feed. The operator's feed override is
-        # for the first provider and would send energy-charts' request to a
-        # URL it was never meant for.
+        # A fallback is asked for ITS OWN feed; the operator's override is for
+        # the first provider.
         o = opts if step == 0 else dict(opts, price_provider=sid,
                                         price_feed_url="")
         read = await load(o, since, until, transport)
@@ -158,8 +135,8 @@ async def resolve(opts: dict, since: datetime, until: datetime, transport,
             series=lambda r: "price_history: it has no price for now",
             no_data=lambda r: r.reason))
     watch.note(STEP_NONE, reasons, opts)
-    # The reason is short on purpose: it is printed on the status page and in
-    # a WARNING every refresh. What each step said is on the DEBUG line.
+    # Short on purpose: it is on the status page and in a WARNING every
+    # refresh.
     return Resolved(PriceRead.no_data(
         "no price source has a price for now"), STEP_NONE,
         tuple(scrub(r, opts) for r in reasons))
@@ -171,13 +148,9 @@ async def resolve(opts: dict, since: datetime, until: datetime, transport,
 
 @dataclass(frozen=True)
 class Gate:
-    """What the 30 s tick takes from the standing plan.
-
-    `covered` is whether a published price covers now. When it is False,
-    `cheap` is False and the charge waits: no price is not a cheap price.
-    `since` is when the cover ended, for the status line, or None when nothing
-    was ever published.
-    """
+    """What the 30 s tick takes from the standing plan. `covered` False means `cheap`
+    is False and the charge waits (no price is not a cheap price). `since` is when
+    the cover ended, or None."""
 
     cheap: bool
     covered: bool
@@ -189,24 +162,16 @@ NO_PLAN = Gate(False, False, None, "No prices yet")
 
 
 def _round5(value: float) -> float:
-    # The Home Assistant template rounded the average to 5 decimals, and a
-    # price to 5 as well. Both sides are compared as it did, so a quarter that
-    # sits within 0.00001 EUR/kWh of the average gets the same answer.
+    # The Home Assistant template rounded both sides to 5 decimals; so do we,
+    # for the same answer.
     return round(float(value), 5)
 
 
 def gate_for(published, now: datetime) -> Gate:
-    """The charge gate for `now`, from the series the chain published.
-
-    THE RULE (owner's decision, PRICE-01): the current 15-minute price is at or
-    below the average of today's prices, today being the Brussels day. This is
-    what `now_p <= avg_p` was on the Home Assistant pair. It is NOT
-    `TariffPlan.cheap_now()`, which is strictly below the mean of the firm
-    hours of the whole plan, and it is not meant to be.
-
-    `published` is a series or None. With no price for now there is no gate
-    answer: the charge waits.
-    """
+    """The charge gate for `now`, from the series the chain published: the current
+    15-minute price is at or below the average of today's (Brussels day) prices,
+    as `now_p <= avg_p` was on the HA pair (owner, PRICE-01). Not
+    `TariffPlan.cheap_now()`. With no price for now the charge waits."""
     if published is None:
         return NO_PLAN
     if not published.covers(now):

goodwe_controller/app/price_forecast.py

@@ -1,163 +1,16 @@
 """FCST-03 - the hours the feed has not published yet, and what may not rest on them.
 
-WHERE THIS LIVES. specs.md §2.2 puts price ingest under `ems/ingest/prices/`.
-That layout does not exist and is not being built; the product owner's decision
-of 2026-08-30 is that everything ships in `goodwe_controller/app/`. The
-BEHAVIOUR §8.3 describes is unchanged and still authoritative - only the path
-moved. Read `ems/...` as `app/...`.
-
-§8.3, in full, because every line below is one clause of it:
-
-    "Day-ahead prices arrive once daily. Until they do, unknown hours use
-     yesterday's profile and are flagged `provisional: true` - and NO
-     IRREVERSIBLE ACTION MAY BE TAKEN ON A PROVISIONAL PRICE. Real-time /
-     imbalance products are treated as high-volatility: arbitrage thresholds
-     widen."
-
-Three separate things, and this module owns the first two. The third - the
-widening arithmetic - lives in price.py beside the product enum it is derived
-from (`Uncertainty`, `widen_factor`, `required_spread`), and is spent by
-`static_tariff.TariffPlan.arbitrage()`, because that is where the verdict this
-repo already refuses to hand out casually is produced. FCST-03 added a refusal
-to that existing ladder rather than a second mechanism beside it.
-
-
-THE DEFECT THIS MODULE IS SHAPED BY: A COPY THAT KEEPS THE WRONG FLAG
-=====================================================================
-A point filled from yesterday and a point published this morning are the SAME
-SHAPE. Three floats and a bool; only the bool tells them apart. And the natural
-way to write a carry-forward fill is:
-
-    PricePoint(start=t, eur_per_kwh=y.eur_per_kwh, provisional=y.provisional)
-                                                                ^^^^^^^^^^^^^
-
-which copies yesterday's `False` onto today's guess and produces exactly the
-thing the ticket exists to prevent: STALE DATA PRESENTED AS CURRENT. It reads
-fine, it type-checks, it round-trips through §9.3's JSON, and every price on
-the status page looks like a price. This is the meter-side SAFETY-18 defect one
-layer up: the reading arrives on time, looks fresh, and is wrong - and a
-freshness check that only asks "did something arrive" cannot see it.
-
-So the flag is not passed through anywhere in this file:
-
-  * A CARRIED POINT IS BUILT BY `_carried()`, WHICH HAS NO PARAMETER FOR THE
-    FLAG. `provisional=True` is a literal in one place. There is no argument a
-    caller can pass, no keyword to forget, and no variable that could hold
-    yesterday's value at the moment the point is constructed.
-  * A PUBLISHED POINT IS NEVER COPIED AT ALL. It is passed through BY IDENTITY -
-    the object the provider produced is the object in the output series - so
-    there is no copy that could lose or gain a flag. `filled.points[i] is
-    fetched.points[j]` is a checkable property, and test_price_forecast.py
-    checks it. EVERY published point in the window is passed through, not one
-    per hour: see the sub-hourly note below.
-  * `_audit()` RE-DERIVES the expected flag for every output point from the set
-    of hours the feed actually published, and RAISES if any point disagrees.
-    It is a post-condition, not a filter: it never fixes a flag, because a
-    module that quietly corrects its own provenance is one whose provenance
-    cannot be trusted.
-
-    ⚠️ IT GRADES THE POINTS THAT ARE EMITTED AND NOTHING ABOUT THE ONES THAT
-    ARE NOT (FCST-05). `_audit()` is a provenance check, NOT a completeness
-    check: fed FCST-04's own decimation defect - four published points in an
-    hour, only the last emitted - it ACCEPTS, and it accepts an empty output
-    too. Measured, and the FCST-03 audit it replaced was equally blind, so
-    this is a limit rather than a regression. What actually guards against a
-    decimated series is the point COUNT and the pass-through IDENTITY checks
-    in `test_price_forecast.py` (section on the quarter-hourly feed) and
-    `test_price_history.py`; see `_audit()`'s own docstring for why the
-    completeness rule is not expressible from its two arguments.
-  * and test_price_forecast.py walks THIS FILE'S AST and fails if any
-    `PricePoint(...)` in it passes anything but a literal for `provisional`, so
-    the pass-through idiom cannot come back in a later edit and pass review by
-    looking ordinary.
-
-⚠️ "PUBLISHED" DOES NOT MEAN "FIRM". §9.3's canonical format carries
-`provisional` PER POINT, not per series, precisely because a real-time /
-imbalance product's current-interval print is settled after the fact and is
-genuinely provisional while it is published. Such a point is published AND
-provisional, and the audit's rule for a published point is "the flag is
-whatever the feed said", never "False". A provenance check that forced
-published points to False would be a bug that looks like a guarantee.
-
-⚠️ NO SHIPPED PLUGIN EMITS ONE TODAY (TARIFF-07 withdrew the only declarer of
-`PriceProduct.REALTIME`), and that is exactly why this paragraph stays. The
-rule is a property of the FORMAT, not of any supplier; weakening it to
-"published implies False" while nothing exercises it is how the first real
-imbalance feed would arrive mispriced and flagged firm.
-
-
-THE FILL, AND WHY IT KEYS ON THE WALL CLOCK
-===========================================
-For every whole hour in the requested horizon that the feed has not published,
-take yesterday's value for THE SAME BRUSSELS WALL-CLOCK HOUR - not `t - 86400
-s`. On the two days a year that matter those are different instants, and the
-difference is not academic: a 23-hour day has no 02:00 at all and a 25-hour day
-has two, so a fill that subtracts a fixed 24 h shifts every carried hour by one
-across a transition and misprices the whole day in a way nothing reports.
-
-On the 25-hour day the two 02:00 hours - `02:00+02:00` and `02:00+01:00` - both
-key to local hour 2 and are BOTH filled from yesterday's single 02:00 value.
-That is deliberate: they are both guesses, they are both flagged, and nothing
-irreversible may rest on either. If yesterday itself was a 25-hour day, the
-first of its two 02:00 points is the one used, deterministically.
-
-An hour with no published price AND no yesterday value is LEFT OUT of the
-series. It is not filled with a neighbour, a mean, or a zero. §11.4 applies to
-that hour - `_Series.at()` raises `Absence` for it - and the caller that wanted
-a tariff for the whole horizon falls back to the static profile (TARIFF-03),
-which is the row the spec actually writes for "no price data". If NOTHING can
-be produced, the result is `PriceRead.no_data(reason)` and not an empty series,
-because an empty series is not constructible on purpose (price.py trap 3).
-
-⚠️ A SUB-HOURLY FEED IS NOT DECIMATED TO ONE POINT AN HOUR, and the hourly walk
-below is about WHICH HOURS NEED FILLING - never about what a published hour is
-allowed to contain. BELGIAN DAY-AHEAD ITSELF SETTLES PER QUARTER since the
-15-minute MTU took effect on 2025-10-01 - `generic_dayahead` reads 96 points a
-day, not 24 - `_validate_raw()` accepts any strictly-increasing spacing, and a
-published hour may therefore hold four points. So EVERY published point inside
-the window is passed through, in order, and a carried point is added only for a
-whole hour with NO published coverage at all.
-
-The alternative was measured rather than reasoned about, because FCST-04's
-first caller shipped it: keying the published set as `{_utc_hour(p.start): p
-for p in r.points}` reads perfectly ordinary and keeps the LAST point of each
-hour, dropping the other three. On a 96-point quarter-hourly feed - all firm,
-fully published, nothing to carry - the series came out 15 points long, the
-arbitrage spread collapsed from 0.143 to 0.014 EUR/kWh, and the cheapest
-"hour" became a `:45` point whose `at()` window runs into the next hour. A feed
-losing 84 % of its own prints is not a windowing effect and is not something a
-provisional flag would ever have reported.
-
-
-AC2: THE IRREVERSIBLE-ACTION GATE
-=================================
-"The distinction should be an explicit property of the action, not a judgement
-call at each call site" - so an irreversible action is a value, `Irreversible`,
-carrying the number of hours it COMMITS. `price_permits()` looks at exactly
-those hours and answers with a `Gate` variant that carries the evidence on the
-permitting arm and a reason on the blocking one, the `_Outcome` shape price.py
-borrowed from `sim/riglock.py`.
-
-The shipped example is the maintenance drain (§12): starting one commits hours
-of forced discharge that cannot be undone if the price turns out to have been
-yesterday's. Its commitment window is DERIVED from `maintenance.DRAIN_TIMEOUT_MIN`
-rather than typed here, so the gate and the phase machine cannot drift apart.
-
-⚠️ WHAT DOES NOT GO THROUGH THIS GATE, AND WHY THAT MATTERS MORE THAN WHAT
-DOES. The maintenance cycle is a CALENDAR obligation (§12.2: a cycle that
-silently never fires is indistinguishable from one that is not due yet), and a
-site with `price_provider: off` - the shipped default - has no price series at
-all. Routing every maintenance start through a gate that blocks on `no_data`
-would stop the monthly cycle on every default install, permanently and
-silently: the exact failure §12 opens by naming. So `begin_phase()` is the
-entry point for a start that is being JUSTIFIED BY A PRICE, main.py's existing
-calendar path is untouched by this ticket, and OPT-04/MAINT-05 own the decision
-of which one a site runs. Nothing here disables anything that runs today.
-
-Reversible actions - ordinary self-consumption modulation, the loop that
-actually holds the grid at zero - are not gated at all and cannot be: §6 says
-absent machinery must not disable the loop.
-"""
+specs.md 8.3: unknown hours use yesterday's profile and are flagged
+`provisional: true`, and no irreversible action may be taken on a provisional
+price. This module owns the fill and the gate; the widening arithmetic is in
+price.py. The flag is never passed through: a carried point is built only by
+`_carried()` (no flag parameter), a published point is passed by identity, and
+`_audit()` raises on a mismatch. The fill keys on the Brussels wall-clock hour,
+and a sub-hourly feed is never decimated. An hour with neither a published
+price nor a yesterday value is left out, never filled (`at()` raises `Absence`,
+11.4 applies). `begin_phase()` is the price-justified entry point only; the
+calendar path is untouched. All of it:
+DECISIONS/FCST-03-the-hours-not-yet-published.md."""
 
 import logging
 from dataclasses import dataclass
@@ -172,13 +25,8 @@ _LOG = logging.getLogger("goodwe.price.forecast")
 
 
 class Provenance(Enum):
-    """Where a point in a filled series came from. INTERNAL - §9.3's wire format
-    carries the boolean and nothing else, so this never leaves the module.
-
-    It exists so `_audit()` has a vocabulary to state its post-condition in, and
-    so the two cases have names in the log rather than being "the ones with the
-    flag" and "the others".
-    """
+    """Where a point in a filled series came from. INTERNAL: the wire format carries
+    only the boolean. It gives `_audit()` and the log names for the two cases."""
     PUBLISHED = "published"    # the provider printed this hour. Flag: the
                                # feed's own - a real-time print may be
                                # published AND provisional (§9.2).
@@ -186,9 +34,7 @@ class Provenance(Enum):
                                # Flag: ALWAYS True, by construction.
 
 
-# --------------------------------------------------------------------------- #
 # The fill
-# --------------------------------------------------------------------------- #
 
 def _utc_hour(instant: datetime) -> datetime:
     u = instant.astimezone(timezone.utc)
@@ -196,16 +42,9 @@ def _utc_hour(instant: datetime) -> datetime:
 
 
 def _published_by_hour(read: PriceRead) -> dict:
-    """UTC hour -> the provider's OWN points that start inside it, in order.
-
-    ⚠️ A TUPLE PER HOUR, NOT A POINT, AND THAT IS THE WHOLE OF THE SUB-HOURLY
-    RULE. `{_utc_hour(p.start): p for p in r.points}` reads identically, is one
-    character shorter, and silently keeps one point per hour - the last one
-    written. The mapping answers two DIFFERENT questions here: "does this hour
-    need filling at all?" is `u in published`, and "what does the output carry
-    for it?" is all of `published[u]`. Collapsing them is how a quarter-hourly
-    feed loses three quarters of its prints.
-    """
+    """UTC hour -> the provider's OWN points that start inside it, in order. A tuple
+    per hour, not a point: a dict of `{hour: p}` silently keeps the last one and
+    decimates a quarter-hourly feed."""
     out: dict = {}
     read.match(
         series=lambda r: [out.setdefault(_utc_hour(p.start), []).append(p)
@@ -215,13 +54,8 @@ def _published_by_hour(read: PriceRead) -> dict:
 
 
 def _carried(start_utc: datetime, eur_per_kwh: float) -> PricePoint:
-    """A point filled from yesterday's profile. §8.3: ALWAYS provisional.
-
-    ⚠️ THERE IS NO `provisional` PARAMETER, AND THAT IS THE MECHANISM. This is
-    the only constructor of a carried point, the flag is a literal, and no
-    caller - including a future one editing in a hurry - has anything to pass,
-    default, or copy from the point being carried.
-    """
+    """A point filled from yesterday's profile. 8.3: ALWAYS provisional. There is no
+    `provisional` parameter: the flag is a literal, nothing to pass or copy."""
     return PricePoint(start=brussels(start_utc),
                       eur_per_kwh=round(float(eur_per_kwh), 6),
                       provisional=True)
@@ -230,88 +64,15 @@ def _carried(start_utc: datetime, eur_per_kwh: float) -> PricePoint:
 def _audit(points, published) -> None:
     """Post-condition: every flag matches the point's TRUE provenance (AC1).
 
-    `published` maps a UTC hour to the TUPLE of points the provider produced
-    for it (`_published_by_hour()`). An hour ABSENT from that mapping is an hour
-    the feed did not print, and a carried point is the only thing that may
-    stand in it.
+    `published` maps a UTC hour to the TUPLE of points the provider produced for it.
+    PUBLISHED: the point must be one of `published[u]` by identity, emitted once,
+    flag whatever the feed said (never forced to False). CARRIED: the hour must not
+    be in `published`, the flag exactly True, no second point in that hour.
 
-    The rule, in the two forms an output point can take:
-
-      * PUBLISHED - the point must BE one of `published[u]`, by identity, and
-        may be emitted only once. Its flag is whatever the feed said, never
-        forced to False: an imbalance print is published AND provisional (§9.2,
-        TARIFF-02), and a check that "corrected" it would be a bug wearing a
-        guarantee.
-      * CARRIED - the hour must not appear in `published` AT ALL, the flag must
-        be exactly True, and that hour may hold no second point.
-
-    ⚠️ WHAT REPLACED "AT MOST ONE POINT PER HOUR", AND WHAT THAT DID AND DID
-    NOT CHANGE. This audit began as FCST-03's `seen` set: any repeated
-    `_utc_hour` raised, beside an identity rule `p is not src`. A bare hour
-    count cannot express a quarter-hourly feed, where four distinct published
-    points share one hour legitimately - so the count was replaced by the two
-    rules above, which subsume it.
-
-    ⚠️ AND IT IS NOT STRICTER. FCST-04's version of this paragraph claimed two
-    strengthenings and BOTH WERE FALSE; FCST-05 measured it. A differential
-    over the whole domain this audit can express - every published mask over 3
-    hours crossed with every output series of length 0-3 drawn from
-    {published, published-provisional, carried, carried-unflagged,
-    copy-of-published} - found ZERO divergence in EITHER direction:
-
-        OLD raised, NEW accepted (WEAKER):   0
-        OLD accepted, NEW raised (STRONGER): 0
-
-    The two specific claims, one at a time:
-
-      * "so does the same published point emitted twice" - the OLD `seen`
-        count already raised on that, because emitting one point twice is one
-        HOUR twice. Preserved by the identity/`emitted` rules, not added.
-      * "a carried point may no longer share an hour with a published one,
-        which the count never checked at all" - true of the COUNT, and the old
-        IDENTITY rule raised on it anyway: a carried point in a published hour
-        took the `else` branch and failed `p is not src`. The message was about
-        a copy rather than about a carry, which is the only thing that moved.
-
-    The one real behavioural change is the intended RELAXATION - several
-    distinct published points in one hour, which the old audit could not
-    express at all and refused. That relaxation is why this was rewritten, and
-    it stays. A right decision with a fabricated reason is still a defect here.
-
-    ⚠️ AND THE REAL LIMIT, WHICH IS NOT A REGRESSION AND IS NOT SMALL: THIS
-    AUDIT DOES NOT CHECK COMPLETENESS. It grades every point that IS emitted
-    and says nothing about the ones that are not. Fed the H1 decimation
-    directly - four published points in an hour, output emitting only the last
-    - it ACCEPTS; so does two of four, and so does an EMPTY output. So `_audit`
-    is NOT what stops H1 recurring. What stops it is the point COUNT and the
-    IDENTITY checks in `test_price_history.py` and `test_price_forecast.py`,
-    which compare the emitted series against the feed's own prints.
-
-    It is not made complete here, and the reason is structural rather than
-    effort: `published` is `_published_by_hour(read)` over the WHOLE read,
-    unwindowed, while `fill_from_yesterday()` emits only [since, until). A
-    published point outside the window is legitimately absent, so "every
-    published point appears" is not a true post-condition of these two
-    arguments - it would need the window passed in, which is a different
-    signature and a different check.
-
-    ⚠️ AND THAT IS MEASURED, NOT ASSUMED. FCST-05 built the rule - raise unless
-    every point of every `published[u]` is emitted, +162 B - and ran it. It
-    takes the 1 h, 12 h and 48 h HORIZON checks in test_price_forecast.py RED,
-    on the shipped fill and a healthy feed: at an off-the-hour instant the
-    feed's already-elapsed prints are outside [since, until) and are correctly
-    dropped, and the rule calls that a provenance failure. (The differential
-    beside those checks scores the same rule as 49 STRONGER cases, so it is a
-    real change of behaviour and not a no-op.) The rule as stated is therefore
-    not merely unimplemented, it is WRONG - and stating a false post-condition
-    is MUTATION.md habit 16's defect: an instrument that asserts a completeness
-    it does not have is worse than no instrument.
-
-    ⚠️ RAISES, NEVER REPAIRS. A module that silently corrects its own
-    provenance is one whose provenance means nothing; the only safe response to
-    "this point's flag disagrees with where it came from" is to refuse to emit
-    the series at all.
-    """
+    Provenance, NOT completeness: it accepts a decimated or empty output, because
+    `published` is unwindowed while the fill emits [since, until). The point count
+    and identity checks in the tests guard that. Raises, never repairs.
+    DECISIONS/FCST-03-the-hours-not-yet-published.md."""
     carried_hours = set()
     emitted = set()
     for p in points:
@@ -351,37 +112,12 @@ def _audit(points, published) -> None:
 def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
                         since: datetime, until: datetime,
                         stamp: datetime) -> PriceRead:
-    """§8.3: fill the hours the feed has not published with yesterday's profile.
+    """8.3: fill the hours the feed has not published with yesterday's profile.
 
-    Every argument is required and keyword-only past the first. In particular
-    `yesterday` has NO DEFAULT: a fill with no yesterday to fill from is a
-    different situation from a fill that found nothing useful in one, and a
-    default `None` would make the two arrive looking identical.
-
-    Returns a `PriceRead`:
-
-      * a series, carrying the provider's own objects - ALL of them, which on
-        a quarter-hourly feed is four inside one hour - for the hours it
-        published, and one `_carried()` point for each remaining whole hour,
-        ordered by instant;
-      * `no_data` when neither source can produce a single hour - never an
-        empty series, which is not constructible (price.py trap 3).
-
-    ⚠️ THE WINDOW IS WHOLE HOURS AT BOTH ENDS. `since` is floored to the hour
-    that CONTAINS it, because the current hour is still a tradeable hour; and
-    so is `until`, which is the half FCST-04's first draft left out. With
-    `since` floored and `until` compared raw, a 48 h horizon asked for at 08:17
-    emitted 49 hours - the hour of `until` was still `< until` - and the count
-    was one too many for every `now` that is not exactly on the hour, which is
-    every `now` a running controller has.
-
-    ⚠️ IDEMPOTENT AND RE-RUNNABLE, WHICH IS THE §5.4 LATE-PUBLICATION CONTRACT.
-    Day-ahead publication at 14-16 h CET can be late or fail, so the fetcher
-    retries and this runs again against the fresher read. Published hours always
-    win over carried ones, so a re-run REPLACES a carried point with the real
-    print and the hour becomes firm - the flag and the number move together
-    because the whole series is rebuilt rather than patched in place.
-    """
+    `yesterday` has no default. Returns a series (every published point, by
+    identity, plus one `_carried()` point per remaining whole hour) or `no_data`,
+    never an empty series. The window is whole hours at both ends. Idempotent and
+    re-runnable (5.4): published hours win and the series is rebuilt."""
     for name, value in (("since", since), ("until", until), ("stamp", stamp)):
         if value.tzinfo is None or value.utcoffset() is None:
             raise ValueError(f"{name} must be tz-aware; a naive instant is "
@@ -390,7 +126,7 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
     published = _published_by_hour(read)
 
     # Yesterday's profile, keyed by BRUSSELS WALL-CLOCK HOUR. First point wins
-    # when yesterday itself was a 25-hour day and printed local hour 2 twice.
+    # when yesterday itself was a 25-hour day.
     by_local_hour = {}
     yesterday.match(
         series=lambda r: [by_local_hour.setdefault(brussels(p.start).hour, p)
@@ -424,14 +160,8 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
     _audit(out, published)
     carried = sum(1 for p in out if _utc_hour(p.start) not in published)
     if carried:
-        # ⚠️ THREE QUANTITIES, THREE NAMES (TARIFF-11). This line read
-        # "%d of %d hours ... ; %d published" with `carried` (a count of
-        # carried HOURS - the fill emits exactly one point per unpublished
-        # hour) over `len(out)` (a count of POINTS, four per hour wherever the
-        # feed printed) and `len(out) - carried` (POINTS again) under the same
-        # noun. On the Belgian quarter-hourly feed that reads "33 of 141
-        # hours" about a 48-hour horizon. The fill's unit is the HOUR and the
-        # feed's is the POINT; nothing derived from one answers for the other.
+        # TARIFF-11: carried hours, total hours and published points are three
+        # different quantities.
         total_h = len({_utc_hour(p.start) for p in out})
         _LOG.info("%d of %s use yesterday's prices, marked as estimated. "
                   "The feed published %s over the other %s.",
@@ -446,17 +176,12 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
     return PriceRead.series(out, product, provider, stamp)
 
 
-# --------------------------------------------------------------------------- #
 # AC2: irreversibility as a property of the ACTION, and the gate that reads it
-# --------------------------------------------------------------------------- #
 
 @dataclass(frozen=True)
 class Irreversible:
-    """An action that cannot be undone once started, and how far it commits.
-
-    `commits_h` is the horizon the action ties up - the hours whose prices must
-    therefore be firm before it may be justified by a price at all.
-    """
+    """An action that cannot be undone once started. `commits_h` is the horizon it
+    ties up: those hours must be firm before a price may justify it."""
 
     name: str            # the §10.2 reason code
     commits_h: float
@@ -473,25 +198,16 @@ class Irreversible:
                 f"reversible one and does not belong here.")
 
 
-# ⚠️ DERIVED FROM THE PHASE MACHINE'S OWN BOUNDS, NOT TYPED HERE. maintenance.py
-# already states how long each phase may run before it is a fault; a second copy
-# of those numbers here would be a place for them to drift apart, and the drift
-# would show up as a gate that checked the wrong hours.
+# Derived from the phase machine's own bounds, not typed here, so the gate
+# cannot drift from it.
 MAINTENANCE_DRAIN = Irreversible("MAINTENANCE_DRAIN", DRAIN_TIMEOUT_MIN / 60.0)
 MAINTENANCE_CHARGE = Irreversible("MAINTENANCE_CHARGE", CHARGE_TIMEOUT_MIN / 60.0)
 
 
 class Gate(_Outcome):
     """May an irreversible action proceed on the price evidence available?
-
-      * `permitted` - carries `.action` and `.hours`, the firm points that were
-                      actually checked. The evidence exists only on this arm.
-      * `blocked`   - carries `.reason`. Nothing else; `.hours` raises `Absence`.
-
-    No `__bool__`, both `match()` arms required and keyword-only, for the reason
-    price.py's `_Outcome` gives: `if gate:` must not look like a guard while
-    being none.
-    """
+    `permitted` carries `.action` and `.hours` (the firm points checked); `blocked`
+    carries `.reason` only. No `__bool__`; both `match()` arms are required."""
 
     def match(self, *, permitted, blocked):
         return {"permitted": permitted, "blocked": blocked}[self.kind](self)
@@ -541,12 +257,7 @@ class _Blocked(Gate):
 
 
 def committed_hours(now: datetime, action: Irreversible) -> tuple:
-    """The whole hours `action` started at `now` would run through.
-
-    Split out because the gate and its caller must agree on what "the hours it
-    commits" means, and because a window that quietly excluded the last hour
-    would be a gate that permits an action on an hour it never looked at.
-    """
+    """The whole hours `action` started at `now` would run through (the gate and its caller must agree)."""
     if not isinstance(action, Irreversible):
         raise TypeError(f"action must be an Irreversible, not {action!r}")
     if now.tzinfo is None or now.utcoffset() is None:
@@ -562,13 +273,9 @@ def committed_hours(now: datetime, action: Irreversible) -> tuple:
 
 def price_permits(read: PriceRead, now: datetime,
                   action: Irreversible) -> Gate:
-    """§8.3's rule, as a value: may this irreversible action rest on this price?
-
-    Blocks when the read observed nothing (§11.4 - an action justified by a
-    price nobody has is an action justified by nothing), when any hour it
-    commits has no price at all, and when any of those hours is provisional.
-    Names the offending hour, so an operator reading the log knows which one.
-    """
+    """8.3's rule as a value: may this irreversible action rest on this price?
+    Blocks on no data (11.4), an hour with no price, or a provisional hour, and
+    names the offending hour."""
     hours = committed_hours(now, action)
     return read.match(
         series=lambda r: _walk(r, hours, action),
@@ -600,18 +307,10 @@ def _walk(series, hours, action) -> Gate:
 
 def begin_phase(maint, now: datetime, read: PriceRead,
                 action: Irreversible) -> Gate:
-    """Start a maintenance phase BECAUSE OF A PRICE, or refuse and say why.
-
-    The AC2 example made real: `maint.force_start(now)` - the call that moves
-    the phase machine out of `idle` and commits the pack to hours of forced
-    discharge - happens on the permitting arm and cannot happen on the other
-    one, because the blocking arm has no code path to it.
-
-    ⚠️ READ THE MODULE DOCSTRING'S LAST WARNING BEFORE WIRING THIS IN. This is
-    the price-justified entry point, not the calendar one; a site with no price
-    provider must keep starting its monthly cycle the way it does today, or
-    §12's opening sentence comes true - a cycle that silently never fires.
-    """
+    """Start a maintenance phase BECAUSE OF A PRICE, or refuse and say why. The
+    price-justified entry point, not the calendar one: a site with no provider must
+    keep starting its monthly cycle as today (12). The blocking arm has no path to
+    `maint.force_start(now)`."""
     gate = price_permits(read, now, action)
     return gate.match(permitted=lambda g: _go(maint, now, g),
                       blocked=lambda g: _no(g))

goodwe_controller/app/price_history.py

@@ -1,185 +1,24 @@
-"""FCST-04 - the day the carry-forward carries, kept somewhere a restart cannot reach.
+"""FCST-04 - the day the carry-forward carries, kept where a restart cannot reach.
 
-WHAT WAS MISSING, AND WHY IT WAS INVISIBLE. FCST-03 shipped
-`price_forecast.fill_from_yesterday()` complete and checked, and shipped the
-consumers that were written to expect it - `TariffPlan.firm_points()`,
-`cheap_now()`'s refusal of a provisional hour, and `arbitrage()`'s refusal 3,
-which drops provisional hours from the trade set instead of refusing the whole
-series. Every one of those was live. The FILL ITSELF HAD NO CALLER: nothing in
-`app/` referenced `fill_from_yesterday`, so no series ever contained a carried
-point and every one of those consumers was exercising its all-firm branch.
+`price_forecast.fill_from_yesterday()` needs a yesterday that survives a
+restart; this module is that store and the one caller of the fill. Four rules:
 
-The defect that produced is not an error anywhere. `load_prices()` returns
-whatever the feed published and nothing widens it to the requested horizon, so
-on a dynamic site between midnight and the 14-16 h CET day-ahead publication
-the series covers the rest of TODAY and nothing more - typically 10-24 of the
-48 hours `price_horizon_h` asked for. `TariffPlan.arbitrage()` then computes
-`max - min` over that truncated window and reports a spread. The number is
-real, the window is half the one the operator configured, and NOTHING SAYS SO:
-tomorrow evening's peak - the hour a morning charge would be sold into - is
-simply not in the series, so the spread it would have created cannot clear a
-threshold it was never compared against. A missing hour is not a wrong price;
-it is an hour the optimiser never learns exists.
+1. It records what the PROVIDER published, never what the fill produced
+   (feeding a fill back in rots the numbers behind a true `provisional` flag).
+   `carry()` is the only public entry point and `_remember()` has exactly one
+   caller; test_price_history.py parses every shipped module for the name and
+   grades the order by driving it.
+2. "Yesterday" is the Brussels day before the instant asked about, not the
+   newest record; any other date is `no_data` naming both dates.
+3. A store that cannot answer says so in the type: `yesterday()` returns a
+   `PriceRead`, never an empty series.
+4. Hours accumulate within a day (merge by instant, the newer price wins), so a
+   feed that serves only the remaining hours cannot overwrite a full day.
 
-So this module is the half FCST-03 left out, and it is deliberately the SMALL
-half: the fill's arithmetic, its DST rule and its provenance audit all stay in
-`price_forecast.py`, untouched. What lives here is the one thing that
-arithmetic needs and could not have: A YESTERDAY THAT SURVIVES A RESTART.
-
-
-WHY PERSISTENCE, AND NOT A VARIABLE ON THE REFRESH TASK
-======================================================
-An in-memory "the last full day I saw" costs nothing and is wrong exactly when
-it matters. The window the fill exists for is midnight -> publication; an
-add-on restarted at 08:00 - a config change, an HA update, a power cut - would
-come up with no yesterday at all and spend that whole window on the truncated
-series, which is the pre-FCST-03 behaviour arriving silently on the mornings
-after an operator touched something. The fill's own value is a function of
-surviving a restart, so the day it carries has to.
-
-⚠️ AND NOT IN `/data/state.json`. That file holds the maintenance history and
-SAFETY-02's sign latch, and `Store.set()` rewrites the whole of it on every
-write. The tariff refresh runs every `TARIFF_REFRESH_S` (1800 s), so folding a
-price cache into it would put 48 extra whole-file rewrites a day through the
-file whose corruption reads as "no maintenance ever ran" and "never tripped".
-The cache is worth having; it is not worth putting anywhere near that. Separate
-file, separate blast radius.
-
-⚠️ AND THE DIRECTORY IS NOT CREATED, which is `tariff.PeakStore`'s rule and its
-reason applies unchanged: `/data` is mounted by the Supervisor and always
-exists on a real install, so `makedirs` here could only ever succeed where the
-durable volume is MISSING - manufacturing a cache on the container's ephemeral
-layer that writes fine, reads fine, and is thrown away on the next restart.
-That is a yesterday that silently forgets, which is worse than one that says it
-cannot answer.
-
-⚠️ AND THAT RULE IS CARRIED OUT IN `_remember()`, NOT ONLY IN `_save()`. FCST-04
-first shipped it half-done: `_save()` short-circuited on `not self.ok` while
-`_remember()` filled `self._days` anyway, so a store with no durable volume
-answered `words` = "unavailable" and `yesterday()` = A SERIES - an in-memory
-yesterday that works all day and is gone on the next restart, which is exactly
-the silently-forgetting cache this rule exists to refuse. A store that cannot
-persist now records nothing, and both of its answers say the same thing.
-
-⚠️ AND "CANNOT PERSIST" IS ONE QUESTION, ASKED ONCE, ABOUT THE OUTCOME -
-FCST-06. The paragraph above enforced that rule against `not self.ok`, which is
-one SYMPTOM of not persisting: the durable volume is missing. There is a second,
-and FCST-06 measured it. With `ok=True` and the directory present, `_save()` can
-still fail - a read-only remount (`[Errno 30] Read-only file system`), a full
-volume (`[Errno 28] No space left on device`) - and it logs, records
-`last_error` and returns. `_remember()` had already populated `self._days`, so
-`words` read `'2026-01-14 (24 points over 24 h); 2026-01-15 (24 points over
-24 h) [could not write (...)]'` while the file on disk held `{}`, and
-`yesterday()` answered 24 REAL POINTS for the rest of the process's life. Gone
-on the next restart, and nothing said it would be - the same silently-forgetting
-cache, reached by the condition the rule did not name.
-
-⚠️ SO IT IS NOT TWO RULES, AND IT IS DELIBERATELY NOT TWO TESTS. "Can this
-store persist?" CANNOT BE ANSWERED BEFORE THE ATTEMPT - a directory that existed
-and was writable a moment ago is not a write that completed - so it is answered
-AFTER it, once, by the only thing holding the evidence: `_save()` returns
-whether the file now holds what memory holds. A missing volume is one of its
-False cases and an `OSError` from the write is another, and `_remember()` KEEPS
-ONLY WHAT THAT ONE ANSWER SAYS WAS KEPT. There is no `not self.ok` test in
-`_remember()` any more, because there is nothing left for a second test to add -
-and a third symptom nobody has thought of is how this defect arrived both times.
-
-⚠️ AND WHAT IS KEPT IS THE LAST STATE THAT IS ON DISK, NOT AN EMPTY ONE. The
-MERGE is undone, not the store. A site whose volume fills at 14:00 goes on
-answering the yesterday it wrote at 13:30 - that record survives a restart, so
-answering it is not a promise the store cannot keep. What it stops doing is
-adding to it. The invariant the rule was always describing, stated once:
-`self._days` NEVER HOLDS A POINT THE FILE DOES NOT. (Not "mirrors the file" -
-`_usable_days()` drops records the file still holds. The only direction that can
-invent a yesterday is the one named.)
-
-
-THE FOUR RULES THIS FILE IS SHAPED BY
-=====================================
-
-1. IT RECORDS WHAT THE PROVIDER PUBLISHED, NEVER WHAT THE FILL PRODUCED.
-   Feeding a filled series back in is the defect that makes the whole mechanism
-   rot: day 2 carries day 1's guesses, day 3 carries day 2's carry of them, and
-   after a week of a dead feed the "yesterday" being carried forward is a
-   fossil of the last real publication with nothing anywhere reporting its age.
-   Every point still carries `provisional=True`, so the flag never lies - what
-   decays is the NUMBER, silently, behind a flag that is telling the truth.
-
-   ⚠️ NO VALUE-LEVEL CHECK CAN CATCH THAT, and saying so is more useful than a
-   guarantee that would not hold. A carried point and a published-provisional
-   point (a real-time product's current interval, §9.2) are the same three
-   fields with
-   the same flag; the difference is provenance, and provenance is not in the
-   value. So the mechanism is ORDERING, not validation: `carry()` is the only
-   public entry point, it remembers the argument and returns the fill, and the
-   filled series exists only as a return value that `carry()` itself never
-   sees again. `_remember()` is private, is called from exactly one place, and
-   `test_price_history.py` PARSES every shipped module under `app/`, `tools/`,
-   `scenarios/` and `estop/` and fails if any of them uses the NAME - an
-   attribute, a bare name, a def, or the string constant a `getattr` needs. By
-   name rather than by substring, so a comment about the rule does not fail it
-   and a call from `tools/` cannot pass unseen.
-
-   ⚠️ AND THE ORDER IS GRADED BY DRIVING IT, NOT BY READING THE SOURCE. The
-   first version of that check compared positions in `ast.walk`, which is
-   breadth-first: `self._remember(...)` is a statement and `self.yesterday(...)`
-   is an ARGUMENT of the fill, one level deeper, so `_remember` came out first
-   whichever statement was written first - shipped and reversed scored the
-   same. What grades it now is the behaviour: a feed carrying yesterday
-   alongside today, into an EMPTY store, must fill the whole horizon, and
-   reversed it fills nothing.
-
-2. "YESTERDAY" MEANS YESTERDAY, NOT "THE NEWEST DAY I HAVE".
-   `newest()` is the natural accessor and it is the one that decays: an add-on
-   down from Friday to Monday would answer Friday's prices to a fill that flags
-   them as one day old. The lookup is BY DATE - the Brussels day before the
-   Brussels day of the instant asked about - and a record for any other date is
-   NO_RECORD with a reason naming both dates. A three-day-old profile is not a
-   worse yesterday; it is not a yesterday.
-
-3. A STORE THAT CANNOT ANSWER SAYS SO, IN THE TYPE.
-   `yesterday()` returns a `PriceRead`: a `series` when a full record exists,
-   `no_data(reason)` for every other outcome - no file, no record for that
-   date, an unreadable file, a record that parses to nothing. There is no
-   empty-series answer and no `.get(..., [])`-shaped accessor, for
-   `price.py`'s reason: an empty series is how "the cache is broken" gets to
-   wear the shape of "yesterday was free". `fill_from_yesterday()` takes a
-   `PriceRead` and handles `no_data` on its own, so the degraded case needs no
-   branch at the call site - it fills nothing and the horizon stays short,
-   which is exactly the behaviour that shipped before this ticket.
-
-4. HOURS ACCUMULATE WITHIN A DAY; THEY DO NOT REPLACE IT.
-   A feed that serves only the REMAINING hours of the day (a legitimate shape -
-   nothing in the plugin contract promises a whole day) would, under
-   replace-the-record, overwrite a complete 24-hour profile with the two points
-   left at 22:00 and hand the next morning a yesterday with two hours in it. So
-   a record is MERGED by instant: a later read updates the hours it carries and
-   leaves the rest, and a revised price for an hour already held wins because
-   it is the newer statement about the same hour.
-
-⚠️ KEYED BY INSTANT, NOT BY LOCAL HOUR, AND THAT IS THE DST DECISION. Storing
-`hour -> price` would collapse the two 02:00s of a 25-hour October day into
-one, inventing a second and different collapsing rule beside the one
-`fill_from_yesterday()` already documents ("the first of its two 02:00 points
-is the one used, deterministically"). Storing the instants keeps both, in
-order, and lets the fill's own rule be the only one in the system.
-
-WHAT THIS DOES NOT DO, ON PURPOSE
-=================================
-It does not extend the fill to a feed that published NOTHING. `resolve_tariff()`
-applies `carry()` only on a `series` read; a `no_data` read still falls to
-`_degrade()` and §11.4's row - "No price data -> fall back to the static
-profile, mark the plan provisional, no arbitrage" - which is the fallback the
-operator configured `static_profile` FOR. Preferring yesterday's feed over it
-would change a documented degradation without being asked, and it would buy
-nothing measurable: a fully-carried series is 100 % provisional, so
-`arbitrage()` finds fewer than two firm hours and refuses, and `cheap_now()` is
-False, exactly as on the §11.4 fallback. The two differ only in which numbers
-the status page shows. `fill_from_yesterday()` handles a `no_data` read anyway,
-and that branch is therefore not reached from production - it stays checked,
-and turning it on is a product decision, not a wiring one. See
-DECISIONS/FCST-04-the-day-that-is-carried.md.
-"""
+Rows are keyed by instant, not local hour (the DST rule stays in the fill). A
+store that cannot persist records nothing (FCST-06). It does not extend the fill
+to a feed that published nothing: that stays 11.4's static fallback.
+DECISIONS/FCST-04-the-day-that-is-carried.md (section 5 has the store details)."""
 
 import copy
 import json
@@ -194,89 +33,31 @@ from .price_forecast import fill_from_yesterday
 
 _LOG = logging.getLogger("goodwe.price.history")
 
-# How many Brussels days of published prices the SORT-ORDER cap keeps. The fill
-# needs exactly one - yesterday - and rule 2 refuses anything older, so this is
-# not a horizon: it is the number of days a record may sit unused before
-# pruning removes it, and it is small because a bigger cache would only hold
-# days no lookup can ask for. Three covers today, yesterday, and the day a
-# fetch spanning midnight writes ahead of itself.
-#
-# ⚠️ IT IS A CAP, NOT THE RETENTION RULE, AND THREE HAS NO SLACK. The steady
-# state is already {yesterday, today, tomorrow}; a feed that publishes to D+2,
-# or ONE stray point in the wrong year - which sorts LAST and is therefore
-# immortal under a newest-N cap - pushes yesterday out of a three-slot store
-# and keeps it out, permanently and silently. So `_prune()` PINS the two days a
-# lookup can actually ask for on top of the cap; see its docstring. The store
-# is then bounded at KEEP_DAYS + 2 records rather than at KEEP_DAYS.
+# Brussels days kept: a sort-order cap, not a horizon (the fill needs only
+# yesterday).
 KEEP_DAYS = 3
 
 SCHEMA = 1
 
 
 def _bdate(instant: datetime) -> str:
-    """The Brussels calendar date of an instant, as `YYYY-MM-DD`.
-
-    ⚠️ BRUSSELS, NOT UTC. 23:30 UTC in July is already tomorrow in Belgium, and
-    a cache keyed on the UTC date would file the last 90-120 minutes of every
-    day under the wrong one - so a lookup on the following morning would find a
-    "yesterday" missing its own evening hours, which are the expensive ones.
-    """
+    """The Brussels calendar date of an instant, as `YYYY-MM-DD` (not UTC: 23:30 UTC in July is tomorrow)."""
     return brussels(instant).strftime("%Y-%m-%d")
 
 
 def _yesterday_of(instant: datetime) -> str:
     """The Brussels date of the day BEFORE `instant`'s Brussels day.
-
-    ⚠️ THE ARITHMETIC IS ON THE LOCAL DATE, NOT ON THE INSTANT, AND THAT IS A
-    DST DEFECT THIS FILE SHIPPED. `brussels()` renders at the FIXED offset in
-    force at that instant, so `brussels(stamp) - timedelta(days=1)` subtracts 24
-    ABSOLUTE hours from a wall clock - and the Brussels day before a
-    spring-forward is 23 hours long. Measured at 2026-03-30T00:30+02:00, the
-    first hour of the morning after the March transition: it returned
-    2026-03-28, so the fill carried a TWO-DAY-OLD profile flagged as yesterday's
-    (or, with only the last three days held, answered `no_data` naming a date
-    that is not yesterday).
-
-    A calendar day minus one day is `date` arithmetic, and a `date` has no
-    offset to lose. The 25-hour October day is right for the same reason.
-    """
+    Arithmetic on the local `date`, not the instant: subtracting 24 absolute hours
+    was wrong after the spring-forward. DECISIONS/FCST-04-the-day-that-is-carried.md."""
     return (brussels(instant).date() - timedelta(days=1)).strftime("%Y-%m-%d")
 
 
 def _point_of(row):
     """One stored row -> a `PricePoint`, or `None` if the row is not one.
 
-    THE ONE VALIDATOR, AND THE ASYMMETRY IT CLOSES (FCST-05's MEDIUM). This
-    file used to hold TWO standards for what a stored point is. The READ path
-    (`_parse_points()`) was properly defensive - every field checked, a
-    malformed row dropped and reported. The WRITE path was
-    `{q["start"]: q for q in raw if isinstance(q, dict) and "start" in q}`
-    followed by `sorted(..., key=lambda q: q["start"])`, which trusts
-    `q["start"]` to be a hashable, sortable string it never checked. Measured,
-    with the malformed row under the day the feed is currently writing to:
-
-        start is an int   -> TypeError: '<' not supported between instances
-                             of 'str' and 'int'
-        start is a dict   -> TypeError: cannot use 'dict' as a dict key
-        start is null     -> TypeError: '<' not supported between 'str' and
-                             'NoneType'
-        start is a list   -> TypeError: cannot use 'list' as a dict key
-
-    ⚠️ AND THE BLAST RADIUS IS PERMANENT, WHICH IS WHY IT IS NOT MERELY UNTIDY.
-    `_remember()` is reached through `carry()` -> `resolve_tariff()` ->
-    `run_tariff_refresh`, which catches `Exception` - so the add-on stays UP
-    and EVERY refresh raises forever. The plan retires after
-    `TARIFF_MAX_AGE_S`, and arbitrage and the cheap window are off from then
-    on. There is no self-heal, because `_remember()` raises before it reaches
-    `_save()`. `_usable_days()` only required `rec["points"]` to be a LIST; the
-    elements were unchecked on the write path, and the existing fixture put its
-    malformed row under a day the feed was NOT writing to, so `_remember()`
-    never touched it.
-
-    So both paths call this, and neither of them has a standard of its own.
-    Returning `None` rather than raising is the contract: a caller decides
-    whether a bad row is dropped (both of them do) and how it is reported.
-    """
+    The one validator for both the read and the write path (FCST-05): a malformed
+    row used to raise out of `carry()` and fail every refresh for good. Returns
+    `None` rather than raising; the caller decides how a bad row is reported."""
     if not isinstance(row, dict):
         return None
     try:
@@ -293,33 +74,8 @@ def _point_of(row):
 
 def _held(rec) -> tuple:
     """`(points, whole hours they cover)` for a day record. `(0, 0)` otherwise.
-
-    ⚠️ POINTS AND HOURS ARE TWO NUMBERS, AND FCST-04's STATUS ROW PRINTED THE
-    FIRST UNDER THE SECOND'S NAME. The row was `f"{d} ({_n_points(rec)} h)"`,
-    which counts POINTS: on the quarter-hourly feed this add-on already
-    supports it read `'2026-01-13 (96 h)'` - 96 "h" for a 24-hour day. That is
-    the points/hours conflation H1 was raised for, on the row H1's own ticket
-    shipped. Both numbers are reported now, so an operator can see a day that
-    is 24 points over 24 h and a day that is 96 points over 24 h and tell them
-    apart, and neither number is wearing the other's unit.
-
-    ⚠️ TOLERANT, AND IT IS THE SECOND LINE OF DEFENCE, NOT THE FIRST. `_load()`
-    drops a malformed day record and says so, so this should never see one. It
-    is written this way because `words` is read from `Controller.__init__` and
-    from every status render: a status LINE that raises takes the add-on down,
-    and "the cache is broken" must never be able to mean "the controller does
-    not start". That is exactly what FCST-04 shipped - `{"days": {"2026-01-14":
-    "oops"}}` gave `ok=True`, `last_error=None`, and an `AttributeError` out of
-    `words`, `yesterday()` and `resolve_tariff()` alike, with no self-heal
-    because `_remember()` raised before it could rewrite the file.
-
-    ⚠️ AND IT COUNTS ONLY ROWS THAT ARE POINTS. A row `_point_of()` refuses is
-    not held prices, and a row count that included it would report a store as
-    healthier than it is - which is the second half of FCST-05's MEDIUM: the
-    status row said `'2026-01-15 (1 h)'` about a record whose single row was
-    killing every tariff refresh. What is dropped is named in `last_error`, and
-    `words` prints that beside the counts.
-    """
+    Two numbers, each in its own unit (96 points over 24 h on a quarter-hourly
+    feed). Total, and counts only rows that are points."""
     if not isinstance(rec, dict):
         return (0, 0)
     raw = rec.get("points")
@@ -337,15 +93,7 @@ def _held(rec) -> tuple:
 
 
 def _row_of(day: str, points: int, hours: int) -> str:
-    """One day's cell of the status row: what is held, in BOTH of its units.
-
-    ⚠️ THE UNIT IS SPELT OUT ON EACH NUMBER. FCST-04's cell was
-    `f"{day} ({points} h)"` - the point count wearing the hour's name, which on
-    a quarter-hourly feed reads `'2026-01-13 (96 h)'` for a 24-hour day. What
-    an operator needs from this row is whether tomorrow morning's fill has a
-    whole day to carry, and that is the HOUR figure; the point count says how
-    finely it is priced. Neither answers for the other.
-    """
+    """One day's cell of the status row, with the unit spelt out on each number."""
     # UX-10: the day as the page writes dates ("26 Sep"), not ISO.
     return (f"{points} price{'' if points == 1 else 's'} over {hours} "
             f"hour{'' if hours == 1 else 's'} for {day_words(day)}")
@@ -373,21 +121,8 @@ def _bad_rows(rec) -> int:
 
 class PriceHistory:
     """The published price series of the last few Brussels days, in /data.
-
-    ⚠️ `ok` IS ABOUT THE FILE, NOT ABOUT THE DATA. A healthy store with no
-    record for yesterday is `ok` and answers `no_data` - a normal state on a
-    site's first day, and a different thing from a store that could not be
-    opened. Both are visible: `ok`/`last_error` describe the file, and
-    `yesterday()`'s reason describes the answer.
-
-    ⚠️ AND `ok` IS NOT "CAN PERSIST" (FCST-06). It says the directory was
-    there when the store opened, which a full volume and a read-only remount
-    both leave true. The one thing that answers "can this store persist" is
-    `_save()`'s return value, and `self._days` NEVER HOLDS A POINT THE FILE DOES
-    NOT, because `_remember()` undoes a merge that answer refused. That is what
-    makes `words` and `yesterday()` describe the same store in EVERY degraded
-    state rather than only in the ones somebody enumerated.
-    """
+    `ok` is about the file, not the data: a healthy store with no record for
+    yesterday is `ok` and answers `no_data`. `ok`/`last_error` describe the file."""
 
     def __init__(self, path: str = "/data/price_history.json"):
         self.path = path
@@ -396,15 +131,14 @@ class PriceHistory:
         self._days: dict = {}
         self._open()
 
-    # -- the file ------------------------------------------------------------
+    # the file
     def _open(self) -> None:
         parent = os.path.dirname(self.path)
-        # See the module note: NOT created. A cache on the ephemeral layer is
-        # one that forgets without saying so.
+        # NOT created (see FCST-04 section 5): a cache on the ephemeral layer
+        # forgets silently.
         if parent and not os.path.isdir(parent):
             self.last_error = f"no durable volume at {parent}"
-            # INFO, not ERROR: on a dev host or in a test container there is no
-            # /data and nothing is wrong.
+            # INFO, not ERROR: a dev host or test container has no /data.
             _LOG.info("No price history is kept (%s), so missing hours are "
                       "not filled from yesterday's prices.", self.last_error)
             return
@@ -421,32 +155,11 @@ class PriceHistory:
                       "after that", self.path)
             return
         except (ValueError, OSError) as err:
-            # A corrupt cache must not stop the controller, and must not be
-            # silently re-created either: the record is discarded, the reason
-            # is kept, and `yesterday()` reports it rather than answering
-            # "no record", which would read as a normal first day.
-            #
-            # ⚠️ `ValueError`, NOT `json.JSONDecodeError`, AND THAT IS
-            # FCST-05's HIGH. Reading this file has two failure families: the
-            # BYTES (`OSError`) and the CONTENT - and the content family has at
-            # least two members, because `open(..., encoding="utf-8")` decodes
-            # before `json` ever sees a character. `UnicodeDecodeError` is
-            # `ValueError -> UnicodeError -> UnicodeDecodeError`; it is NOT a
-            # `json.JSONDecodeError` and it is NOT an `OSError`
-            # (`issubclass(UnicodeDecodeError, OSError)` is False). So ONE
-            # non-UTF-8 byte in /data/price_history.json escaped `_load()` ->
-            # `_open()` -> `PriceHistory.__init__`, which is unguarded at
-            # main.py's `Controller.__init__`, AND THE ADD-ON DID NOT START.
-            # Measured: `UnicodeDecodeError: 'utf-8' codec can't decode byte
-            # 0xff in position 39`. Valid-UTF-8-invalid-JSON, a UTF-8 BOM and a
-            # non-dict day record all degraded correctly - it was the one byte
-            # class left uncovered, which is the same class as the defect the
-            # `_usable_days()` rework was raised for.
-            #
-            # The tuple names the FAMILY rather than the two members known
-            # today, because "the file's content is not readable as JSON" is
-            # exactly what this handler says, and a third `ValueError` subclass
-            # nobody has thought of is how this defect arrived the first time.
+            # A corrupt cache must not stop the controller nor be silently re-
+            # created: the record is discarded and the reason kept, so
+            # `yesterday()` reports it. `ValueError` is the family caught, not
+            # `json.JSONDecodeError` (one non-UTF-8 byte raised
+            # `UnicodeDecodeError` and the add-on did not start, FCST-05).
             self.last_error = f"unreadable ({err})"
             _LOG.warning("Price history at %s is %s, so it starts empty. "
                          "Missing hours cannot be filled in until a full day "
@@ -454,10 +167,7 @@ class PriceHistory:
                          self.path, self.last_error)
             return
         found = blob.get("version") if isinstance(blob, dict) else None
-        # ⚠️ THE TYPE IS PART OF THE VERSION. `1.0 == 1` in Python, so a float
-        # written by some other tool would pass a bare `!=` and be read as
-        # schema 1 - a version check that cannot tell 1 from 1.0 is one that
-        # would not notice a writer this build has never met.
+        # The type is part of the version: `1.0 == 1` in Python.
         if not isinstance(blob, dict) or isinstance(found, bool) \
                 or not isinstance(found, int) or found != SCHEMA:
             self.last_error = f"version {found!r}, not {SCHEMA}"
@@ -474,35 +184,8 @@ class PriceHistory:
 
     def _usable_days(self, days: dict) -> dict:
         """The day records that are shaped like day records. The rest are dropped.
-
-        ⚠️ THE ASYMMETRY THAT PRODUCED THE DEFECT: `_parse_points()` below is
-        carefully defensive about every field of a POINT, and `_load()` was not
-        defensive about the record holding them at all. `{"version": 1, "days":
-        {"2026-01-14": "oops"}}` therefore loaded as `ok=True`,
-        `last_error=None` - and then `rec.get(...)` raised `AttributeError` out
-        of `words`, `yesterday()` and `resolve_tariff()`. `PriceHistory(...)`
-        and `.words` are both unguarded in `Controller.__init__`, so THE ADD-ON
-        DID NOT START; and it never self-healed, because `_remember()` raised on
-        the same record before it could reach `_save()`.
-
-        A broken cache is a short horizon. It is not a controller that will not
-        regulate a battery, and §6's rule - absent machinery must not disable
-        the loop - does not stop applying because the machinery is a JSON file.
-
-        Dropped, not repaired: an unusable record has nothing in it to keep, and
-        the next `_remember()` writes a fresh one under that date.
-
-        ⚠️ AND THE ROWS INSIDE A KEPT RECORD ARE COUNTED, NOT ONLY THE RECORD
-        (FCST-05). This checked that `rec["points"]` is a LIST and stopped
-        there, so a record holding one row with a `start` of `7` loaded as
-        healthy: `last_error=None`, and `words` said `'2026-01-15 (1 h)'` about
-        a store whose next `_remember()` would raise on that row and go on
-        raising forever. The rows are NOT dropped here - `_parse_points()` is
-        the read path's one filter and stays so - but they are COUNTED, so the
-        store stops reporting health it does not have from the moment it is
-        opened. `_remember()` drops them on the next refresh and `_save()`
-        rewrites the file, after which a restart clears the note.
-        """
+        A broken cache is a short horizon, never a controller that will not start.
+        Rows inside a kept record are counted, not dropped (`_parse_points()` filters)."""
         kept, dropped, malformed = {}, [], {}
         for key, rec in days.items():
             if not isinstance(key, str) or not isinstance(rec, dict) \
@@ -524,9 +207,8 @@ class PriceHistory:
                 + ", ".join(f"{day_words(d)} ({n})"
                             for d, n in sorted(malformed.items())))
         if notes:
-            # Recorded, not silent: `yesterday()` and `words` both report
-            # `last_error`, and a cache that quietly discards half a file reads
-            # to an operator exactly like a normal first day.
+            # Recorded, not silent: a cache that quietly discards half a file
+            # reads like a first day.
             self.last_error = " and ".join(notes)
             _LOG.warning("Price history at %s: %s. The add-on starts anyway, "
                          "and fills in only what the rest holds.",
@@ -535,27 +217,7 @@ class PriceHistory:
 
     def _save(self) -> bool:
         """Write `self._days` out. True only if the file now holds it.
-
-        ⚠️ THE RETURN VALUE IS THE "CAN THIS STORE PERSIST?" PREDICATE, AND
-        IT IS THE ONLY ONE (FCST-06). Both ways of not persisting end here and
-        are the same answer: no durable volume returns False without touching
-        the disk, an `OSError` out of the write returns False after recording
-        why. `_remember()` acts on that one answer, so the second place that
-        used to test the first symptom on its own - and missed the second - has
-        nothing left to test. See the module docstring's fifth warning.
-
-        ⚠️ AND IT REPORTS, IT DOES NOT RAISE. §6 and this module's opening: a
-        broken cache must not be a broken controller. An add-on that will not
-        start because /data filled up is a worse defect than the one FCST-06
-        fixed, so a failed write is logged, kept in `last_error` - where `words`
-        and `yesterday()` both read it - and RETURNED, never thrown.
-
-        ⚠️ THE TEMP FILE IS REMOVED ON EVERY FAILING PATH. A write that dies
-        between `mkstemp` and `os.replace` used to leave its temp behind, and
-        the refresh task runs 48 times a day: a persistent write failure - a
-        full volume being the likeliest cause - leaked 48 inodes a day onto the
-        volume that was already the problem.
-        """
+        The one "can this store persist?" answer (FCST-06), asked after the attempt."""
         if not self.ok:
             return False
         tmp = None
@@ -563,8 +225,7 @@ class PriceHistory:
             fd, tmp = tempfile.mkstemp(dir=os.path.dirname(self.path))
             with os.fdopen(fd, "w", encoding="utf-8") as fh:
                 json.dump({"version": SCHEMA, "days": self._days}, fh, indent=1)
-            # Atomic: a power cut mid-write must not leave a truncated file
-            # that parses as an empty day.
+            # Atomic: a power cut mid-write must not leave a truncated file.
             os.replace(tmp, self.path)
             tmp = None                      # it IS the file now; do not unlink
         except OSError as err:
@@ -579,45 +240,24 @@ class PriceHistory:
                     pass                    # failed cleanup is not a fault
         return True
 
-    # -- the one public entry point -----------------------------------------
+    # the one public entry point
     def carry(self, read: PriceRead, *, since: datetime, until: datetime,
               stamp: datetime, remember: bool = True) -> PriceRead:
-        """Remember what this read published, then §8.3-fill the missing hours.
-
-        THE ORDER IS DELIBERATE AND IS THE POINT OF THE METHOD. The read is
-        recorded FIRST, so a feed that hands back yesterday alongside today
-        refreshes yesterday's record from live data before it is consumed as
-        the profile; and the filled series - the one thing that must never be
-        recorded - exists only as this method's return value, which this object
-        never sees again. See rule 1, including how that order is graded.
-
-        Returns whatever `fill_from_yesterday()` returns: a series over the
-        whole hours of [since, until), carrying EVERY point the provider
-        published inside it - by identity, and four of them in one hour on a
-        quarter-hourly feed - plus one carried point for each remaining whole
-        hour FOR WHICH YESTERDAY HELD THAT WALL-CLOCK HOUR. An hour neither
-        source can price is left out (§11.4 for that hour), and `no_data` comes
-        back when that is every hour.
-        """
+        """Remember what this read published, then 8.3-fill the missing hours.
+        Recorded FIRST, so the filled series exists only as the return value (rule 1).
+        Returns `fill_from_yesterday()`'s series, or `no_data` when no hour can be priced."""
         if remember:
-            # PRICE-01: False only for a read that CAME FROM this store
-            # (`stored()`), which is already filed; filing it again would
-            # rewrite the same file for nothing, and nothing else may pass it.
+            # PRICE-01: False only for a read that came from this store,
+            # already filed.
             self._remember(read, stamp)
         return fill_from_yesterday(read, yesterday=self.yesterday(stamp),
                                    since=since, until=until, stamp=stamp)
 
-    # -- the halves, private because rule 1 is an ordering ------------------
+    # the halves, private because rule 1 is an ordering
     def _remember(self, read: PriceRead, stamp: datetime) -> None:
         """File a provider read's points under their own Brussels days.
-
-        ⚠️ PRIVATE, AND CALLED FROM EXACTLY ONE PLACE. A caller that can reach
-        this can record a filled series, which is the decay in rule 1. There is
-        no value-level defence against that - a carried point and a published
-        provisional point are the same three fields - so the defence is that
-        nothing outside this file names it, and `test_price_history.py` checks
-        the tree for that rather than trusting the underscore.
-        """
+        Private, called from exactly one place: no value-level defence can tell a
+        carried point from a published-provisional one, so the defence is the ordering."""
         points = read.match(series=lambda r: r.points, no_data=lambda _r: ())
         if not points:
             return
@@ -626,23 +266,9 @@ class PriceHistory:
         provider = read.match(series=lambda r: r.provider,
                               no_data=lambda _r: None)
 
-        # ⚠️ THE STATE THIS READ STARTED FROM, KEPT SO IT CAN BE PUT BACK
-        # (FCST-06). Everything below merges into `self._days` IN PLACE, and
-        # whether any of it may be KEPT is not knowable until `_save()` has
-        # tried - so the merge runs, and it is undone if the file did not take
-        # it. There is no `not self.ok` branch above any more: a store with no
-        # durable volume is one of the answers `_save()` gives, not a separate
-        # symptom with a test of its own. Module docstring, fifth warning.
-        #
-        # ⚠️ DEEP, NOT `dict(self._days)`. A one-level copy shares the day
-        # RECORDS, and the loop below rebinds keys on the ones it touches - so
-        # the "previous" state would hand back records the merge had already
-        # edited, and a store with a good yesterday on disk would go on
-        # answering the merge of it that never reached the file. It would also
-        # be right only for as long as nobody makes this loop mutate a `points`
-        # list or a row in place. A copy that is right by construction outlives
-        # that, and the store holds at most KEEP_DAYS + 2 records, 48 times a
-        # day.
+        # The state this read started from, kept so it can be put back
+        # (FCST-06): the merge runs in place and is undone if `_save()` did not
+        # take it. Deep copy, since the loop rebinds the day records.
         before = copy.deepcopy(self._days)
 
         touched = set()
@@ -651,29 +277,11 @@ class PriceHistory:
             day = _bdate(p.start)
             rec = self._days.setdefault(
                 day, {"product": product, "provider": provider, "points": []})
-            # Rule 4: MERGE by instant. A later read updates the hours it
-            # carries and leaves the rest; a revised price for an hour already
-            # held wins, because it is the newer statement about that hour.
-            #
-            # ⚠️ EVERY HELD ROW GOES THROUGH `_point_of()` (FCST-05's MEDIUM).
-            # This was `{q["start"]: q for q in raw if isinstance(q, dict) and
-            # "start" in q}` sorted by `q["start"]` - a key and a sort key that
-            # trusted a value read off disk to be a hashable, sortable string.
-            # An `int`, `null`, a `dict` or a `list` there raised `TypeError`
-            # out of `carry()` on the day the feed was writing to, and
-            # `run_tariff_refresh` caught it, so the add-on stayed up while
-            # EVERY refresh failed for good. A row that is not a point is now
-            # dropped and reported here, exactly as the read path drops it, and
-            # `_save()` below writes the record back clean - which is the
-            # self-heal the raising version could never reach.
-            #
-            # ⚠️ AND THE MERGE KEY IS THE VALIDATED INSTANT, NOT ITS SPELLING.
-            # Aware datetimes hash and compare by instant, so this is rule 4 as
-            # rule 4 is written. The old string key merged by SPELLING, and the
-            # old lexicographic sort put the second 02:00 of the 25-hour
-            # October day (`+01:00`) BEFORE the first (`+02:00`). Only the
-            # stored order was affected - `_parse_points()` re-sorts by instant
-            # on the way out - but the store now holds what it says it holds.
+            # Rule 4: MERGE by instant; a later read updates the hours it
+            # carries. Every held row goes through `_point_of()` and the key is
+            # the validated instant, not its spelling (FCST-05). A row that is
+            # not a point is dropped and reported, and `_save()` writes the
+            # record back clean.
             raw = rec.get("points")
             held = {}
             for q in (raw if isinstance(raw, list) else ()):
@@ -689,13 +297,8 @@ class PriceHistory:
             touched.add(day)
 
         if junked:
-            # Said, not swallowed. `words` prints `last_error`, so a store that
-            # has just discarded rows off disk stops reporting plain health -
-            # and after `_save()` below the file is clean, so a restart clears
-            # this. `_save()` overwrites it if the write itself fails, which is
-            # the more urgent fact of the two - and on that path the drop is
-            # undone with the rest of the merge, so those rows are still in the
-            # file and the next write that completes drops them again.
+            # Said, not swallowed: `words` prints `last_error`. A failed
+            # `_save()` overwrites it and undoes the drop.
             self.last_error = (
                 f"{messages.count(sum(junked.values()), 'bad price')} dropped "
                 f"from " + ", ".join(f"{day_words(d)} ({n})"
@@ -705,48 +308,19 @@ class PriceHistory:
                          self.path, self.last_error)
         self._prune(stamp)
         if not self._save():
-            # ⚠️ A STORE THAT CANNOT PERSIST RECORDS NOTHING - the rule, asked
-            # ONCE as a question about the outcome instead of tested twice
-            # against two symptoms of it. Keeping the merge here is exactly the
-            # cache the module docstring refuses: `yesterday()` would answer a
-            # series the file does not contain, all day, until a restart
-            # dropped it without a word - and `words` and `yesterday()` would
-            # be describing two different stores. The reason is already in
-            # `last_error` (from `_save()`, or from `_open()` when there is no
-            # volume at all), so both answers now describe what is on disk.
-            #
-            # It does NOT raise, and §6 is why: a broken cache must not be a
-            # broken controller. `carry()` still returns the fill, the horizon
-            # is as short as the feed makes it, and the add-on regulates.
+            # A store that cannot persist records nothing (FCST-06):
+            # `_save()`'s answer decides what is kept, so `yesterday()` never
+            # answers a series the file does not hold.
             self._days = before
             return
         _LOG.debug("price history: %d point(s) filed under %s; %d day(s) held",
                    len(points), ", ".join(sorted(touched)), len(self._days))
 
     def _prune(self, stamp: datetime) -> None:
-        """Drop records no lookup can reach. A sort-order cap, plus two pins.
-
-        ⚠️ NOTHING IS DELETED BY ARITHMETIC AGAINST THE CLOCK. A clock that
-        jumped - the failure mode WITNESS-03 spent a session on - would
-        otherwise delete every record in one pass and leave the fill with
-        nothing on the morning after, which is the one morning it is for.
-        Deleting on a bad clock is unrecoverable; holding a few days too many
-        is not, so the cap is `sorted(...)[-KEEP_DAYS:]` and stays that way.
-
-        ⚠️ AND A CAP ALONE IS DEFEATED BY ONE POINT IN THE WRONG YEAR. Sorting
-        is lexicographic on the date string, so a stray far-future record sorts
-        LAST and is immortal - it consumes a slot for good, and with the steady
-        state already {yesterday, today, tomorrow} filling all three, yesterday
-        is what falls out. A feed that publishes to D+2 does the same thing
-        without any stray at all. So the two days `yesterday()` can ACTUALLY be
-        asked for are pinned on top of the cap.
-
-        `stamp` is READ here, which it was not before: the pin is the only use
-        of it, and it is additive. Pinning can only RETAIN a record, never
-        delete one, so a jumped `stamp` pins two dates that are not held and
-        changes nothing - the WITNESS-03 property is preserved by construction
-        rather than by remembering to check it.
-        """
+        """Drop records no lookup can reach: a sort-order cap plus two pins. Nothing is
+        deleted by arithmetic against the clock (a jumped clock would delete everything,
+        WITNESS-03). The pin of the two dates `yesterday()` can be asked for only
+        retains, so a far-future record cannot push yesterday out."""
         if len(self._days) <= KEEP_DAYS:
             return
         keep = set(sorted(self._days)[-KEEP_DAYS:])
@@ -756,11 +330,7 @@ class PriceHistory:
 
     def yesterday(self, stamp: datetime) -> PriceRead:
         """The published series of the Brussels day BEFORE `stamp`'s, or no_data.
-
-        ⚠️ THE DATE IS COMPUTED, NOT LOOKED UP. See rule 2: `newest()` would
-        answer Friday's prices to a Monday fill, and the fill would flag them as
-        one day old because that is the only thing its flag can say.
-        """
+        Computed, not looked up (rule 2)."""
         if stamp.tzinfo is None or stamp.utcoffset() is None:
             raise ValueError(
                 f"yesterday({stamp!r}): a naive datetime is not an instant, "
@@ -803,19 +373,9 @@ class PriceHistory:
                                 stamp)
 
     def stored(self, stamp: datetime) -> PriceRead:
-        """PRICE-01: every price this store holds, as one series, or no_data.
-
-        This is the LAST step of the price server's fallback (price_chain.py):
-        the answer of the last fetch that worked, kept on disk, so a site can
-        plan for as long as the days it holds last. It is a read of what was
-        PUBLISHED and filed, in the order they happened, and it is never the
-        carried fill (rule 1 holds: `carry(..., remember=False)` is how this
-        read is filled, and it is not filed again).
-
-        The prices are the all-in ones stored when they were fetched. They are
-        not worked out again, so a change of markup or taxes shows from the
-        next fetch that works, not in these.
-        """
+        """PRICE-01: every price this store holds, as one series, or no_data. The last
+        step of the price server's fallback (price_chain.py): what was PUBLISHED and
+        filed, never what a fill produced."""
         if stamp.tzinfo is None or stamp.utcoffset() is None:
             raise ValueError(f"stored({stamp!r}): a naive datetime is not an "
                              f"instant")
@@ -833,25 +393,12 @@ class PriceHistory:
         return PriceRead.series(points, PriceProduct.DAY_AHEAD,
                                 "price_history", stamp)
 
-    # -- observability -------------------------------------------------------
+    # observability
     @property
     def words(self) -> str:
         """One line for the status page. Says what is held, or why nothing is.
-
-        ⚠️ THIS MUST NOT RAISE, EVER. It is read once from `Controller.__init__`
-        and again on every status render, and neither call site guards it - so
-        an exception here is an add-on that does not start. It went out that
-        way: a day record that was a string instead of a dict raised
-        `AttributeError` from the `len(...)` below. `_load()` now drops such a
-        record and `_held()` is total, so this has two independent reasons not
-        to fail on a broken file.
-
-        ⚠️ AND IT COUNTED POINTS AND CALLED THEM HOURS (FCST-05's LOW). The row
-        was `f"{d} ({_n_points(rec)} h)"`; on the quarter-hourly feed this
-        add-on already supports that reads `'2026-01-13 (96 h)'` for a 24-hour
-        day. Both numbers are printed now - see `_held()` - because they are
-        two different facts and only one of them was ever being shown.
-        """
+        Must not raise, ever: it runs from `Controller.__init__` and every status
+        render, unguarded. Prints points and hours separately (FCST-05)."""
         if not self.ok:
             return f"unavailable - {self.last_error}"
         if not self._days:
@@ -859,26 +406,20 @@ class PriceHistory:
             return f"empty{why} - nothing to carry forward yet"
         held = ", ".join(_row_of(d, *_held(self._days[d]))
                          for d in sorted(self._days, key=str))
-        # A file that PARTLY loaded says so, or the dropped days read as days
-        # that were simply never written.
+        # A file that partly loaded says so, or dropped days read as never
+        # written.
         return held + (f" [{self.last_error}]" if self.last_error else "")
 
 
 def _parse_points(raw) -> tuple:
-    """Canonical dicts -> PricePoints, and a phrase naming what was dropped.
-
-    ⚠️ A MALFORMED POINT IS DROPPED, NOT DEFAULTED, and the drop is reported.
-    `float(row.get("eur_per_kwh", 0))` is the shape of the whole family of
-    defects this repo has been removing: a cache that lost a field would answer
-    "that hour was free" to a fill that flags it as an ordinary guess.
-    """
+    """Canonical dicts -> PricePoints, and a phrase naming what was dropped. A
+    malformed point is dropped, not defaulted: a lost field must not read as a free hour."""
     if not isinstance(raw, list):
         return (), "the `points` field is not a list"
     out, dropped = [], 0
     for row in raw:
-        # ⚠️ `_point_of()` IS THE ONE VALIDATOR, and this loop used to BE it.
-        # The write path had its own, weaker standard; see `_point_of()` for
-        # what that cost. One standard, two callers, no asymmetry to re-open.
+        # `_point_of()` is the one validator; this loop used to be a weaker
+        # one.
         pt = _point_of(row)
         if pt is None:
             dropped += 1
@@ -889,20 +430,8 @@ def _parse_points(raw) -> tuple:
 
 
 class NoHistory:
-    """The explicit "this caller keeps no history" - a NAME, not a `None`.
-
-    ⚠️ IT EXISTS SO THE PARAMETER CAN BE REQUIRED. `history=None` meaning "skip
-    the fill" is the shape this repo keeps removing: a caller who forgets the
-    argument gets the truncated-horizon behaviour of the bug this ticket is
-    about, silently, and the code reads as though the fill is happening. With
-    no default there is nothing to forget, and a caller with no durable volume
-    - a check, a replay harness - has to say `NoHistory()` and be visible in
-    the diff.
-
-    It carries out the ordering faithfully: it records nothing and carries
-    nothing, so `carry()` returns the provider's read unchanged and the plan is
-    exactly what it was before FCST-04.
-    """
+    """The explicit "this caller keeps no history": a NAME, not `None`, so the
+    parameter can be required. It records nothing and carries nothing."""
 
     ok = False
     last_error = "no history is kept by this caller"

goodwe_controller/app/solarfc.py

@@ -28,6 +28,20 @@ A reading older than `FRESH_S`, or from before local midnight, is stale,
 and a stale or missing forecast is no forecast: the day plan is off and
 every mode acts as in P3 option A.
 
+OPT-27: but the last fresh reading of each sensor is kept (`Hold`), so the
+night plan is not made blind. Forecast.Solar's sensors stop changing in the
+evening and api.forecast.solar is sometimes out for a poll. A kept reading
+stands in for its sensor (a) for up to `FRESH_S` when the sensor is missing
+or unavailable, as a sensor that merely stopped updating is already
+tolerated, and (b) from the end of the bell (`BELL_TO_H`) until local
+midnight, if it is at most `KEPT_MAX_AGE_S` old when used.
+Never beyond that, and never for another day: a today figure is only today's,
+a tomorrow figure is tomorrow's until midnight and then, until the bell starts
+(`BELL_FROM_H`, 06:00 local), today's (OPT-34: at most `KEPT_MORNING_MAX_AGE_S`
+old, and it must have been usable at midnight).
+DECISIONS/OPT-27-last-fresh-forecast-for-the-night.md,
+DECISIONS/OPT-34-the-night-charge-keeps-its-level.md.
+
 OPT-17: each day may instead name a list (`pv_forecast_entities`,
 `pv_forecast_tomorrow_entities`), summed by `read_sum()`. One member that is
 not usable makes that day's sum unusable, never a partial sum.
@@ -50,6 +64,19 @@ FRESH_S = 3 * 3600.0
 # The bell a state-only forecast is spread over, in local hours.
 BELL_FROM_H, BELL_TO_H = 6.0, 20.0
 
+# OPT-27: a kept reading serves the night plan from the end of the bell until
+# local midnight, and a reading older than this when used is not kept (a
+# morning figure must not drive the night).
+KEPT_MAX_AGE_S = 12 * 3600.0
+# OPT-34: the evening's "tomorrow" figure, once midnight has passed, is today's
+# until the bell starts (`BELL_FROM_H`): nothing has been produced yet, so it
+# is still the whole day. A 17:05 reading is 12 h 55 min old at 06:00, so this
+# case may be older than `KEPT_MAX_AGE_S`, up to this, but only a figure that
+# was usable at midnight (at most `KEPT_MAX_AGE_S` old then), so one that has
+# not been used all evening does not come back at 00:00.
+KEPT_MORNING_MAX_AGE_S = 15 * 3600.0
+SAVE_EVERY_S = 900.0
+
 # Why there is no forecast (the page words are in ui_text `home_words`).
 NOT_SET, MISSING, UNIT, STALE, BAD = (
     "not_set", "missing", "unit", "stale", "bad")
@@ -75,6 +102,10 @@ class Forecast:
     today: Day
     tomorrow: Day | None
     at: datetime                # when the sensor last reported
+    # OPT-27: a reading kept past `FRESH_S` is in it (the evening's figure at
+    # night). The screens say so. Last, so `Forecast(today, tomorrow, at)` is
+    # as before.
+    kept: bool = False
 
     def between(self, t0: datetime, t1: datetime,
                 since: datetime | None = None) -> float | None:
@@ -246,6 +277,112 @@ def _reported(state):
     return max(ts) if ts else None
 
 
+class Hold:
+    """OPT-27: the last fresh reading of each forecast sensor, per day it is
+    for. `read_sum()` remembers every fresh reading here and, when a sensor
+    has none now, asks it (`stand_in()`).
+
+    Keyed `(kind, entity, day0)`: `kind` is "today" (energy still to come on
+    `day0`) or "tomorrow" (all of `day0`), and `day0` is the day the figure is
+    FOR. A today figure therefore never answers for another day, and a
+    tomorrow figure answers for its own day only: tomorrow until midnight,
+    then today until the bell starts (OPT-34). Only the newest reading of a
+    key is kept, so the next fresh reading ends the hold at once.
+
+    `dump()` / `load()` are what the controller keeps in its store, so an
+    evening restart does not lose it (`load()` drops what is bad).
+    `changed` is set when `dump()` would differ."""
+
+    def __init__(self, data=None):
+        self._r = {}
+        self._saved = {}        # key -> the `at` last flagged for saving
+        self.changed = False
+        if isinstance(data, dict):
+            self.load(data)
+
+    def remember(self, kind, entity, day: "Day", at: datetime) -> None:
+        key = (kind, entity, day.day0)
+        old = self._r.get(key)
+        if old is not None and at <= old[1]:
+            return
+        self._r[key] = (day, at)
+        # A sensor that reports every minute with the same figure must not
+        # rewrite the store every minute: the saved age may lag by
+        # `SAVE_EVERY_S` (the bounds are hours).
+        mark = self._saved.get(key)
+        if old is None or old[0].kwh != day.kwh or mark is None \
+                or (at - mark).total_seconds() >= SAVE_EVERY_S:
+            self._saved[key] = at
+            self.changed = True
+
+    def forget_before(self, day0: datetime) -> None:
+        """Drop what is for a day before `day0` (the local midnight now)."""
+        gone = [k for k in self._r if k[2] < day0]
+        for k in gone:
+            del self._r[k]
+            self._saved.pop(k, None)
+        if gone:
+            self.changed = True
+
+    def stand_in(self, kind, entity, day0, now, *, as_today=False):
+        """`(Day, at, kept)` for a sensor that has no fresh reading, or None.
+
+        The kept reading must be for `day0`, and either (a) at most `FRESH_S`
+        old, or (b) used at night: from the end of the bell to local midnight,
+        at most `KEPT_MAX_AGE_S` old. `kept` is true when (b) was needed,
+        or `as_today` (OPT-34: a tomorrow figure standing in for today, after
+        midnight and until the bell starts, `KEPT_MORNING_MAX_AGE_S`)."""
+        rec = self._r.get((kind, entity, day0))
+        if rec is None:
+            return None
+        day, at = rec
+        age = (now - at).total_seconds()
+        if age <= FRESH_S and not as_today:
+            return day, at, False
+        if as_today:
+            ok = (day0 <= now < _bell_start(day0)
+                  and age <= KEPT_MORNING_MAX_AGE_S
+                  and (day0 - at).total_seconds() <= KEPT_MAX_AGE_S)
+            return (day, at, True) if ok else None
+        if age > KEPT_MAX_AGE_S:
+            return None
+        # A tomorrow sensor is asked with day0 = the next midnight, which is
+        # in the future all day, so the evening ends at that day's end.
+        evening = _local_hour(now) >= BELL_TO_H and now < _bounds(day0)[1]
+        return (day, at, True) if evening else None
+
+    def dump(self) -> dict:
+        return {"v": 1, "r": [
+            [kind, ent, d.day0.isoformat(), d.kwh, at.isoformat(),
+             [[s.isoformat(), e.isoformat(), k] for s, e, k in d.periods]]
+            for (kind, ent, _d0), (d, at) in sorted(
+                self._r.items(), key=lambda kv: (kv[0][0], kv[0][1],
+                                                 kv[0][2]))]}
+
+    def load(self, data: dict) -> None:
+        rows = data.get("r") if isinstance(data, dict) else None
+        if not isinstance(rows, list):
+            return
+        for row in rows:
+            try:
+                kind, ent, d0, kwh, at, per = row
+                day0, at = _parse_time(d0), _parse_time(at)
+                kwh = float(kwh)
+                periods = tuple((_parse_time(s), _parse_time(e), float(k))
+                                for s, e, k in per)
+                ok = (kind in ("today", "tomorrow") and isinstance(ent, str)
+                      and day0 is not None and at is not None
+                      and math.isfinite(kwh) and kwh >= 0
+                      and all(s is not None and e is not None and e > s
+                              and math.isfinite(k) and k >= 0
+                              for s, e, k in periods))
+            except (TypeError, ValueError):
+                continue
+            if ok:
+                self._r[(kind, ent, day0)] = (Day(day0, kwh, periods), at)
+                self._saved[(kind, ent, day0)] = at
+
+
 def entities(opts: dict, *, tomorrow=False) -> tuple:
     """The forecast entities one day names, in configured order: the list
     if it has any entry, else the single key, else (). A repeated id is
@@ -267,6 +404,15 @@ def _bounds(now):
     return d0.astimezone(timezone.utc), d1.astimezone(timezone.utc)
 
 
+def _bell_start(day0):
+    """The moment the bell starts on the local day that begins at `day0`
+    (`BELL_FROM_H` local, so 06:00 on a 23 h or 25 h day too)."""
+    here = day0.astimezone(BILLING_TZ)
+    t = datetime(here.year, here.month, here.day, tzinfo=BILLING_TZ) \
+        + timedelta(hours=BELL_FROM_H)
+    return t.astimezone(timezone.utc)
+
+
 def _today(state, day0, now):
     """`(Day, at, None)` or `(None, None, why)` for one today sensor."""
     today, why = _day(state, day0, now, today=True)
@@ -282,14 +428,14 @@ def _today(state, day0, now):
 
 
 def _tomorrow(state, day0, day1, now):
-    """`(Day, None)` or `(None, why)` for one tomorrow sensor."""
+    """`(Day, at, None)` or `(None, None, why)` for one tomorrow sensor."""
     t, why = _day(state, day1, now, today=False)
     if t is None:
-        return None, why
+        return None, None, why
     t_at = _reported(state)
     if t_at is None or t_at < day0 or (now - t_at).total_seconds() > FRESH_S:
-        return None, STALE
-    return t, None
+        return None, None, STALE
+    return t, t_at, None
 
 
 def read(today_state, tomorrow_state, now: datetime, *,
@@ -305,7 +451,7 @@ def read(today_state, tomorrow_state, now: datetime, *,
         return None, why
     tomorrow = None
     if tomorrow_state is not None:
-        tomorrow, _w = _tomorrow(tomorrow_state, day0, day1, now)
+        tomorrow, _at, _w = _tomorrow(tomorrow_state, day0, day1, now)
     return Forecast(today, tomorrow, at), None
 
 
@@ -321,7 +467,12 @@ def _sum(days):
     return Day(days[0].day0, sum(d.kwh for d in days), periods)
 
 
-def read_sum(today, tomorrow, now: datetime):
+# Why a sensor may be covered by a kept reading: it has none now, or it is
+# too old. A bad value or a wrong unit is a set-up fault and is never covered.
+_COVERABLE = (MISSING, STALE)
+
+
+def read_sum(today, tomorrow, now: datetime, hold: Hold | None = None):
     """OPT-17: `(Forecast or None, why, gaps)` over lists of
     `(entity, state)`, one per configured member, in configured order.
 
@@ -334,29 +485,67 @@ def read_sum(today, tomorrow, now: datetime):
     `gaps` is `((day, position, entity, why), ...)` for every unusable
     member (`day` "today" or "tomorrow", `position` 1-based), so the page
     and the log can name it. With one member per day the forecast is what
-    `read()` gives (test_opt17.py proves it)."""
+    `read()` gives (test_opt17.py proves it).
+
+    OPT-27: with a `hold`, every fresh reading is remembered in it, and a
+    member that is missing or stale is covered by its last fresh reading
+    where `Hold.stand_in()` allows it (the forecast then has `kept` set when
+    that took a reading older than `FRESH_S`). After midnight, if the today
+    side is still short, the tomorrow figures read before midnight are
+    today's, until the bell starts (`stand_in()`). Without a `hold` this is
+    exactly as before."""
     if not today:
         return None, NOT_SET, ()
     day0, day1 = _bounds(now)
-    gaps, days, ats, why0 = [], [], [], None
+    if hold is not None:
+        hold.forget_before(day0)
+    gaps, days, ats, why0, kept = [], [], [], None, False
     for i, (ent, st) in enumerate(today, 1):
         d, at, why = _today(st, day0, now)
+        if d is not None and hold is not None:
+            hold.remember("today", ent, d, at)
+        elif hold is not None and why in _COVERABLE:
+            r = hold.stand_in("today", ent, day0, now)
+            if r is not None:
+                d, at, k = r
+                kept = kept or k
         if d is None:
             gaps.append(("today", i, ent, why))
             why0 = why0 or why
         else:
             days.append(d)
             ats.append(at)
-    tdays = []
+    tdays, tats, tkept = [], [], False
     for i, (ent, st) in enumerate(tomorrow, 1):
-        t, why = _tomorrow(st, day0, day1, now)
+        t, t_at, why = _tomorrow(st, day0, day1, now)
+        if t is not None and hold is not None:
+            hold.remember("tomorrow", ent, t, t_at)
+        elif hold is not None and why in _COVERABLE:
+            r = hold.stand_in("tomorrow", ent, day1, now)
+            if r is not None:
+                t, t_at, k = r
+                tkept = tkept or k
         if t is None:
             gaps.append(("tomorrow", i, ent, why))
         else:
             tdays.append(t)
+            tats.append(t_at)
+    if why0 is not None and hold is not None and tomorrow and all(
+            g[3] in _COVERABLE for g in gaps if g[0] == "today"):
+        # Past midnight the sensors may still show yesterday's "left today".
+        # The figure each tomorrow sensor gave before midnight is for this
+        # day; all of them are needed, as for any sum.
+        subs = [hold.stand_in("tomorrow", ent, day0, now, as_today=True)
+                for ent, _st in tomorrow]
+        if all(r is not None for r in subs):
+            days = [r[0] for r in subs]
+            ats = [r[1] for r in subs]
+            gaps = [g for g in gaps if g[0] != "today"]
+            why0, kept = None, True
     gaps = tuple(gaps)
     if why0 is not None:
         return None, why0, gaps
     tday = _sum(tdays) if tomorrow and len(tdays) == len(tomorrow) else None
+    kept = kept or (tday is not None and tkept)
     # The oldest member's report is when the sum was last fully known.
-    return Forecast(_sum(days), tday, min(ats)), None, gaps
+    return Forecast(_sum(days), tday, min(ats), kept), None, gaps

goodwe_controller/app/ui_text/en.json

@@ -360,7 +360,7 @@
       "tops_up": "It charges from the grid to {pct}. That covers {kwh} of expensive hours the sun will not.",
       "no_forecast": "No solar forecast, so it charges from solar only."
     },
-    "solar": {"line": "Solar still to come today: {kwh}, we count on {count}. Updated {at}.", "uncovered": "The expensive hours need more than Leftover solar can hold. The rest, {kwh}, comes from another battery or the grid.", "no_forecast": "No solar forecast now, so Leftover solar charges from solar only.", "learning": "The add-on is learning your house's use. The plan starts after one full day."},
+    "solar": {"line": "Solar still to come today: {kwh}, we count on {count}. Updated {at}.", "uncovered": "The expensive hours need more than Leftover solar can hold. The rest, {kwh}, comes from another battery or the grid.", "kept": "Solar forecast read {at}, kept for tonight.", "no_forecast": "No solar forecast now, so Leftover solar charges from solar only.", "latched": "No solar forecast now. The charge under way goes on to its planned level.", "learning": "The add-on is learning your house's use. The plan starts after one full day."},
     "today": {
       "not_planned": "Not planned yet.",
       "no_runs": "No cheap or expensive hours left today.",
@@ -437,6 +437,9 @@
     "step_in_would": "The batteries would step in above {kw}.",
     "period": "This 15-minute period is heading for {kw}.",
     "period_unmeasured": "Part of this 15-minute period was not measured.",
+    "period_over": "At this rate this 15-minute period reaches {kw}.",
+    "charge_cut": "The grid charge is cut back to stay under {kw}.",
+    "charge_cut_would": "The grid charge would be cut back to stay under {kw}.",
     "prices": {
       "now": "Price now {eur} per kWh, all in.",
       "today": "Today: lowest {lo} at {lo_at}, highest {hi} at {hi_at}.",

goodwe_controller/app/ui_text/nl.json

@@ -300,7 +300,7 @@
       "tops_up": "Ze laadt van het net tot {pct}. Dat dekt {kwh} dat de zon in dure uren niet levert.",
       "no_forecast": "Geen zonneprognose, dus ze laadt alleen met zonne-energie."
     },
-    "solar": {"line": "Nog verwachte zon vandaag: {kwh}, we rekenen op {count}. Bijgewerkt om {at}.", "uncovered": "De dure uren vragen meer dan Overschot zonne-energie kan opslaan. De rest, {kwh}, komt van een andere batterij of het net.", "no_forecast": "Nu geen zonneprognose, dus Overschot zonne-energie laadt alleen met zon.", "learning": "De add-on leert eerst het verbruik van uw huis. Het plan start na één volle dag."},
+    "solar": {"line": "Nog verwachte zon vandaag: {kwh}, we rekenen op {count}. Bijgewerkt om {at}.", "uncovered": "De dure uren vragen meer dan Overschot zonne-energie kan opslaan. De rest, {kwh}, komt van een andere batterij of het net.", "kept": "Zonneprognose van {at}, bewaard voor vannacht.", "no_forecast": "Nu geen zonneprognose, dus Overschot zonne-energie laadt alleen met zon.", "latched": "Nu geen zonneprognose. De lopende lading gaat door tot het geplande niveau.", "learning": "De add-on leert eerst het verbruik van uw huis. Het plan start na één volle dag."},
     "today": {
       "not_planned": "Nog niet gepland.",
       "no_runs": "Vandaag geen goedkope of dure uren meer.",
@@ -372,6 +372,9 @@
     "step_in_would": "De batterijen zouden bijspringen boven {kw}.",
     "period": "Dit kwartier gaat richting {kw}.",
     "period_unmeasured": "Een deel van dit kwartier is niet gemeten.",
+    "period_over": "Aan dit tempo komt dit kwartier op {kw}.",
+    "charge_cut": "Laadt minder van het net om onder {kw} te blijven.",
+    "charge_cut_would": "Zou minder van het net laden om onder {kw} te blijven.",
     "prices": {"now": "Prijs nu {eur} per kWh, alles inbegrepen.", "today": "Vandaag: laagste {lo} om {lo_at}, hoogste {hi} om {hi_at}.", "none": "Geen prijzen voor vandaag."},
     "tomorrow": {"known": "De prijzen van morgen zijn binnen.", "unknown": "De prijzen van morgen komen meestal na 13:00."},
     "day": {

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.19.0"
+version: "0.19.2"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over its RS485 EMS port by sending it a

goodwe_controller/test_arbitrage.py

@@ -936,6 +936,8 @@ def _s45_assigned(name, clear=("None",)):
 
 
 _s45_head_src = _s45_assigned("arb_headroom_w")
+# SAFETY-125: the guard's headroom with a late reading's seconds counted.
+S125_ROOM = "peakguard.charge_room_w(self.peak_guard, self._peak_proj)"
 print(f"    main.py has {len(_s45_calls)} `arbitrage.decide(` call site(s); "
       f"charge_headroom_w= is {_s45_arg}, and self.arb_headroom_w is assigned "
       f"from {_s45_head_src}")
@@ -944,7 +946,7 @@ check("main.py passes the guard's OWN measured headroom at its one "
       "transcription of it, so a mutation back to a literal or to max_w is red "
       "rather than silent",
       _s45_arg == ["self.arb_headroom_w"]
-      and _s45_head_src == ["peakguard.charge_headroom_w(self.peak_guard)"])
+      and _s45_head_src == [S125_ROOM])
 # ⚠️ AND THE HOIST DID NOT MOVE IT OUT OF THE CYCLE. An `arb_headroom_w` set
 # once in `__init__` and never refreshed would satisfy the pin above and would
 # size every trade from the guard decision of whatever cycle happened to run
@@ -960,8 +962,7 @@ check("...and the assignment is INSIDE the same `cycle()` that makes the call, "
       "and not one carried from an arbitrary earlier one",
       any(isinstance(n, ast.Assign)
           and [ast.unparse(t) for t in n.targets] == ["self.arb_headroom_w"]
-          and ast.unparse(n.value)
-          == "peakguard.charge_headroom_w(self.peak_guard)"
+          and ast.unparse(n.value) == S125_ROOM
           for n in ast.walk(_s45_cycle)))
 
 

goodwe_controller/test_modes_p4.py

@@ -540,6 +540,12 @@ rp.Hass.state = _sensor
 rp_start = [UTC0]
 FC_OPTS = {"pv_forecast_entity": "sensor.energy_production_today_remaining",
            "cycle_cost_threshold_eur": 0.20}
+# TARIFF-24 round 2: with a forecast read, a price mode needs the cycle cost
+# itself (0.20 here), no longer 1.5 times it (0.30). These scenarios were
+# written for a 0.30 gap, and a midday 0.21 gap now plans a grid top-up they
+# are not about, so they ask for 0.30 with the forecast; the no-forecast leg
+# (`rows_nf`) keeps 0.20, which is 0.30 widened: the same gate on both sides.
+GATE_030 = {"cycle_cost_threshold_eur": 0.30}
 
 
 def seed_profile(c):
@@ -597,7 +603,8 @@ def invariants(tag, rows, c):
 
 
 # Sunny: 40 kWh forecast. B (Leftover solar) at 30 % needs nothing.
-rows, st_, c = run_day(SF_LS, fc=40.0, soc0={"a": 60.0, "b": 30.0})
+rows, st_, c = run_day(SF_LS, fc=40.0, soc0={"a": 60.0, "b": 30.0},
+                       extra=GATE_030)
 charge = invariants("sunny", rows, c)
 _last = nth(rows, -1, "a cycle")
 print(f"    sunny: verdict {present(_last) and _last['plan'] and _last['plan'].verdict}, "
@@ -607,6 +614,35 @@ check("sunny: a day plan is made, and says sunny",
           for r in rows))
 check("sunny: no grid charge at all", not charge)
 
+# TARIFF-24 round 2: the same day at the cycle cost 0.20 itself. With the
+# forecast read the gap needed is 0.20 (not 1.5 x = 0.30), so the midday
+# quarter 0.339 against the evening 0.551 (gap 0.21, between 1x and 1.5x) is
+# a planned top-up for B (Leftover solar) up to its planned level.
+rows_g, st_, c_g = run_day(SF_LS, fc=40.0, soc0={"a": 60.0, "b": 30.0})
+charge_g = invariants("gap between 1x and 1.5x", rows_g, c_g)
+_first_g = nth(charge_g, 0, "a charge cycle")
+_gaps = [min(g.mean_eur_kwh for g in r["runs"].give)
+         - r["runs"].cheap.mean_eur_kwh for r in charge_g
+         if r["runs"] is not None and r["runs"].give]
+print(f"    gap 0.20 <= gap < 0.30: {len(charge_g)} charge cycles, run gap "
+      f"{min(_gaps, default=0):.3f}, B to "
+      f"{max((r['soc']['b'] for r in rows_g), default=0):.1f} %")
+check("a forecast day whose price gap lies between 1x and 1.5x the cycle "
+      "cost (0.20 < 0.21 < 0.30) plans a cheap run: B charges from the grid "
+      "inside it, only B, and only up to its planned level",
+      present(_first_g) and len(_gaps) == len(charge_g)
+      and all(0.20 <= g < 0.30 for g in _gaps)
+      and all(r["runs"].cheap.holds(r["now"]) for r in charge_g)
+      and all(r["roles"][B] == modetrade.CHARGE for r in charge_g)
+      and all(r["roles"][A] != modetrade.CHARGE for r in charge_g)
+      and max(r["soc"]["b"] for r in rows_g) <= 45.64 + 2.0)
+check("...and the same day with no forecast read does not (it needs 0.30): "
+      "the old gate, kept for a day without a forecast",
+      not [r for r in run_day(SF_LS, fc=None,
+                              soc0={"a": 60.0, "b": 30.0})[0]
+           if r["action"] == arbitrage.CHARGE
+           and r["now"].astimezone(L).hour == 12])
+
 # Dark: 1 kWh. B buys the evening's shortfall only, in the cheap run.
 rows, st_, c = run_day(SF_LS, fc=1.0, soc0={"a": 60.0, "b": 30.0})
 charge = invariants("dark", rows, c)
@@ -623,7 +659,8 @@ check("dark: A rests while B charges", all(r["roles"][A] == modetrade.REST
                                            for r in charge))
 
 # Cheap hours on a partly sunny day: ignores the plan, fills as in P3.
-rows, st_, c = run_day(SF_CH, fc=14.0, soc0={"a": 60.0, "b": 30.0})
+rows, st_, c = run_day(SF_CH, fc=14.0, soc0={"a": 60.0, "b": 30.0},
+                       extra=GATE_030)
 charge = invariants("cheap hours, partly", rows, c)
 top = max(r["soc"]["b"] for r in rows)
 print(f"    cheap hours partly: B reached {top:.1f} %")
@@ -634,21 +671,49 @@ check("Cheap hours with a sun forecast charges as with none (P3)",
       charge and abs(max(r["soc"]["b"] for r in rows_nf) - top) < 1.0
       and top > 80.0)
 
-# The forecast goes away mid-run: Leftover solar stops at once (P3 option A).
+# The forecast goes away mid-run: a charge under way goes on to its level
+# (OPT-34; it stopped at once, P3 option A, before). With no charge under way
+# the levels go with the forecast (below, and test_opt27.py).
+# OPT-27: a sensor that is unavailable is covered by its last fresh reading
+# for up to 3 h (`solarfc.Hold`), so "lost" here is a hold that never covers;
+# the next scenario is the same loss with the hold (test_opt27.py).
 DROP = UTC0 + timedelta(hours=1, minutes=30)
+
+
+class _NoHold(solarfc.Hold):
+    def stand_in(self, *a, **k):
+        return None
+
+
+def seed_profile_no_hold(c):
+    seed_profile(c)
+    c.fc_hold = _NoHold()
+
+
 rows, st_, c = run_day(SF_LS, fc=lambda now: 1.0 if now < DROP else None,
-                       soc0={"a": 60.0, "b": 10.0})
+                       soc0={"a": 60.0, "b": 10.0}, patch=seed_profile_no_hold)
 invariants("forecast lost mid-run", rows, c)
 before = [r for r in rows if r["now"] < DROP and r["action"]
           == arbitrage.CHARGE]
 late = [r for r in rows if r["now"] > DROP + timedelta(
     seconds=2 * 60 + 10) and r["action"] == arbitrage.CHARGE]
-check("forecast lost mid-run: Leftover solar was charging, and stops within "
-      "a forecast read (60 s) and a cycle", before and not late)
+check("forecast lost mid-run (OPT-34): Leftover solar was charging, and goes "
+      "on charging past a forecast read (60 s) and a cycle, to its level",
+      before and late)
+rows, st_, c = run_day(SF_LS, fc=lambda now: 1.0 if now < DROP else None,
+                       soc0={"a": 60.0, "b": 10.0})
+invariants("forecast unavailable mid-run, covered", rows, c)
+check("forecast unavailable mid-run (OPT-27): the last reading covers it, so "
+      "Leftover solar goes on charging past the point where it was lost",
+      [r for r in rows if r["now"] < DROP and r["action"]
+       == arbitrage.CHARGE]
+      and [r for r in rows if r["now"] > DROP + timedelta(
+          seconds=2 * 60 + 10) and r["action"] == arbitrage.CHARGE])
 
 # The forecast is far too high (40 kWh, and there is no sun at all): no grid
 # charge, so B covers less of the evening - a money risk, never a safety one.
-rows, st_, c = run_day(SF_LS, fc=40.0, soc0={"a": 30.0, "b": 30.0})
+rows, st_, c = run_day(SF_LS, fc=40.0, soc0={"a": 30.0, "b": 30.0},
+                       extra=GATE_030)
 invariants("forecast too high", rows, c)
 check("forecast too high: no grid charge, and B still keeps its power for "
       "the dear run", not [r for r in rows if r["action"]
@@ -658,7 +723,7 @@ check("forecast too high: no grid charge, and B still keeps its power for "
 
 # A refusal wins over the plan.
 rows, st_, c = run_day(SF_LS, fc=1.0, soc0={"a": 60.0, "b": 30.0},
-                       refuse=("b",))
+                       refuse=("b",), extra=GATE_030)
 invariants("refusal", rows, c)
 check("refusal: B refuses to charge, so the plan's charge ends and B is "
       "never a charger after it", rows and not [
@@ -736,12 +801,25 @@ _m1 = c._run_mark("charge", _run, _packs, lambda p: True, ((B, 40.0),))
 _m2 = c._run_mark("charge", _run, _packs, lambda p: False, ((B, 50.0),))
 check("a level the hysteresis moved opens the run to that battery again",
       _m1 and not _m2)
+latch, c._charge_latch = c._charge_latch, None
 c.solar_fc = None
-check("the levels are dropped as soon as the forecast goes, even before "
-      "the plan is rebuilt", c._plan_targets and c.plan_targets() is None)
+check("with no charge under way, the levels are dropped as soon as the "
+      "forecast goes, even before the plan is rebuilt",
+      c._plan_targets and c.plan_targets() is None)
 check("a lost forecast says so: no forecast, Leftover solar solar only",
       homeview.solar_block(c, datetime.now(timezone.utc))["state"]
       == "no_forecast" and homeview.day_key(c, B) == "no_forecast")
+c._charge_latch = latch
+# the latch ends at its end time; this replay ran in September, so ask at a
+# moment inside it
+_real_dt = rp.m.datetime
+rp.m.datetime = type("_DT", (datetime,), {"now": classmethod(
+    lambda cls, tz=None: latch[0] - timedelta(hours=1))})
+check("OPT-34: with a charge under way (B charged in this run), the level "
+      "stays: plan_targets() gives it (the line: test_opt34.py)",
+      latch is not None and c.plan_targets() is not None
+      and B in c.plan_targets() and c.plan_targets()[B] == c._plan_targets[B])
+rp.m.datetime = _real_dt
 check("the Why line wins over 'saves its power' only while holding",
       homeview.battery_why(modes_on=True, mode="leftover_solar", off=False,
                            reading=True, phase="idle", shadow=False,

goodwe_controller/test_opt20.py

@@ -243,12 +243,16 @@ check("no opposite-direction split on any of these cycles",
 # ============================================================================ #
 print("\n4. battery modes on, no probe: byte-identical to release/1.0 bf9019e")
 # Printed by tools/opt20_scen.py on release/1.0 bf9019e (2026-10-15),
-# goodwe-addon-checks:1.
+# goodwe-addon-checks:1. SAFETY-125 (0.19.2) moved the two runs that charge
+# against the peak aim: the rig's P1 sample is 0.35 s old, and a grid charge
+# now counts those seconds, so ch_ch's quarters land on 3450.0 W where they
+# landed 1.3-1.4 W over it (bf9019e: 15fc25dd...), and ch_ch_maint's first,
+# partial quarter charges a little less at its end (bf9019e: e46e3c66...).
 AT_BASE = {
     "sf_ch": "422d6578a7decf1ae3749edd1898ff3cd0541d904c95f636cdd9b1de8c1a07c9",
-    "ch_ch": "15fc25dd34186e56d34b752d37c9e8613295ba737938c92454acca08c83080fb",
+    "ch_ch": "2b5879ec95810c39a5f0f82c04b9f8e358ea03ddce4ba187cc2b7e0885dfcbfa",
     "ch_ch_maint":
-        "e46e3c666dd63ab33b56e83c0a560c07cec7774a9a70560f55c62a6ae6f55920",
+        "e56eddabdb785f81793e7afa525f8e6da237b0b2165860aa8e0f8a6499b275a9",
 }
 _got = sc.no_probe_digests()
 for _k in AT_BASE:
@@ -256,7 +260,8 @@ for _k in AT_BASE:
           f"{_got[_k][:16]}")
 check("with no refusal every share, grid, trade sentence, role and plant "
       "power of a scripted cheap run equals bf9019e's (A Solar first, A "
-      "charging, A in maintenance charge)", _got == AT_BASE)
+      "charging, A in maintenance charge; the last two as SAFETY-125 moved "
+      "them)", _got == AT_BASE)
 
 print()
 if fails:

goodwe_controller/test_opt27.py

@@ -0,0 +1,655 @@
+"""Runnable check for OPT-27.  `python3 test_opt27.py`
+
+Forecast.Solar's sensors stop changing in the evening, so at night every
+Forecast.Solar site was "no forecast": a price mode's night cheap run needed
+1.5x the cycle cost and Leftover solar bought nothing. And one missed poll
+(`unavailable`) dropped the forecast at once. `solarfc.Hold` now keeps the last
+fresh reading of each sensor, for the day it is FOR:
+
+* up to `FRESH_S` when the sensor is missing or unavailable (a short outage);
+* from the end of the bell (20:00) until local midnight, if the reading is at
+  most `KEPT_MAX_AGE_S` (12 h) old when used (the night plan); after midnight
+  the evening's tomorrow figure is today's until the bell starts (06:00, OPT-34,
+  test_opt34.py); never beyond, never for another day.
+
+DECISIONS/OPT-27-last-fresh-forecast-for-the-night.md.
+
+1. `solarfc` alone: the evening, the outage, the bounds, the day a figure is
+   for, restart (dump/load), and no hold = as before.
+2. The real Controller on a day/night tariff (0.34/0.26, gap 0.08, cycle cost
+   0.07), forecast sensors that stop updating at 17:05 local:
+   a. the 22:00 night run is planned with the cycle-cost gap and charges;
+   b. no forecast all day: the night run still needs 1.5x and does not charge;
+   c. an evening restart keeps it (a new Controller on the saved store);
+   d. a one-hour outage at 18:47 does not drop it;
+   e. from 06:00 (the bell) the figure is not used, before it it is (OPT-34).
+3. The screens: the forecast line says when it was read and that it is kept
+   for tonight (EN and NL), and Home agrees with control.
+
+Mutations (MUTATION.md, purged copies, graded over this file): see the
+DECISIONS note and the dev report.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import tempfile
+import time
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11p3_replay as rp                                    # noqa: E402
+from named_absence import first, nth, present                  # noqa: E402
+import app.main as m                                           # noqa: E402
+from app import homeview, modetrade, solarfc                   # noqa: E402
+from app.main import Controller                                # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+L = timezone(timedelta(hours=1))             # Brussels in winter (CET)
+
+
+def at(day, hh, mm=0):
+    """Local time on 2026-11-`day` (CET) as UTC."""
+    return datetime(2026, 11, day, hh, mm, tzinfo=L).astimezone(timezone.utc)
+
+
+def st(kwh, when, *, unit="kWh"):
+    return {"state": f"{kwh}", "attributes": {"unit_of_measurement": unit},
+            "last_updated": when.isoformat(),
+            "last_reported": when.isoformat()}
+
+
+GONE = {"state": "unavailable", "attributes": {}}
+T_ENT, M_ENT = "sensor.fc_today", "sensor.fc_tomorrow"
+
+# --------------------------------------------------------------------------- #
+print("1. solarfc: the hold")
+D1_READ = at(3, 17, 5)                       # the last fresh reading, 17:05
+EVE = at(3, 22, 0)
+
+
+def rs(today, tomorrow, now, hold):
+    return solarfc.read_sum([(T_ENT, today)], [(M_ENT, tomorrow)], now, hold)
+
+
+h = solarfc.Hold()
+fc, why, gaps = rs(st(0.4, D1_READ), st(12.0, D1_READ), at(3, 17, 10), h)
+check("a fresh reading is a forecast, not kept", fc is not None
+      and not fc.kept and fc.tomorrow.kwh == 12.0 and fc.today.kwh == 0.4)
+check("it is remembered (the hold is flagged for saving)", h.changed)
+fc_no, why_no, _g = rs(st(0.4, D1_READ), st(12.0, D1_READ), EVE, None)
+check("with no hold, 22:00 is no forecast (as before)",
+      fc_no is None and why_no == solarfc.STALE)
+fc, why, gaps = rs(st(0.4, D1_READ), st(12.0, D1_READ), EVE, h)
+print(f"    22:00, sensors still show 17:05: {fc and fc.kept=}, {gaps=}")
+check("22:00 with the sensors stale since 17:05: the 17:05 figures are used",
+      fc is not None and fc.kept and fc.tomorrow.kwh == 12.0
+      and fc.at == D1_READ and gaps == ())
+check("... today has no sun left in it, tomorrow's is counted from 06:00",
+      fc is not None and fc.between(EVE, at(4, 7, 0)) is not None
+      and 0.0 < fc.between(EVE, at(4, 7, 0)) < 0.5
+      and fc.today.kwh == 0.4)
+fc2, _w, _g = rs(GONE, GONE, EVE, h)
+check("the same when the sensors are unavailable at 22:00",
+      fc2 is not None and fc2.kept and fc2.tomorrow.kwh == 12.0)
+# A new fresh reading replaces the old one at once.
+fc3, _w, _g = rs(st(0.0, at(3, 22, 20)), st(14.5, at(3, 22, 20)),
+                 at(3, 22, 30), h)
+check("a newer fresh reading is used and is not 'kept'",
+      fc3 is not None and not fc3.kept and fc3.tomorrow.kwh == 14.5)
+fc3b, _w, _g = rs(st(0.4, D1_READ), st(12.0, D1_READ), at(3, 23, 0), h)
+check("... and later the newest reading is the one kept, not the old one",
+      fc3b is not None and fc3b.tomorrow.kwh == 14.5)
+
+# A short outage: unavailable for one or two polls, any time of day.
+h2 = solarfc.Hold()
+rs(st(1.1, at(3, 18, 5)), st(12.0, at(3, 18, 5)), at(3, 18, 6), h2)
+for label, now in (("18:47", at(3, 18, 47)), ("19:20", at(3, 19, 20)),
+                   ("19:47", at(3, 19, 47)), ("20:55", at(3, 20, 55))):
+    fo, _w, _g = rs(GONE, GONE, now, h2)
+    check(f"unavailable at {label}: the 18:05 forecast is still used",
+          fo is not None and fo.tomorrow.kwh == 12.0)
+fo, _w, _g = rs(GONE, GONE, at(3, 20, 55), solarfc.Hold())
+check("(nothing was ever read: still no forecast)", fo is None)
+# Daytime is as before: an outage longer than FRESH_S drops it.
+h3 = solarfc.Hold()
+rs(st(6.0, at(4, 9, 5)), st(12.0, at(4, 9, 5)), at(4, 9, 6), h3)
+d_in = rs(GONE, GONE, at(4, 11, 50), h3)[0]
+d_out = rs(GONE, GONE, at(4, 12, 10), h3)[0]
+d_out2 = rs(st(6.0, at(4, 9, 5)), st(12.0, at(4, 9, 5)), at(4, 14, 0), h3)[0]
+check("daytime: an outage under 3 h is covered, one over 3 h is not",
+      d_in is not None and not d_in.kept and d_out is None)
+check("daytime: a sensor that stopped is stale after 3 h, as before "
+      "(the hold does not start before the bell ends)", d_out2 is None)
+
+# Round 2: today fresh, tomorrow's sensor stopped or down in the daytime.
+h9 = solarfc.Hold()
+rs(st(5.0, at(4, 9, 5)), st(12.0, at(4, 9, 5)), at(4, 9, 6), h9)
+for label, tm in (("stale", st(12.0, at(4, 9, 5))), ("unavailable", GONE)):
+    fd = rs(st(3.0, at(4, 13, 55)), tm, at(4, 14, 0), h9)[0]
+    check(f"14:00, today fresh, tomorrow {label} since 09:05 (over 3 h): "
+          "no tomorrow, nothing kept",
+          fd is not None and fd.tomorrow is None and not fd.kept)
+    fn = rs(st(0.1, at(4, 20, 55)), tm, at(4, 21, 0), h9)[0]
+    check(f"21:00, tomorrow {label}: the 09:05 figure covers it, kept",
+          fn is not None and fn.tomorrow is not None
+          and fn.tomorrow.kwh == 12.0 and fn.kept)
+    fs = rs(st(3.0, at(4, 10, 55)), tm, at(4, 11, 0), h9)[0]
+    check(f"11:00, tomorrow {label} for under 3 h: still covered, not kept",
+          fs is not None and fs.tomorrow is not None and not fs.kept)
+
+# The bound: the bell start (06:00), and the day a figure is for.
+fm = rs(st(0.0, at(3, 23, 0)), st(0.0, at(3, 23, 0)), at(4, 1, 0), h2)[0]
+check("00:30 is covered by the 18:05 tomorrow figure, as TODAY's",
+      rs(GONE, GONE, at(4, 0, 30), h2)[0] is not None)
+fmid = rs(GONE, GONE, at(4, 2, 59), h2)[0]
+print(f"    02:59: {fmid and (fmid.today.kwh, fmid.tomorrow, fmid.kept)}")
+check("02:59: tomorrow's 12.0 kWh is now today's, there is no tomorrow",
+      fmid is not None and fmid.today.kwh == 12.0 and fmid.tomorrow is None
+      and fmid.kept and fmid.today.day0 == at(4, 0, 0))
+check("... its sun is counted on the day it is for (06:00-20:00 on the 4th)",
+      fmid is not None and fmid.between(at(4, 3, 0), at(4, 7, 0)) is not None
+      and fmid.between(at(4, 3, 0), at(4, 7, 0)) > 0.0)
+check("03:01: still used (OPT-34: until the bell starts at 06:00)",
+      rs(GONE, GONE, at(4, 3, 1), h2)[0] is not None
+      and rs(GONE, GONE, at(4, 5, 59), h2)[0] is not None)
+check("06:00 (the bell starts): not used any more",
+      rs(GONE, GONE, at(4, 6, 0), h2)[0] is None)
+check("... and not the next evening either (past 06:00)",
+      rs(GONE, GONE, at(4, 22, 0), h2)[0] is None)
+fe = rs(st(0.1, at(4, 21, 50)), GONE, at(4, 22, 0), h2)[0]
+check("... the next evening, with today fresh and tomorrow's sensor down, "
+      "there is no tomorrow: the 4th's figure is not the 5th's",
+      fe is not None and fe.today.kwh == 0.1 and fe.tomorrow is None)
+# Never today's figure for tomorrow.
+h4 = solarfc.Hold()
+rs(st(3.0, at(3, 17, 0)), st(12.0, at(3, 17, 0)), at(3, 17, 5), h4)
+# Next day 00:30: today's sensor is fresh again (4.0), tomorrow's is gone.
+fx = rs(st(4.0, at(4, 0, 20)), GONE, at(4, 0, 30), h4)[0]
+check("00:30: today is the fresh 4.0, and there is NO tomorrow "
+      "(the 3rd's 'today' 3.0 and 'tomorrow' 12.0 are not the 5th's)",
+      fx is not None and fx.today.kwh == 4.0 and fx.tomorrow is None
+      and not fx.kept)
+fy = rs(st(4.0, at(4, 0, 20)), st(9.0, at(4, 0, 20)), at(4, 0, 30), h4)[0]
+check("00:30 with both fresh: tomorrow is the fresh 9.0, not the old 12.0",
+      fy is not None and fy.tomorrow.kwh == 9.0 and not fy.kept)
+# A tomorrow sensor that is down while today's is fresh, in the evening: the
+# hold gives the tomorrow figure for tomorrow, never today's figure.
+h5 = solarfc.Hold()
+rs(st(3.0, at(3, 17, 0)), st(12.0, at(3, 17, 0)), at(3, 17, 5), h5)
+fz = rs(st(0.2, at(3, 21, 30)), GONE, at(3, 21, 40), h5)[0]
+check("21:40: today fresh, tomorrow down: tomorrow is the kept 12.0 (not "
+      "today's 0.2 or 3.0)", fz is not None and fz.tomorrow.kwh == 12.0
+      and fz.today.kwh == 0.2 and fz.kept)
+# A set-up fault is never covered.
+h6 = solarfc.Hold()
+rs(st(3.0, at(3, 17, 0)), st(12.0, at(3, 17, 0)), at(3, 17, 5), h6)
+fb = rs(st("lots", at(3, 21, 30)), st(12.0, at(3, 21, 30)),
+        at(3, 21, 40), h6)
+fu = rs(st(0.2, at(3, 21, 30), unit="W"), st(12.0, at(3, 21, 30)),
+        at(3, 21, 40), h6)
+check("a bad value or a wrong unit is not covered by the hold",
+      fb[0] is None and fb[1] == solarfc.BAD and fu[0] is None
+      and fu[1] == solarfc.UNIT)
+# Several sensors: all or nothing.
+h7 = solarfc.Hold()
+two_t = [("sensor.t1", st(1.0, at(3, 17, 0))),
+         ("sensor.t2", st(2.0, at(3, 17, 0)))]
+two_m = [("sensor.m1", st(5.0, at(3, 17, 0))),
+         ("sensor.m2", st(6.0, at(3, 17, 0)))]
+solarfc.read_sum(two_t, two_m, at(3, 17, 5), h7)
+gone2 = [("sensor.t1", GONE), ("sensor.t2", GONE)]
+f2 = solarfc.read_sum(gone2, [("sensor.m1", GONE), ("sensor.m2", GONE)],
+                      at(3, 22, 0), h7)
+check("three or two sensors: the kept figures are summed",
+      f2[0] is not None and f2[0].tomorrow.kwh == 11.0
+      and f2[0].today.kwh == 3.0 and f2[2] == ())
+h8 = solarfc.Hold()
+solarfc.read_sum(two_t[:1] + [("sensor.t2", GONE)], two_m, at(3, 17, 5), h8)
+f3 = solarfc.read_sum(gone2, [("sensor.m1", GONE), ("sensor.m2", GONE)],
+                      at(3, 22, 0), h8)
+check("one sensor never read fresh: no partial sum, the gap is named",
+      f3[0] is None and any(g[:3] == ("today", 2, "sensor.t2") for g in f3[2]))
+# Restart: what the store holds comes back.
+saved = json.loads(json.dumps(h.dump()))
+hr = solarfc.Hold(saved)
+fr = rs(GONE, GONE, at(3, 23, 0), hr)[0]
+check("dump/load through JSON: the kept figures come back (40 min old: "
+      "inside FRESH_S, so not 'kept' in the screens' sense)",
+      fr is not None and not fr.kept and fr.tomorrow.kwh == 14.5
+      and fr.at == at(3, 22, 20))
+junk = solarfc.Hold({"r": [["today", 7, "x", "y", "z", []],
+                           ["tomorrow", T_ENT, "2026-11-04T00:00:00+00:00",
+                            -1, "2026-11-03T16:00:00+00:00", []],
+                           "bad", None]})
+check("a damaged store entry is dropped, not raised",
+      rs(GONE, GONE, at(3, 22, 0), junk)[0] is None
+      and solarfc.Hold(None).dump()["r"] == [] and solarfc.Hold(5).changed
+      is False)
+hp = solarfc.Hold()
+rs(st(8.0, at(3, 9, 0), ), st(12.0, at(3, 9, 0)), at(3, 9, 5), hp)
+periods = [{"period_start": f"2026-11-04T{hh:02d}:00:00+01:00",
+            "pv_estimate": 1.0} for hh in range(8, 16)]
+s_per = st(10.0, at(3, 17, 0))
+s_per["attributes"]["detailedForecast"] = periods
+rs(st(0.0, at(3, 17, 0)), s_per, at(3, 17, 5), hp)
+hq = solarfc.Hold(json.loads(json.dumps(hp.dump())))
+fq = rs(GONE, GONE, at(3, 22, 0), hq)[0]
+check("an hourly split (Solcast shape) survives the store",
+      fq is not None and fq.tomorrow.periods
+      and abs(fq.between(at(4, 8, 0), at(4, 16, 0)) - 7.5) < 1e-6)
+
+# Round 3. F1: a kept reading is at most KEPT_MAX_AGE_S old when used.
+hz = solarfc.Hold()
+rs(st(0.4, at(3, 0, 5)), st(12.0, at(3, 0, 5)), at(3, 0, 10), hz)
+print(f"    00:05 reading, sensors dead: 19:59 "
+      f"{rs(GONE, GONE, at(3, 19, 59), hz)[0]}, 20:00 "
+      f"{rs(GONE, GONE, at(3, 20, 0), hz)[0]}")
+check("F1: a 00:05 reading with the sensors dead all day is not kept at "
+      "20:00 (20 h old): no forecast",
+      rs(GONE, GONE, at(3, 20, 0), hz)[0] is None
+      and rs(GONE, GONE, at(3, 23, 0), hz)[0] is None)
+check("... nor after midnight until 03:00 (as today's, 26 h old)",
+      rs(GONE, GONE, at(4, 0, 30), hz)[0] is None
+      and rs(GONE, GONE, at(4, 2, 30), hz)[0] is None)
+hy = solarfc.Hold()
+rs(st(0.4, at(3, 17, 5)), st(12.0, at(3, 17, 5)), at(3, 17, 10), hy)
+check("F1: a 17:05 reading is kept at 22:00 (5 h) ...",
+      (lambda f: f is not None and f.kept)(rs(GONE, GONE, at(3, 22, 0), hy)[0]))
+check("... and at 02:59 next day (9 h 54 min) ...",
+      (lambda f: f is not None and f.kept)(rs(GONE, GONE, at(4, 2, 59),
+                                              hy)[0]))
+check("... and at 03:00 and 05:59 next day (OPT-34: the bell starts at 06:00)",
+      (lambda f: f is not None and f.kept)(rs(GONE, GONE, at(4, 3, 0),
+                                              hy)[0])
+      and (lambda f: f is not None and f.kept)(rs(GONE, GONE, at(4, 5, 59),
+                                                  hy)[0]))
+check("... and at 06:00 it is not (12 h 55 min old, the bell has started)",
+      rs(GONE, GONE, at(4, 6, 0), hy)[0] is None)
+hm = solarfc.Hold()
+rs(st(0.9, at(3, 9, 5)), st(12.0, at(3, 9, 5)), at(3, 9, 10), hm)
+check("F1: a 09:05 reading is kept at 20:00 (10 h 55 min) but not at 22:00",
+      rs(GONE, GONE, at(3, 20, 0), hm)[0] is not None
+      and rs(GONE, GONE, at(3, 22, 0), hm)[0] is None)
+
+# F2: the 25 h autumn day (2026-10-25) and the 23 h spring day (2027-03-28).
+BRU = solarfc.BILLING_TZ        # Europe/Brussels, or the encoded EU rule
+
+
+def bru(y, mo, d, hh, mm=0):
+    return datetime(y, mo, d, hh, mm, tzinfo=BRU).astimezone(timezone.utc)
+
+
+for (y, mo, d), label in (((2026, 10, 25), "25 h autumn day 2026-10-25"),
+                          ((2027, 3, 28), "23 h spring day 2027-03-28")):
+    hd = solarfc.Hold()
+    t17 = bru(y, mo, d, 17, 5)
+    rs(st(0.4, t17), st(12.0, t17), t17 + timedelta(minutes=5), hd)
+    # real hours from 20:00 local to the next local midnight, each hour
+    start = bru(y, mo, d, 20, 0)
+    end = bru(y, mo, d + 1, 0)
+    t, miss = start, []
+    while t < end:
+        if rs(GONE, GONE, t, hd)[0] is None:
+            miss.append(t.astimezone(BRU).strftime("%H:%M"))
+        t += timedelta(minutes=30)
+    print(f"    {label}: not kept at {miss}")
+    check(f"F2: {label}: the 17:05 figure is kept every half hour "
+          "from 20:00 to local midnight", not miss)
+    check(f"... and just before the next local midnight",
+          rs(GONE, GONE, bru(y, mo, d + 1, 0) - timedelta(minutes=1),
+             hd)[0] is not None)
+
+# F5: old days are dropped from the stored hold, so it does not grow.
+hp5 = solarfc.Hold()
+sizes = []
+for dd in range(3, 13):
+    t0_ = at(dd, 17, 5)
+    rs(st(0.4, t0_), st(12.0, t0_), t0_ + timedelta(minutes=5), hp5)
+    sizes.append(len(hp5.dump()["r"]))
+day0s = {row[2] for row in hp5.dump()["r"]}
+print(f"    F5: stored entries per day over 10 days: {sizes}")
+check("F5: the stored hold does not grow day after day (at most today's and "
+      "tomorrow's entry, with yesterday's tomorrow)", max(sizes) <= 3
+      and len(day0s) <= 2)
+check("... and a day before today is gone",
+      all(row[2] >= at(12, 0, 0).isoformat() for row in hp5.dump()["r"]))
+
+# --------------------------------------------------------------------------- #
+print("\n2. The real Controller: day/night 0.34 / 0.26, cycle cost 0.07")
+A, B = "inverter-a", "inverter-b"
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.26},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.34}]}')
+CHOICE = {"a": (True, "leftover_solar", False),
+          "b": (True, "cheap_hours", False)}
+DAY3 = 3
+
+
+def opts(cost=0.07):
+    o = dict(rp.options(True, False, 2))
+    o.update(cycle_cost_threshold_eur=cost, static_profile=PROFILE,
+             pv_forecast_entity=T_ENT, pv_forecast_tomorrow_entity=M_ENT)
+    return o
+
+
+def stops_at(last, *, down=()):
+    """Sensors that update until `last` and then show that reading for
+    good. `down`: (from, to) windows in which they are unavailable."""
+    def f(now, ent):
+        for a, z in down:
+            if a <= now < z:
+                return GONE
+        when = min(now, last)
+        return st(0.4 if ent == T_ENT else 12.0, when)
+    return f
+
+
+def never(now, ent):
+    return st(0.0 if ent == T_ENT else 12.0, now - timedelta(hours=9))
+
+
+def drive27(o, sensors, *, pre, start, minutes=20, restart=None,
+            keep_store=True, snap=False):
+    """-> (controller, rows, pre_rows). `pre`: the times the forecast is read
+    before the first cycle (the evening). `restart`: a time in `pre` at which
+    the add-on restarts: a new Controller on the saved store."""
+    store = rp._Store()
+    for u, (use, mode, sell) in CHOICE.items():
+        for k, val in (("pack_use", use), ("pack_mode", mode),
+                       ("pack_sell", sell)):
+            store.data[unit_key(f"inverter-{u}", k)] = val
+    clock = [pre[0] if pre else start]
+    rows, pre_rows = [], []
+    cur = [store]
+
+    class H(rp.Hass):
+        async def state(self, e):
+            return sensors(clock[0], e)
+
+    def build(store):
+        hass = H(("a", "b"), lambda t: 300.0, {"a": 40.0, "b": 40.0})
+        tmp = tempfile.mkdtemp(prefix="o27-")
+        c = Controller(dict(o), hass, store, rp._Pub(), stop=asyncio.Event(),
+                       peak_db_path=os.path.join(tmp, "tariff.db"),
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        # A house profile a few days old (300 W round the clock), so the day
+        # plan is made as it is on a site that has run for a week.
+        c.house_profile.load({d: {str(hh): 300.0 for hh in range(24)}
+                              for d in ("2026-10-31", "2026-11-01",
+                                        "2026-11-02")})
+        return c, hass
+
+    async def go():
+        c, hass = build(store)
+        real_dt, real_hv = m.datetime, homeview.datetime
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+
+        m.datetime = homeview.datetime = _DT
+        task = None
+        try:
+            for t_pre in pre:
+                clock[0] = t_pre
+                if restart is not None and t_pre == restart:
+                    # The saved file, through JSON; `keep_store=False` loses
+                    # the hold only (the control for the test).
+                    data = json.loads(json.dumps(cur[0].data))
+                    if not keep_store:
+                        data.pop(m.FC_HOLD_KEY, None)
+                    new = rp._Store()
+                    new.data.update(data)
+                    cur[0] = new
+                    c, hass = build(new)
+                await c._read_forecast()
+                pre_rows.append((t_pre, c.solar_fc is not None,
+                                 bool(c.solar_fc and c.solar_fc.kept)))
+            clock[0] = start
+            task = asyncio.create_task(c.run_tariff_refresh())
+            t = 0.0
+            while t < minutes * 60:
+                now = start + timedelta(seconds=t)
+                hass.t = t
+                clock[0] = now
+                if t == 0.0:
+                    for _ in range(500):
+                        if c.tariff_plan is not None and (
+                                c.tariff_at is not None and c.tariff_at >= now):
+                            break
+                        await asyncio.sleep(0)
+                imp, exp = split_signed(hass.grid())
+                c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                                        ingest_ts=now,
+                                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(5.0, 10.0)
+                rp_ = c.mode_runs
+                rows.append(dict(
+                    t=t, fc_none=c.solar_fc is None,
+                    kept=bool(c.solar_fc and c.solar_fc.kept),
+                    runs_on=None if rp_ is None else rp_.on,
+                    reason=None if rp_ is None else rp_.reason,
+                    roles=dict(c.mode_tick.roles) if c.mode_tick else {},
+                    charging=hass.plants["b"].p < -200.0,
+                    soc_b=hass.plants["b"].soc))
+                t += 5.0
+            keep = c.o
+            c.o = dict(keep, arbitrage_enabled=True)
+            try:
+                c.mirror, c.mirror_why = homeview.trade_verdict(
+                    c, c.fresh_tariff_plan(clock[0]), clock[0])
+            finally:
+                c.o = keep
+            c.cards = homeview.battery_rows(c, False, True)
+            c.block = homeview.solar_block(c, clock[0])
+            c.hold_saved = json.loads(json.dumps(cur[0].data.get(
+                m.FC_HOLD_KEY)))
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+            m.datetime, homeview.datetime = real_dt, real_hv
+        return c
+
+    return asyncio.run(go()), rows, pre_rows
+
+
+def why_of(c, name):
+    card = first((b for b in c.cards if b["name"] == name), f"card {name}")
+    return card["why_key"]
+
+
+EVENING = [at(DAY3, 16, 0) + timedelta(minutes=30 * i) for i in range(12)]
+LAST = at(DAY3, 17, 5)
+NIGHT_START = at(DAY3, 22, 0)
+
+# a. a forecast that stops updating at sunset
+ca, ra, pa = drive27(opts(), stops_at(LAST), pre=EVENING + [at(DAY3, 21, 55)],
+                     start=NIGHT_START)
+la = nth(ra, -1, "last cycle")
+print(f"    a. 22:00 with the 17:05 forecast: kept={la['kept']} on="
+      f"{la['runs_on']} reason={la['reason']}; B charging "
+      f"{sum(r['charging'] for r in ra)} of {len(ra)}; Why A {why_of(ca, A)} "
+      f"B {why_of(ca, B)}; Home mirror {ca.mirror}")
+check("the forecast was read fresh before 17:05 and kept after it",
+      any(not k for _t, ok, k in pa if _t <= LAST + timedelta(minutes=30))
+      and all(ok for _t, ok, _k in pa)
+      and all(k for _t, _ok, k in pa if _t >= at(DAY3, 20, 15)))
+check("22:00 night run: planned with the cycle-cost gap (needs 0.07 < 0.08)",
+      present(la) and not la["fc_none"] and la["kept"]
+      and la["runs_on"] is True and la["reason"] != "not_worth")
+check("... and B (Cheap hours) charges from the grid in the night period",
+      sum(r["charging"] for r in ra) > len(ra) // 2
+      and la["roles"].get(B) == modetrade.CHARGE
+      and why_of(ca, A) != "no_spread" and why_of(ca, B) != "no_spread")
+check("the day plan is made from the kept forecast (levels for Leftover "
+      "solar), as it is from a fresh one",
+      ca.day_plan is not None and ca.plan_targets() is not None
+      and ca.block["state"] == "plan")
+check("Home's mirror of the gate allows it, as control does",
+      ca.mirror is not None and ca.mirror_why == "allowed")
+
+# b. no forecast all day
+cb, rb, pb = drive27(opts(), never, pre=EVENING + [at(DAY3, 21, 55)],
+                     start=NIGHT_START)
+lb = nth(rb, -1, "last cycle")
+print(f"    b. no forecast all day: on={lb['runs_on']} reason={lb['reason']}; "
+      f"B charging {sum(r['charging'] for r in rb)}; Why A {why_of(cb, A)} "
+      f"B {why_of(cb, B)}")
+check("with no forecast all day the night run still needs 1.5x (0.105 > 0.08)"
+      ": not worth, no charge, 'Prices differ too little'",
+      present(lb) and lb["fc_none"] and lb["runs_on"] is False
+      and lb["reason"] == "not_worth"
+      and not any(r["charging"] for r in rb)
+      and why_of(cb, A) == "no_spread" and why_of(cb, B) == "no_spread"
+      and not any(ok for _t, ok, _k in pb))
+check("... and there is no day plan (Leftover solar takes solar only)",
+      cb.day_plan is None and cb.plan_targets() is None
+      and cb.block["state"] == "no_forecast")
+check("... Home's mirror refuses it too, for the gap ('not_worth')",
+      cb.mirror is None and cb.mirror_why == "not_worth")
+check("... and nothing is saved for the night (no fresh reading was made)",
+      cb.hold_saved is None or cb.hold_saved.get("r") == [])
+
+# c. an evening restart
+cc, rc, pc = drive27(opts(), stops_at(LAST),
+                     pre=EVENING + [at(DAY3, 21, 55)], start=NIGHT_START,
+                     restart=at(DAY3, 21, 55))
+lc = nth(rc, -1, "last cycle")
+check("an evening restart (new Controller on the saved store) keeps the "
+      "forecast: the night run is planned and charges",
+      present(lc) and lc["kept"] and lc["runs_on"] is True
+      and sum(r["charging"] for r in rc) > len(rc) // 2
+      and present(nth(pc, -1, "last read")) and pc[-1][1] and pc[-1][2])
+cc0, rc0, pc0 = drive27(opts(), stops_at(LAST),
+                        pre=EVENING + [at(DAY3, 21, 55)], start=NIGHT_START,
+                        restart=at(DAY3, 21, 55), keep_store=False)
+lc0 = nth(rc0, -1, "last cycle")
+check("(control: the same restart with the store lost is blind, 1.5x)",
+      present(lc0) and lc0["fc_none"] and lc0["runs_on"] is False
+      and present(nth(pc0, -1, "last read")) and not pc0[-1][1])
+
+# d. a one-hour outage at 18:47
+OUT = (at(DAY3, 18, 47), at(DAY3, 19, 47))
+quarter = [at(DAY3, 16, 0) + timedelta(minutes=15 * i) for i in range(24)]
+cd, rd, pd = drive27(opts(), stops_at(at(DAY3, 18, 5), down=[OUT]),
+                     pre=quarter + [at(DAY3, 21, 55)], start=NIGHT_START)
+ld = nth(rd, -1, "last cycle")
+inside = [(t_, ok) for t_, ok, _k in pd if OUT[0] <= t_ < OUT[1]]
+print(f"    d. reads inside the outage: {len(inside)}, with a forecast: "
+      f"{sum(ok for _t, ok in inside)}")
+check("a one-hour outage at 18:47 does not drop the forecast "
+      "(every read from 16:00 to 22:00 has one)",
+      present(pd) and len(inside) >= 4 and all(ok for _t, ok, _k in pd))
+check("... and the 22:00 night run is planned and charges",
+      present(ld) and ld["runs_on"] is True
+      and sum(r["charging"] for r in rd) > len(rd) // 2)
+
+# e. the bound: until the bell starts (06:00, OPT-34; it was midnight + 3 h)
+mid = [at(DAY3, 16, 0) + timedelta(minutes=30 * i) for i in range(12)]
+ce, re_, pe = drive27(opts(), stops_at(LAST), pre=mid + [at(4, 5, 30)],
+                      start=at(4, 5, 30))
+le = nth(re_, -1, "last cycle")
+check("05:30 (before the bell starts): the figure from 17:05 is still used, "
+      "as today's; the night run is planned",
+      present(le) and le["kept"] and le["runs_on"] is True)
+cf, rf, pf = drive27(opts(), stops_at(LAST), pre=mid + [at(4, 6, 30)],
+                     start=at(4, 6, 30))
+lf = nth(rf, -1, "last cycle")
+check("06:30 (the bell has started): a figure from before the night is not "
+      "used: no forecast, 1.5x, not worth, no charge",
+      present(lf) and lf["fc_none"] and lf["runs_on"] is False
+      and lf["reason"] == "not_worth" and not any(r["charging"] for r in rf))
+
+# g. OPT-28's shortfall sizing on a kept figure: Leftover solar (A) is sized
+# from the kept forecast exactly as from a fresh one, not "no forecast"
+def fresh_all(now, ent):
+    return st(0.4 if ent == T_ENT else 12.0, now)
+
+
+cg, rg, pg = drive27(opts(), fresh_all, pre=EVENING + [at(DAY3, 21, 55)],
+                     start=NIGHT_START)
+kp, fp_ = ca.day_plan, cg.day_plan
+print(f"    g. kept   : short={kp and kp.short_kwh} uncovered="
+      f"{kp and kp.uncovered_kwh} targets={kp and kp.targets} "
+      f"need={kp and kp.need_kwh} sun={kp and kp.sun_kwh}")
+print(f"       fresh  : short={fp_ and fp_.short_kwh} uncovered="
+      f"{fp_ and fp_.uncovered_kwh} targets={fp_ and fp_.targets} "
+      f"need={fp_ and fp_.need_kwh} sun={fp_ and fp_.sun_kwh}")
+check("a kept figure sizes the night by OPT-28's shortfall, with a level for "
+      "Leftover solar (A): not 'no forecast', which has no plan at all",
+      kp is not None and A in kp.targets and kp.short_kwh > 0.0
+      and cb.day_plan is None and not cg.solar_fc.kept)
+check("... and the level, the grid need, the shortfall and the sun counted "
+      "are those a fresh figure gives (counted once, from the right time)",
+      fp_ is not None and kp.targets == fp_.targets
+      and kp.need_kwh == fp_.need_kwh and kp.share_kwh == fp_.share_kwh
+      and abs(kp.short_kwh - fp_.short_kwh) < 1e-9
+      and abs(kp.uncovered_kwh - fp_.uncovered_kwh) < 1e-9
+      and abs(kp.sun_kwh - fp_.sun_kwh) < 1e-9)
+
+# --------------------------------------------------------------------------- #
+print("\n3. The screens")
+blk = ca.block
+print(f"    forecast line: {blk['line']!r} (state {blk['state']})")
+check("the forecast line says when it was read and that it is kept for "
+      "tonight", blk["line"] == "Solar forecast read 17:05, kept for tonight.")
+check("the same line comes from the Forecast tab (dayview) on today",
+      homeview.line_solar(0.4, 0.3, "17:05", kept=True) == blk["line"]
+      and homeview.line_solar(0.4, 0.3, "17:05").startswith(
+          "Solar still to come today"))
+en = json.load(open(os.path.join(HERE, "app", "ui_text", "en.json"),
+                    encoding="utf-8"))
+nl = json.load(open(os.path.join(HERE, "app", "ui_text", "nl.json"),
+                    encoding="utf-8"))
+k_en = en["home_words"]["solar"]["kept"]
+k_nl = nl["home_words"]["solar"]["kept"]
+print(f"    EN {k_en!r}\n    NL {k_nl!r}")
+check("EN and NL both say it, with the time, and the NL is not the English",
+      "{at}" in k_en and "{at}" in k_nl and k_en != k_nl
+      and "tonight" in k_en and "vannacht" in k_nl)
+check("a daytime reading keeps the old line (daytime unchanged)",
+      "Updated 09:05" in homeview.line_solar(1.0, 0.7, "09:05")
+      and "Bijgewerkt" in json.dumps(nl["home_words"]["solar"]["line"]))
+check("no forecast: the old 'No solar forecast now' line, no 'kept'",
+      cb.block["state"] == "no_forecast"
+      and "tonight" not in cb.block["line"])
+check("control and Batteries screen agree on the 22:00 run: not 'no_spread'",
+      why_of(ca, A) != "no_spread" and why_of(ca, B) != "no_spread"
+      and la["runs_on"] is True)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print("  -", f)
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_opt34.py

@@ -0,0 +1,747 @@
+"""Runnable check for OPT-34.  `python3 test_opt34.py`
+
+OPT-27 keeps the last fresh Forecast.Solar figure over the night. With the
+sensors silent from 17:05 it ended at local midnight + 3 h, in the middle of the
+night grid charge: Leftover solar's planned level went with it and the charge
+stopped (rig, 2026-10-31: battery A 49.8 % at 07:00 against 79.9 % with a fresh
+figure). Forecast.Solar may not refresh after midnight on a live site, so the
+add-on must not depend on it. OPT-34:
+
+1. a night charge that has started keeps its planned level when the forecast
+   goes (`Controller._latch_charge()`), and the next slice of the run is planned
+   with it (the wide no-forecast gap does not refuse it);
+2. the evening's "tomorrow" figure is today's until the bell starts (06:00
+   local, `BELL_FROM_H`) instead of until midnight + 3 h;
+3. for that case only, a reading may be up to 15 h old (a 17:05 reading is
+   12 h 55 min old at 06:00), but only if it was at most 12 h old at midnight;
+4. a fresh figure replaces the kept one at once.
+
+DECISIONS/OPT-34-the-night-charge-keeps-its-level.md.
+
+Mutations (MUTATION.md, purged copies, graded over this file): see the
+DECISIONS note and the dev report.
+
+1. `solarfc` alone: the window, the age limits, the day, DST, restart.
+2. The real Controller, the owner's shape (modes on, arbitrage off, A Leftover
+   solar + B Cheap hours, both 10 % at the start of the night, the night rate
+   22:00-07:00, tomorrow 6 kWh, a 2.5 kW peak limit so the charge takes hours),
+   sensors silent from 17:05, whole nights at 5 s per cycle (run in parallel
+   processes, about 2.5 minutes each):
+   a. silent from 17:05: both batteries end the night where a fresh figure
+      ends them (the base left A at 57 % against 87 %), and the screens agree;
+   b. restarts at 01:00 and 04:00 change nothing;
+   c. a charge that cannot start before 03:00 (the price dips at 04:00) still
+      starts at 04:00 on the kept figure;
+   d. a fresh figure at 02:00 replaces the level at once, up, during the charge;
+      and before a charge has started, up and down;
+   e. the last hour, after the kept figure has ended at 06:00: the charge under
+      way goes on to its level, also over a restart; the screens say so.
+3. The text, EN and NL.
+4. `_latch_charge()` alone: a battery that leaves the plan leaves the latch.
+"""
+
+import asyncio
+import json
+import logging
+import os
+import sys
+import tempfile
+import time
+from concurrent.futures import ProcessPoolExecutor
+from datetime import datetime, timedelta, timezone
+from multiprocessing import get_context
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11p3_replay as rp                                    # noqa: E402
+import app.main as m                                           # noqa: E402
+from app import homeview, solarfc                              # noqa: E402
+from app.main import Controller                                # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+L = timezone(timedelta(hours=1))             # Brussels in winter (CET)
+
+
+def at(day, hh, mm=0):
+    """Local time on 2026-11-`day` (CET) as UTC."""
+    return datetime(2026, 11, day, hh, mm, tzinfo=L).astimezone(timezone.utc)
+
+
+def st(kwh, when, *, unit="kWh"):
+    return {"state": f"{kwh}", "attributes": {"unit_of_measurement": unit},
+            "last_updated": when.isoformat(),
+            "last_reported": when.isoformat()}
+
+
+GONE = {"state": "unavailable", "attributes": {}}
+T_ENT, M_ENT = "sensor.fc_today", "sensor.fc_tomorrow"
+BRU = solarfc.BILLING_TZ
+
+
+def bru(y, mo, d, hh, mm=0):
+    return datetime(y, mo, d, hh, mm, tzinfo=BRU).astimezone(timezone.utc)
+
+
+def rs(today, tomorrow, now, hold):
+    return solarfc.read_sum([(T_ENT, today)], [(M_ENT, tomorrow)], now, hold)
+
+
+def near(a, b, tol):
+    """`|a - b| < tol`, and False (not a crash) when `a` is missing."""
+    return a is not None and abs(a - b) < tol
+
+
+def used(hold, now):
+    f = rs(GONE, GONE, now, hold)[0]
+    return f is not None
+
+
+def hold_of(read_at, today=0.4, tomorrow=12.0):
+    h = solarfc.Hold()
+    rs(st(today, read_at), st(tomorrow, read_at),
+       read_at + timedelta(minutes=5), h)
+    return h
+
+
+# --------------------------------------------------------------------------- #
+print("1. solarfc: the evening figure serves until the bell starts")
+h17 = hold_of(at(3, 17, 5))
+check("a 17:05 reading is kept at 20:00, 22:00, 00:00, 03:00 and 05:59",
+      all(used(h17, t) for t in (at(3, 20, 0), at(3, 22, 0), at(4, 0, 0),
+                                 at(4, 3, 0), at(4, 5, 59))))
+f_late = rs(GONE, GONE, at(4, 5, 59), h17)[0]
+check("... at 05:59 it is tomorrow's 12.0 kWh as TODAY's, the whole day",
+      f_late is not None and f_late.kept and f_late.today.kwh == 12.0
+      and f_late.tomorrow is None and f_late.at == at(3, 17, 5)
+      and f_late.between(at(4, 6, 0), at(4, 20, 0)) is not None
+      and abs(f_late.between(at(4, 6, 0), at(4, 20, 0)) - 12.0) < 1e-6)
+check("... and at 06:00 (12 h 55 min old, the bell starts) it is not",
+      not used(h17, at(4, 6, 0)) and not used(h17, at(4, 6, 30))
+      and not used(h17, at(4, 12, 0)))
+check("... not the next evening either, and not on the 5th",
+      not used(h17, at(4, 22, 0)) and not used(h17, at(5, 3, 0)))
+
+# The age limit of this case: 15 h, for a figure that was usable at midnight.
+h1230 = hold_of(at(3, 12, 30))
+check("a 12:30 reading (11 h 30 min old at midnight): used until 03:29 "
+      "(14 h 59 min old) ...",
+      used(h1230, at(4, 0, 0)) and used(h1230, at(4, 3, 29)))
+check("... and not from 03:31 (15 h 01 min), though it is before 06:00",
+      not used(h1230, at(4, 3, 31)) and not used(h1230, at(4, 5, 30)))
+h1600 = hold_of(at(3, 16, 0))
+check("a 16:00 reading: the 06:00 window ends it, not the 15 h limit "
+      "(14 h old at 06:00)", used(h1600, at(4, 5, 59))
+      and not used(h1600, at(4, 6, 0)))
+
+# Not used: a morning figure at night (12 h), and no come-back after midnight.
+h0905 = hold_of(at(3, 9, 5))
+check("a 09:05 reading: kept at 20:00 (10 h 55 min), not at 22:00 (12 h 55 min)",
+      used(h0905, at(3, 20, 0)) and not used(h0905, at(3, 22, 0)))
+check("... and it does not come back after midnight (14 h 55 min at 00:00, "
+      "under the 15 h of the evening-to-morning case): it was not usable "
+      "at midnight",
+      not used(h0905, at(4, 0, 0)) and not used(h0905, at(4, 0, 2))
+      and not used(h0905, at(4, 2, 0)))
+h1105 = hold_of(at(3, 11, 59))
+check("the same for a reading that is 12 h 01 min old at midnight",
+      not used(h1105, at(4, 0, 0)) and not used(h1105, at(4, 0, 30)))
+h1201 = hold_of(at(3, 12, 1))
+check("... and one that is 11 h 59 min old at midnight is used",
+      used(h1201, at(4, 0, 0)) and used(h1201, at(4, 3, 0)))
+check("a same-day figure past 12 h is not used: a 07:05 reading at 20:00 "
+      "(12 h 55 min)", not used(hold_of(at(3, 7, 5)), at(3, 20, 0)))
+check("a figure over 15 h old is not used: 17:05 read, 08:06 next day "
+      "(15 h 01 min, bell started)", not used(h17, at(4, 8, 6)))
+check("(a figure from the day before is not used either)",
+      not used(hold_of(at(2, 17, 5)), at(3, 22, 0))
+      and not used(hold_of(at(2, 17, 5)), at(4, 3, 0)))
+
+# Today's figure is not tomorrow's, and the figure is for its own day only.
+hd = solarfc.Hold()
+rs(st(3.0, at(3, 17, 0)), st(12.0, at(3, 17, 0)), at(3, 17, 5), hd)
+fx = rs(GONE, GONE, at(4, 4, 0), hd)[0]
+check("04:00: today's sensor is gone: the 4th gets the 3rd's TOMORROW "
+      "figure (12.0), never the 3rd's today figure (3.0)",
+      fx is not None and fx.today.kwh == 12.0)
+fy = rs(st(5.0, at(4, 3, 50)), st(9.0, at(4, 3, 50)), at(4, 4, 0), hd)[0]
+check("a fresh figure replaces the kept one at once (04:00: 5.0 today, "
+      "9.0 tomorrow; not kept)", fy is not None and not fy.kept
+      and fy.today.kwh == 5.0 and fy.tomorrow.kwh == 9.0)
+fy2 = rs(st(5.0, at(4, 7, 55)), GONE, at(4, 8, 0), hd)[0]
+check("... and at 08:00, today fresh and tomorrow's sensor down for over 3 h: "
+      "no tomorrow (the 3rd's figure is not the 5th's)",
+      fy2 is not None and fy2.tomorrow is None and fy2.today.kwh == 5.0)
+
+# Restart: the saved hold keeps the figure.
+for label, now in (("01:00", at(4, 1, 0)), ("04:00", at(4, 4, 0))):
+    back = solarfc.Hold(json.loads(json.dumps(hold_of(at(3, 17, 5)).dump())))
+    fr = rs(GONE, GONE, now, back)[0]
+    check(f"restart at {label}: the saved hold (FC_HOLD_KEY) gives the "
+          "17:05 figure again", fr is not None and fr.kept
+          and fr.today.kwh == 12.0 and fr.at == at(3, 17, 5))
+
+# DST: the 25 h autumn day and the 23 h spring day. The window ends at 06:00
+# LOCAL, not 6 h after midnight.
+for (y, mo, d), label in (((2026, 10, 25), "25 h day 2026-10-25"),
+                          ((2027, 3, 28), "23 h day 2027-03-28")):
+    t17 = bru(y, mo, d - 1, 17, 5)
+    hs = hold_of(t17)
+    ok_in = used(hs, bru(y, mo, d - 1, 23, 59)) and all(
+        used(hs, bru(y, mo, d, hh, mm)) for hh, mm in
+        ((0, 0), (1, 30), (4, 0), (5, 59)))
+    check(f"{label}: the 17:05 figure serves 23:59 to 05:59 local", ok_in)
+    check(f"... and not at 06:00 local", not used(hs, bru(y, mo, d, 6, 0))
+          and not used(hs, bru(y, mo, d, 6, 30)))
+
+# --------------------------------------------------------------------------- #
+print("\n2. The real Controller, whole nights (parallel processes)")
+A, B = "inverter-a", "inverter-b"
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.26},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.34}]}')
+# The price dips at 04:00 (a dynamic site): the cheap run starts after 03:00.
+PROFILE_LATE = ('{"periods": ['
+                '{"name": "night", "days": "all", "from": "22:00",'
+                ' "to": "04:00", "eur_per_kwh": 0.28},'
+                '{"name": "dawn", "days": "all", "from": "04:00",'
+                ' "to": "07:00", "eur_per_kwh": 0.20},'
+                '{"name": "day", "days": "all", "from": "07:00",'
+                ' "to": "22:00", "eur_per_kwh": 0.34}]}')
+CHOICE = {"a": (True, "leftover_solar", False),
+          "b": (True, "cheap_hours", False)}
+LAST = at(3, 17, 5)
+EVENING = [at(3, 16, 0) + timedelta(minutes=30 * i) for i in range(12)] \
+    + [at(3, 21, 55)]
+
+
+def opts(late=False, cap=2500):
+    o = dict(rp.options(True, False, 2))
+    o.update(cycle_cost_threshold_eur=0.07,
+             static_profile=PROFILE_LATE if late else PROFILE,
+             pv_forecast_entity=T_ENT, pv_forecast_tomorrow_entity=M_ENT,
+             peak_cap_w=cap)
+    return o
+
+
+def sensors(*, silent=True, fresh_from=None, fresh=(1.0, 5.0),
+            fresh_until=None):
+    """Sensors that update until 17:05 (or all night) and then show that
+    reading for good; from `fresh_from` a new reading every call."""
+    def f(now, ent):
+        if fresh_from is not None and now >= fresh_from:
+            when = now if fresh_until is None else min(now, fresh_until)
+            return st(fresh[0] if ent == T_ENT else fresh[1], when)
+        when = min(now, LAST) if silent else now
+        return st(0.4 if ent == T_ENT else 6.0, when)
+    return f
+
+
+def run_night(spec):
+    """One scenario in this process -> a plain dict. `spec`: start (UTC),
+    hours, silent, fresh_from, fresh, restarts, soc, load_until_s, marks."""
+    start = spec["start"]
+    soc0 = spec.get("soc", {"a": 10.0, "b": 10.0})
+    house_w = spec.get("house_w", 700.0)
+    store = rp._Store()
+    for u, (use, mode, sell) in CHOICE.items():
+        for k, val in (("pack_use", use), ("pack_mode", mode),
+                       ("pack_sell", sell)):
+            store.data[unit_key(f"inverter-{u}", k)] = val
+    if spec.get("latch"):
+        store.data[m.CHARGE_LATCH_KEY] = spec["latch"]
+    sens = sensors(silent=spec.get("silent", True),
+                   fresh_from=spec.get("fresh_from"),
+                   fresh=spec.get("fresh", (1.0, 5.0)),
+                   fresh_until=spec.get("fresh_until"))
+    clock = [EVENING[0]]
+
+    class H(rp.Hass):
+        async def state(self, e):
+            return GONE if spec.get("gone") else sens(clock[0], e)
+
+    hass = H(("a", "b"), lambda t: 300.0, soc0)
+    out = dict(marks={}, soc_at={})
+
+    def build(sto):
+        tmp = tempfile.mkdtemp(prefix="o34-")
+        c = Controller(dict(opts(spec.get("late", False),
+                                 spec.get("cap", 2500))), hass, sto,
+                       rp._Pub(),
+                       stop=asyncio.Event(),
+                       peak_db_path=os.path.join(tmp, "tariff.db"),
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        c.house_profile.load({d: {str(hh): house_w for hh in range(24)}
+                              for d in ("2026-10-31", "2026-11-01",
+                                        "2026-11-02")})
+        return c
+
+    async def go():
+        cur = store
+        c = build(cur)
+        real_dt, real_hv = m.datetime, homeview.datetime
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+
+        m.datetime = homeview.datetime = _DT
+        try:
+            for t_pre in EVENING:
+                clock[0] = t_pre
+                await c._read_forecast()
+            pending = sorted(spec.get("restarts", ()))
+            marks = sorted(spec.get("marks", ()))
+            first, t = True, 0.0
+            hz = spec["hours"] * 3600.0
+            while t < hz:
+                now = start + timedelta(seconds=t)
+                clock[0] = now
+                if pending and now >= pending[0]:
+                    pending.pop(0)
+                    data = json.loads(json.dumps(cur.data))
+                    cur = rp._Store()
+                    cur.data.update(data)
+                    c = build(cur)
+                    first = True
+                if first or int(t) % 600 == 0:
+                    # The tariff, resolved here at its own pace: the real
+                    # refresh task sleeps on the wall clock.
+                    hor = float(m.price_option(c.o, "price_horizon_h"))
+                    c.tariff_plan = await m.resolve_tariff(
+                        c.o, now, now + timedelta(hours=hor), now=now,
+                        history=c.price_history, watch=c.price_watch)
+                    c.tariff_at = now
+                    first = False
+                hass.t = t
+                imp, exp = split_signed(hass.grid())
+                c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                                        ingest_ts=now,
+                                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(5.0, 10.0)
+                if int(t) % 300 == 0:
+                    out["soc_at"][now.astimezone(L).strftime("%H:%M")] = (
+                        hass.plants["a"].soc, hass.plants["b"].soc,
+                        hass.plants["a"].p, c.solar_fc is None,
+                        bool(c.solar_fc and c.solar_fc.kept),
+                        None if c.plan_targets() is None
+                        else c.plan_targets().get(A))
+                while marks and now >= marks[0]:
+                    marks.pop(0)
+                    cards = homeview.battery_rows(c, False, True)
+                    blk = homeview.solar_block(c, now)
+                    a_card = next(b for b in cards if b["name"] == A)
+                    out["marks"][now.astimezone(L).strftime("%H:%M")] = dict(
+                        line=blk["line"], state=blk["state"],
+                        why_a=a_card["why_key"],
+                        fc_none=c.solar_fc is None,
+                        kept=bool(c.solar_fc and c.solar_fc.kept),
+                        target_a=(c.plan_targets() or {}).get(A),
+                        soc_a=hass.plants["a"].soc,
+                        p_a=hass.plants["a"].p,
+                        charging=hass.plants["b"].p < -200.0)
+                t += 5.0
+            out["soc"] = (hass.plants["a"].soc, hass.plants["b"].soc)
+            out["latch"] = getattr(c, "_charge_latch", None) is not None
+        finally:
+            m.datetime, homeview.datetime = real_dt, real_hv
+        return out
+
+    return asyncio.run(go())
+
+
+NIGHT = at(3, 22, 0)
+SCEN = {
+    "fresh": dict(start=NIGHT, hours=9, silent=False,
+                  marks=[at(4, 4, 30)]),
+    "silent": dict(start=NIGHT, hours=9,
+                   marks=[at(4, 1, 0), at(4, 4, 30), at(4, 6, 30)]),
+    "restart": dict(start=NIGHT, hours=9,
+                    restarts=[at(4, 1, 0), at(4, 4, 0)],
+                    marks=[at(4, 1, 30), at(4, 4, 30)]),
+    # c. the charge cannot start before 03:00 (the price dips at 04:00)
+    "late": dict(start=at(4, 2, 30), hours=4.5, late=True, house_w=500.0,
+                 soc={"a": 40.0, "b": 70.0}, marks=[at(4, 3, 30)]),
+    "late_fresh": dict(start=at(4, 2, 30), hours=4.5, late=True,
+                       house_w=500.0, soc={"a": 40.0, "b": 70.0},
+                       silent=False),
+    # d. a fresh, darker figure at 02:00 during the charge (a lighter house
+    # use, so the level has room to rise)
+    "dark": dict(start=at(4, 1, 30), hours=2.0, soc={"a": 45.0, "b": 45.0},
+                 house_w=500.0, fresh_from=at(4, 2, 0), fresh=(1.0, 5.0),
+                 marks=[at(4, 1, 59), at(4, 2, 5)]),
+    "kept": dict(start=at(4, 1, 30), hours=2.0, soc={"a": 45.0, "b": 45.0},
+                 house_w=500.0, marks=[at(4, 1, 59), at(4, 2, 5)]),
+    # before the charge starts: a fresh figure replaces the kept one, up and
+    # down, at once
+    "pre_kept": dict(start=at(4, 2, 30), hours=0.25, late=True,
+                     house_w=500.0, marks=[at(4, 2, 44)]),
+    "pre_dark": dict(start=at(4, 2, 30), hours=0.25, late=True,
+                     house_w=500.0, fresh_from=at(4, 2, 40),
+                     fresh=(1.0, 5.0), marks=[at(4, 2, 44)]),
+    "pre_bright": dict(start=at(4, 2, 30), hours=0.25, late=True,
+                       house_w=500.0, fresh_from=at(4, 2, 40),
+                       fresh=(30.0, 30.0), marks=[at(4, 2, 44)]),
+    # d. the last hour, after the kept figure ended at 06:00
+    "tail": dict(start=at(4, 5, 40), hours=80 / 60.0,
+                 soc={"a": 70.0, "b": 70.0}, restarts=[at(4, 6, 30)],
+                 marks=[at(4, 5, 50), at(4, 6, 10), at(4, 6, 40)]),
+    # a fresh, brighter figure at 03:10 lowers A's level below its SoC (A
+    # stops, B goes on), then the sensors go quiet: the forecast ends at 06:10
+    "lowered": dict(start=at(4, 2, 30), hours=4.5, house_w=500.0,
+                    soc={"a": 30.0, "b": 30.0}, fresh_from=at(4, 3, 10),
+                    fresh_until=at(4, 3, 10), fresh=(30.0, 30.0),
+                    marks=[at(4, 3, 5), at(4, 3, 20), at(4, 6, 30)]),
+    # F1: the add-on was down when the latch of the night before ended; it is
+    # back inside a cheap run, with the sensors unavailable (no forecast)
+    "stale": dict(start=at(3, 22, 0), hours=0.5, gone=True,
+                  latch={"until": at(3, 7, 15).isoformat(),
+                         "born": at(2, 23, 0).isoformat(),
+                         "levels": {A: 80.0, B: 80.0}},
+                  marks=[at(3, 22, 20)]),
+    "stale_live": dict(start=at(3, 22, 0), hours=0.5, gone=True,
+                       latch={"until": at(4, 7, 15).isoformat(),
+                              "born": at(3, 22, 0).isoformat(),
+                              "levels": {A: 80.0, B: 80.0}},
+                       marks=[at(3, 22, 20)]),
+    # the same, B already full and a 1.5 kW limit: the run is sized at the
+    # battery's 2.5 kW rating and ends at 06:33, before A is there, so the
+    # next slice is planned after 06:00 and is only A's
+    "tail_bfull": dict(start=at(4, 5, 40), hours=80 / 60.0, cap=1500,
+                       soc={"a": 65.0, "b": 95.0},
+                       marks=[at(4, 5, 50), at(4, 6, 10), at(4, 6, 45)]),
+}
+t0 = time.time()
+with ProcessPoolExecutor(max_workers=min(6, os.cpu_count() or 2),
+                         mp_context=get_context("fork")) as pool:
+    futs = {k: pool.submit(run_night, v) for k, v in SCEN.items()}
+    R = {k: f.result() for k, f in futs.items()}
+print(f"    {len(R)} scenarios in {time.time() - t0:.0f} s")
+
+
+def show(k):
+    r = R[k]
+    print(f"    {k:10} A {r['soc'][0]:.2f} %  B {r['soc'][1]:.2f} %  "
+          f"marks {', '.join(sorted(r['marks']))}")
+
+
+for k in R:
+    show(k)
+fa, si, rr = R["fresh"], R["silent"], R["restart"]
+
+# a. silent from 17:05
+check("a fresh figure all night: A ends at its planned level (87 %), B "
+      "full", abs(fa["soc"][0] - 86.9) < 0.5 and fa["soc"][1] > 94.5)
+check("sensors silent from 17:05: A ends where the fresh run ends it "
+      f"({si['soc'][0]:.1f} against {fa['soc'][0]:.1f} %)",
+      abs(si["soc"][0] - fa["soc"][0]) < 0.3)
+check("... and so does B (Cheap hours; the wide no-forecast gap does not "
+      f"stop its slices): {si['soc'][1]:.1f} against {fa['soc'][1]:.1f} %",
+      abs(si["soc"][1] - fa["soc"][1]) < 0.3)
+check("A charges through 03:00 without a break (no step at 03:00)",
+      si["soc_at"]["03:30"][0] > si["soc_at"]["03:00"][0] + 4.0
+      and si["soc_at"]["03:00"][0] > si["soc_at"]["02:55"][0] + 0.3)
+m1, m4 = si["marks"]["01:00"], si["marks"]["04:30"]
+check("01:00 and 04:30: the kept figure is in use, with a day plan, and the "
+      "line says so (EN)",
+      not m1["fc_none"] and m1["kept"] and not m4["fc_none"] and m4["kept"]
+      and m4["state"] == "plan"
+      and m4["line"] == "Solar forecast read 17:05, kept for tonight."
+      and m4["target_a"] is not None
+      and near(m4["target_a"], fa["marks"]["04:30"]["target_a"], 1e-9))
+check("... and the level is the fresh run's (the kept figure counts as a "
+      "fresh one)", near(m4["target_a"], 86.87, 0.2))
+m6 = si["marks"]["06:30"]
+check("06:30: the kept figure has ended (the bell started) and the screen "
+      "does not say 'kept' (the charge was done by then in this shape)",
+      m6["fc_none"] and "kept" not in m6["line"])
+
+# b. restarts
+check("restarts at 01:00 and 04:00 (a new Controller on the saved store): "
+      f"A {rr['soc'][0]:.1f}, B {rr['soc'][1]:.1f} % as without them",
+      abs(rr["soc"][0] - si["soc"][0]) < 0.3
+      and abs(rr["soc"][1] - si["soc"][1]) < 0.3)
+check("... with the figure kept right after each restart",
+      all(rr["marks"][k]["kept"] and not rr["marks"][k]["fc_none"]
+          and rr["marks"][k]["target_a"] is not None
+          for k in ("01:30", "04:30")))
+
+# c. a charge that cannot start before 03:00
+la, lf = R["late"], R["late_fresh"]
+ml = la["marks"]["03:30"]
+check("the cheap hours start at 04:00: nothing charges at 03:30",
+      ml["soc_a"] < 40.1 and not ml["charging"])
+check("... the kept figure still stands at 03:30 (no charge had started, so "
+      "no level to latch): the plan is kept, not 'no forecast'",
+      not ml["fc_none"] and ml["kept"] and ml["target_a"] is not None)
+check("... and the charge starts at 04:00 on it: A ends where a fresh "
+      f"figure ends it ({la['soc'][0]:.1f} against {lf['soc'][0]:.1f} %)",
+      lf["soc"][0] > 50.0 and abs(la["soc"][0] - lf["soc"][0]) < 0.3
+      and abs(la["soc"][1] - lf["soc"][1]) < 0.3)
+
+# d. a fresh figure replaces the kept one at once
+dk, kp = R["dark"], R["kept"]
+check("a fresh, darker figure at 02:00 during the charge: the level goes "
+      "UP at once (02:05)",
+      kp["marks"]["02:05"]["target_a"] is not None
+      and dk["marks"]["02:05"]["target_a"] is not None
+      and dk["marks"]["02:05"]["target_a"] > kp["marks"]["02:05"]["target_a"]
+      + 3.0 and not dk["marks"]["02:05"]["kept"]
+      and dk["marks"]["01:59"]["kept"])
+check("... and A charges on to it (more than on the kept figure: "
+      f"{dk['soc'][0]:.1f} against {kp['soc'][0]:.1f} %)",
+      dk["soc"][0] > kp["soc"][0] + 3.0)
+pk, pd, pb = R["pre_kept"], R["pre_dark"], R["pre_bright"]
+t_k, t_d, t_b = (x["marks"]["02:44"]["target_a"] for x in (pk, pd, pb))
+print(f"    level before any charge, 02:44: kept {t_k}, dark {t_d}, "
+      f"bright {t_b}")
+check("before a charge has started (nothing charges at 02:44): a darker "
+      "fresh figure raises the level and a brighter one lowers it, at once",
+      all(not x["marks"]["02:44"]["charging"] for x in (pk, pd, pb))
+      and t_k is not None and t_d is not None and t_b is not None
+      and t_d > t_k + 3.0 and t_b < t_k - 3.0
+      and not pd["marks"]["02:44"]["kept"]
+      and not pb["marks"]["02:44"]["kept"])
+
+# e. the last hour, after the kept figure ended
+tl = R["tail"]
+t5, t6, t7 = (tl["marks"][k] for k in ("05:50", "06:10", "06:40"))
+check("05:50: charging on the kept figure; 06:10: the figure has ended",
+      t5["kept"] and not t5["fc_none"] and t6["fc_none"])
+check("06:10 and 06:40 (the second after a restart at 06:30): A still "
+      "charges to its level, 'charges from the grid' is the Why",
+      t6["p_a"] < -500.0 and t7["p_a"] < -500.0
+      and t6["why_a"] == "grid_charge" and t7["why_a"] == "grid_charge")
+check("... and ends the hour higher than it was (+8 % or more from 06:00)",
+      tl["soc_at"]["06:55"][0] > tl["soc_at"]["06:00"][0] + 8.0)
+lo = R["lowered"]
+l0, l1, l2 = (lo["marks"][k] for k in ("03:05", "03:20", "06:30"))
+check("a fresh, brighter figure lowers A's level below its SoC during the "
+      f"charge ({l0['target_a']} -> {l1['target_a']}, SoC "
+      f"{l1['soc_a']:.1f} %), and A stops",
+      l0["target_a"] is not None and l1["target_a"] is not None
+      and l1["target_a"] < l1["soc_a"] - 2.0
+      and l1["target_a"] < l0["target_a"] - 10.0
+      and lo["soc_at"]["03:30"][0] < lo["soc_at"]["03:20"][0] + 0.5)
+check("the sensors go quiet, the forecast ends (06:30): the latch holds the "
+      "LOWERED level, so A does not charge back up to the old one "
+      f"({lo['soc_at']['03:30'][0]:.1f} -> {lo['soc_at']['06:55'][0]:.1f} %), "
+      "while B goes on",
+      l2["fc_none"] and l2["target_a"] is not None
+      and l2["target_a"] < l2["soc_a"] and l2["p_a"] > -200.0
+      and lo["soc_at"]["06:55"][0] < lo["soc_at"]["03:30"][0] + 1.0
+      and lo["soc"][1] > lo["soc_at"]["03:30"][1] + 15.0)
+st_, sl_ = R["stale"], R["stale_live"]
+check("F1: a latch from the night before (ended 07:15) loaded at a restart "
+      "inside a cheap run, with no forecast: nothing grid-charges "
+      f"(A {st_['soc'][0]:.1f}, B {st_['soc'][1]:.1f} %) and the line does "
+      "not say the charge goes on",
+      st_["soc"][0] < 10.2 and st_["soc"][1] < 10.2
+      and st_["marks"]["22:20"]["state"] == "no_forecast"
+      and not st_["latch"])
+check("(control: the same latch, still valid until tomorrow 07:15, does "
+      f"charge both: A {sl_['soc'][0]:.1f}, B {sl_['soc'][1]:.1f} %)",
+      sl_["soc"][0] > 11.0 and sl_["soc"][1] > 11.0
+      and sl_["marks"]["22:20"]["state"] == "latched")
+tb = R["tail_bfull"]
+check("B full: the run ends at 06:33 before A is at its level, so the next "
+      "slice is only A's, planned after the figure has ended with A's "
+      "latched level: A goes on charging (06:10, 06:45; "
+      f"{tb['soc_at']['06:00'][0]:.1f} to {tb['soc_at']['06:55'][0]:.1f} %)",
+      tb["marks"]["06:10"]["fc_none"] and tb["marks"]["06:10"]["p_a"] < -500.0
+      and tb["marks"]["06:45"]["p_a"] < -500.0
+      and tb["soc_at"]["06:55"][0] > tb["soc_at"]["06:00"][0] + 8.0)
+check("the screens say what control does (EN): 'No solar forecast now. The "
+      "charge under way goes on to its planned level.'",
+      t6["state"] == "latched" and t7["state"] == "latched"
+      and t6["line"] == "No solar forecast now. The charge under way goes "
+      "on to its planned level.")
+
+# --------------------------------------------------------------------------- #
+print("\n3. The text (EN and NL)")
+en = json.load(open(os.path.join(HERE, "app", "ui_text", "en.json"),
+                    encoding="utf-8"))
+nl = json.load(open(os.path.join(HERE, "app", "ui_text", "nl.json"),
+                    encoding="utf-8"))
+l_en, l_nl = (x["home_words"]["solar"]["latched"] for x in (en, nl))
+print(f"    EN {l_en!r}\n    NL {l_nl!r}")
+check("the new line is short and plain in both languages and the NL is not "
+      "the English", l_en != l_nl and len(l_en.split()) <= 24
+      and len(l_nl.split()) <= 24 and "{" not in l_en + l_nl)
+check("'kept for tonight' is unchanged (EN and NL)",
+      en["home_words"]["solar"]["kept"]
+      == "Solar forecast read {at}, kept for tonight."
+      and nl["home_words"]["solar"]["kept"]
+      == "Zonneprognose van {at}, bewaard voor vannacht.")
+
+# --------------------------------------------------------------------------- #
+print("\n4. The latch alone: a battery that leaves the plan leaves the latch")
+from types import SimpleNamespace                              # noqa: E402
+from app import modetrade, priceruns                           # noqa: E402
+
+CLOCK = [at(4, 1, 0)]
+_dt0 = m.datetime
+
+
+class _FixedDT(_dt0):
+    @classmethod
+    def now(cls, tz=None):
+        return CLOCK[0] if tz is None else CLOCK[0].astimezone(tz)
+
+
+m.datetime = homeview.datetime = _FixedDT
+_tmp = tempfile.mkdtemp(prefix="o34-")
+lc = Controller(dict(opts()), rp.Hass(("a", "b"), lambda t: 300.0,
+                                      {"a": 40.0, "b": 40.0}),
+                rp._Store(), rp._Pub(), stop=asyncio.Event(),
+                peak_db_path=os.path.join(_tmp, "tariff.db"),
+                price_history_path=os.path.join(_tmp, "ph.json"))
+n0 = at(4, 1, 0)
+lruns = SimpleNamespace(cheap=priceruns.Run(at(3, 22, 0), at(4, 7, 0), 0.26))
+charging = SimpleNamespace(action=modetrade.CHARGE,
+                           roles={A: modetrade.CHARGE, B: modetrade.CHARGE})
+resting = SimpleNamespace(action=None, roles={A: modetrade.HOLD,
+                                              B: modetrade.HOLD})
+
+
+def latch_step(fc, tick, targets, now=n0, runs=None, packs=None):
+    CLOCK[0] = now
+    lc.solar_fc, lc.mode_tick = fc, tick
+    lc._latch_charge(now, runs or lruns, targets, packs)
+    return lc._charge_latch, lc.store.data.get(m.CHARGE_LATCH_KEY)
+
+
+FC = object()                   # a forecast is read (fresh or kept)
+lt, saved = latch_step(FC, charging, {A: 80.0, B: 70.0})
+check("both batteries charge with a forecast: both are latched at their "
+      "levels, to the run's end + one slot, and saved",
+      lt is not None and lt[1] == {A: 80.0, B: 70.0}
+      and lt[0] == at(4, 7, 15) and saved is not None
+      and saved["levels"] == {A: 80.0, B: 70.0})
+lt, saved = latch_step(FC, charging, {B: 70.0})
+check("A leaves the plan (its mode or use changed): A is dropped from the "
+      "latch at once, B stays", lt is not None and lt[1] == {B: 70.0}
+      and saved["levels"] == {B: 70.0})
+lc.solar_fc = None
+check("... and with the forecast then gone, A has no latched level (it is "
+      "not charged back to 80 %)", lc.plan_targets() == {B: 70.0})
+lt, saved = latch_step(FC, resting, {A: 80.0, B: 70.0})
+check("A back in the plan while nothing charges: it does not rejoin",
+      lt is not None and lt[1] == {B: 70.0})
+lt, saved = latch_step(FC, resting, {A: 80.0})
+check("B leaves the plan too: the latch is empty, so it is gone and "
+      "cleared from the store", lt is None and saved is None
+      and lc.plan_targets() is None)
+latch_step(FC, charging, {A: 80.0})
+lc.solar_fc = None
+ia = next((i for i in lc.inverters if i.name == A), None)
+st_below = st_at = st_after = None
+lc.mode_runs = lruns
+if ia is not None:
+    ia.soc = 50.0
+    st_below = homeview.plan_state(lc)
+    CLOCK[0] = at(4, 7, 5)          # the run has ended, the latch has not
+    st_after = homeview.plan_state(lc)
+    CLOCK[0] = n0
+    ia.soc = 80.0
+    st_at = homeview.plan_state(lc)
+check("the screen says the charge goes on only while the latched battery is "
+      f"below its level ({st_below!r} at 50 %, {st_at!r} at 80 %)",
+      st_below == "latched" and st_at == "no_forecast")
+check("F2: and only while a cheap run is on: at 07:05, the run over and the "
+      f"latch in its grace slot, it does not ({st_after!r})",
+      st_after == "no_forecast")
+
+print("\n5. The latch ends: expiry, a changed mode, the night's bell")
+long_run = SimpleNamespace(cheap=priceruns.Run(at(4, 7, 0), at(4, 23, 0), .2))
+lc._charge_latch = (at(4, 7, 15), {A: 80.0}, at(4, 1, 0))
+lt, saved = latch_step(None, resting, None, now=at(4, 7, 20), runs=long_run)
+check("F1: past its end (07:15) the latch is dropped even with a cheap run "
+      "on and no forecast (it was only dropped when no run held)",
+      lt is None and saved is None)
+lc._charge_latch = (at(4, 7, 15), {A: 80.0}, at(4, 1, 0))
+CLOCK[0] = at(4, 7, 20)
+lc.solar_fc = None
+check("... plan_targets() ignores a latch past its end", lc.plan_targets()
+      is None)
+CLOCK[0] = at(4, 1, 0)
+check("... and _load_latch() does not bring one back from the store",
+      m._load_latch({"until": at(4, 7, 15).isoformat(), "born":
+                     at(4, 1, 0).isoformat(), "levels": {A: 80.0}},
+                    at(4, 7, 20)) is None
+      and m._load_latch({"until": at(4, 7, 15).isoformat(), "born":
+                         at(4, 1, 0).isoformat(), "levels": {A: 80.0}},
+                        at(4, 6, 0)) is not None)
+
+# F3: the mode or use of a latched battery changes
+def packs_of(a_mode, a_use=True):
+    return [modetrade.Pack(A, a_use, a_mode, False, 2500.0, 50.0, 10.0),
+            modetrade.Pack(B, True, "cheap_hours", False, 2500.0, 50.0, 10.0)]
+
+
+lc._charge_latch = (at(4, 7, 15), {A: 80.0}, at(4, 1, 0))
+lt, _s = latch_step(None, resting, None, packs=packs_of("leftover_solar"))
+check("F3: A is still Leftover solar and on: it stays latched",
+      lt is not None and lt[1] == {A: 80.0})
+lt, saved = latch_step(None, resting, None, packs=packs_of("solar_first"))
+check("F3: the user changes A to Solar first (no forecast): it leaves the "
+      "latch, which is then gone and cleared, so the narrow gap goes too",
+      lt is None and saved is None)
+lc._charge_latch = (at(4, 7, 15), {A: 80.0}, at(4, 1, 0))
+lt, _s = latch_step(None, resting, None,
+                    packs=packs_of("leftover_solar", a_use=False))
+check("F3: or switches A off", lt is None)
+
+# F4: the night's bell
+lc._charge_latch = None
+lt, _s = latch_step(FC, charging, {A: 80.0}, now=at(4, 1, 0))
+check("F4: the latch began at 01:00, so its night's bell is 06:00 the same "
+      "day", m._night_limit(lt[2]) == at(4, 6, 0)
+      and m._night_limit(at(3, 23, 0)) == at(4, 6, 0)
+      and m._night_limit(at(4, 6, 0)) == at(5, 6, 0))
+r1 = SimpleNamespace(cheap=priceruns.Run(at(4, 0, 0), at(4, 7, 0), .2))
+r2 = SimpleNamespace(cheap=priceruns.Run(at(4, 7, 0), at(4, 23, 0), .2))
+r3 = SimpleNamespace(cheap=priceruns.Run(at(4, 6, 0), at(4, 9, 0), .2))
+lc._charge_latch = None
+lt, _s = latch_step(FC, charging, {A: 80.0}, now=at(4, 1, 0), runs=r1)
+check("F4: first run 00:00-07:00 sets the end at 07:15", lt[0] == at(4, 7, 15))
+lt, _s = latch_step(None, resting, None, now=at(4, 6, 50), runs=r1)
+lt2, _s = latch_step(None, resting, None, now=at(4, 7, 5), runs=r2)
+check("F4: a back-to-back run that starts after the bell (07:00-23:00) does "
+      "NOT carry it on: still 07:15", lt2 is not None
+      and lt2[0] == at(4, 7, 15))
+lt3, _s = latch_step(None, resting, None, now=at(4, 7, 20), runs=r2)
+check("F4: and at 07:20 it has ended, though the run goes on", lt3 is None)
+lc._charge_latch = (at(4, 6, 10), {A: 80.0}, at(4, 1, 0))
+lt, _s = latch_step(None, resting, None, now=at(4, 6, 5), runs=r3)
+check("F4: a run that starts AT the bell (06:00-09:00) does carry it on, "
+      "to its end + one slot", lt is not None and lt[0] == at(4, 9, 15))
+m.datetime = homeview.datetime = _dt0
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print("  -", f)
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_price_run_fixes.py

@@ -609,6 +609,10 @@ print("\n5. modes off: byte-identical to release/1.0 e3e4ba6")
 #   AT_BASE      the same rows through `ident.trade_digest()`, equal to what
 #                e3e4ba6 gives through it;
 #   AT_NOW       this tree's own digests with nothing hidden.
+# SAFETY-125 (0.19.2) moved the two lag pins: their P1 sample is 0.35 s old on
+# every cycle, and a grid charge now counts those seconds at the held reading,
+# so 16 of 1080 cycles charge about 1.7 W less (before: n1_lag f6c67b35...
+# masked, 78aac892... full; n2_lag as n2). n1 and n2 still equal e3e4ba6.
 AT_BASE_OLD = {
     "n1": "71245b227ca40bada4f71f57ea6154475f4b0bd60239c9ad4f80bffb0094514c",
     "n2": "56cf28010b06765c29e5479abb815d7503d570b39240d82dfc818efa90c93722",
@@ -618,14 +622,14 @@ AT_BASE_OLD = {
 AT_BASE = {
     "n1": "33886ef03f364852883f0370230e6e04823fbb46a4704f88ca75bf9082d98c01",
     "n2": "666a31f41491c22750720524853d95944d5fba395d1d14040c460d71414b275f",
-    "n1_lag": "f6c67b351bd732fb69e62cafbfdb2bcff6032f5d8845836659d096b8c677d3c0",
-    "n2_lag": "666a31f41491c22750720524853d95944d5fba395d1d14040c460d71414b275f",
+    "n1_lag": "28e3182ae73c52dae0e65b2495bc04b2b71003889bf9de1a394b047d2c0e0edf",
+    "n2_lag": "45bfb095b5707a91316f56afc408dba616afc729ce4c83a10b337f36948fa3f2",
 }
 AT_NOW = {
     "n1": "939b3d47bbd64fa50e3d70538f092fb98e5c4bd5ead85a7fc696a1dbb514039e",
     "n2": "c51008213dd739e1e5142c236d9a950aa585992393e4af120086f1ba52ff3e0d",
-    "n1_lag": "78aac892975be81a7ceac0c000ed441a731bd4f42ff9f729996cbee53d6b7f02",
-    "n2_lag": "c51008213dd739e1e5142c236d9a950aa585992393e4af120086f1ba52ff3e0d",
+    "n1_lag": "1827918d570bfa0cc371c35dbbb64378b4937557061e7e1a396aba7663e68117",
+    "n2_lag": "6acc1d1b5a11f3481c7a30d384612f37b59f8e5e9cf89204edd07d09a5b90d8d",
 }
 _cmd_digest = ident.trade_digest
 _rows5 = {k: ident.run(**ident.SCENARIOS[k])[0] for k in AT_BASE}
@@ -636,7 +640,8 @@ for _k in AT_BASE:
           f"{_got[_k][:16]}")
 check("with battery modes off every command, integrator, allocation and "
       "trade action equals e3e4ba6's (the sentence masked as above), also when "
-      "every quarter boundary's cycle still sees the old P1 block",
+      "every quarter boundary's cycle still sees the old P1 block (there, as "
+      "SAFETY-125 moved it)",
       _got == AT_BASE)
 check("...the mask is needed and nothing more: unmasked, the digests differ "
       "from e3e4ba6's printed ones, and equal this tree's own pins, so a "

goodwe_controller/test_safety119.py

@@ -19,7 +19,9 @@ DECISIONS/SAFETY-121-bound-every-quarter.md.
 1. The rig's shape (1 s meter that lags the battery, 1 s battery lag, house
    800 W, rating 2500 W, limit 2500 W, margin 50, charge 2000 W, no
    forecast), 2 h, three seeds: no notification, the cap held, every command
-   the same as without the fix; without the fix it warns.
+   the same as without the fix; without the fix it warns. SAFETY-125 sized
+   the N=1 charge to the room, which removed this hand-back; these runs keep
+   the old sizing, and one run checks that with it nothing hands back.
 2. A genuine integrator bound still warns: the loop in charge with the house
    over the rating (at once, as before), and the loop at its rail after a
    hand-back (after the settle).
@@ -140,10 +142,29 @@ def house(seed, base=800.0, step=None):
     return load
 
 
+_SIZED_CH = Controller._charge_headroom
+
+
+def _n1_unsized(self, floor, claims):
+    """The N=1 cheap-window charge as before SAFETY-125: not sized to the
+    quarter's room, so the guard steps in at each quarter's end and hands
+    back - the shape this file grades the settle on."""
+    return floor if len(self.inverters) < 2 \
+        else _SIZED_CH(self, floor, claims)
+
+
 def run(load, *, n=1, dur=7200.0, delay=1, extra=None, cheap=True, cut=None,
-        charging=True, blind=0.0):
+        charging=True, blind=0.0, sized=False):
     """One run of `n` inverters of 2500 W; `charging=False`: no maintenance,
-    the loop in charge; `blind`: no meter reading until that second."""
+    the loop in charge; `blind`: no meter reading until that second.
+    SAFETY-125 sizes the N=1 charge to the room, so it no longer hands back
+    at a quarter's end; an N=1 charge here keeps the old sizing unless
+    `sized`, so the hand-back this file is about still happens."""
+    if n == 1 and charging and not sized:
+        return patched(Controller, "_charge_headroom", _n1_unsized)(
+            lambda: run(load, n=n, dur=dur, delay=delay, extra=extra,
+                        cheap=cheap, cut=cut, charging=charging,
+                        blind=blind, sized=True))
     extra = dict(extra or {})
     s84.OPT = dict(OPT0, peak_cap_w=int(CAP * n), peak_margin_w=50,
                    maintenance_charge_w=2000)
@@ -231,6 +252,15 @@ check("non-vacuous: without the fix every run warns, at a quarter's edge",
       all(len(notes(c)) >= 1 for _r, c in OLD.values())
       and all(min(t % QUARTER, QUARTER - t % QUARTER) <= 40
               for _r, c in OLD.values() for t in notes(c)))
+_sz = run(house(1), sized=True)
+print(f"    SAFETY-125's sizing, seed 1: guard step-ins "
+      f"{guard_steps(_sz[1])}, notifications {notes(_sz[1])}, highest "
+      f"quarter {max(quarters(_sz[1]), default=0.0):.0f} W")
+check("SAFETY-125: with the N=1 charge sized to the room the guard does not "
+      "step in at the quarter's end, nothing warns and the cap holds",
+      not any(r[-1][1] and r[-1][1][0] for r in _sz[0])
+      and notes(_sz[1]) == [] and any(r[1] < -1000.0 for r in _sz[0])
+      and len(quarters(_sz[1])) == 8 and max(quarters(_sz[1])) < CAP)
 
 # ============================================================================ #
 print("\n2. a genuine integrator bound still warns")

goodwe_controller/test_safety125.py

@@ -0,0 +1,565 @@
+"""Runnable check for SAFETY-125.  `python3 test_safety125.py`
+
+A meter reading that is late near a quarter's end left seconds the
+projection did not count (SAFETY-99), and `charge_headroom_w()` read them as
+room: a grid charge went back to full power in the quarter's last seconds and
+the billed quarter went over the aim, above a banked month peak or the cap.
+And the peak guard's row said "under" while the period was over the limit at
+the current rate. DECISIONS/SAFETY-125-grid-charge-under-the-month-peak.md.
+
+Drives the REAL Controller (read_inputs + cycle, the tariff task on a
+day/night profile, a P1 meter on a simulated clock) in the live shape: modes
+on, inverter-a Cheap hours at 5000 W charging harder than asked (as it did
+live), inverter-b Solar first, a house of 1 kW, cap 3500 W, margin 50 W.
+
+1. `charge_room_w()` on its own.
+2. A reading 30 s late at each quarter's end: every quarter at or under the
+   aim, with a month peak banked above the cap and with none, with the P1
+   projection and with a `peak_forecast_entity`; the charge is cut late in
+   the quarter and back in the next one.
+3. The same for a price trade with modes off, and a maintenance charge at N=2.
+4. A healthy meter: the quarters as before, and the row and the month-peak
+   line say what is true.
+5. The words on their own.
+6. One inverter: the maintenance charge is sized to the room too (owner
+   2026-10-29), on a 5 s and a 10 s meter, with and without a banked peak
+   and with late readings; the guard no longer steps in during it.
+7. The row during an N=2 maintenance charge and in shadow mode.
+8. Edge cases: a reading past its 30 s hold (blind), a start mid-quarter,
+   the summer-time change, the forecast entity in W, a 10 s meter, the
+   quarter's last second.
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import asyncio
+import logging
+import os
+import sys
+import tempfile
+import types
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11_identity as rig                                   # noqa: E402
+import opt11p3_replay as rp                                    # noqa: E402
+import safety84_identity as s84                                # noqa: E402
+import app.main as m                                           # noqa: E402
+import app.p1 as p1mod                                         # noqa: E402
+from named_absence import first, nth, present                  # noqa: E402
+from app import homeview, messages, peakguard, tariff          # noqa: E402
+from app import price as _price, static_tariff as _st          # noqa: E402
+from app.main import Controller                                # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+from app.tariff import QUARTER_S, Projection                   # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+PEAK = 5413.17          # October's banked peak on the live site
+AIM_PEAK = PEAK - 50.0
+AIM_CAP = 3500.0 - 50.0
+TOL = 10.0              # W over the aim a quarter may land (SAFETY-81)
+FC = "sensor.piek_prognose_kwartier"
+L = timezone(timedelta(hours=1))
+START = datetime(2026, 10, 29, 0, 0, tzinfo=L).astimezone(timezone.utc)
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.2333},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.2801}]}')
+
+
+def opts(*, fc=False, modes=True, arb=False):
+    o = dict(rp.options(modes, arb, 2))
+    o.update(cycle_cost_threshold_eur=0.03, static_profile=PROFILE,
+             peak_cap_w=3500, peak_margin_w=50)
+    o["inverters"][0].update(max_w=5000, capacity_kwh=15.36)
+    o["inverters"][1].update(max_w=4600, capacity_kwh=20.48)
+    if fc:
+        o["peak_forecast_entity"] = FC
+    return o
+
+
+class Harder(rp.Plant):
+    """Charges harder than asked, as inverter-a did live (asked -4271 W,
+    measured about -4750 W; asked -5000 W, about -5210 W)."""
+
+    def step(self, dt, floor):
+        c = self.cmd
+        if c < 0:
+            self.cmd = max(c * 1.11, -5216.0)
+        try:
+            super().step(dt, floor)
+        finally:
+            self.cmd = c
+
+
+async def _no_fetch(*a, **k):
+    raise AssertionError("the tariff task reached for a price feed")
+
+
+class OnItsOwn(rp.Plant):
+    """Charges 5000 W whatever it is asked (shadow mode: nothing is
+    written, the inverter charges on its own)."""
+
+    def step(self, dt, floor):
+        self.cmd = -5000.0
+        super().step(dt, floor)
+
+
+def drive(o, *, peak=None, late=0.0, minutes=31, every=0, start=None,
+          period=0.0, fc_unit="kW", plant=Harder):
+    """The real Controller from `start` (00:00 local) for `minutes` at a 1 s
+    cycle (OPT-15's lag). `late`: no P1 telegram in each quarter's last
+    `late` s; `period`: one telegram every `period` s (0: every cycle).
+    -> (controller, rows, {quarter start: true grid average}, samples), the
+    samples taken every `every` cycles from the second quarter (the first
+    starts before the first reading): (projection, ceiling, engaged,
+    peak_guard row, month-peak line)."""
+    store = rp._Store()
+    for u, mode in (("a", "cheap_hours"), ("b", "solar_first")):
+        store.data[unit_key(f"inverter-{u}", "pack_use")] = True
+        store.data[unit_key(f"inverter-{u}", "pack_mode")] = mode
+        store.data[unit_key(f"inverter-{u}", "pack_sell")] = False
+    rows, samples, sums = [], [], {}
+    t0 = start or START
+
+    async def go():
+        lag = rp.Lag()
+        hass = rp.Hass(("a", "b"), lambda t: 1000.0, {"a": 11.0, "b": 10.0},
+                       limits={"a": (-5000.0, 5000.0),
+                               "b": (-4600.0, 4600.0)}, lag=lag)
+        hass.plants["a"].__class__ = plant
+        fc_kw = [0.0]
+
+        async def state(e):
+            # The HA quarter projection, in kW like the live template.
+            return None if e != FC else {
+                "state": (f"{fc_kw[0]:.3f}" if fc_unit == "kW"
+                          else f"{fc_kw[0] * 1000.0:.0f}"),
+                "attributes": {"unit_of_measurement": fc_unit}}
+        hass.state = state
+        tmp = tempfile.mkdtemp(prefix="s125-")
+        db = os.path.join(tmp, "tariff.db")
+        if peak is not None:
+            tariff.PeakStore(db)._db.execute(
+                "INSERT INTO monthly_peak VALUES (?, ?, ?, NULL)",
+                (tariff.month_key(t0), peak,
+                 "2026-10-21T20:15:00+00:00")).connection.commit()
+        c = Controller(dict(o), hass, store, rp._Pub(), stop=asyncio.Event(),
+                       peak_db_path=db,
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        c.inverters[0].dev_min, c.inverters[0].dev_max = -5000.0, 5000.0
+        c.inverters[1].dev_min, c.inverters[1].dev_max = -4600.0, 4600.0
+        c.auto = True
+        real = m.datetime, homeview.datetime, p1mod.time
+        clock, simt = [t0], [0.0]
+
+        class _DT(real[0]):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+        m.datetime = homeview.datetime = _DT
+        p1mod.time = types.SimpleNamespace(monotonic=lambda: 1e6 + simt[0])
+        real_load = _price.load_prices, _st.load_prices
+        _price.load_prices = _st.load_prices = _no_fetch
+        task = asyncio.create_task(c.run_tariff_refresh())
+        try:
+            hass.advance(0.0, 10.0)
+            t, n = 0.0, 0
+            while t < minutes * 60:
+                now = t0 + timedelta(seconds=t)
+                hass.t, simt[0], clock[0] = t, t, now
+                if t == 0.0:
+                    for _ in range(500):
+                        if c.tariff_plan is not None:
+                            break
+                        await asyncio.sleep(0)
+                q = int(now.timestamp() // QUARTER_S)
+                acc = sums.setdefault(q, [0.0, 0])
+                g_now = hass.grid()
+                fc_kw[0] = (acc[0] + g_now * (QUARTER_S - acc[1])) \
+                    / QUARTER_S / 1000.0
+                if now.timestamp() % QUARTER_S < QUARTER_S - late \
+                        and t >= lag.p1_s \
+                        and (not period or t % period < 1e-9):
+                    imp, exp = split_signed(hass._past(lag.meter_s
+                                                       + lag.p1_s)[0])
+                    c.p1.submit(make_sample(
+                        "ha_signed", imp, exp, phases=1,
+                        ingest_ts=now - timedelta(seconds=lag.p1_s),
+                        ingest_mono=1e6 + t))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(lag.tick, 10.0)
+                acc[0] += max(0.0, hass.grid())
+                acc[1] += 1
+                rows.append((now, c.target, hass.plants["a"].p,
+                             getattr(c.arb, "action", None)))
+                pg = c.peak_guard
+                if every and n % every == 0 and t >= QUARTER_S \
+                        and pg is not None and pg.projected_w is not None:
+                    row = first((r["text"] for r in c.checks(now)
+                                 if r["id"] == "peak_guard"), "guard row")
+                    samples.append((pg.projected_w, pg.ceiling_w, pg.engaged,
+                                    row, homeview.month_peak(c, now)["line"]))
+                t += lag.tick
+                n += 1
+        finally:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+            m.datetime, homeview.datetime, p1mod.time = real
+            _price.load_prices, _st.load_prices = real_load
+        return c
+    c = asyncio.run(go())
+    full = {datetime.fromtimestamp(q * QUARTER_S, L).strftime("%H:%M"):
+            s / k for q, (s, k) in sorted(sums.items()) if k >= QUARTER_S}
+    return c, rows, full, samples
+
+
+def into(now):
+    return now.timestamp() % QUARTER_S
+
+
+# ============================================================================ #
+print("1. charge_room_w(): a late reading's seconds count at that reading")
+_dec = peakguard.decide(
+    Projection(5800.0, 5800.0, 450.0, 1.0, True, START, 5800.0),
+    batt_w=-4800.0, cap_w=3500, margin_w=50,
+    reading=types.SimpleNamespace(is_observed=True, peak_w=PEAK),
+    achievable_w=9600.0, soc=50.0, soc_floor=20.0)
+_room = peakguard.charge_headroom_w(_dec)
+_late = Projection(5800.0, 5800.0, 450.0, 430.0 / 450.0, False, START,
+                   5800.0)
+print(f"    headroom {_room:.0f} W; 20 s late, 450 s left: "
+      f"{peakguard.charge_room_w(_dec, _late):.0f} W")
+check("with every second counted it is charge_headroom_w() exactly",
+      peakguard.charge_room_w(
+          _dec, Projection(5800.0, 5800.0, 450.0, 1.0, True, START, 5800.0))
+      == _room and _room > 0.0)
+check("20 s late at a 5800 W reading with 450 s left: 5800 x 20 / 450 W "
+      "less room",
+      abs(peakguard.charge_room_w(_dec, _late)
+          - (_room - 5800.0 * 20.0 / 450.0)) < 1e-6)
+check("never below 0 W, and an export held counts nothing",
+      peakguard.charge_room_w(_dec, Projection(
+          5800.0, 5800.0, 880.0, 850.0 / 880.0, False, START, 5800.0)) == 0.0
+      and peakguard.charge_room_w(_dec, Projection(
+          5800.0, 5800.0, 450.0, 430.0 / 450.0, False, START, -900.0))
+      == _room)
+check("None, blind (0 W) and no projection pass through",
+      peakguard.charge_room_w(None, _late) is None
+      and peakguard.charge_room_w(_dec, None) == _room
+      and peakguard.charge_room_w(
+          peakguard.PeakDecision(engaged=True, floor_w=0.0, ceiling_w=3500.0,
+                                 ceiling_from="cap", blind="frozen"),
+          _late) == 0.0)
+
+
+# ============================================================================ #
+def graded(label, full, aim):
+    print(f"    {label}: quarters "
+          f"{ {k: round(v, 1) for k, v in full.items()} } W, aim {aim:.0f}")
+    return len(full) >= 2 and all(v <= aim + TOL for v in full.values())
+
+
+def cut_and_back(rows):
+    """The charge is off in each quarter's last 5 s, and back (A charging
+    over 2 kW) within the next quarter's first minute."""
+    ends = [r for r in rows if into(r[0]) >= QUARTER_S - 5]
+    starts = {}
+    for r in rows:
+        if into(r[0]) < 60:
+            q = int(r[0].timestamp() // QUARTER_S)
+            starts[q] = starts.get(q, False) or r[2] < -2000.0
+    return (present(first(iter(ends), "a quarter end"))
+            and all(r[1] > -1.0 for r in ends)
+            and len(starts) >= 2 and all(starts.values()))
+
+
+print("\n2. a reading 30 s late at each quarter's end, the live shape")
+GAP = {}
+for name, kw, aim in (
+        ("month peak 5413 W banked, P1 projection",
+         dict(peak=PEAK), AIM_PEAK),
+        ("month peak banked, peak_forecast_entity (kW)",
+         dict(peak=PEAK, fc=True), AIM_PEAK),
+        ("no peak banked (aim = cap - margin), P1 projection",
+         dict(), AIM_CAP),
+        ("no peak banked, peak_forecast_entity", dict(fc=True), AIM_CAP)):
+    fc = kw.pop("fc", False)
+    _c, _rows, _full, _s = drive(opts(fc=fc), late=30.0, **kw)
+    GAP[name] = (_c, _rows, _full)
+    check(f"{name}: every quarter at or under the aim "
+          f"({aim:.0f} W, +{TOL:.0f} W landing)", graded(name, _full, aim))
+    check(f"{name}: the charge is off in the quarter's last seconds and "
+          f"back in the next quarter", cut_and_back(_rows))
+_c_fc = GAP["month peak banked, peak_forecast_entity (kW)"][0]
+check("the forecast entity is read, in kW, as the live template (SAFETY-118), "
+      "and the cheap run's charge does not depend on it",
+      _c_fc.peak_fc is not None and _c_fc.peak_fc > 1000.0
+      and [r[1] for r in GAP["month peak banked, peak_forecast_entity (kW)"]
+           [1]] == [r[1] for r in GAP[
+               "month peak 5413 W banked, P1 projection"][1]])
+
+
+# ============================================================================ #
+print("\n3. the same for a price trade (modes off) and a maintenance charge")
+_ca, _ra, _fa = drive(opts(modes=False, arb=True), peak=PEAK, late=30.0)[:3]
+check("modes off, price trading on, a reading 30 s late: every quarter at "
+      "or under the aim", graded("trade", _fa, AIM_PEAK)
+      and any(r[3] == "ARBITRAGE_CHARGE" for r in _ra))
+
+
+def late_feed(gap, every=0.0, look=None):
+    """safety84's cheap-window feed, no telegram in each quarter's last
+    `gap` s, and one only every `every` s (0: every cycle). `look(c, t)`
+    runs first, on the state the previous cycle left."""
+    feed = s84.feed(True)
+
+    def before(c, t):
+        if look is not None:
+            look(c, t)
+        if ((rig.BASE.timestamp() + t) % QUARTER_S < QUARTER_S - gap
+                and (not every or t % every < 1e-9)) \
+                or not getattr(c.hass, "_s84", False):
+            feed(c, t)
+    return before
+
+
+def rig_quarters(rows, load):
+    """The safety84 rig's whole quarters: the true average import (W)."""
+    qs = {}
+    for r in rows:
+        q = int((rig.BASE.timestamp() + r[0]) // QUARTER_S)
+        a = qs.setdefault(q, [0.0, 0])
+        a[0] += max(0.0, load(r[0]) - sum(v for _u, v in r[2]))
+        a[1] += 1
+    return {datetime.fromtimestamp(q * QUARTER_S, L).strftime("%H:%M"):
+            s / k for q, (s, k) in sorted(qs.items())
+            if k * rig.TICK >= QUARTER_S}
+
+
+for peak, house, aim in ((5413.0, 4000.0, 5363.0), (None, 2500.0, AIM_CAP)):
+    _mr, _mc = s84.run(2, load=lambda t, h=house: h, dur=2700.0,
+                       month_peak=peak, before=late_feed(30.0))
+    _mf = rig_quarters(_mr, lambda t, h=house: h)
+    check(f"N=2 maintenance charge, house {house:.0f} W, "
+          f"{'peak banked' if peak else 'no peak banked'}, a reading 30 s "
+          f"late: every quarter at or under the aim",
+          graded("maintenance", _mf, aim)
+          and any(mm.phase == "charge" for mm in _mc.maints))
+
+
+# ============================================================================ #
+print("\n4. a healthy meter: the quarters, and the words")
+for name, kw, aim, kw_text in (("month peak banked", dict(peak=PEAK),
+                                AIM_PEAK, "5.4 kW"),
+                               ("no peak banked", dict(), AIM_CAP, "3.5 kW")):
+    _c, _rows, _full, _s = drive(opts(), every=10, **kw)
+    check(f"{name}: every quarter at or under the aim",
+          graded(name, _full, aim))
+    over = [s for s in _s if not s[2] and s[0] > s[1]]
+    under = [s for s in _s if not s[2] and s[0] <= s[1]]
+    _o, _u = first(iter(over), "an over sample"), \
+        first(iter(under), "an under sample")
+    print(f"    over the limit at this rate ({len(over)} samples): "
+          f"{_o[3] if present(_o) else _o!s} / "
+          f"{_o[4] if present(_o) else _o!s}")
+    print(f"    under it ({len(under)}): "
+          f"{_u[3] if present(_u) else _u!s} / "
+          f"{_u[4] if present(_u) else _u!s}")
+    check(f"{name}: over the limit at this rate the guard row never says "
+          f"'under'; it says the grid charge is limited",
+          present(_o) and all(
+              "under" not in s[3] and "Peak guard: grid charge limited, "
+              "at this rate" in s[3] and " over " in s[3] for s in over))
+    check(f"{name}: ...and the month-peak line says the rate, and that the "
+          f"grid charge is cut back to stay under {kw_text}",
+          present(_o) and all(
+              s[4].startswith("At this rate this 15-minute period reaches")
+              and s[4].endswith("The grid charge is cut back to stay "
+                                f"under {kw_text}.") for s in over))
+    check(f"{name}: under the limit both read as before",
+          present(_u) and all(
+              s[3].startswith("Peak guard: idle, heading for")
+              and " under " in s[3]
+              and s[4].startswith("This 15-minute period is heading for")
+              and s[4].endswith(f"The batteries step in above {kw_text}.")
+              for s in under))
+
+
+# ============================================================================ #
+print("\n5. the words on their own")
+_en = messages.row_peak_guard_idle(5814.0, 5413.0, month_peak=True)
+_cut = messages.row_peak_guard_idle(5814.0, 5413.0, month_peak=True,
+                                    cut=True)
+_ok = messages.row_peak_guard_idle(5200.0, 5413.0, month_peak=True)
+print(f"    {_en}\n    {_cut}\n    {_ok}")
+check("over, nothing cut: 'idle, at this rate ..., over ...'",
+      _en == "Peak guard: idle, at this rate 5 814 W, over 5 413 W")
+check("over, a grid charge cut",
+      _cut == "Peak guard: grid charge limited, at this rate 5 814 W, "
+              "over 5 413 W")
+check("under: the 0.19.1 sentence, unchanged",
+      _ok == "Peak guard: idle, heading for 5 200 W, under this month's "
+             "5 413 W peak")
+check("the Dutch forms say the same",
+      _cut.nl == "Piekbewaking: laden beperkt, aan dit tempo 5 814 W, "
+                 "boven 5 413 W"
+      and _en.nl.startswith("Piekbewaking: in rust, aan dit tempo"))
+check("the month-peak line in shadow mode says 'would'",
+      homeview.line_period(5814.0, 5413.0, True, cut=True).endswith(
+          "The grid charge would be cut back to stay under 5.4 kW.")
+      and homeview.line_period(5814.0, 5413.0, False).endswith(
+          "The batteries step in above 5.4 kW."))
+
+
+# ============================================================================ #
+print("\n6. one inverter: the maintenance charge is sized to the room too")
+# The start-up quarter on a 10 s meter: the charge's first step is not seen
+# until the second reading, so it may land up to START_TOL over the aim; the
+# same at N=2 and before this fix. Every later quarter is graded at TOL.
+START_TOL = 15.0
+N1 = {}
+for peak, house, aim in ((5413.0, 4000.0, 5363.0), (None, 2500.0, AIM_CAP)):
+    for late, every in ((0.0, 0.0), (30.0, 0.0), (20.0, 10.0)):
+        _r, _c = s84.run(1, load=lambda t, h=house: h, dur=2700.0,
+                         month_peak=peak, before=late_feed(late, every))
+        _q = rig_quarters(_r, lambda t, h=house: h)
+        N1[peak, late, every] = (_r, _c)
+        _vals = list(_q.values())
+        _tag = (f"N=1, {'peak banked' if peak else 'no peak banked'}, "
+                f"{'10 s' if every else '5 s'} meter, "
+                f"{'late ' + format(late, '.0f') + ' s' if late else 'healthy'}")
+        print(f"    {_tag}: quarters "
+              f"{ {k: round(v, 1) for k, v in _q.items()} } W, aim {aim:.0f}")
+        check(f"{_tag}: every quarter at or under the aim",
+              len(_vals) == 3
+              and all(v <= aim + TOL for v in _vals[1:])
+              and nth(_vals, 0, "a first quarter")
+              <= aim + (START_TOL if every else TOL)
+              and any(mm.phase == "charge" for mm in _c.maints))
+_hr, _hc = N1[5413.0, 0.0, 0.0]
+_eng = sum(1 for r in _hr if r[-1][1] and r[-1][1][0])
+print(f"    healthy, peak banked: guard engaged on {_eng} of {len(_hr)} "
+      f"cycles; A charges on "
+      f"{sum(1 for r in _hr if dict(r[2])['a'] < -1.0)} cycles")
+check("N=1: the guard no longer steps in during the charge (no hand-back), "
+      "and the battery charges on every cycle, at no more than its rate",
+      _eng == 0 and all(-2000.0 <= dict(r[2])["a"] < -1.0 for r in _hr)
+      and not any("suspended" in e for e in _hc.events))
+
+
+# ============================================================================ #
+print("\n7. the row during an N=2 maintenance charge and in shadow mode")
+_rows7 = []
+
+
+def _look(c, t):
+    pg = c.peak_guard
+    if t >= QUARTER_S and pg is not None and pg.projected_w is not None \
+            and not pg.engaged and pg.projected_w > pg.ceiling_w:
+        _rows7.append(first((r["text"] for r in c.checks()
+                             if r["id"] == "peak_guard"), "guard row"))
+
+
+def _steps(t):
+    """4000 W, 800 W more for the first 30 s of every minute."""
+    return 4000.0 + (800.0 if t % 60.0 < 30.0 else 0.0)
+
+
+_m2r, _m2c = s84.run(2, load=_steps, dur=1800.0, month_peak=5413.0,
+                     before=late_feed(0.0, look=_look))
+_m2q = rig_quarters(_m2r, _steps)
+print(f"    N=2 maintenance charge, house steps 4000/4800 W: "
+      f"{len(_rows7)} over-the-limit rows, e.g. "
+      f"{first(iter(_rows7), 'a row')}; quarters "
+      f"{ {k: round(v, 1) for k, v in _m2q.items()} } W")
+check("N=2 maintenance charge, over the limit at this rate: the row says the "
+      "grid charge is limited",
+      present(first(iter(_rows7), "a row")) and all(
+          r.startswith("Peak guard: grid charge limited, at this rate")
+          for r in _rows7)
+      and all(v <= 5363.0 + TOL for v in _m2q.values()))
+_sh_o = dict(opts(), shadow_mode="on")
+_csh, _rsh, _fsh, _ssh = drive(_sh_o, peak=PEAK, minutes=17, every=10,
+                               plant=OnItsOwn)
+_sh_over = [s for s in _ssh if not s[2] and s[0] > s[1]]
+_sh1 = first(iter(_sh_over), "an over sample")
+print(f"    shadow mode, the inverter charging 5000 W on its own: "
+      f"{len(_sh_over)} over samples, e.g. "
+      f"{_sh1[3] if present(_sh1) else _sh1!s} / "
+      f"{_sh1[4] if present(_sh1) else _sh1!s}")
+check("shadow mode: nothing is cut on the wire, so the row says 'idle', "
+      "never 'grid charge limited', and the line says 'would'",
+      _csh.shadow and present(_sh1) and all(
+          s[3].startswith("Peak guard: idle, at this rate")
+          and "would" in s[4] for s in _sh_over))
+
+
+# ============================================================================ #
+print("\n8. edge cases")
+_e45 = drive(opts(), peak=PEAK, late=45.0)
+check("a reading 45 s late, past the 30 s hold (the guard goes blind): every "
+      "quarter at or under the aim", graded("late 45 s", _e45[2], AIM_PEAK))
+_e07 = drive(opts(), peak=PEAK, late=30.0, minutes=24,
+             start=START + timedelta(minutes=7))
+check("a start at 00:07, mid-quarter, then 30 s late: the next quarter at or "
+      "under the aim",
+      len(_e07[2]) == 1 and all(v <= AIM_PEAK + TOL
+                                for v in _e07[2].values()))
+print(f"    start at 00:07: {_e07[2]}")
+_dst = drive(opts(), peak=PEAK, late=30.0,
+             start=datetime(2026, 10, 25, 0, 45, tzinfo=timezone.utc))
+check("across the end of summer time (2026-10-25 01:00 UTC), 30 s late: "
+      "every quarter at or under the aim", graded("DST", _dst[2], AIM_PEAK))
+_ew = drive(opts(fc=True), peak=PEAK, late=30.0, fc_unit="W")
+check("the forecast entity in W: read as W, and the charge as with kW",
+      _ew[0].peak_fc is not None and _ew[0].peak_fc > 1000.0
+      and [r[1] for r in _ew[1]] == [r[1] for r in GAP[
+          "month peak banked, peak_forecast_entity (kW)"][1]])
+_e10 = drive(opts(), peak=PEAK, period=10.0)
+_e10v = list(_e10[2].values())
+print(f"    10 s meter: {_e10[2]}")
+check("a 10 s meter: every quarter after the start-up one at or under the "
+      "aim, and that one within START_TOL",
+      len(_e10v) == 2 and all(v <= AIM_PEAK + TOL for v in _e10v[1:])
+      and nth(_e10v, 0, "a first quarter") <= AIM_PEAK + START_TOL)
+_p_end = Projection(5800.0, 5800.0, 899.5, 898.5 / 899.5, False, START,
+                    5800.0)
+check("0.5 s left and 1 s late: finite, the formula, at its floor of 0 W",
+      peakguard.charge_room_w(_dec, _p_end) == max(
+          0.0, _room - 5800.0 * 1.0 / 0.5))
+_d_end = peakguard.decide(
+    Projection(5800.0, 5800.0, 900.0, 1.0, True, START, 5800.0),
+    batt_w=-4800.0, cap_w=3500, margin_w=50,
+    reading=types.SimpleNamespace(is_observed=True, peak_w=PEAK),
+    achievable_w=9600.0, soc=50.0, soc_floor=20.0)
+check("no second left: no room is measured (None), and nothing divides by 0",
+      peakguard.charge_room_w(_d_end, Projection(
+          5800.0, 5800.0, 900.0, 890.0 / 900.0, False, START, 5800.0))
+      is None)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_safety126.py

@@ -0,0 +1,473 @@
+"""Runnable check for SAFETY-126.  `python3 test_safety126.py`
+
+During the night grid charge, with both batteries under the peak reserve,
+the add-on logged ERROR PEAK_GUARD_FLOOR_LIMITED and raised "Battery stopped
+limiting the peak" at quarter ends, and the Batteries "Why" blinked "The peak
+limit needs power from the batteries.", while every quarter landed on the aim.
+The cause: the charge lands the quarter on the aim, a 1 W landing error in
+the quarter's last second becomes tens of kW through `excess_w()`'s
+900 / remaining, and the alarm fired on any `wanted > 0` when no battery can
+give. DECISIONS/SAFETY-126-landing-error-is-not-an-overrun.md.
+
+Drives the REAL Controller (read_inputs + cycle, the tariff task on a
+day/night profile, a P1 meter on a simulated clock, OPT-15's lag), as
+test_safety125.py does, with the cycle a fraction of a second off the
+quarter's edge as on the rig.
+
+1. The night grid charge under the reserve: no ERROR, no notification, no
+   red peak row, no "Why" peak, every quarter on the aim; the guard did want
+   power at the quarter's end (not vacuous); with the fix reverted the same
+   run alarms. The commands are the same with and without the fix.
+2. A real overrun under the reserve still alarms, a step load at the same
+   cycle as before, and names both batteries. After it, the latch is reset:
+   the night's later landings are quiet again.
+3. `misses_aim()` on its own.
+4. The page and the "Why" on a decision within the aim.
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import asyncio
+import dataclasses
+import io
+import logging
+import os
+import sys
+import tempfile
+import types
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+
+import opt11p3_replay as rp                                    # noqa: E402
+from named_absence import first, nth, present                  # noqa: E402
+import app.main as m                                           # noqa: E402
+import app.p1 as p1mod                                         # noqa: E402
+from app import homeview, messages, peakguard, tariff          # noqa: E402
+from app import price as _price, static_tariff as _st          # noqa: E402
+from app.main import Controller                                # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+from app.tariff import QUARTER_S, Projection                   # noqa: E402
+
+logging.disable(logging.NOTSET)
+logging.getLogger().setLevel(logging.CRITICAL)
+_ERRORS = io.StringIO()
+_h = logging.StreamHandler(_ERRORS)
+_h.setLevel(logging.ERROR)
+logging.getLogger("goodwe").addHandler(_h)
+logging.getLogger("goodwe").setLevel(logging.ERROR)
+logging.getLogger("goodwe").propagate = False
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+PEAK = 5413.17          # October's banked peak on the live site
+AIM_CAP = 3500.0 - 50.0
+AIM_PEAK = PEAK - 50.0
+TOL = 10.0              # W over the aim a quarter may land (SAFETY-81)
+L = timezone(timedelta(hours=1))
+NIGHT = datetime(2026, 10, 30, 22, 0, tzinfo=L).astimezone(timezone.utc)
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.2333},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.2801}]}')
+OWNER = {"a": "leftover_solar", "b": "cheap_hours"}
+
+
+def opts(*, modes=True, arb=False):
+    o = dict(rp.options(modes, arb, 2))
+    o.update(cycle_cost_threshold_eur=0.03, static_profile=PROFILE,
+             peak_cap_w=3500, peak_margin_w=50)
+    o["inverters"][0].update(max_w=5000, capacity_kwh=15.36)
+    o["inverters"][1].update(max_w=4600, capacity_kwh=20.48)
+    return o
+
+
+class Harder(rp.Plant):
+    """Charges harder than asked, as inverter-a did live (test_safety125.py:
+    asked -4271 W, measured about -4750 W; asked -5000 W, about -5210 W), up
+    to `cap` W. So a charge sized to the aim lands a few W over it, as on the
+    rig (worst +7 W)."""
+    cap = -5216.0
+
+    def step(self, dt, floor):
+        c = self.cmd
+        if c < 0:
+            self.cmd = max(c * 1.11, self.cap)
+        try:
+            super().step(dt, floor)
+        finally:
+            self.cmd = c
+
+
+async def _no_fetch(*a, **k):
+    raise AssertionError("the tariff task reached for a price feed")
+
+
+def without_fix(fn):
+    """release/1.0 cc9bbeb: no decision is ever within the aim."""
+    real = getattr(Controller, "_peak_landing", None)
+    if real is None:
+        return fn()
+    Controller._peak_landing = lambda self, decision: decision
+    try:
+        return fn()
+    finally:
+        Controller._peak_landing = real
+
+
+def drive(o, *, modes=OWNER, socs=(10.0, 10.0), house=600.0, minutes=46,
+          start=NIGHT, off=0.7, peak=None):
+    """The real Controller from `start` + `off` s for `minutes` at a 1 s
+    cycle with OPT-15's lag, so a cycle lands `1 - off` s before each
+    quarter's end. `house` is W or a function of t. Returns a dict: the
+    quarters' true grid averages, the commands, the reserve notifications,
+    the ERROR lines, and per cycle where the guard engaged: (t, floor
+    limited, within the aim, battery "Why" peak, red reserve row, red
+    saturated row, alarm latched)."""
+    store = rp._Store()
+    for u, mode in (modes or {}).items():
+        store.data[unit_key(f"inverter-{u}", "pack_use")] = True
+        store.data[unit_key(f"inverter-{u}", "pack_mode")] = mode
+        store.data[unit_key(f"inverter-{u}", "pack_sell")] = False
+    load = house if callable(house) else (lambda t: float(house))
+    t0 = start + timedelta(seconds=off)
+    out = {"cmds": [], "notes": [], "seen": [], "sums": {}}
+    _ERRORS.seek(0)
+    _ERRORS.truncate()
+
+    async def go():
+        lag = rp.Lag()
+        hass = rp.Hass(("a", "b"), load, {"a": socs[0], "b": socs[1]},
+                       limits={"a": (-5000.0, 5000.0),
+                               "b": (-4600.0, 4600.0)}, lag=lag)
+        for u, cap in (("a", -5216.0), ("b", -4800.0)):
+            hass.plants[u].__class__ = Harder
+            hass.plants[u].cap = cap
+        real_set = hass.set_number
+
+        async def set_number(e, v):
+            out["cmds"].append((round(hass.t, 3), e, float(v)))
+            return await real_set(e, v)
+
+        async def call(*a):
+            if a[:2] == ("persistent_notification", "create") \
+                    and a[2]["notification_id"] == messages.ID_PEAK_RESERVE:
+                out["notes"].append((hass.t, a[2]["message"]))
+            return True
+        hass.set_number, hass.call = set_number, call
+        tmp = tempfile.mkdtemp(prefix="s126-")
+        db = os.path.join(tmp, "tariff.db")
+        if peak is not None:
+            tariff.PeakStore(db)._db.execute(
+                "INSERT INTO monthly_peak VALUES (?, ?, ?, NULL)",
+                (tariff.month_key(t0), peak,
+                 "2026-10-21T20:15:00+00:00")).connection.commit()
+        c = Controller(dict(o), hass, store, rp._Pub(), stop=asyncio.Event(),
+                       peak_db_path=db,
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        c.inverters[0].dev_min, c.inverters[0].dev_max = -5000.0, 5000.0
+        c.inverters[1].dev_min, c.inverters[1].dev_max = -4600.0, 4600.0
+        c.auto = True
+        real = m.datetime, homeview.datetime, p1mod.time
+        clock, simt = [t0], [0.0]
+
+        class _DT(real[0]):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+        m.datetime = homeview.datetime = _DT
+        p1mod.time = types.SimpleNamespace(monotonic=lambda: 1e6 + simt[0])
+        real_load = _price.load_prices, _st.load_prices
+        _price.load_prices = _st.load_prices = _no_fetch
+        task = (asyncio.create_task(c.run_tariff_refresh())
+                if o.get("battery_modes_enabled") or o.get("arbitrage_enabled")
+                else None)
+        try:
+            hass.advance(0.0, 10.0)
+            t = 0.0
+            while t < minutes * 60:
+                now = t0 + timedelta(seconds=t)
+                hass.t, simt[0], clock[0] = t, t, now
+                if t == 0.0 and task is not None:
+                    for _ in range(500):
+                        if c.tariff_plan is not None:
+                            break
+                        await asyncio.sleep(0)
+                q = int(now.timestamp() // QUARTER_S)
+                acc = out["sums"].setdefault(q, [0.0, 0])
+                if t >= lag.p1_s:
+                    imp, exp = split_signed(hass._past(lag.meter_s
+                                                       + lag.p1_s)[0])
+                    c.p1.submit(make_sample(
+                        "ha_signed", imp, exp, phases=1,
+                        ingest_ts=now - timedelta(seconds=lag.p1_s),
+                        ingest_mono=1e6 + t))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(lag.tick, 10.0)
+                acc[0] += max(0.0, hass.grid())
+                acc[1] += 1
+                g = c.peak_guard
+                if g is not None and g.engaged and g.blind is None:
+                    rows = {r["id"]: r for r in c.checks(now)}
+                    row = rows.get("peak_guard", {})
+                    red = row.get("ok") is False and not row.get("warn")
+                    out["seen"].append((
+                        t, g.floor_limited, getattr(g, "within_aim", False),
+                        homeview.peak_engaged(c),
+                        red and "banner" in row,
+                        red and "banner" not in row,
+                        c._peak_floor_limited))
+                t += lag.tick
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+            m.datetime, homeview.datetime, p1mod.time = real
+            _price.load_prices, _st.load_prices = real_load
+        return c
+    out["c"] = asyncio.run(go())
+    out["quarters"] = {
+        datetime.fromtimestamp(q * QUARTER_S, L).strftime("%H:%M"): s / k
+        for q, (s, k) in sorted(out["sums"].items()) if k >= QUARTER_S - 1}
+    out["errors"] = [x for x in _ERRORS.getvalue().splitlines()
+                     if "PEAK_GUARD_FLOOR_LIMITED" in x]
+    return out
+
+
+def show(tag, r):
+    print(f"    {tag}: quarters "
+          f"{ {k: round(v, 1) for k, v in r['quarters'].items()} }, "
+          f"guard cycles {len(r['seen'])}, floor-limited "
+          f"{sum(1 for s in r['seen'] if s[1])}, within-aim "
+          f"{sum(1 for s in r['seen'] if s[2])}, Why peak "
+          f"{sum(1 for s in r['seen'] if s[3])}, notes {len(r['notes'])}, "
+          f"errors {len(r['errors'])}")
+
+
+def quiet(r):
+    """No reserve alarm in any form: ERROR, notification, red row, latch,
+    "Why" peak, and no red saturated row."""
+    return (not r["errors"] and not r["notes"]
+            and not any(s[3] or s[4] or s[5] or s[6] for s in r["seen"]))
+
+
+def on_aim(r, aim):
+    q = r["quarters"]
+    return len(q) >= 3 and all(v <= aim + TOL for v in q.values())
+
+
+# ============================================================================ #
+print("1. the night grid charge under the peak reserve")
+NIGHTS = {}
+# The owner's shape at the cap's aim. At the banked peak's aim it is
+# test_safety125.py's live shape (A Cheap hours, B Solar first), because
+# B's 4 600 W alone stays under that aim.
+LIVE = {"a": "cheap_hours", "b": "solar_first"}
+for tag, kw, aim in (
+        ("aim 3450, cycle 0.3 s before the edge", dict(off=0.7), AIM_CAP),
+        ("aim 3450, cycle 0.01 s before the edge", dict(off=0.99), AIM_CAP),
+        ("month peak 5413, cycle 0.01 s before the edge",
+         dict(off=0.99, peak=PEAK, modes=LIVE, socs=(11.0, 10.0)),
+         AIM_PEAK)):
+    head = drive(opts(), **kw)
+    base = without_fix(lambda: drive(opts(), **kw))
+    NIGHTS[tag] = (head, base)
+    show("head " + tag, head)
+    show("fix reverted", base)
+    check(f"⭐ {tag}: no ERROR, no notification, no red peak row and no "
+          f"'Why' peak", quiet(head))
+    check(f"{tag}: every quarter at or under the aim ({aim:.0f} W + "
+          f"{TOL:.0f} W)", on_aim(head, aim))
+    check(f"{tag}: not vacuous, the guard wanted power under the reserve "
+          f"at a quarter's end (floor-limited, within the aim)",
+          any(s[1] and s[2] for s in head["seen"]))
+    check(f"{tag}: with the fix reverted the same run alarms",
+          not quiet(base))
+    check(f"{tag}: the commands are the same with and without the fix",
+          head["cmds"] == base["cmds"] and len(head["cmds"]) > 100)
+_h, _b = NIGHTS["aim 3450, cycle 0.01 s before the edge"]
+check("fix reverted, at 0.01 s: the ERROR, the notification and the "
+      "'Why' peak all come back (the rig's three symptoms)",
+      _b["errors"] and _b["notes"] and any(s[3] for s in _b["seen"]))
+
+
+# ============================================================================ #
+print("\n2. a real overrun under the reserve still alarms")
+
+
+def evening(t):
+    """600 W, then an oven and a car charger from 20 minutes on."""
+    return 600.0 if t < 1200 else 6500.0
+
+
+for tag, onset, kw in (
+        ("night grid charge, then 6500 W", 1200.0, dict(house=evening)),
+        ("modes off, 5500 W all along", 0.0,
+         dict(house=5500.0, modes=None, socs=(15.0, 12.0)))):
+    o = opts(modes=kw.get("modes", OWNER) is not None)
+    head = drive(o, minutes=35, **kw)
+    base = without_fix(lambda: drive(o, minutes=35, **kw))
+    show("head " + tag, head)
+    show("fix reverted", base)
+    # From the load's onset: before it, the fix reverted shows the night's
+    # false alarm (part 1).
+    first_h = next((s[0] for s in head["seen"] if s[6] and s[0] >= onset),
+                   None)
+    first_b = next((s[0] for s in base["seen"] if s[6] and s[0] >= onset),
+                   None)
+    check(f"⭐ {tag}: the ERROR and the notification, naming both "
+          f"batteries",
+          head["errors"] and head["notes"]
+          and all("inverter-a and inverter-b" in n for _t, n in head["notes"]))
+    _th = [t for t, _n in head["notes"]]
+    _tb = [t for t, _n in base["notes"] if t >= onset]
+    print(f"    notifications at {_th} s; with the fix reverted {_tb} s")
+    check(f"{tag}: the first at the same cycle as before the fix "
+          f"({first_h} s, {first_b} s), and none that was not raised before",
+          first_h is not None and first_h == first_b
+          and present(nth(_th, 0)) and nth(_th, 0) == nth(_tb, 0)
+          and set(_th) <= set(_tb))
+    check(f"{tag}: the red peak row and its banner while it stands",
+          any(s[4] for s in head["seen"]))
+
+
+def burst(t):
+    """600 W, a 6 500 W load from 20 to 25 minutes, then 600 W again while
+    the night charge goes on."""
+    return 6500.0 if 1200 <= t < 1500 else 600.0
+
+
+# F3 (review): `_peak_landing()` resets its latch when the guard lets go, so
+# a real overrun does not keep the later landing errors alarming.
+_bh = drive(opts(), house=burst, off=0.99, minutes=61)
+_bb = without_fix(lambda: drive(opts(), house=burst, off=0.99,
+                                     minutes=61))
+show("head real overrun, then the night again", _bh)
+show("fix reverted", _bb)
+# The burst banked a new month peak, which the later quarters stay under.
+_new_peak = _bh["c"].peak_guard.ceiling_w
+
+
+def _late(r):
+    """From the next quarter on: the overrun's own quarter ends over."""
+    return [x for x in r["seen"] if x[0] >= 1800]
+
+
+print(f"    notifications at {[t for t, _n in _bh['notes']]} s; with the fix "
+      f"reverted {[t for t, _n in _bb['notes']]} s; limit after the burst "
+      f"{_new_peak:.0f} W")
+check("⭐ after a real overrun ends, the latch is reset: the alarm came "
+      "during the overrun, and the later quarters' landings are quiet "
+      "(no notification, no 'Why' peak, no red row) and under the new peak",
+      any(1200 <= t < 1500 for t, _n in _bh["notes"])
+      and not [t for t, _n in _bh["notes"] if t >= 1800]
+      and not any(x[3] or x[4] or x[5] for x in _late(_bh))
+      and present(nth([v for k, v in _bh["quarters"].items()
+                       if k >= "22:30"], 0))
+      and all(v <= _new_peak for k, v in _bh["quarters"].items()
+              if k >= "22:30"))
+check("...not vacuous: the guard wanted power at those landings, and with "
+      "the fix reverted they show the 'Why' peak or an alarm",
+      any(x[2] for x in _late(_bh))
+      and (any(x[3] or x[4] or x[5] for x in _late(_bb))
+           or bool([t for t, _n in _bb["notes"] if t >= 1800])))
+
+
+# ============================================================================ #
+print("\n3. misses_aim() on its own")
+START = datetime(2026, 10, 30, 21, 15, tzinfo=timezone.utc)
+
+
+def proj(projected, elapsed, held):
+    return Projection(projected, projected, elapsed, 1.0, True, START, held)
+
+
+check("the rig's case: 3452 W against 3450 W, 0.3 s left, charging "
+      "1250 W from the grid: not a miss",
+      not peakguard.misses_aim(proj(3452.0, 899.7, 3452.0), batt_w=-1250.0,
+                               target_w=AIM_CAP))
+check("...although decide() wants power there (its gain, 900 / 0.3 s)",
+      (peakguard.decide(proj(3452.0, 899.7, 3452.0), batt_w=-1250.0,
+                        cap_w=3500, margin_w=50, reading=None,
+                        achievable_w=0.0, soc=10.0, soc_floor=20.0)
+       .wanted_w or 0.0) > 1000.0)
+check("a quarter heading 11 W over the aim with the batteries at 0 W is a "
+      "miss", peakguard.misses_aim(proj(3461.0, 899.7, 3461.0), batt_w=0.0,
+                                   target_w=AIM_CAP))
+check("...and 10 W is not (ALARM_MISS_W, as for 'Load too high')",
+      not peakguard.misses_aim(proj(3460.0, 899.7, 3460.0), batt_w=0.0,
+                               target_w=AIM_CAP))
+check("the add-on's own grid charge counts as stoppable: 4000 W on the "
+      "meter mid-quarter, 3000 W of it charging, is not a miss",
+      not peakguard.misses_aim(proj(2500.0, 450.0, 4000.0), batt_w=-3000.0,
+                               target_w=AIM_CAP))
+check("...and a house of 6000 W the batteries are covering is one",
+      peakguard.misses_aim(proj(1000.0, 450.0, 0.0), batt_w=6000.0,
+                           target_w=AIM_CAP))
+check("no battery reading, or no seconds left: not a miss (decide() files "
+      "nothing there)",
+      not peakguard.misses_aim(proj(9000.0, 450.0, 9000.0), batt_w=None,
+                               target_w=AIM_CAP)
+      and not peakguard.misses_aim(proj(9000.0, 900.0, 9000.0), batt_w=0.0,
+                                   target_w=AIM_CAP))
+
+
+# ============================================================================ #
+print("\n4. the page and the 'Why' on a decision within the aim")
+_c = NIGHTS["aim 3450, cycle 0.01 s before the edge"][0]["c"]
+_dec = peakguard.PeakDecision(
+    engaged=True, floor_w=5000.0, ceiling_w=3500.0,
+    ceiling_from=peakguard.CEILING_CAP, projected_w=3451.0, excess_w=9e4,
+    wanted_w=9e4, target_w=AIM_CAP, saturated=True, soc=30.0, soc_floor=20.0)
+
+
+def page(d):
+    """(the peak row is red, the "Why" says peak) for decision `d`."""
+    _c.peak_guard, _c._peak_floor_limited = d, False
+    row = first((r for r in _c.checks(datetime.now(timezone.utc))
+                 if r["id"] == "peak_guard"), "peak row")
+    if not present(row):
+        return {"red": None}, None
+    return dict(row, red=row["ok"] is False and not row.get("warn")), \
+        homeview.peak_engaged(_c)
+
+
+_r1, _w1 = page(_dec)
+_r2, _w2 = page(dataclasses.replace(_dec, within_aim=True))
+check("a saturated decision: red 'Load too high' row and the 'Why' peak, "
+      "as before", _r1["red"] and _w1)
+check("...within the aim: neither", _r2["red"] is False and _w2 is False)
+_lim = dataclasses.replace(_dec, floor_w=0.0, saturated=False,
+                         floor_limited=True, soc=10.0,
+                         soc_floor_reason=peakguard.FLOOR_AT_SOC_FLOOR)
+_r3, _w3 = page(_lim)
+_r4, _w4 = page(dataclasses.replace(_lim, within_aim=True))
+check("floor-limited at 0 W: the red reserve row with its banner, as "
+      "before", _r3["red"] and "banner" in _r3 and not _w3)
+check("...within the aim: no red row",
+      _r4["red"] is False and _w4 is False)
+
+
+# ============================================================================ #
+print()
+if fails:
+    print(f"{len(fails)} SAFETY-126 check(s) FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all SAFETY-126 checks passed")

goodwe_controller/test_safety84.py

@@ -476,13 +476,18 @@ print("\n8. the N=1 and N=2 digests")
 # loop's bound just after the guard hands back are gone; every command and
 # claim is the same (test_safety119.py part 6). SAFETY-121 re-pinned all six
 # again: only OUTPUT_CLAMP rows (test_safety119.py part 6).
+# SAFETY-125 (0.19.2, owner 2026-10-29) re-pinned n1_charge and
+# n1_charge_banked: at N=1 the cheap-window charge is now sized to the
+# quarter's room, as at N=2, so the guard no longer steps in and discharges.
+# The banked quarters go 3461.9 -> 3450.0 W (aim 3450) and 3938.9 -> 3950.0
+# W (aim 3950). n1_charge_dear (no cheap window) is unchanged.
 PINNED = {
     "n1_charge":
-        "0ed25c856456b97acb07a39299a8cb7b1a762c4d0005b88a0823c03057a80be5",
+        "00f0a16b3ac1bd2830e9e0aaac8923fd9d1736c2bc6c543669bdd35b2fb542e9",
     "n1_charge_dear":
         "c25340b56060d4581f7204e200b07e7c8618711be2baca3b1667b7ebeb600dc3",
     "n1_charge_banked":
-        "2619acdd06b04e56c000b168d64e1d044346c6ba3f929c94258d6ad8189ec609",
+        "09a08298d35195380ff427cdd2448d9212119be4692db26b2b1a45957fdf3300",
     "n2_charge":
         "b16d692128f14bcce3d87b142d290e0d6b13724289680e44a05215c9eaa24a7c",
     "n2_charge_dear":
@@ -496,8 +501,9 @@ for k in PINNED:
           f"{_now[k][:16]}")
 check("⭐ at N=1 a charge in and out of a cheap window and under a banked "
       "month peak is byte-identical to 9d5b7d1 (commands, reasons and every "
-      "claim; the log as re-pinned by SAFETY-121), and N=2 outside a cheap "
-      "window matches its SAFETY-85 pin",
+      "claim; the log as re-pinned by SAFETY-121; in a cheap window as "
+      "SAFETY-125 re-pinned it), and N=2 outside a cheap window matches its "
+      "SAFETY-85 pin",
       all(_now[k] == PINNED[k] for k in ("n1_charge", "n1_charge_dear",
                                          "n1_charge_banked",
                                          "n2_charge_dear")))

goodwe_controller/test_safety87.py

@@ -522,7 +522,9 @@ print("\n9. N=1 is byte-identical to release/1.0 b8ddfd7")
 # log. The loop's bound just after a hand-back is not counted, so OUTPUT_CLAMP
 # rows are gone or count fewer; every command and claim is the same
 # (test_safety119.py part 6). SAFETY-121 re-pinned the same three again:
-# only OUTPUT_CLAMP rows (test_safety119.py part 6).
+# only OUTPUT_CLAMP rows (test_safety119.py part 6). SAFETY-125 (0.19.2)
+# re-pinned n1_charge_low: the N=1 cheap-window charge is sized to the
+# quarter's room, so the banked quarter goes 3458.9 -> 3450.0 W (aim 3450).
 PINNED = {   # tools/safety87_identity.py on b8ddfd7
     "n1_under":
         "d2395ef8d74fb23607ad864d5a4bf62c03044bbd9367e873675d7ad10e8c169f",
@@ -533,7 +535,7 @@ PINNED = {   # tools/safety87_identity.py on b8ddfd7
     "n1_under_banked":
         "a2876c7cc873bc4c974d2b4bd98e23bba2d007b84545587d2fe0b713b0a6249b",
     "n1_charge_low":
-        "91336e3c0314985a3b00f314c79b5ffb5a740d218de3ad44f88a4db6e4235b32",
+        "c3af6218cc14c072e08b09550b153502dafec806009a92ba9032738b9ac9fa61",
     "n1_hold":
         "0a1df347754c69166b20d04c15ee878bbcefb02abb824b9b452334f68f03e46d",
 }
@@ -542,8 +544,8 @@ for k in PINNED:
     print(f"    {k} {'same' if _now[k] == PINNED[k] else 'DIFFERS'}")
 check("⭐ every N=1 digest (claims, commands, the guard's decision and the "
       "log) equals b8ddfd7's (the log as re-pinned by SAFETY-121), under, "
-      "crossing and above the reserve, in a charge and a HOLD, and under a "
-      "banked peak",
+      "crossing and above the reserve, in a charge (as SAFETY-125 re-pinned "
+      "it) and a HOLD, and under a banked peak",
       _now == PINNED)
 
 # ============================================================================ #

goodwe_controller/test_tariff24.py

@@ -0,0 +1,374 @@
+"""Runnable check for TARIFF-24.  `python3 test_tariff24.py`
+
+Battery modes on, a day/night `static_profile`, no price feed and the site trade
+switch off used to start no tariff task: `Controller.tariff_plan` stayed None,
+`mode_runs` stayed None, Leftover solar and Cheap hours never charged from the
+grid, and the Batteries screen said "No prices" while Home priced the day from
+the profile itself. DECISIONS/TARIFF-24-modes-need-the-tariff-task.md.
+
+1. The startup gate: `tariff_refresh_wanted()` by configuration, and the guard
+   `amain()` really puts on the task (read from its source, not retyped).
+2. End to end, on the real Controller and the real `run_tariff_refresh()` task,
+   started only if `amain()`'s own guard says so: night period, one battery
+   Leftover solar and one Cheap hours.
+3. The same with a gap below the cycle cost.
+4. Home and the Batteries screen agree.
+5. UX-55: with every battery Solar first Home no longer says "no prices have
+   arrived" on a static profile, and still does with no profile and no feed.
+6. Nothing else moved: modes off starts no task; the gate rows in part 1 keep
+   the arbitrage and feed cases as before.
+
+Mutations (MUTATION.md, purged copies, graded over this file): the gate
+reverted to `provider or arbitrage` fails 18 checks in parts 1 to 5; `True`
+fails the modes-off rows; `bool(opts.get(...))` fails the exact-true row;
+dropping the arbitrage term fails the arbitrage rows.
+"""
+
+import ast
+import asyncio
+import logging
+import os
+import sys
+import tempfile
+import time
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11p3_replay as rp                                    # noqa: E402
+from named_absence import first, nth, present                  # noqa: E402
+import app.main as m                                           # noqa: E402
+from app import homeview, modetrade, packmode                  # noqa: E402
+from app import price as _price, static_tariff as _st          # noqa: E402
+from app.main import Controller, tariff_refresh_wanted         # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+A, B = "inverter-a", "inverter-b"
+
+# A Belgian-style day/night tariff, example values: dear 07:00-22:00, cheap
+# 22:00-07:00, every day. The gap is 0.08 EUR/kWh.
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.22},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.30}]}')
+# A Friday in winter time (+01:00), 23:00 local: inside the night period.
+L = timezone(timedelta(hours=1))
+NIGHT = datetime(2026, 10, 30, 23, 0, tzinfo=L).astimezone(timezone.utc)
+
+
+def opts(*, modes=True, arb=False, profile=PROFILE, provider=None,
+         cost=0.05):
+    o = dict(rp.options(modes, arb, 2))
+    o["cycle_cost_threshold_eur"] = cost
+    if profile is not None:
+        o["static_profile"] = profile
+    if provider is not None:
+        o["price_provider"] = provider
+    return o
+
+
+# --------------------------------------------------------------------------- #
+# The guard amain() puts on the tariff task, read from amain()'s source.
+# --------------------------------------------------------------------------- #
+def _guards_of(node, guards=()):
+    """[(guards, coroutine name)] for every create_task(...) under `node`."""
+    out = []
+    for child in ast.iter_child_nodes(node):
+        if isinstance(child, ast.If):
+            test = ast.unparse(child.test)
+            for stmt in child.body:
+                out += _guards_of(stmt, guards + (test,))
+            for stmt in child.orelse:
+                out += _guards_of(stmt, guards + (f"not ({test})",))
+            continue
+        if isinstance(child, ast.Call) and \
+                ast.unparse(child.func).endswith("create_task") and child.args:
+            arg = child.args[0]
+            name = (arg.func.attr if isinstance(arg, ast.Call)
+                    and isinstance(arg.func, ast.Attribute)
+                    else ast.unparse(arg))
+            out.append((guards, name))
+            continue
+        out += _guards_of(child, guards)
+    return out
+
+
+_TREE = ast.parse(open(os.path.join(HERE, "app", "main.py"),
+                       encoding="utf-8").read())
+_AMAIN = first((n for n in ast.walk(_TREE)
+                if isinstance(n, ast.AsyncFunctionDef) and n.name == "amain"),
+               "amain() in main.py")
+_TASK_GUARDS = [g for g, n in _guards_of(_AMAIN) if n == "run_tariff_refresh"]
+
+
+def task_started(o) -> bool:
+    """Would amain() start the tariff refresh task for options `o`?"""
+    if len(_TASK_GUARDS) != 1:
+        return False
+    return all(bool(eval(g, vars(m), {"opts": o})) for g in _TASK_GUARDS[0])
+
+
+# --------------------------------------------------------------------------- #
+print("1. the startup gate")
+check("amain() starts the tariff refresh from exactly one guard, and that "
+      "guard can be decided from the options alone",
+      len(_TASK_GUARDS) == 1 and len(_TASK_GUARDS[0]) >= 1
+      and all(isinstance(eval(g, vars(m), {"opts": opts()}), bool)
+              for g in _TASK_GUARDS[0]))
+GATE = [
+    # label, options, task wanted
+    ("modes on + static day/night only", opts(), True),
+    ("modes on + a fixed price only",
+     opts(profile='{"periods": [{"name": "all", "days": "all", "from": '
+                  '"00:00", "to": "24:00", "eur_per_kwh": 0.27}]}'), True),
+    ("modes on, nothing else", opts(profile=None), True),
+    ("modes off + arbitrage off + no feed (static profile)",
+     opts(modes=False), False),
+    ("modes off + arbitrage off + no feed, no profile",
+     opts(modes=False, profile=None), False),
+    ("modes off + arbitrage on", opts(modes=False, arb=True), True),
+    ("modes off + a feed", opts(modes=False, provider="generic_dayahead"),
+     True),
+    ("modes on + a feed", opts(provider="generic_dayahead"), True),
+    ("modes on + arbitrage on", opts(arb=True), True),
+]
+for label, o, want in GATE:
+    got = tariff_refresh_wanted(o)
+    print(f"    wanted={got!s:5}  started={task_started(o)!s:5}  {label}")
+    check(f"{label}: tariff_refresh_wanted() is {want}", got is want)
+    check(f"{label}: amain() starts the task exactly as that says",
+          task_started(o) is want)
+check("battery_modes_enabled has to be exactly true (packmode.enabled()): "
+      "'true' as text or 1 does not start the task",
+      not tariff_refresh_wanted(dict(opts(), battery_modes_enabled="true"))
+      and not tariff_refresh_wanted(dict(opts(), battery_modes_enabled=1)))
+
+
+# --------------------------------------------------------------------------- #
+# The real Controller over a few minutes of a night: the task starts only if
+# amain()'s own guard says so; then read_inputs() + cycle() as the control
+# loop runs them.
+# --------------------------------------------------------------------------- #
+CHOICE = {"a": (True, "leftover_solar", False),
+          "b": (True, "cheap_hours", False)}
+
+
+FETCHES = []
+
+
+async def _no_fetch(*a, **k):
+    FETCHES.append(a)
+    raise AssertionError("the tariff task reached for a price feed")
+
+
+def drive(o, *, start=NIGHT, minutes=20, soc0=None, choice=CHOICE,
+          house_w=300.0, tick=5.0):
+    """-> (controller, rows, task_was_started)."""
+    store = rp._Store()
+    for u, (use, mode, sell) in choice.items():
+        store.data[unit_key(f"inverter-{u}", "pack_use")] = use
+        store.data[unit_key(f"inverter-{u}", "pack_mode")] = mode
+        store.data[unit_key(f"inverter-{u}", "pack_sell")] = sell
+    rows = []
+
+    async def go():
+        hass = rp.Hass(("a", "b"), lambda t: house_w,
+                       soc0 or {"a": 40.0, "b": 40.0})
+        tmp = tempfile.mkdtemp(prefix="t24-")
+        c = Controller(dict(o), hass, store, rp._Pub(),
+                       stop=asyncio.Event(),
+                       peak_db_path=os.path.join(tmp, "tariff.db"),
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        real_dt, real_hv = m.datetime, homeview.datetime
+        clock = [start]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+
+        m.datetime = homeview.datetime = _DT
+        _real_load = _price.load_prices, _st.load_prices
+        _price.load_prices = _st.load_prices = _no_fetch
+        started = task_started(o)
+        task = (asyncio.create_task(c.run_tariff_refresh())
+                if started else None)
+        try:
+            t = 0.0
+            while t < minutes * 60:
+                now = start + timedelta(seconds=t)
+                hass.t = t
+                clock[0] = now
+                if t == 0.0 and started:
+                    for _ in range(500):     # let the task do its first pass
+                        if c.tariff_plan is not None:
+                            break
+                        await asyncio.sleep(0)
+                imp, exp = split_signed(hass.grid())
+                c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                                        ingest_ts=now,
+                                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(tick, 10.0)
+                rows.append(dict(
+                    now=now, runs=c.mode_runs, tick=c.mode_tick,
+                    plan=c.fresh_tariff_plan(now),
+                    action=getattr(c.arb, "action", None),
+                    p={u: p.p for u, p in hass.plants.items()},
+                    soc={u: p.soc for u, p in hass.plants.items()}))
+                t += tick
+            # What the two screens say at the end, while the clock is still
+            # the simulated one.
+            c.home_plan = homeview.build_plan(c, clock[0], False, True)
+            c.battery_cards = homeview.battery_rows(c, False, True)
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+            m.datetime, homeview.datetime = real_dt, real_hv
+            _price.load_prices, _st.load_prices = _real_load
+        return c, started
+
+    c, started = asyncio.run(go())
+    return c, rows, started
+
+
+def charging_b(rows):
+    """Cycles in which the Cheap hours battery was charging (grid: no sun and
+    a 300 W house in this scenario)."""
+    return [r for r in rows if r["p"]["b"] < -200.0]
+
+
+def why_of(c, name):
+    card = first((b for b in c.battery_cards if b["name"] == name),
+                 f"a card for {name}")
+    return card["why_key"]
+
+
+# --------------------------------------------------------------------------- #
+print("\n2. end to end, night, modes on, static day/night, no feed, no arbitrage")
+c1, r1, started1 = drive(opts())
+_last = nth(r1, -1, "the last cycle")
+_first1 = nth(r1, 0, "the first cycle")
+print(f"    tariff task started by amain's guard: {started1}")
+print(f"    tariff_plan: {None if c1.tariff_plan is None else c1.tariff_plan.words}")
+print(f"    mode_runs: {_last['runs']}")
+print(f"    mode_tick reason / roles: "
+      f"{None if _last['tick'] is None else (_last['tick'].why, dict(_last['tick'].roles))}")
+print(f"    Batteries screen why_key: A {why_of(c1, A)}, B {why_of(c1, B)}")
+print(f"    cycles with B charging: {len(charging_b(r1))} of {len(r1)}, "
+      f"B soc {_first1['soc']['b']:.1f} -> {_last['soc']['b']:.1f}")
+check("the tariff refresh task is started", started1)
+check("...and it adds no network call: with price_provider off the feed "
+      "loader is never reached (it is replaced by one that fails)",
+      not FETCHES and not _price.provider_configured(opts()))
+check("a fresh tariff plan with prices is held", present(_last)
+      and _last["plan"] is not None and _last["plan"].has_prices)
+check("the price runs exist (mode_runs is not None) and carry a cheap run "
+      "that holds in the night period",
+      present(_last) and _last["runs"] is not None and _last["runs"].on
+      and _last["runs"].cheap is not None
+      and _last["runs"].cheap.holds(_last["now"]))
+check("the Cheap hours battery charges from the grid in the night period",
+      len(charging_b(r1)) > len(r1) // 2
+      and present(_last, _first1)
+      and _last["soc"]["b"] > _first1["soc"]["b"] + 0.3)
+check("...and the Leftover solar battery does not (no sun, no forecast)",
+      not any(r["p"]["a"] < -200.0 for r in r1))
+check("...the reason is not 'no prices': neither battery reads no_prices",
+      why_of(c1, A) != "no_prices" and why_of(c1, B) != "no_prices")
+check("...only the Cheap hours battery got the grid charge role",
+      present(_last) and _last["tick"] is not None
+      and _last["tick"].roles.get(B) == modetrade.CHARGE
+      and _last["tick"].roles.get(A) != modetrade.CHARGE)
+
+# --------------------------------------------------------------------------- #
+print("\n3. the same with a gap below the cycle cost")
+c3, r3, started3 = drive(opts(cost=0.20))
+_l3 = nth(r3, -1, "the last cycle")
+print(f"    started {started3}; mode_runs {_l3['runs']}; "
+      f"why A {why_of(c3, A)}, B {why_of(c3, B)}")
+check("the task is started and the plan is there, so mode_runs is not None",
+      started3 and present(_l3) and _l3["plan"] is not None
+      and _l3["runs"] is not None)
+check("the reason is the gap: no_spread ('Prices differ too little'), "
+      "never no_prices, on both batteries",
+      why_of(c3, A) == "no_spread" and why_of(c3, B) == "no_spread"
+      and present(_l3) and _l3["runs"] is not None
+      and not _l3["runs"].on)
+check("...and no battery charges from the grid",
+      not charging_b(r3) and not any(r["p"]["a"] < -200.0 for r in r3))
+
+# --------------------------------------------------------------------------- #
+print("\n4. Home and the Batteries screen agree")
+hp = c1.home_plan
+_bars = [b for b in hp["prices"] if b["eur_kwh"] is not None]
+_words = {b["why_key"]: b["why"] for b in c1.battery_cards}
+print(f"    Home: has_prices {hp['has_prices']}, {len(_bars)} priced bars, "
+      f"verdict {hp['verdict_key']}, lines {hp['lines']}")
+print(f"    Batteries: {[(b['name'], b['why_key'], b['why']) for b in c1.battery_cards]}")
+check("Home prices the day, and the Batteries screen does not say it has no "
+      "prices", hp["has_prices"] and _bars
+      and all(b["why_key"] != "no_prices" for b in c1.battery_cards))
+check("Home's plan has the grid charge block for the Cheap hours battery "
+      "(the 'trade' verdict) and no 'no prices have arrived' line",
+      hp["verdict_key"] == "trade"
+      and any(r["kind"] == "grid" for r in hp["runs"])
+      and not any("no prices have arrived" in ln for ln in hp["lines"]))
+hp3 = c3.home_plan
+check("with the gap too small both say so: Home 'price gap is too small', "
+      "the batteries 'differ too little'; neither says no prices",
+      any("price gap is too small" in ln for ln in hp3["lines"])
+      and all(b["why_key"] == "no_spread" for b in c3.battery_cards))
+
+# --------------------------------------------------------------------------- #
+print("\n5. UX-55: every battery Solar first, static day/night, no feed")
+SF = {"a": (True, "solar_first", False), "b": (True, "solar_first", False)}
+c5, r5, s5 = drive(opts(), choice=SF, minutes=5)
+print(f"    Home lines: {c5.home_plan['lines']}")
+check("Home no longer says 'no prices have arrived' with every battery Solar "
+      "first on a static profile",
+      s5 and not any("no prices have arrived" in ln
+                     for ln in c5.home_plan["lines"]))
+c5b, r5b, s5b = drive(opts(profile=None), choice=SF, minutes=5)
+print(f"    no profile, no feed: started {s5b}, Home lines "
+      f"{c5b.home_plan['lines']}")
+check("...and with no profile and no feed there are truly no prices, and "
+      "Home still says so",
+      any("no prices have arrived" in ln for ln in c5b.home_plan["lines"]))
+
+# --------------------------------------------------------------------------- #
+print("\n6. nothing else moved")
+c6, r6, s6 = drive(opts(modes=False), choice={}, minutes=5)
+check("modes off, arbitrage off, no feed: no task, no plan, no price runs "
+      "(as before)", not s6 and c6.tariff_plan is None
+      and all(r["runs"] is None for r in r6))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_tariff24_weather.py

@@ -0,0 +1,518 @@
+"""Runnable check for TARIFF-24 round 2 (AUDIT-02 F1).  `python3 test_tariff24_weather.py`
+
+With battery modes on, the price gap a mode needs was always widened x1.5
+(`Uncertainty.NO_WEATHER`) even with a solar forecast read. Now the doubt is
+added only when no usable forecast is read (`arbitrage.weather_uncertainty()`),
+in the run plan (`_price_runs()`), the charge gate (`_mode_roles()`) and Home's
+mirror (`homeview.trade_verdict()`). Modes off is untouched.
+DECISIONS/TARIFF-24-modes-need-the-tariff-task.md.
+
+1. The rule itself, and that modes off keeps the doubt.
+2. Day/night 0.34/0.26 (gap 0.08), modes on, real Controller, night period:
+   with a forecast at cycle cost 0.07 the cheap run is planned and the Cheap
+   hours battery charges; without one, or with a stale one, the same cost needs
+   0.105 and the reason is `not_worth` / "Prices differ too little".
+3. A dynamic day with a 0.12 gap at cost 0.10: on with a forecast, not worth
+   without.
+4. The forecast coming (the gate follows in the same cycle) and going mid-run:
+   a run under way keeps its gap to its end, the next run needs the wider one;
+   a forecast unavailable for one or two reads mid-run does not stop or
+   restart the charge.
+5. Home agrees with control in each case (Batteries Why, Home line, and
+   `trade_verdict()`, Home's mirror of the gate).
+6. The hold's edges (TARIFF-24 review R4, R5): a forecast lost while only the
+   day's give run is under way holds to that run's end and no further, so the
+   night's cheap run needs the wider gap; and a give run that starts during a
+   hold runs to its end (`keep_started()`), with no grid charge after the hold.
+
+Mutations (MUTATION.md, purged copies, graded over this file): the doubt always
+added (the old code) fails parts 2 to 5; never added fails the without-forecast
+rows; Home's mirror left on the old rule fails part 5; `_wx_track()` also
+recording without a forecast (its `solar_fc is None` return dropped) fails part 6.
+"""
+
+import asyncio
+import logging
+import math
+import os
+import sys
+import tempfile
+import time
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+sys.path.insert(0, os.path.join(HERE, "tools"))
+logging.disable(logging.WARNING)
+
+import opt11p3_replay as rp                                    # noqa: E402
+from named_absence import first, nth, present                  # noqa: E402
+import app.main as m                                           # noqa: E402
+from app import arbitrage, homeview, modetrade, solarfc        # noqa: E402
+from app.main import Controller                                # noqa: E402
+from app.p1 import make_sample, split_signed                   # noqa: E402
+from app.price import (PricePoint, PriceProduct, PriceRead,    # noqa: E402
+                       Uncertainty, brussels)
+from app.static_tariff import TariffPlan                       # noqa: E402
+from app.store import unit_key                                 # noqa: E402
+
+fails = []
+
+
+class _NoHold(solarfc.Hold):
+    """OPT-27: a hold that never stands in for a lost sensor."""
+
+    def stand_in(self, *a, **k):
+        return None
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+A, B = "inverter-a", "inverter-b"
+PROFILE = ('{"periods": ['
+           '{"name": "night", "days": "all", "from": "22:00", "to": "07:00",'
+           ' "eur_per_kwh": 0.26},'
+           '{"name": "day", "days": "all", "from": "07:00", "to": "22:00",'
+           ' "eur_per_kwh": 0.34}]}')
+L = timezone(timedelta(hours=1))
+NIGHT = datetime(2026, 10, 30, 23, 0, tzinfo=L).astimezone(timezone.utc)
+CHOICE = {"a": (True, "leftover_solar", False),
+          "b": (True, "cheap_hours", False)}
+FC_TODAY, FC_TOMORROW = "sensor.fc_today", "sensor.fc_tomorrow"
+TARIFF_REFRESH_S = m.TARIFF_REFRESH_S
+
+
+def opts(cost, *, arb=False, sensors=True):
+    o = dict(rp.options(True, arb, 2))
+    o.update(cycle_cost_threshold_eur=cost, static_profile=PROFILE)
+    if sensors:
+        o.update(pv_forecast_entity=FC_TODAY,
+                 pv_forecast_tomorrow_entity=FC_TOMORROW)
+    return o
+
+
+def dynamic_points(start):
+    """A dynamic day-ahead shape, 0.16 .. 0.28 (gap 0.12), 15-minute points."""
+    out, t = [], start.replace(minute=0, second=0, microsecond=0)
+    for _ in range(48 * 4):
+        h = brussels(t).hour + brussels(t).minute / 60
+        p = 0.22 + 0.06 * math.cos((h - 19) / 24 * 2 * math.pi)
+        out.append(PricePoint(start=brussels(t), eur_per_kwh=round(p, 4),
+                              provisional=False))
+        t += timedelta(minutes=15)
+    return out
+
+
+def sensor(kwh, at):
+    return {"state": f"{kwh}", "attributes": {"unit_of_measurement": "kWh"},
+            "last_updated": at.isoformat(), "last_reported": at.isoformat()}
+
+
+def forecast_mode(mode, t, now):
+    """What the two forecast sensors read: 'fresh', 'stale', 'gone', or a
+    function of the simulated seconds that returns one of those."""
+    if callable(mode):
+        mode = mode(t)
+    if mode == "gone":
+        return {"state": "unavailable", "attributes": {}}
+    at = now if mode == "fresh" else now - timedelta(hours=5)
+    return at
+
+
+def take(c, now):
+    """What Home and the Batteries screen say now, and Home's mirror of the
+    gate (it reads the trade switch, so ask it as a site that has it on next
+    to the modes)."""
+    keep = c.o
+    c.o = dict(keep, arbitrage_enabled=True)
+    try:
+        mirror, why = homeview.trade_verdict(c, c.fresh_tariff_plan(now), now)
+    finally:
+        c.o = keep
+    return dict(home=homeview.build_plan(c, now, False, True),
+                cards=homeview.battery_rows(c, False, True),
+                mirror=mirror, mirror_why=why)
+
+
+def drive(o, *, fc="fresh", points=None, minutes=20, tick=5.0,
+          house_w=300.0, soc0=None, snap_at=(), t0=NIGHT):
+    """-> (controller, rows). `points`: a feed-shaped plan injected every
+    cycle (no task); else the static profile via the real tariff task. `t0`:
+    the first cycle's instant."""
+    store = rp._Store()
+    for u, (use, mode, sell) in CHOICE.items():
+        for k, val in (("pack_use", use), ("pack_mode", mode),
+                       ("pack_sell", sell)):
+            store.data[unit_key(f"inverter-{u}", k)] = val
+    rows = []
+    snaps = {}
+
+    class H(rp.Hass):
+        async def state(self, e):
+            now = t0 + timedelta(seconds=self.t)
+            if fc is None:
+                return None
+            at = forecast_mode(fc, self.t, now)
+            if isinstance(at, dict):
+                return at
+            return sensor(0.0 if e == FC_TODAY else 12.0, at)
+
+    async def go():
+        hass = H(("a", "b"), lambda t: house_w, soc0 or {"a": 40.0, "b": 40.0})
+        tmp = tempfile.mkdtemp(prefix="t24w-")
+        c = Controller(dict(o), hass, store, rp._Pub(), stop=asyncio.Event(),
+                       peak_db_path=os.path.join(tmp, "tariff.db"),
+                       price_history_path=os.path.join(tmp, "ph.json"))
+        for i in c.inverters:
+            i.dev_min, i.dev_max = -5000.0, 5000.0
+        c.auto = True
+        # OPT-27: a sensor that is missing is covered for up to 3 h by its last
+        # fresh reading. This file is about what the plan does when the
+        # forecast IS lost, so it runs with a hold that never covers
+        # (test_opt27.py tests the cover).
+        c.fc_hold = _NoHold()
+        real_dt, real_hv = m.datetime, homeview.datetime
+        clock = [t0]
+
+        class _DT(real_dt):
+            @classmethod
+            def now(cls, tz=None):
+                return clock[0] if tz is None else clock[0].astimezone(tz)
+
+        m.datetime = homeview.datetime = _DT
+        pts = None if points is None else points
+        task = None
+        if pts is None:
+            task = asyncio.create_task(c.run_tariff_refresh())
+        try:
+            t = 0.0
+            while t < minutes * 60:
+                now = t0 + timedelta(seconds=t)
+                hass.t = t
+                clock[0] = now
+                if pts is not None:
+                    c.tariff_plan = TariffPlan(
+                        PriceRead.series(pts, PriceProduct.DAY_AHEAD,
+                                         "generic_dayahead", now), None,
+                        "provider")
+                    c.tariff_at = now
+                elif t == 0.0 or t % TARIFF_REFRESH_S == 0.0:
+                    # The task's own 30 min wait is wall clock, so the
+                    # simulated clock restarts it: one refresh per period.
+                    if task is not None and t > 0.0:
+                        task.cancel()
+                        try:
+                            await task
+                        except asyncio.CancelledError:
+                            pass
+                        task = asyncio.create_task(c.run_tariff_refresh())
+                    for _ in range(500):
+                        if c.tariff_plan is not None and (
+                                c.tariff_at is not None and c.tariff_at >= now):
+                            break
+                        await asyncio.sleep(0)
+                imp, exp = split_signed(hass.grid())
+                c.p1.submit(make_sample("ha_signed", imp, exp, phases=1,
+                                        ingest_ts=now,
+                                        ingest_mono=time.monotonic()))
+                await c.read_inputs(now_mono=t)
+                await c.cycle()
+                hass.advance(tick, 10.0)
+                rp_ = c.mode_runs
+                rows.append(dict(
+                    t=t, now=now, fc_none=c.solar_fc is None,
+                    runs_on=None if rp_ is None else rp_.on,
+                    reason=None if rp_ is None else rp_.reason,
+                    roles=dict(c.mode_tick.roles) if c.mode_tick else {},
+                    free_to=c._wx_free_to, held=c.weather_held(now),
+                    why=None if c.mode_tick is None else c.mode_tick.why,
+                    charging=hass.plants["b"].p < -200.0,
+                    soc_b=hass.plants["b"].soc,
+                    cheap_end=None if rp_ is None or rp_.cheap is None
+                    else rp_.cheap.end))
+                if t in snap_at:
+                    snaps[t] = take(c, now)
+                t += tick
+            last = take(c, clock[0])
+            c.home_plan, c.cards = last["home"], last["cards"]
+            c.mirror, c.mirror_why = last["mirror"], last["mirror_why"]
+            c.snaps = snaps
+        finally:
+            if task is not None:
+                task.cancel()
+                try:
+                    await task
+                except asyncio.CancelledError:
+                    pass
+            m.datetime, homeview.datetime = real_dt, real_hv
+        return c
+
+    return asyncio.run(go()), rows
+
+
+def why_of(c, name):
+    card = first((b for b in c.cards if b["name"] == name), f"card {name}")
+    return card["why_key"]
+
+
+# --------------------------------------------------------------------------- #
+print("1. the rule")
+NW = frozenset({Uncertainty.NO_WEATHER})
+check("modes on with a forecast read: no doubt", arbitrage.weather_uncertainty(
+    True, object()) == frozenset())
+check("modes on with no forecast (None): the doubt", arbitrage.weather_uncertainty(
+    True, None) == NW)
+check("modes off, forecast or not: the doubt, as before",
+      arbitrage.weather_uncertainty(False, object()) == NW
+      and arbitrage.weather_uncertainty(False, None) == NW)
+
+# --------------------------------------------------------------------------- #
+print("\n2. day/night 0.34 / 0.26 (gap 0.08), night period")
+c1, r1 = drive(opts(0.07), fc="fresh")
+l1 = nth(r1, -1, "last cycle")
+print(f"    forecast read, cost 0.07: mode_runs on={l1['runs_on']} "
+      f"reason={l1['reason']}; B charging {sum(r['charging'] for r in r1)} of "
+      f"{len(r1)}; Why A {why_of(c1, A)} B {why_of(c1, B)}")
+check("with a forecast at cost 0.07 the cheap run is planned (needed 0.07 < "
+      "0.08) and the Cheap hours battery charges in the night period",
+      present(l1) and not l1["fc_none"] and l1["runs_on"] is True
+      and sum(r["charging"] for r in r1) > len(r1) // 2
+      and l1["roles"].get(B) == modetrade.CHARGE)
+for label, mode in (("no forecast sensor reads", "gone"),
+                    ("a stale forecast", "stale")):
+    c, rr = drive(opts(0.07), fc=mode)
+    ll = nth(rr, -1, "last cycle")
+    print(f"    {label}, cost 0.07: on={ll['runs_on']} reason={ll['reason']}; "
+          f"B charging {sum(r['charging'] for r in rr)}; Why A "
+          f"{why_of(c, A)} B {why_of(c, B)}")
+    check(f"{label}: the same cost needs 0.105 > 0.08, so not_worth and "
+          f"'Prices differ too little', no grid charge",
+          present(ll) and ll["fc_none"] and ll["runs_on"] is False
+          and ll["reason"] == "not_worth"
+          and why_of(c, A) == "no_spread" and why_of(c, B) == "no_spread"
+          and not any(r["charging"] for r in rr))
+c0, r0 = drive(opts(0.07, sensors=False), fc=None)
+check("no forecast sensor configured at all: not_worth too (as 0.19.0)",
+      present(nth(r0, -1)) and r0[-1]["runs_on"] is False)
+c2, r2 = drive(opts(0.10), fc="fresh")
+check("at the shipped cost 0.10 even a forecast does not make 0.08 enough "
+      "(needs 0.10): still not_worth, honestly",
+      present(nth(r2, -1)) and r2[-1]["runs_on"] is False
+      and r2[-1]["reason"] == "not_worth")
+
+# --------------------------------------------------------------------------- #
+print("\n3. a dynamic day, gap 0.12, cost 0.10")
+pts = dynamic_points(NIGHT - timedelta(hours=1))
+cd, rd = drive(opts(0.10), fc="fresh", points=pts)
+cn, rn = drive(opts(0.10), fc="gone", points=pts)
+_ld, _ln = nth(rd, -1, "last cycle"), nth(rn, -1, "last cycle")
+print(f"    with forecast: on={_ld['runs_on']} reason={_ld['reason']}; "
+      f"without: on={_ln['runs_on']} reason={_ln['reason']}")
+check("with a forecast the run plan is on (needs 0.10 < 0.12)",
+      present(nth(rd, -1)) and rd[-1]["runs_on"] is True
+      and why_of(cd, A) != "no_spread")
+check("without one it is not_worth (needs 0.15 > 0.12) and says so",
+      present(nth(rn, -1)) and rn[-1]["runs_on"] is False
+      and rn[-1]["reason"] == "not_worth"
+      and why_of(cn, B) == "no_spread")
+
+# --------------------------------------------------------------------------- #
+print("\n4. the forecast going and coming mid-run (a run under way keeps its gap)")
+CUT = 600.0                      # 10 min in
+SOC = {"a": 40.0, "b": 60.0}     # B's cheap run is then about 2 h
+
+
+def going(t):
+    return "fresh" if t < CUT else "gone"
+
+
+def coming(t):
+    return "gone" if t < CUT else "fresh"
+
+
+def flap(n_reads):
+    """Unavailable for `n_reads` forecast reads (60 s apart) from CUT."""
+    return lambda t: "gone" if CUT <= t < CUT + 60.0 * n_reads else "fresh"
+
+
+MID, AFTER = 3000.0, 7800.0
+cg, rg = drive(opts(0.07), fc=going, minutes=135, soc0=SOC,
+               snap_at=(MID, AFTER))
+cc, rc = drive(opts(0.07), fc=coming, minutes=25)
+_end = nth([r["cheap_end"] for r in rg if r["cheap_end"] is not None], 0,
+           "the cheap run's end")
+_end_t = (_end - NIGHT).total_seconds() if present(_end) else 1e9
+lost = [r for r in rg if r["fc_none"]]
+print(f"    going: cheap run ends at t={_end_t:.0f} s; forecast lost from "
+      f"t={lost[0]['t'] if lost else None}")
+check("going: the run planned with the forecast ends before the snapshot "
+      "taken after it (the scenario is long enough)",
+      present(_end) and CUT + 300.0 < _end_t < AFTER - 300.0 and bool(lost)
+      and lost[0]["t"] - CUT <= 60.0)
+check("going: the forecast read is lost mid-run and the run under way KEEPS "
+      "its gap: the plan stays on and B keeps charging, cycle after cycle, "
+      "until B is full or the run ends",
+      all(r["runs_on"] is True and (r["roles"].get(B) == modetrade.CHARGE
+                                    or r["soc_b"] >= 94.0)
+          for r in rg if r["fc_none"] and r["t"] < _end_t - 60.0)
+      and all(r["charging"] or r["soc_b"] >= 94.0 for r in rg
+              if 60.0 <= r["t"] < _end_t - 60.0)
+      and max(r["soc_b"] for r in rg if r["fc_none"]) >= 90.0)
+check("going: from the run's end the wider gap is back: the next run is "
+      "not_worth (needs 0.105 at 0.07), no new run, and no grid charge",
+      all(r["runs_on"] is False and r["reason"] == "not_worth"
+          for r in rg if r["t"] >= _end_t + 30.0)
+      and not any(r["charging"] for r in rg if r["t"] >= _end_t + 60.0))
+_sm, _sa = cg.snaps.get(MID), cg.snaps.get(AFTER)
+check("going, Home agrees mid-run: its mirror still allows, the Batteries "
+      "screen says it charges from the grid, and Home does not say the gap "
+      "is too small",
+      _sm is not None and _sm["mirror"] is not None
+      and first((b for b in _sm["cards"] if b["name"] == B),
+                "a card")["why_key"] == "grid_charge"
+      and not any("price gap is too small" in ln
+                  for ln in _sm["home"]["lines"]))
+check("going, Home agrees after the run: its mirror refuses, the Batteries "
+      "screen says 'differ too little' and Home says the gap is too small",
+      _sa is not None and _sa["mirror"] is None
+      and first((b for b in _sa["cards"] if b["name"] == B),
+                "a card")["why_key"] == "no_spread"
+      and any("price gap is too small" in ln for ln in _sa["home"]["lines"]))
+for n in (1, 2):
+    cf, rf = drive(opts(0.07), fc=flap(n), minutes=30, soc0=SOC,
+                   snap_at=(CUT + 30.0,))
+    gone = [r for r in rf if r["fc_none"]]
+    print(f"    flap, {n} read(s) lost: {len(gone)} cycles without a "
+          f"forecast; B charging in {sum(r['charging'] for r in rf)} of "
+          f"{len(rf)}")
+    check(f"flap: the forecast is unavailable for {n} read(s) mid-run: the "
+          f"plan stays on and B charges without a break (no stop, no "
+          f"restart)",
+          bool(gone) and all(r["runs_on"] is True for r in rf)
+          and all(r["charging"] and r["roles"].get(B) == modetrade.CHARGE
+                  for r in rf if r["t"] >= 60.0))
+    sf = cf.snaps.get(CUT + 30.0)
+    check(f"flap, {n} read(s): Home agrees while the read is lost (mirror "
+          f"allows, Batteries 'charges from the grid')",
+          sf is not None and sf["mirror"] is not None
+          and first((b for b in sf["cards"] if b["name"] == B),
+                    "a card")["why_key"] == "grid_charge")
+
+
+def flips(rows):
+    """Cycles where the forecast read changed, and whether the plan and the
+    charge gate changed in that very cycle."""
+    out = []
+    for i in range(1, len(rows)):
+        if rows[i]["fc_none"] != rows[i - 1]["fc_none"]:
+            out.append((i, rows[i]["t"], rows[i]["runs_on"],
+                        rows[i]["charging"], rows[i - 1]["charging"]))
+    return out
+
+
+fcm = flips(rc)
+print(f"    coming: forecast read arrives at cycle/t {fcm}")
+check("coming (no run under way before): not_worth until the read is back, "
+      "then on in the same cycle, and the battery charges",
+      len(fcm) == 1 and fcm[0][1] - CUT <= 60.0 and fcm[0][2] is True
+      and all(r["runs_on"] is False for r in rc if r["fc_none"])
+      and all(r["runs_on"] is True for r in rc if not r["fc_none"])
+      and any(r["charging"] for r in rc if r["t"] >= fcm[0][1] + 40.0))
+
+# --------------------------------------------------------------------------- #
+print("\n5. Home agrees with control")
+CASES = (("forecast, cost 0.07", c1, r1, True),
+         ("no forecast, cost 0.07", *drive(opts(0.07), fc="gone"), False),
+         ("dynamic, forecast", cd, rd, True),
+         ("dynamic, no forecast", cn, rn, False))
+for label, cx, rx, on in CASES:
+    last = nth(rx, -1, "last cycle")
+    hp = cx.home_plan
+    mirror_ok = cx.mirror is not None
+    print(f"    {label}: control on={last['runs_on']}; Home mirror "
+          f"{'allows' if mirror_ok else 'refuses'} ({cx.mirror_why}); "
+          f"lines {hp['lines'][:1]}; Why B {why_of(cx, B)}")
+    check(f"{label}: Home's mirror of the gate allows exactly when control "
+          f"plans", present(last) and mirror_ok is on
+          and last["runs_on"] is on)
+    check(f"{label}: the Batteries screen and the Home line say the gap is "
+          f"too small exactly when control does",
+          (why_of(cx, B) == "no_spread") is (not on)
+          and any("price gap is too small" in ln for ln in hp["lines"])
+          is (not on))
+    if label.startswith("dynamic"):
+        continue    # its cheap run is tomorrow morning: not on today's chart
+    check(f"{label}: Home draws a grid charge block exactly when control "
+          f"charges", any(r["kind"] == "grid" for r in hp["runs"]) is on)
+
+# --------------------------------------------------------------------------- #
+print("\n6. the hold's edges (review probes R4, R5)")
+T_R4 = datetime(2026, 10, 30, 21, 40, tzinfo=L).astimezone(timezone.utc)
+TEN = datetime(2026, 10, 30, 22, 0, tzinfo=L).astimezone(timezone.utc)
+c4, r4 = drive(opts(0.07), fc=lambda t: "fresh" if t < 300.0 else "gone",
+               minutes=60, t0=T_R4)
+_held4 = [r for r in r4 if r["held"]]
+_l4 = nth(r4, -1, "last cycle")
+print(f"    R4: forecast lost 21:45; held {len(_held4)} cycles, to "
+      f"{_l4['free_to']}; after 22:00 on={ {r['runs_on'] for r in r4 if r['now'] >= TEN} } "
+      f"charging {sum(r['charging'] for r in r4)}")
+check("R4, forecast lost before the next run: while only the day's give run "
+      "was under way the hold is that run's end, 22:00, and stays there",
+      present(_l4) and all(r["free_to"] == TEN for r in r4
+                                   if r["t"] >= 5.0)
+      and bool(_held4) and all(r["now"] < TEN for r in _held4))
+check("R4: from 22:00 the night's cheap run needs the wider gap: "
+      "not_worth, and no grid charge at any time",
+      all(r["runs_on"] is False and r["reason"] == "not_worth"
+          for r in r4 if r["now"] >= TEN)
+      and not any(r["charging"] for r in r4))
+
+
+def r5_points(t0):
+    """04:00-07:00 at 0.20, 07:00-10:00 at 0.30, else 0.25 (local)."""
+    out, t = [], t0.replace(minute=0, second=0, microsecond=0) - timedelta(hours=1)
+    for _ in range(4 * 30):
+        h = brussels(t).hour
+        p = 0.20 if 4 <= h < 7 else 0.30 if 7 <= h < 10 else 0.25
+        out.append(PricePoint(start=brussels(t), eur_per_kwh=p,
+                              provisional=False))
+        t += timedelta(minutes=15)
+    return out
+
+
+T_R5 = datetime(2026, 10, 30, 5, 0, tzinfo=L).astimezone(timezone.utc)
+GIVE_END = datetime(2026, 10, 30, 10, 0, tzinfo=L).astimezone(timezone.utc)
+c5, r5 = drive(opts(0.07), fc=lambda t: "fresh" if t < 3600.0 else "gone",
+               points=r5_points(T_R5), minutes=320, t0=T_R5,
+               soc0={"a": 40.0, "b": 30.0})
+_ft5 = nth([r["free_to"] for r in r5 if r["t"] == 3600.0], 0, "the hold")
+_in = [r for r in r5 if present(_ft5) and _ft5 <= r["now"] < GIVE_END]
+_out = [r for r in r5 if r["now"] >= GIVE_END + timedelta(seconds=30)]
+print(f"    R5: forecast lost 06:00, hold to {_ft5}; after it, until 10:00, "
+      f"on in {sum(r['runs_on'] is True for r in _in)} of {len(_in)}, B "
+      f"{sorted({str(r['roles'].get(B)) for r in _in})}; after 10:00 "
+      f"{ {r['reason'] for r in _out} }")
+check("R5: the hold is the cheap run's end, before the give run's end",
+      present(_ft5) and T_R5 < _ft5 < GIVE_END)
+check("R5, a run that has started runs to its end: the give run that began "
+      "during the hold stays on after it, B gives, and nothing charges from "
+      "the grid",
+      len(_in) > 100 and all(r["runs_on"] is True
+                             and r["roles"].get(B) == modetrade.GIVE
+                             and not r["charging"] for r in _in))
+check("R5: when the give run ends the wider gap decides: not_worth, no grid "
+      "charge",
+      bool(_out) and all(r["runs_on"] is False and r["reason"] == "not_worth"
+                         and not r["charging"] for r in _out))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_ux54.py

@@ -1456,6 +1456,35 @@ hi_ = tab(c_t, at(10, 7))["days"][0]["batteries"][0]["levels"]
 check("on a controller the curve is built with the plan's trust "
       "(`solar_trust_pct`)", hi_ and max(v for _h, v in hi_) > hi_[0][1])
 
+# TARIFF-24 (sync 0.19): the tab extends tomorrow's cheap run as control
+# re-plans it, so it asks control's gap: the cycle cost with a forecast read,
+# not 1.5 x it.
+from app.price import required_spread, uncertainty_of               # noqa: E402
+gaps, _plan_real = [], dayview.priceruns.plan
+
+
+def _spy(*a, **k):
+    gaps.append(k.get("required_eur_kwh"))
+    return _plan_real(*a, **k)
+
+
+c_g = S.make("dynamic", at(17, 0))
+dayview.priceruns.plan = _spy
+try:
+    tab(c_g, at(17, 0))
+finally:
+    dayview.priceruns.plan = _plan_real
+_p = c_g.fresh_tariff_plan(at(17, 0))
+want = required_spread(arbitrage.threshold_eur_kwh(c_g.o),
+                       uncertainty_of(_p.read.product)
+                       | arbitrage.weather_uncertainty(True, c_g.solar_fc))
+print(f"    dynamic 17:00: the tab's extension asks {gaps}, control needs {want}")
+check("the tab extends tomorrow's cheap run with control's gap (with a "
+      "forecast: the cycle cost, not 1.5 x it)",
+      c_g.solar_fc is not None and bool(gaps)
+      and all(abs(g - want) < 1e-9 for g in gaps)
+      and abs(want - arbitrage.threshold_eur_kwh(c_g.o)) < 1e-9)
+
 print()
 if fails:
     print(f"{len(fails)} FAILED")

goodwe_controller/tools/maint20_same_code.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""MAINT-20: prove a comment/docstring cut changed no code, and show the ratio.
+
+    python3 goodwe_controller/tools/maint20_same_code.py [BASE_REF] [FILE ...]
+
+For each FILE (default: every goodwe_controller/app/*.py that differs from
+BASE_REF, default release/1.0) the ast.dump() of the tree with docstrings
+removed must be identical at BASE_REF and in the working tree. Also prints
+code lines vs comment-only + docstring lines (whole lines, via tokenize) before
+and after. Run from the repository root. Exit 1 on any code difference.
+"""
+import ast
+import io
+import subprocess
+import sys
+import tokenize
+
+SCOPES = (ast.Module, ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)
+
+
+def docstring(n):
+    if isinstance(n, SCOPES) and n.body:
+        e = n.body[0]
+        if (isinstance(e, ast.Expr) and isinstance(e.value, ast.Constant)
+                and isinstance(e.value.value, str)):
+            return e
+    return None
+
+
+def dump(src):
+    tree = ast.parse(src)
+    for n in ast.walk(tree):
+        if docstring(n) is not None:
+            n.body = n.body[1:] or [ast.Pass()]
+    return ast.dump(tree)
+
+
+def counts(src):
+    doc = set()
+    for n in ast.walk(ast.parse(src)):
+        e = docstring(n)
+        if e is not None:
+            doc.update(range(e.lineno, e.end_lineno + 1))
+    skip = (tokenize.NL, tokenize.NEWLINE, tokenize.INDENT, tokenize.DEDENT,
+            tokenize.ENDMARKER, tokenize.COMMENT)
+    code, com = set(), set()
+    for tk in tokenize.generate_tokens(io.StringIO(src).readline):
+        if tk.type == tokenize.COMMENT:
+            com.add(tk.start[0])
+        elif tk.type not in skip:
+            code.update(range(tk.start[0], tk.end[0] + 1))
+    code -= doc
+    return len(code), len(doc) + len(com - code - doc)
+
+
+def git(*a):
+    return subprocess.run(["git", *a], check=True, capture_output=True,
+                          text=True).stdout
+
+
+def main(argv):
+    base = argv[0] if argv else "release/1.0"
+    files = argv[1:] or [
+        f for f in git("diff", "--name-only", base, "--",
+                       "goodwe_controller/app").split()
+        if f.endswith(".py")]
+    bad = 0
+    print(f"base {base} = {git('rev-parse', base).strip()}")
+    for f in files:
+        old = git("show", f"{base}:{f}")
+        new = open(f, encoding="utf-8").read()
+        same = dump(old) == dump(new)
+        (c0, m0), (c1, m1) = counts(old), counts(new)
+        print(f"{'SAME CODE' if same else 'CODE DIFFERS'}  {f}  "
+              f"code {c0}->{c1}  comment+doc {m0}->{m1}  "
+              f"ratio {m0 / c0:.2f}->{m1 / c1:.2f}")
+        bad += not same
+    print("OK: no code change" if not bad else f"FAIL: {bad} file(s) differ")
+    return 1 if bad else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

goodwe_controller/tools/ux54_scenarios.py

@@ -247,6 +247,12 @@ def make(name, now, *, soc=(55.0, 40.0), modes=("solar_first",
         tomorrow = False
     if name == "sunny":
         sun_today, sun_tomorrow = 40.0, 40.0
+    if name not in ("nofc", "off", "stale") and \
+            opts.get("battery_modes_enabled"):
+        # TARIFF-24: with a forecast the gap needed is the cycle cost, not
+        # 1.5 x it. These scenarios were written for the old gate (0.15 at
+        # the shipped 0.10), so they keep it: the cost is 0.15.
+        opts["cycle_cost_threshold_eur"] = 0.15
     c = Controller(opts, Hass(), Store(), Pub(), stop=asyncio.Event())
     c.auto = True
     for i, inv in enumerate(c.inverters):