SMA-2: each inverter is reached through a driver; GoodWe behaviour unchanged

app/drivers.py holds one Driver per roster entry (configured, actuator_id,
limits, read, write, release, probe, link_stale_s, batt_bound, settle_s, brand,
words). GoodWeEsphomeDriver makes the calls the code it replaced made, in the
same order. Inverter gets driver; has_writer, is_live and link_note read it. The
SoC/power read, the write, the device range (run_control, amain, the settings
panel), rule 2 per unit and the SAFETY-28 census go through it.

setpoint_entity is optional per entry beside driver, host, port, unit_id and
maintenance; only goodwe_esphome is selectable, the rest are checked and unused.

Co-Authored-By: Claude <noreply@anthropic.com>

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+### Not in a release yet
+
+- Each inverter is now reached through a driver, so another make can be added later. Nothing changes for a GoodWe site, and the inverter list accepts five new optional settings that nothing reads yet ([[SMA-2]]).
+- Home now draws today's charge from the grid for every hour the add-on will really charge, not only the run under way ([[UX-77]]).
+- When Home Assistant passes readings on late, control no longer swings on them: it waits until the battery shows its last power request, and the peak limit no longer asks for full power on them. The page says so, and if the readings stay too late every inverter goes to 0 W ([[SAFETY-128]]).
+- With a 5 s meter, readings 30 s late are now noticed within 100 seconds, not 3 minutes ([[SAFETY-129]]).
+- If one of the tomorrow solar forecast sensors stops updating in the afternoon, tomorrow's forecast now stays on the Forecast tab instead of vanishing until 20:00 ([[OPT-38]]).
+
 ## 0.20.1
 
 **A patch bump: Leftover solar no longer buys from the grid what other batteries will already cover. No option changes.**

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

@@ -44,3 +44,5 @@ tonight." (`home_words.solar.kept`, EN and NL). The event log says
 **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.
+
+**OPT-38 (2026-11-07).** A kept TOMORROW reading (at most `KEPT_MAX_AGE_S` old, same `day0`) now stands in at any hour, not only from `BELL_TO_H`: one sensor that stopped at 14:54 had dropped the whole sum (OPT-17) from 17:54 to 20:00. Today readings and the OPT-34 morning rules are unchanged; `test_opt38.py`.

goodwe_controller/DECISIONS/SAFETY-128-late-readings.md

@@ -0,0 +1,92 @@
+# SAFETY-128 - a reading that does not answer the last command is not current
+
+**Status: FIXED on release/1.0 (after 0.20.0).** Code: `app/lateness.py`,
+`control.compute(hold=, hold_w=)`, `peakguard.cap_floor()`,
+`Controller._readings_late()`, `Controller.read_inputs()` (feeds the fits).
+Tests: `test_safety128.py` (`tools/safety128_rig.py`, TEST-23's plant).
+
+**Cause** (SAFETY-127 report). Home Assistant can deliver readings late but
+still changing. Every gate judges arrival (SAFETY-01) or a value that stops
+changing (SAFETY-18, SAFETY-37), so a late reading passes them all. The loop
+then corrects, each cycle, an error its last command has already fixed: a
+loop with a dead time far longer than its cycle, which swings and grows. The
+peak guard projects the quarter from the same late figures and pushes to the
+inverter limit in its last seconds (OPT-34 rig F-2).
+
+**Rule.**
+1. *Find late readings* (`Answer.watch()`, every 2 s, from the 1 s reads).
+   - **Batteries** (`Delay`): fit one `d` so that each battery's reading minus
+     its own request at `t - d` (averaged over 2 s for the battery's lag and
+     the read) is flattest. The house does not move that reading, so a
+     repeating load cannot line up with it (review round 1, B1). Needs 5 new
+     readings in 60 s and the request and the reading each to move 300 W.
+     Late from 9.5 s, after 2 late fits in a row. A late fit must explain 75 %
+     and beat every fit up to 6.5 s by 2x; the shortest delay that fits about
+     as well (within 2x, or within 2 500 W^2) is taken instead, since a swing's
+     period fits again. A slow battery (3-10 s lag) answering at once gives no
+     late fit; at a 15-20 s lag some fits read late (see "What it costs").
+     No late battery fit counts for 60 s
+     after a battery gave nothing under its ask: an emptied battery lined its
+     old movement up as 85 s late.
+   - **Meter** (`MeterFit`, round 1's fit): `meter(t) + request(t - d)` is the
+     house alone at the right `d`. Quick, but confounded by the house. Needs
+     16 new values in 60 s, so only a meter of about 3.5 s or faster: at 5 s
+     it gave false delays. Late over 8 s. At a slower meter (a 5 s P1) the
+     same fit runs over 120 s and calls only a delay over 16 s late, on 2 fits
+     in a row, and never ends a verdict (SAFETY-129). Alone it reads 35-90 s on healthy
+     runs, a few times in a row; only the slow-start and battery-fit check
+     below keeps those from a verdict. 10 s late is not found: it cannot be
+     told from a 10 s slow battery, and it does not swing at 5 s.
+   - A meter fit says late only with evidence from the batteries' side too:
+     a request more than 100 W from the battery reading took 3 s or more to
+     move a reading towards it (`SLOW_START_S`; on time they start within
+     0-1 s in the recorded house at 1 and 2 s ticks), and no battery fit in
+     the last 60 s said on time (under 9.5 s). An ask during which a battery
+     gave nothing under its ask is no slow evidence. A repeating load fools
+     the meter fit but not these. No meter verdict in the first 150 s.
+   - On time again on a battery fit under 6.5 s, or a meter fit within 8 s
+     unless a battery fit said late (hysteresis). With no fit for 120 s the
+     verdict is dropped.
+2. *Hold.* While late, a request more than 100 W from the battery reading is
+   pending until that reading comes within 100 W of it, or half way. Meanwhile
+   the loop may not lead the reading by more than 100 W that way, and the peak
+   guard's floor is capped at the request that stands. The loop is not held
+   while a battery gives nothing under its ask or refuses (SAFETY-52/94).
+3. *Late verdict.* Pending for `LATE_S` (23 s) with no reading moving 100 W
+   towards it: control holds, then after `stale_input_s` goes to 0 W
+   ("readings late"), as for a missing input.
+4. *Seen.* While late an amber row says "Home Assistant readings show requests
+   about N seconds late, so control holds the batteries." (NL too). N is the
+   batteries' fitted delay: Home Assistant's lag plus the battery's own
+   answer. While only the meter has shown it the row gives no figure. One
+   WARNING (`READINGS_LATE`) per episode and one line when it ends.
+
+**With readings on time** no verdict was reached in any reviewer scenario
+(owner-shaped house, ovens 20/40 to 60/60 s, clouds, a 300 W/s battery, 6-8 s
+dead times, HA jitter 0-4 s, an EV following the meter, capped batteries, HA
+restarts, meter pauses; 1, 2 and 5 s meters) nor in 2 days of the recorded
+house at 1, 2 and 5 s ticks, so the commands are the same as without the gate.
+The fits run all the time; the pull request has the counts.
+
+**What it costs.**
+- Found 36-68 s after a lag starts at 1-2 s meters; at a 5 s meter 30 s late
+  is found within 100 s after it starts (88 s measured) (the loop first moves 100 W after 60 s,
+  SAFETY-129) with the export above -200 W, and 10 s late is not found. Until
+  then control is as before. In a quiet house the "readings late" row stays
+  about 2 minutes longer after the lag ends (126 s against 32 s on base); no
+  harm measured, and it clears as early as on base when the load changes.
+- A battery that answers slowly is read as late readings and held: a dead
+  time of 10 s or more (8 s reads 7-8; 10 s reads 10 at 1-2 s meters, 9 at
+  5 s), or a 15-20 s lag (review round 2). The GoodWe measured settles in 6 s
+  (`freshness.PLANT_SETTLE_S`); the row then blames Home Assistant wrongly.
+- The row can stay up to 180 s after the readings are on time on a steady
+  site. While only the meter has shown the delay it gives no figure.
+- A battery that cannot follow while the readings are late (at a limit, not
+  reading 0 W) is held, then set to 0 W after 38 s.
+- The fits cost a few ms every 2 s (x86, measured after 3 idle days); the
+  history they read is bounded (60 s of readings, 150 s of requests).
+
+**Left out.** The setpoint -> Home Assistant round trip: the fitted delay gives
+the figure from readings the add-on already has. The hold's step-and-pull-back
+at extreme lag and the arbitrage charge's sizing on late readings
+(`charge_room_w()`) are follow-up cards.

goodwe_controller/DECISIONS/SMA-2-driver-seam.md

@@ -0,0 +1,39 @@
+# SMA-2 - each inverter is reached through a driver
+
+**Status: for review.** Tests: `test_sma2_driver.py`. Source: SMA-9 report
+section 1.1. A pure refactor: no behaviour change for GoodWe, no change to a
+command, a log line or a sentence the add-on shows.
+
+Every place that read or steered an inverter used the GoodWe ESPHome entities
+directly, so a second make meant touching all of them. `app/drivers.py` now
+holds one `Driver` per roster entry (`Inverter.driver`): `configured()`,
+`actuator_id()`, `limits()`, `read()`, `write()`, `release()`, `probe()`, and
+`link_stale_s`, `batt_bound`, `settle_s`, `brand`, `words`. `GoodWeEsphomeDriver`
+makes the same calls in the same order as the code it replaced; its
+`release()` is `write(0)`.
+
+**Moved to the driver:** the SoC and power read (`_read_unit`), the write
+(`_write_unit`, still under the SAFETY-28 gate, the clamp, shadow mode and the
+write budget), the device range (`run_control`, `amain`, the settings panel),
+liveness and its window (`has_writer`, `is_live`, `link_note`), the freshness
+bound, the status rows' "is a source set" test, rule 2's per-unit range check
+and SAFETY-28's census. **Not moved:** the clamp, the gate, the heartbeat and
+`command_site_zero()`; stop is still 0 W for every unit, and nothing calls
+`release()` yet (SMA-10). `settle_s` and the control constants are not read
+from the driver yet either: with only GoodWe they would change nothing.
+
+**The seam is not TCP-shaped.** The census asks each entry's driver for its
+actuator id: the setpoint entity for GoodWe, `host:port:unit_id` for a driver
+reached over a socket, so two units behind one gateway are two actuators and
+one unit named twice is the SAFETY-28 refusal. The driver binds its Home
+Assistant on first use by the Controller, so a unit added later is wired too.
+
+**Schema.** `setpoint_entity` is optional per entry (rule 9(d) still requires
+it for GoodWe, with the same sentence), beside `driver` (only `goodwe_esphome`),
+`host`, `port`, `unit_id`, `maintenance`. The last four are checked for shape
+and not read. The Supervisor shape probe was re-run (section K).
+
+**Checked against 23ff9d0:** replay digests and a log of every Home Assistant
+call are byte-identical at N=1 and N=2; the TEL-07 announce diff is 0/0/0; a
+fake driver beside a GoodWe unit allocates, grades, drops and publishes per
+unit; a call site that goes round the seam is caught.

goodwe_controller/DECISIONS/UX-54-forecast-tab.md

@@ -97,9 +97,14 @@ is `SolarToday.add()` after the solar read, in a `try`, in memory.
 - Prices are planned about a day ahead (`priceruns.HORIZON`), so a block of
   tomorrow later than 24 h from now, or one that needs prices not yet
   published, appears as the day comes near. The tab says so.
-- Today's blocks are Home's, and are not extended or shortened: control may
-  plan more once they end, and Home draws it then. The curve stops charging
-  at its level (`charge_to()`) and giving at the floor.
+- Today's blocks are Home's. UX-77: Home draws today's grid block to where
+  control will stop charging, as the tab does for tomorrow's: the cheap run
+  rolls on at its end while a battery is short (`cheaproll.roll_end()`, the
+  same loop as `dayview._levels()`), the level read at the charge power the
+  peak limit leaves (peak aim less the house, else the rating) and shared by
+  room left to full as control shares it (`packshare.weights()`, re-read as
+  the levels move), and each battery's block ends at its own stop. The curve stops charging at its level
+  (`charge_to()`) and giving at the floor.
 - Today, a give run in the plan on a battery that is empty now has no block on
   Home (no energy to give). The tab equals Home, and says so: "The add-on plans
   to give power. No block shows while a battery has no energy to give." The

goodwe_controller/app/cheaproll.py

@@ -0,0 +1,201 @@
+"""UX-77: where the cheap run rolls on. Display only; control is unchanged.
+
+A cheap run is sized for the batteries charging together, at their full
+rating, and starts at the first of the cheapest hours. The peak limit leaves
+less power than that, so a battery is still short when the run ends, and
+control plans the next run then (`Controller._price_runs()`). On a flat night
+that goes on until the batteries are at their level or the cheap hours end.
+
+`roll_end()` asks what control asks at each run end, of the same functions
+(`modetrade.energy()`, `priceruns.plan()`), until nothing is short or the next
+run does not follow on. `for_today()` reads the batteries at the level they
+will have by then: the charge power is the peak limit's room (peak aim minus
+the house, as `dayplan` counts it), shared as control shares it: by room
+left to full (`packshare.weights()`), read again as the levels move, so a
+battery that fills drops out and its share goes to the others. Where that
+room is not known (no house profile or no aim), the rating is used.
+DECISIONS/UX-54-forecast-tab.md has the record.
+"""
+
+import dataclasses
+import math
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from . import arbitrage, dayplan, modetrade, packshare, priceruns
+from .dayplan import EFF
+from .price import required_spread, uncertainty_of
+
+SLOT_S = 900                    # a price slot
+STEP = timedelta(minutes=5)     # how finely the level is followed
+LIMIT = 24                      # rolls at most (a day of one-hour runs)
+
+
+def roll_end(run, points, packs_at, *, required, floor_pct, ceiling_pct,
+             targets=None, limit=LIMIT):
+    """Where the cheap run `run` ends once control has rolled it on.
+
+    `packs_at(end)` gives the `modetrade.Pack`s as they stand when a run
+    ends at `end`. At each end the charge still short is asked of
+    `modetrade.energy()` and the next run of `priceruns.plan()`, as control
+    asks them. It stops when nothing is short or the next run does not follow
+    on, and is `run.end` when control would not roll it."""
+    end_t = run.end
+    for _ in range(limit):
+        e = modetrade.energy(packs_at(end_t), floor_pct, ceiling_pct,
+                             targets=targets)
+        if e[0] <= 1e-6:
+            break
+        new = priceruns.plan(points, end_t, required_eur_kwh=required,
+                             charge_kwh=e[0], charge_kw=e[1], sell_kwh=0.0,
+                             sell_kw=0.0)
+        nxt = new.cheap
+        if nxt is None or not new.charge_useful() or nxt.start > end_t \
+                or nxt.end <= end_t:
+            break
+        end_t = nxt.end
+    return end_t
+
+
+@dataclass(frozen=True)
+class Roll:
+    """`end`: where control stops charging, `stops`: name -> when that battery
+    reaches its level (rounded up to a price slot), None while it still
+    charges at `end`. A battery not in `stops` does not charge in the run."""
+    end: datetime
+    stops: dict
+
+    def end_for(self, name, base_end):
+        """The end of `name`'s block: its stop, no later than `end`."""
+        if name not in self.stops:
+            return base_end
+        stop = self.stops[name]
+        return self.end if stop is None else min(self.end, stop)
+
+    def last(self, base_end):
+        """The last end of any battery's block (the chart's cheap bar)."""
+        return max([base_end] + [self.end_for(n, base_end)
+                                 for n in self.stops])
+
+
+def _ceil_slot(t):
+    return datetime.fromtimestamp(
+        math.ceil(t.timestamp() / SLOT_S) * SLOT_S, tz=t.tzinfo
+        or timezone.utc)
+
+
+class _Charge:
+    """The batteries' levels followed from `t0` while the chargers charge at
+    the room the peak limit leaves: `min(sum of ratings, aim - house)`, shared
+    by room left to full as control does (`_shares()`), each stopping at `modetrade.charge_to()`."""
+
+    def __init__(self, packs, t0, ceiling_pct, targets, aim_w, house):
+        self.packs = {p.name: p for p in packs}
+        self.t = t0
+        self.ceil = ceiling_pct
+        self.targets = targets
+        self.aim = aim_w
+        self.house = house
+        self.stops = {}
+
+    def at(self, end):
+        """The packs when a run ends at `end`."""
+        self._to(end)
+        return list(self.packs.values())
+
+    def _room_w(self, hour, total):
+        if self.aim is None or self.house is None:
+            return total
+        house_w, base_w = self.house
+        return min(total, max(0.0, float(self.aim)
+                              - max(house_w(hour), base_w, 0.0)))
+
+    def _to(self, end):
+        while self.t < end:
+            nxt = min(end, self.t + STEP)
+            for s, e, hour in dayplan._hour_slices(self.t, nxt):
+                self._charge(s, e, hour)
+            self.t = nxt
+
+    def _shares(self, ch, w):
+        """Watts per charger: `w` shared by `packshare.weights()` over all
+        packs (room left to full, as control passes it), no charger above its
+        rating, the surplus going to the others. By rating where the room left
+        is not known (no capacity)."""
+        wt = packshare.weights(list(self.packs.values()), -1.0)
+        if wt is None:
+            wt = {p.name: abs(p.rating_w) for p in ch}
+        wt = {p.name: wt.get(p.name, 0.0) for p in ch}
+        cap = {p.name: abs(p.rating_w) for p in ch}
+        out, open_, left = {}, set(wt), float(w)
+        while open_:
+            tot = sum(wt[n] for n in open_)
+            if tot <= 0.0:
+                for n in open_:
+                    out[n] = 0.0
+                break
+            over = [n for n in open_ if left * wt[n] / tot > cap[n] + 1e-9]
+            if not over:
+                for n in open_:
+                    out[n] = left * wt[n] / tot
+                break
+            for n in over:
+                out[n] = cap[n]
+                left -= cap[n]
+                open_.discard(n)
+        return out
+
+    def _charge(self, s, e, hour):
+        ch = modetrade.chargers(list(self.packs.values()), self.ceil,
+                                targets=self.targets)
+        total = sum(abs(p.rating_w) for p in ch)
+        if not ch or total <= 0.0:
+            return
+        w = self._room_w(hour, total)
+        hrs = (e - s).total_seconds() / 3600.0
+        share = self._shares(ch, w)
+        for p in ch:
+            self.stops.setdefault(p.name, None)
+            if not p.capacity_kwh:
+                continue
+            to = modetrade.charge_to(p, self.ceil, self.targets)
+            kwh = share[p.name] * hrs / 1000.0 * EFF
+            room = (to - p.soc) / 100.0 * float(p.capacity_kwh)
+            if kwh <= 0.0:
+                continue
+            if kwh >= room - 1e-9:
+                self.stops[p.name] = _ceil_slot(
+                    s + (e - s) * (room / kwh))
+                kwh = room
+            self.packs[p.name] = dataclasses.replace(
+                p, soc=p.soc + kwh / float(p.capacity_kwh) * 100.0)
+
+
+def for_today(c, rp, now):
+    """The `Roll` of the cheap run `rp.cheap` now under way or to come today,
+    or None when control does not roll it on (no run left, charging not
+    useful, the trade gate shut, nothing short at its end). Display only:
+    nothing here is fed back to control."""
+    if rp is None or not rp.on or rp.cheap is None or rp.cheap.end <= now \
+            or not rp.charge_useful() \
+            or getattr(c, "mode_gate", None) is not None:
+        return None
+    plan = c.fresh_tariff_plan(now)
+    if plan is None:
+        return None
+    floor, ceil = arbitrage.soc_bounds(c.o)
+    hp = getattr(c, "house_profile", None)
+    sim = _Charge(c._mode_packs(), max(now, rp.cheap.start), ceil,
+                  c.plan_targets(), c.peak_aim_w(),
+                  None if hp is None else hp.estimator())
+    required = required_spread(
+        arbitrage.threshold_eur_kwh(c.o),
+        uncertainty_of(plan.read.product)
+        | arbitrage.weather_uncertainty(True, c.solar_fc,
+                                        bool(c.weather_held(now))))
+    end = roll_end(rp.cheap, plan.read.points, sim.at, required=required,
+                   floor_pct=floor, ceiling_pct=ceil,
+                   targets=c.plan_targets())
+    if end <= rp.cheap.end:
+        return None
+    return Roll(end, dict(sim.stops))

goodwe_controller/app/control.py

@@ -298,6 +298,9 @@ PROBE_S = 34.0
 # command: every battery that may move this way is at its mode's limit.
 MODE_BOUND = "mode-bound"
 
+# SAFETY-128. The loop's reason while it waits for the readings to answer.
+WAITING = "waiting for readings"
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -486,6 +489,8 @@ def compute(
     bound: tuple | None = None,
     gave_nothing: bool | None = None,
     idle_w: float = 0.0,
+    hold: int = 0,
+    hold_w: float | None = None,
 ) -> Decision:
     """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).
 
@@ -506,6 +511,9 @@ def compute(
     `idle_w`   SAFETY-97: what `actual_w` reads while the batteries give
                nothing (app/idle.py). The refusal's band and its end are
                centred on it. 0 is the law as it was.
+    `hold`     SAFETY-128: +1 / -1, the batteries have not answered the last
+               command that way (app/lateness.py), so the loop may not go
+               past `hold_w` (None: `prev_w`) that way. 0 is the law as it was.
     """
     reason = "tracking"
     # OPT-11: a bound that leaves out 0 W would FORCE a direction, which no
@@ -622,6 +630,11 @@ def compute(
             i_w = min(moved, i_w)
         else:
             i_w = max(moved, i_w)
+    # SAFETY-128: no further than `hold_w` until the readings answer the ask.
+    held_at = float(prev_w if hold_w is None else hold_w)
+    if hold and hold * (i_w - held_at) > 0:
+        i_w = held_at
+        reason = WAITING
 
     # OPT-11: the integrator does not wind past what the modes let the
     # batteries place. Only a side tighter than the rail is left in `bound`

goodwe_controller/app/dayview.py

@@ -19,7 +19,8 @@ empty chart. DECISIONS/UX-54-forecast-tab.md has the record.
 import dataclasses
 from datetime import datetime, timedelta
 
-from . import arbitrage, dayplan, homeview as hv, modetrade, priceruns
+from . import arbitrage, cheaproll, dayplan, homeview as hv, modetrade
+from . import priceruns
 from . import solarfc
 from .daycurve import Batt, curve
 from .packmode import SOLAR_FIRST
@@ -210,25 +211,18 @@ def _levels(c, est, fc, trust, now, end, runs, floor, ceil, notes_b, shadow,
             arbitrage.threshold_eur_kwh(c.o),
             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(
+
+        def packs_at(end_t):
+            """The packs at the curve's level when a run ends at `end_t`."""
+            at = dataclasses.replace(rp, cheap=priceruns.Run(
                 cheap.start, end_t, cheap.mean_eur_kwh))
-            rt, lv = settle(ext, lv0)
-            at_end = [dataclasses.replace(packs[n], soc=v)
-                      for n, v in ((n, _level_at(lv.get(n, ()), end_t))
-                                   for n in lv) if v is not None]
-            e = modetrade.energy(at_end, floor, ceil, targets=targets)
-            if e[0] <= 1e-6:
-                break
-            new = priceruns.plan(
-                plan.read.points, end_t, required_eur_kwh=required,
-                charge_kwh=e[0], charge_kw=e[1], sell_kwh=0.0, sell_kw=0.0)
-            nxt = new.cheap
-            if nxt is None or not new.charge_useful() or nxt.start > end_t \
-                    or nxt.end <= end_t:
-                break
-            end_t = nxt.end
+            _rt, lv = settle(at, lv0)
+            return [dataclasses.replace(packs[n], soc=v)
+                    for n, v in ((n, _level_at(lv.get(n, ()), end_t))
+                                 for n in lv) if v is not None]
+        end_t = cheaproll.roll_end(
+            cheap, plan.read.points, packs_at, required=required,
+            floor_pct=floor, ceiling_pct=ceil, targets=targets)
         ext = dataclasses.replace(rp, cheap=priceruns.Run(
             cheap.start, end_t, cheap.mean_eur_kwh))
     rt, lv = settle(ext, lv0)

goodwe_controller/app/drivers.py

@@ -0,0 +1,299 @@
+"""The inverter driver seam (SMA-2): how this add-on reads and steers ONE inverter.
+
+Before this, every place that read or steered an inverter talked to the GoodWe
+ESPHome entities itself (`hass.limits`, `hass.number`, `hass.set_number`, the
+SAFETY-28 census, selfconfig, validate), so a second brand meant touching all of
+them. Now each `Inverter` holds a `Driver`, and those places ask it. This card
+is a pure refactor: `GoodWeEsphomeDriver` does exactly what the code it replaced
+did, in the same order, with the same arguments. DECISIONS/SMA-2-driver-seam.md.
+
+THE SEAM IS NOT TCP-SHAPED. Nothing here assumes a connection, or one connection
+per host: a later FoxESS unit is RTU framing over a TCP socket, and its
+`actuator_id()` is host:port:unit_id, so two units behind one gateway are two
+actuators and one unit named twice is the SAFETY-28 refusal.
+
+WHAT STAYS OUTSIDE THE DRIVER, on purpose. The gate (SAFETY-28), the clamp
+(SAFETY-03), shadow mode and the write budget all sit above `write()` in
+`Controller._write_unit`, and the freshness gate sits above `read()`; a driver
+never sees a value those did not pass. A driver moves one number to or from one
+inverter and says whether it worked.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .control import PLANT_SETTLE_S
+from .freshness import BOUNDS
+
+# How long every write to one GoodWe inverter must have been REJECTED before
+# this controller stops claiming it can command it. Layer 1's own window: the
+# ESP32 commands 0 W after ~30 s without a refresh (`validate.
+# FIRMWARE_INGEST_VETO_S`). `inverter.LINK_STALE_S` is this number, re-exported.
+GOODWE_LINK_STALE_S = 30.0
+
+# `driver` when an entry does not say: every install that exists today.
+DEFAULT_DRIVER = "goodwe_esphome"
+
+# The `driver` values the options accept. Only the GoodWe one for now; the
+# registry below may hold more (a test registers a fake), but this tuple is
+# what validate.py rule 9 lets through and what config.yaml's schema lists.
+SELECTABLE = (DEFAULT_DRIVER,)
+
+
+class DriverNotBound(RuntimeError):
+    """A driver was asked to talk to the world before it was given a Home
+    Assistant. A wiring bug, so it is loud rather than a quiet "no answer"."""
+
+
+@dataclass(frozen=True)
+class Probe:
+    """What a read-only look at one inverter found. None means "did not answer"."""
+
+    dev_min: float | None = None
+    dev_max: float | None = None
+    soc: float | None = None
+    batt_w: float | None = None
+    extra: dict = field(default_factory=dict)
+
+
+def census_key(actuator_id: str) -> str:
+    """The form SAFETY-28 compares: stripped and lowercase, so a config cannot
+    name one actuator twice by changing its case (`Number.X` vs `number.x`)."""
+    return str(actuator_id or "").strip().lower()
+
+
+class Driver:
+    """One inverter's I/O. Subclasses set the class attributes and the methods.
+
+    Constructed once per roster entry, with no Home Assistant: `bind()` gives
+    it one (the Controller does, and so does the settings panel, which has no
+    Controller). Everything that talks to the world is a coroutine.
+    """
+
+    #: the `driver` option value that selects this class
+    name = ""
+    #: the option key that names the actuator in an entry (the census reads it)
+    writer_key = ""
+    #: the brand word the per-driver sentences and device names use
+    brand = ""
+    #: per-driver sentences (SMA-10 and later). Empty until a caller needs one.
+    words: dict = {}
+    #: how long all-rejected writes last before the unit stops being live
+    link_stale_s = GOODWE_LINK_STALE_S
+    #: this driver's `freshness.Bound` for the battery power reading
+    batt_bound = BOUNDS["batt"]
+    #: the plant's settling time after a step, in s (control.PLANT_SETTLE_S)
+    settle_s = PLANT_SETTLE_S
+
+    # -- from the options ----------------------------------------------------
+    @classmethod
+    def from_entry(cls, entry: dict) -> "Driver":
+        raise NotImplementedError
+
+    @classmethod
+    def actuator_id_of(cls, entry: dict) -> str:
+        """The actuator an options entry names, or "" for none. Pure: the
+        SAFETY-28 census runs on options, before any driver exists."""
+        raise NotImplementedError
+
+    # -- wiring --------------------------------------------------------------
+    def bind(self, hass) -> "Driver":
+        """Give this driver its Home Assistant (or whatever it talks through)."""
+        return self
+
+    def bind_getter(self, getter) -> "Driver":
+        """Like `bind()`, but looked up at each use: the Controller passes
+        `lambda: self.hass`, so replacing `controller.hass` is seen at once."""
+        return self
+
+    def bound(self) -> bool:
+        """Has it been given what it talks through? A driver that talks
+        through nothing the Controller owns is always bound."""
+        return True
+
+    # -- what it is ----------------------------------------------------------
+    def configured(self) -> bool:
+        """Is there any way to reach this inverter at all?"""
+        raise NotImplementedError
+
+    def actuator_id(self) -> str:
+        """What this driver writes to. Two units with one id are one actuator."""
+        raise NotImplementedError
+
+    def soc_source(self) -> str:
+        """Where the pack level is read from; "" when nowhere. Status rows only."""
+        return ""
+
+    def batt_source(self) -> str:
+        """Where the battery power is read from; "" when nowhere."""
+        return ""
+
+    # -- what it does --------------------------------------------------------
+    async def limits(self) -> tuple:
+        """`(dev_min, dev_max)` in W the device accepts; (None, None) unread."""
+        raise NotImplementedError
+
+    async def read(self) -> tuple:
+        """`(soc, batt_w, extra)`. A value that did not arrive is None. `batt_w`
+        is the RAW power, in the sign the controller uses; the freshness gate
+        is the caller's."""
+        raise NotImplementedError
+
+    async def write(self, w: float) -> bool:
+        """Put `w` on the inverter. True only when it took it."""
+        raise NotImplementedError
+
+    async def release(self) -> bool:
+        """Stop steering this inverter. For a driver with nothing better, 0 W."""
+        return await self.write(0.0)
+
+    async def probe(self) -> Probe:
+        """A read-only look, usable without a Controller (panel, wizard)."""
+        raise NotImplementedError
+
+
+class GoodWeEsphomeDriver(Driver):
+    """The GoodWe behind the ESP32: three Home Assistant entities.
+
+    A transcription of what `main.py` and `selfconfig.py` did inline: `limits()`
+    is `hass.limits(setpoint)`, `read()` is `hass.number(soc)` then
+    `hass.number(batt, invert)`, `write()` is `hass.set_number(setpoint, w)`.
+    `release()` is `write(0)`: the board's own watchdog is what hands back.
+    """
+
+    name = DEFAULT_DRIVER
+    writer_key = "setpoint_entity"
+    brand = "GoodWe"
+
+    def __init__(self, setpoint_entity="", soc_entity="", batt_entity="",
+                 batt_invert=False):
+        self.setpoint_entity = str(setpoint_entity or "")
+        self.soc_entity = str(soc_entity or "")
+        self.batt_entity = str(batt_entity or "")
+        self.batt_invert = bool(batt_invert)
+        self._hass = None
+        self._getter = None
+
+    @classmethod
+    def from_entry(cls, entry: dict) -> "GoodWeEsphomeDriver":
+        return cls(setpoint_entity=entry.get("setpoint_entity", ""),
+                   soc_entity=entry.get("soc_entity", ""),
+                   batt_entity=entry.get("batt_entity", ""),
+                   batt_invert=bool(entry.get("batt_invert")))
+
+    @classmethod
+    def actuator_id_of(cls, entry: dict) -> str:
+        return str(entry.get("setpoint_entity") or "").strip()
+
+    def bind(self, hass) -> "GoodWeEsphomeDriver":
+        self._hass, self._getter = hass, None
+        return self
+
+    def bind_getter(self, getter) -> "GoodWeEsphomeDriver":
+        self._hass, self._getter = None, getter
+        return self
+
+    def bound(self) -> bool:
+        return self._hass is not None or self._getter is not None
+
+    def _h(self):
+        hass = self._getter() if self._getter is not None else self._hass
+        if hass is None:
+            raise DriverNotBound(f"{self.brand} driver for "
+                                 f"{self.setpoint_entity!r} has no Home Assistant")
+        return hass
+
+    def configured(self) -> bool:
+        return bool(self.setpoint_entity)
+
+    def actuator_id(self) -> str:
+        return self.setpoint_entity
+
+    def soc_source(self) -> str:
+        return self.soc_entity
+
+    def batt_source(self) -> str:
+        return self.batt_entity
+
+    async def limits(self) -> tuple:
+        dev_min, dev_max, _step = await self._h().limits(self.setpoint_entity)
+        return dev_min, dev_max
+
+    async def read(self) -> tuple:
+        hass = self._h()
+        soc = await hass.number(self.soc_entity)
+        raw = await hass.number(self.batt_entity, self.batt_invert)
+        return soc, raw, {}
+
+    async def write(self, w: float) -> bool:
+        return await self._h().set_number(self.setpoint_entity, w)
+
+    async def probe(self) -> Probe:
+        dev_min, dev_max = await self.limits()
+        soc, raw, extra = await self.read()
+        return Probe(dev_min, dev_max, soc, raw, extra)
+
+
+class UnavailableDriver(Driver):
+    """What an entry naming a driver this build does not have gets. Validation
+    refuses such an entry before a Controller exists; this is only what
+    `build_roster()` (which refuses nothing) builds meanwhile: a unit that is
+    not configured, so the refusal branch names it and commands 0 W."""
+
+    name = ""
+    # The census still counts a `setpoint_entity` on such an entry: refusing
+    # too much is the safe direction for SAFETY-28.
+    writer_key = "setpoint_entity"
+    brand = ""
+
+    def __init__(self, wanted=""):
+        self.wanted = str(wanted or "")
+
+    @classmethod
+    def from_entry(cls, entry: dict) -> "UnavailableDriver":
+        return cls(entry.get("driver"))
+
+    @classmethod
+    def actuator_id_of(cls, entry: dict) -> str:
+        return str(entry.get("setpoint_entity") or "").strip()
+
+    def configured(self) -> bool:
+        return False
+
+    def actuator_id(self) -> str:
+        return ""
+
+    async def limits(self) -> tuple:
+        return None, None
+
+    async def read(self) -> tuple:
+        return None, None, {}
+
+    async def write(self, w: float) -> bool:
+        return False
+
+    async def probe(self) -> Probe:
+        return Probe()
+
+
+# name -> class. The options' `driver` value picks one. A test may add a fake;
+# `SELECTABLE` (not this) is what the options accept.
+REGISTRY = {GoodWeEsphomeDriver.name: GoodWeEsphomeDriver}
+
+
+def driver_name(entry) -> str:
+    """The `driver` an options entry selects; blank or absent is the default."""
+    raw = entry.get("driver") if isinstance(entry, dict) else None
+    return str(raw).strip() if raw not in (None, "") else DEFAULT_DRIVER
+
+
+def driver_class(entry):
+    """The class an options entry selects, `UnavailableDriver` if none."""
+    return REGISTRY.get(driver_name(entry), UnavailableDriver)
+
+
+def build_driver(entry) -> Driver:
+    """The driver for ONE options entry (or the flat options, for one inverter)."""
+    entry = entry if isinstance(entry, dict) else {}
+    return driver_class(entry).from_entry(entry)

goodwe_controller/app/homeview.py

@@ -19,7 +19,7 @@ section at the bottom and is held to STYLE.md by test_messages.py.
 import contextlib
 from datetime import datetime, timedelta, timezone
 
-from . import arbitrage, messages, peakguard, uitext
+from . import arbitrage, cheaproll, messages, peakguard, priceruns, uitext
 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
@@ -218,14 +218,20 @@ def price_windows(c, plan, verdict, now=None):
     """`[(kind, start, end)]`: where the add-on itself buys ("cheap") and
     gives ("dear"). With battery modes on that is the kept `priceruns.RunPlan`
     (`c.mode_runs`): the cheap run when charging in it pays and the trade gate
-    allows it (UX-53), and every give run. With them off it is the arbitrage
-    verdict's legs the add-on will take, the ones `trade_runs()` draws
-    (`trade_legs()`, given `now`). Nothing is classified here."""
+    allows it (UX-53), and every give run. UX-77: the cheap run is drawn to
+    where control stops charging as it rolls on (`cheaproll`). With them off
+    it is the arbitrage verdict's legs the add-on will take, the ones
+    `trade_runs()` draws (`trade_legs()`, given `now`). Nothing is classified
+    here."""
     if getattr(c, "modes_on", False):
         rp = getattr(c, "mode_runs", None)
         if rp is None or not rp.on or not _price_mode_in_use(c):
             return []
-        out = [("cheap", rp.cheap.start, rp.cheap.end)] \
+        end = rp.cheap.end
+        roll = None if now is None else cheaproll.for_today(c, rp, now)
+        if roll is not None:
+            end = roll.last(end)            # UX-77: to where control stops
+        out = [("cheap", rp.cheap.start, end)] \
             if rp.charge_useful() and getattr(c, "mode_gate", None) is None \
             else []
         return out + [("dear", g.start, g.end) for g in rp.give]
@@ -422,6 +428,7 @@ def mode_runs(c, day0, day1, now, shadow, ahead=False, rp=None):
     `ahead=True`) a charge from the floor and a give from the ceiling. The
     same filter, the same `MIN_KWH`. `rp`: a run plan to read instead of
     `c.mode_runs`. Home never passes either."""
+    today = rp is None and not ahead
     rp = rp if rp is not None else getattr(c, "mode_runs", None)
     if getattr(c, "mode_tick", None) is None:
         return [], None             # no cycle yet: nothing is known
@@ -431,6 +438,9 @@ def mode_runs(c, day0, day1, now, shadow, ahead=False, rp=None):
         return [], "not_worth"
     floor, ceiling = arbitrage.soc_bounds(c.o)
     gate = getattr(c, "mode_gate", None)
+    # UX-77: today's grid block runs to where control stops charging (the run
+    # rolls on when it ends), each battery's to its own stop.
+    roll = cheaproll.for_today(c, rp, now) if today else None
     out = []
     for i, inv in enumerate(c.inverters):
         pm = c.pack_mode(inv)
@@ -465,7 +475,10 @@ def mode_runs(c, day0, day1, now, shadow, ahead=False, rp=None):
         if gate is None and rp.charge_useful() and (
                 need > 0.0 if need is not None
                 else pm.mode in GRID_CHARGE_MODES):
-            blocks.append(("grid", rp.cheap))
+            cheap = rp.cheap if roll is None else priceruns.Run(
+                rp.cheap.start, roll.end_for(inv.name, rp.cheap.end),
+                rp.cheap.mean_eur_kwh)
+            blocks.append(("grid", cheap))
         sell = rp.sell if pm.sell and pm.can_sell else None
         for g in rp.give:
             if sell is not None and g.start <= sell.start < g.end:

goodwe_controller/app/inverter.py

@@ -124,9 +124,12 @@ from datetime import datetime
 from .clamp import ClampResult
 from .delivery import DeliveryConfig, DeliveryWatchdog
 from . import messages
+# SMA-2. The driver seam: how this unit's inverter is read and steered.
+from .drivers import (GOODWE_LINK_STALE_S, GoodWeEsphomeDriver,
+                      build_driver)
 # SAFETY-37. The freshness policy, and the ONE place its bounds are written.
 # freshness.py imports nothing from this package, so the direction is one-way.
-from .freshness import BOUNDS, Freshness
+from .freshness import Freshness
 from .idle import IdleReading
 # CFG-03's ONE in-code mirror of config.yaml's SAFETY-24 defaults. Imported
 # rather than retyped: the flat-keys path below needs `bms_soc_floor`'s
@@ -149,7 +152,11 @@ from .watchdog import SignWatchdog, SignWatchdogConfig
 # decided it will not. No config key: CFG-03 tracks three places a default has
 # to be kept in step and this does not earn a fourth - it is derived from a
 # constant the firmware and validate.py already share.
-LINK_STALE_S = 30.0
+#
+# SMA-2. This is the GoodWe driver's `link_stale_s` (drivers.py), kept under its
+# old name for the checks and for main.py. `is_live()` and `link_note()` now ask
+# each unit's DRIVER for its window; a driver for another make states its own.
+LINK_STALE_S = GOODWE_LINK_STALE_S
 
 # The name of the inverter a SINGLE-INVERTER config describes. ⚠️ A NAME, NOT A
 # CONFIGURATION - it exists so that a per-inverter claim has an actuator to be
@@ -195,12 +202,14 @@ class Inverter:
     def __init__(self, name, *, setpoint_entity="", soc_entity="",
                  batt_entity="", batt_invert=False, max_w=2000.0,
                  bms_soc_floor=None, capacity_kwh=None, store=None,
-                 sign_cfg=None, delivery_cfg=None):
+                 sign_cfg=None, delivery_cfg=None, driver=None):
         self.name = str(name)
-        self.setpoint_entity = str(setpoint_entity or "")
-        self.soc_entity = str(soc_entity or "")
-        self.batt_entity = str(batt_entity or "")
-        self.batt_invert = bool(batt_invert)
+        # SMA-2. HOW THIS UNIT IS READ AND STEERED. The entity keywords above
+        # are the GoodWe driver's, kept so every existing caller builds the
+        # same unit; a roster entry that selects another driver passes
+        # `driver` and the entity keywords stay empty.
+        self.driver = driver if driver is not None else GoodWeEsphomeDriver(
+            setpoint_entity, soc_entity, batt_entity, batt_invert)
         # The supervised cap on what may be written to THIS setpoint entity.
         # See the module docstring on why this is a number and not a `Tuning`.
         self.max_w = float(max_w)
@@ -256,7 +265,7 @@ class Inverter:
         # constructed here: SoC's obligation term is energy through the pack, not
         # command travel, and the constant it needs has not been measured. That
         # is TEL-08's, and freshness.py's docstring says exactly what it owes.
-        self.batt_fresh = Freshness(BOUNDS["batt"])
+        self.batt_fresh = Freshness(self.driver.batt_bound)
 
         # --- what this unit was last told, and what it last accepted ---------
         # `target` is THIS unit's share of the site target from the last
@@ -338,6 +347,25 @@ class Inverter:
     def idle_w(self) -> float:
         return self.idle.w
 
+    # -- the GoodWe driver's entities, read through for the callers that name
+    # them (the panel's range check, the status rows, the checks). A driver
+    # without such an entity answers "" - the same as "not set".
+    @property
+    def setpoint_entity(self) -> str:
+        return getattr(self.driver, "setpoint_entity", "")
+
+    @property
+    def soc_entity(self) -> str:
+        return getattr(self.driver, "soc_entity", "")
+
+    @property
+    def batt_entity(self) -> str:
+        return getattr(self.driver, "batt_entity", "")
+
+    @property
+    def batt_invert(self) -> bool:
+        return bool(getattr(self.driver, "batt_invert", False))
+
     # -- store ---------------------------------------------------------------
     def key(self, name: str) -> str:
         """This unit's namespaced Store key for `name`. See store.unit_key()."""
@@ -387,7 +415,7 @@ class Inverter:
         return out
 
     def has_writer(self) -> bool:
-        return bool(self.setpoint_entity)
+        return self.driver.configured()
 
     # -- liveness ------------------------------------------------------------
     def note_write(self, ok: bool, now: datetime) -> None:
@@ -398,7 +426,7 @@ class Inverter:
         elif self.rejected_since is None:
             self.rejected_since = now
 
-    def is_live(self, now: datetime, stale_s: float = LINK_STALE_S):
+    def is_live(self, now: datetime, stale_s: float | None = None):
         """`(live, why_not)` - may this controller command this unit THIS TICK?
 
         Read the module docstring before widening this - in particular on why a
@@ -411,7 +439,11 @@ class Inverter:
 
         ⚠️ ANSWERED PER TICK, NEVER CACHED, for `allocator.plan()`'s reason: a
         link goes stale between one cycle and the next.
+
+        `stale_s` is the driver's `link_stale_s` unless a caller passes one.
         """
+        if stale_s is None:
+            stale_s = self.driver.link_stale_s
         if self.rejected_since is not None:
             held = (now - self.rejected_since).total_seconds()
             if held >= float(stale_s):
@@ -451,9 +483,11 @@ class Inverter:
         held = (0.0 if self.rejected_since is None
                 else (now - self.rejected_since).total_seconds())
         if not live:
-            return messages.row_not_controllable(self.name, held, LINK_STALE_S)
+            return messages.row_not_controllable(self.name, held,
+                                                 self.driver.link_stale_s)
         if self.rejected_since is not None:
-            return messages.row_commands_refused(self.name, held, LINK_STALE_S)
+            return messages.row_commands_refused(self.name, held,
+                                                 self.driver.link_stale_s)
         return ""
 
     def __repr__(self) -> str:
@@ -556,10 +590,8 @@ def build_roster(opts: dict, store, sign_cfg=None,
         # identically, which is AC 3.
         return [Inverter(
             UNIT_A,
-            setpoint_entity=opts.get("setpoint_entity", ""),
-            soc_entity=opts.get("soc_entity", ""),
-            batt_entity=opts.get("batt_entity", ""),
-            batt_invert=bool(opts.get("batt_invert")),
+            # SMA-2. The flat keys are the GoodWe shape and only that.
+            driver=GoodWeEsphomeDriver.from_entry(opts),
             max_w=_flat_max_w(opts),
             # SAFETY-32. THE FLAT KEY, because this IS the single-inverter shape
             # - the one pack the flat options describe is the one pack whose
@@ -588,10 +620,9 @@ def build_roster(opts: dict, store, sign_cfg=None,
         entry = entry if isinstance(entry, dict) else {}
         roster.append(Inverter(
             name,
-            setpoint_entity=entry.get("setpoint_entity", ""),
-            soc_entity=entry.get("soc_entity", ""),
-            batt_entity=entry.get("batt_entity", ""),
-            batt_invert=bool(entry.get("batt_invert")),
+            # SMA-2. The entry's `driver` (default goodwe_esphome) picks the
+            # class; the entry itself says where its entities are.
+            driver=build_driver(entry),
             # ⚠️ NOT `opts["max_w"]`. See the docstring: a rating an entry did
             # not state is not the flat one, it is a rating rule 9 refuses.
             max_w=_entry_max_w(entry),

goodwe_controller/app/lateness.py

@@ -0,0 +1,410 @@
+"""SAFETY-128: a reading that does not answer the last command is not current.
+
+When Home Assistant delivers readings late but still changing, every gate that
+judges arrival (SAFETY-01) or an unchanged value (SAFETY-18, SAFETY-37) passes
+them, and the loop corrects again, each cycle, an error its last command has
+already fixed. The readings show it: they answer each power request late.
+
+`Answer.watch()` (each 1 s read) fits two delays every FIT_EVERY_S:
+- `Delay`: how long after its request each battery's reading shows it. The
+  house does not move that reading, so a repeating load cannot fool it. It
+  needs the request to move FIT_MOVE_W; one reading per 10 s makes it slow.
+- `MeterFit`: how long after the site request the meter shows it. Quick at a
+  1-3 s meter, slower and for long lags only at a 5 s one (SAFETY-129), and a
+  house load that repeats can fool it.
+The meter counts only when an ask was slow to start and no battery fit said
+"on time"; with hysteresis (ON_S / OFF_S) the result is `late_seen`. Then (`observe()`, each cycle):
+- a new command more than ANSWER_W from the battery reading is PENDING until
+  that reading comes within ANSWER_W of it, or half way;
+- while pending the loop may not lead the battery reading by more than
+  ANSWER_W that way (`hold`, `hold_w`; not while `exempt`: a battery that
+  gives nothing under its ask or refuses is SAFETY-52/94's case) and the peak
+  guard may not push past what stands (`peak_cap`). Pending for LATE_S with
+  no reading moving towards it is LATE: control holds, then 0 W after
+  `stale_input_s`, as for a missing input.
+
+Not `late_seen`, nothing here acts. DECISIONS/SAFETY-128-late-readings.md.
+"""
+
+import bisect
+from collections import deque
+
+from . import freshness
+from .control import PROBE_ANSWER_W
+
+# Within this of the command the reading has answered it (a probe's answer).
+ANSWER_W = PROBE_ANSWER_W                                         # 100
+# The slowest healthy battery answer: SAFETY-75's 6 s dead time, the 6 s plant
+# settle, one 10 s publish and one 1 s read.
+LATE_S = (2 * freshness.PLANT_SETTLE_S + freshness.PUBLISH_PERIOD_S
+          + freshness.READ_PERIOD_S)                              # 23.0
+
+
+# Each battery reading's delay is fitted over this much history, up to this.
+FIT_S = 60.0
+MAX_DELAY_S = 90
+FIT_EVERY_S = 2.0
+# A fit needs this many new readings (all batteries) and this much movement
+# of the reading and the request.
+FIT_ROWS = 5
+FIT_MOVE_W = 3 * ANSWER_W                                         # 300
+# Late from ON_S, on time again under OFF_S (hysteresis).
+ON_S = 9.5
+OFF_S = 6.5
+# ...after this many late fits in a row.
+ON_FITS = 2
+# With no fit for this long the evidence is dropped (a steady site shows none).
+FIT_GONE_S = 120.0
+# A fit counts only if the commands explain this share of the reading's swing.
+FIT_SHARE = 0.5
+# A late delay must explain this share.
+FIT_SHARE_LATE = 0.75
+# ...and a late delay only if it fits this much better than any fresh one.
+FIT_BETTER = 0.5
+# A shorter delay within this factor of the best fit is taken instead.
+FIT_NEAR = 2.0
+# ...or within this of it (W^2): two fits this good are both exact.
+FIT_FLOOR_W2 = (ANSWER_W / 2) ** 2                               # 2 500
+
+
+def per_second(cmds, first, last):
+    """The request standing at each whole second from `first` to `last`."""
+    ts = [t for t, _c in cmds]
+    return [cmds[max(0, bisect.bisect_right(ts, k) - 1)][1]
+            for k in range(first, last + 1)]
+
+
+def pooled(sets, d):
+    """Pooled variance over [(rows, c, first, sign)] of value + sign *
+    c[t - d], each set about its own mean."""
+    tot, n = 0.0, 0
+    for rows, c, first, sign in sets:
+        e = [v + sign * c[int(t) - d - first] for t, v in rows]
+        m = sum(e) / len(e)
+        tot += sum((x - m) ** 2 for x in e)
+        n += len(e)
+    return tot / n
+
+
+class UnitFit:
+    """One battery's power requests and readings, as they were seen."""
+
+    def __init__(self):
+        self.cmds = deque()      # (t, request) when it changed
+        self.reads = deque()     # (t, reading) when it changed
+
+    def add(self, now, cmd, reading):
+        if cmd is not None and (not self.cmds or self.cmds[-1][1] != cmd):
+            self.cmds.append((now, float(cmd)))
+        if reading is not None and (not self.reads
+                                    or self.reads[-1][1] != reading):
+            self.reads.append((now, float(reading)))
+        while self.reads and self.reads[0][0] < now - FIT_S:
+            self.reads.popleft()
+        while (len(self.cmds) > 1
+               and self.cmds[1][0] <= now - FIT_S - MAX_DELAY_S):
+            self.cmds.popleft()
+
+    def series(self):
+        """(rows, request each second, first second) for the fit, or None:
+        too few new readings, or a reading or a request that has not moved
+        FIT_MOVE_W. The request is averaged over the 2 s before each second:
+        the battery's own lag and the read."""
+        rows = [r for r in self.reads
+                if self.cmds and r[0] >= self.cmds[0][0] + MAX_DELAY_S]
+        vals = [v for _t, v in rows]
+        if len(rows) < 3 or max(vals) - min(vals) < FIT_MOVE_W:
+            return None
+        cs = [c for _t, c in self.cmds]
+        if max(cs) - min(cs) < FIT_MOVE_W:
+            return None
+        first, last = int(rows[0][0]) - MAX_DELAY_S - 2, int(rows[-1][0])
+        c = per_second(self.cmds, first, last)
+        avg = [c[0], c[0]] + [(c[k - 2] + c[k - 1] + c[k]) / 3
+                              for k in range(2, len(c))]
+        return rows, avg, first
+
+
+class Delay:
+    """How long after a power request the batteries' readings show it.
+
+    A reading follows its battery's own request and the house does not move
+    it, so `reading(t) - request(t - d)` is flattest at the right `d`. Each new
+    reading counts once, at the second it was seen, so the 10 s publish adds no
+    delay. One `d` for every battery (Home Assistant delays them all). None
+    with too few readings, or when the requests explain too little of them (a
+    battery that does not follow); not late unless it fits clearly better than
+    any fresh delay, and then the shortest delay that fits about as well."""
+
+    def __init__(self):
+        self.units = {}
+
+    def add(self, now, unit, cmd, reading):
+        self.units.setdefault(unit, UnitFit()).add(now, cmd, reading)
+
+    def estimate(self):
+        ser = [x for x in (u.series() for u in self.units.values()) if x]
+        if sum(len(rows) for rows, _c, _f in ser) < FIT_ROWS:
+            return None
+        sets = [(rows, c, first, -1.0) for rows, c, first in ser]
+        r_var = pooled([(rows, [0.0] * len(c), first, -1.0)
+                        for rows, c, first in ser], 0)
+        pure = [pooled(sets, d) for d in range(0, MAX_DELAY_S + 1)]
+        # The shortest that fits about as well: a swing's period fits again.
+        best = next(d for d, v in enumerate(pure)
+                    if v <= FIT_NEAR * min(pure) + FIT_FLOOR_W2)
+        if r_var <= 0 or pure[best] > (1 - FIT_SHARE) * r_var:
+            return None
+        if best < ON_S:
+            return float(best)
+        if (pure[best] > (1 - FIT_SHARE_LATE) * r_var
+                or pure[best] > FIT_BETTER * min(pure[:int(OFF_S) + 1])):
+            return None
+        return float(best)
+
+
+# The meter's delay: fitted over this much history, from this many new
+# values (a meter of about 3.5 s or faster; a slower one see M_SLOW_FIT_S);
+# late over M_LATE_S (the plant's 6 s settle and one 2 s meter tick), but only
+# when the batteries' own readings have not just shown them on time.
+M_FIT_S = 60.0
+M_ROWS = 16
+M_LATE_S = freshness.PLANT_SETTLE_S + 2.0                          # 8.0
+M_SHARE, M_BETTER = 0.4, 0.7
+# SAFETY-129: a meter slower than that (a 5 s P1) has fewer than M_ROWS values
+# in M_FIT_S, so it is fitted over M_SLOW_FIT_S instead, from the same M_ROWS
+# values. It calls a delay late only over M_SLOW_LATE_S and on ON_FITS fits in
+# a row. Alone it reads 35-90 s on healthy runs, a few times in a row; what
+# keeps those from a verdict is the slow-start and battery-fit check in
+# watch(), not the limit. A 10 s lag is not found: it cannot be told from a
+# slow battery (R2-1), nor does it swing at 5 s.
+M_SLOW_FIT_S = 120.0
+M_SLOW_LATE_S = 16.0
+# A meter fit counts only after an ask that took this long to start moving a
+# reading: on time they start within 1-2 s (the recorded house, at 1-5 s).
+SLOW_START_S = 3.0
+
+
+class MeterFit:
+    """How long after a site request the meter shows it (round 1's fit).
+
+    `meter(t) + request(t - d)` is the house alone at the right `d`. Quick,
+    as the meter reads every 1-5 s, but a house load that repeats can line
+    up with an earlier request, so it only counts while the batteries' own
+    fit is not on time (`Answer.watch`)."""
+
+    def __init__(self, fit_s=M_FIT_S, late_s=M_LATE_S):
+        self.fit_s, self.late_s = fit_s, late_s
+        self.cmds = deque()      # (t, request) when it changed
+        self.grid = deque()      # (t, meter) new values only
+
+    def slow(self):
+        """The meter is too slow for M_ROWS values in `fit_s`: the usual gap
+        between its new values (median, so a pause does not count) is over
+        fit_s / M_ROWS."""
+        ts = [t for t, _g in self.grid]
+        if len(ts) < 5:
+            return False
+        gaps = sorted(b - a for a, b in zip(ts, ts[1:]))
+        return gaps[len(gaps) // 2] * M_ROWS > self.fit_s
+
+    def add(self, now, cmd, grid):
+        if cmd is not None and (not self.cmds or self.cmds[-1][1] != cmd):
+            self.cmds.append((now, float(cmd)))
+        if grid is not None and (not self.grid or self.grid[-1][1] != grid):
+            self.grid.append((now, float(grid)))
+        while self.grid and self.grid[0][0] < now - self.fit_s:
+            self.grid.popleft()
+        while (len(self.cmds) > 1
+               and self.cmds[1][0] <= now - self.fit_s - MAX_DELAY_S):
+            self.cmds.popleft()
+
+    def estimate(self):
+        if len(self.cmds) < 2:
+            return None
+        rows = [(t, g) for t, g in self.grid
+                if t >= self.cmds[0][0] + MAX_DELAY_S]
+        cs = [c for _t, c in self.cmds]
+        if len(rows) < M_ROWS or max(cs) - min(cs) < ANSWER_W:
+            return None
+        first, last = int(rows[0][0]) - MAX_DELAY_S, int(rows[-1][0])
+        c = per_second(self.cmds, first, last)
+        g_var = pooled([(rows, [0.0] * len(c), first, 1.0)], 0)
+        pure = [pooled([(rows, c, first, 1.0)], d)
+                for d in range(0, MAX_DELAY_S + 1)]
+        best = min(range(len(pure)), key=lambda d: (pure[d], d))
+        if g_var <= 0 or pure[best] > (1 - M_SHARE) * g_var:
+            return None
+        if best <= self.late_s:
+            return float(best)
+        if pure[best] > M_BETTER * min(pure[:int(self.late_s) + 1]):
+            return None
+        return float(best)
+
+
+class Answer:
+    """The answer gate. `observe()` once per cycle, before the loop."""
+
+    def __init__(self):
+        self.ask = None          # the pending command, W (site, + = give)
+        self.from_w = None       # the battery reading when it was asked
+        self.from_grid = None    # the meter when it was asked
+        self.since = None        # when it was asked
+        self.started = False     # a reading has moved towards it
+        self.late_seen = False   # the batteries' readings run late
+        self.late_at = None      # when the late verdict started
+        self.exempt = False      # a battery that cannot follow explains it
+        self._was = None         # (command, reading, meter) at the last call
+        self.delay = Delay()
+        self.meter = MeterFit()
+        self.meter_slow = MeterFit(M_SLOW_FIT_S, M_SLOW_LATE_S)   # SAFETY-129
+        self._ms_run = 0         # late slow-meter fits in a row
+        self._batt_fit = None     # (when, d): the batteries' last fit
+        self._b_run = 0          # late battery fits in a row
+        self._start_age = None   # (when, how long the last ask took to start)
+        self._exempt_at = None   # when a battery last gave nothing under its ask
+        self._ask_exempt = False
+        self._start = None
+        self.delay_s = None      # the last fitted delay (either fit), s
+        self.shown_s = None      # the batteries' last late delay, for the page
+        self.fits = 0            # fits made (instrumentation)
+        self._fit_at = self._fit_ok = None
+
+    @property
+    def active(self) -> bool:
+        return self.ask is not None and self.late_seen
+
+    @property
+    def hold(self) -> int:
+        """+1 / -1: the loop may not push further that way. 0: no hold."""
+        if not self.active or self.exempt:
+            return 0
+        return 1 if self.ask > self.from_w else -1
+
+    @property
+    def hold_w(self):
+        """How far the loop may go while held: ANSWER_W past the reading."""
+        if not self.hold:
+            return None
+        return self._was[1] + self.hold * ANSWER_W
+
+    def peak_cap(self, standing_w):
+        """The most the peak guard may ask, or None."""
+        return max(float(standing_w), 0.0) if self.active else None
+
+    def late_s(self, now):
+        """Seconds the late verdict has stood, or None."""
+        return None if self.late_at is None else max(0.0, now - self.late_at)
+
+    def watch(self, now, units, standing_w=None, grid_w=None):
+        """Each read (1 s): `units` = [(name, request on its wire, its battery
+        reading)], the site request and the meter. Every FIT_EVERY_S, fit both
+        delays. Late on ON_FITS battery fits from ON_S, or on a meter fit
+        over M_LATE_S when an ask was slow to start (SLOW_START_S) and no
+        battery fit within FIT_S said on time: a house load that repeats can
+        fool the meter fit, not these. A meter too slow for M_ROWS values in
+        M_FIT_S (a 5 s P1) is fitted over M_SLOW_FIT_S and counts only over
+        M_SLOW_LATE_S, on ON_FITS fits in a row. On time again on a battery fit
+        under OFF_S, or a meter fit within M_LATE_S unless a battery fit said
+        late.
+        """
+        if self._start is None:
+            self._start = now
+        for name, cmd, reading in units:
+            self.delay.add(now, name, cmd, reading)
+        self.meter.add(now, standing_w, grid_w)
+        self.meter_slow.add(now, standing_w, grid_w)
+        if self._fit_at is not None and now - self._fit_at < FIT_EVERY_S:
+            return
+        self._fit_at = now
+        b = self.delay.estimate()
+        if (b or 0.0) >= ON_S and self._exempt_at is not None \
+                and now - self._exempt_at <= FIT_S:
+            b = None          # a battery that stopped following: no late fit
+        m = self.meter.estimate()
+        ms = None
+        if self.meter.slow():
+            ms = self.meter_slow.estimate()
+        if b is not None:
+            self._batt_fit = (now, b)
+            self.shown_s = b if b >= ON_S else None
+        recent = (self._batt_fit is not None
+                  and now - self._batt_fit[0] <= FIT_S)
+        b_fresh = recent and self._batt_fit[1] < ON_S
+        b_late = recent and self._batt_fit[1] >= ON_S
+
+        self._b_run = self._b_run + 1 if (b or 0.0) >= ON_S else 0
+        self._ms_run = self._ms_run + 1 if (ms or 0.0) > M_SLOW_LATE_S else 0
+        # A slow-meter fit only ever adds a late verdict: it counts as a fit
+        # when it is late on ON_FITS in a row, and never ends one, so a slow
+        # battery (R2-1) runs exactly as before.
+        if self._ms_run < ON_FITS:
+            ms = None
+        d = b if b is not None else m if m is not None else ms
+        if d is None:
+            if self._fit_ok is None or now - self._fit_ok > FIT_GONE_S:
+                self.late_seen = False            # nothing to tell it by
+            return
+        self.fits += 1
+        self.delay_s, self._fit_ok = d, now
+        warm = now - self._start >= MAX_DELAY_S + FIT_S
+        m_late = ((m or 0.0) > M_LATE_S and warm) or (
+            self._ms_run >= ON_FITS
+            and now - self._start >= MAX_DELAY_S + M_SLOW_FIT_S)
+        slow = (self._start_age is not None
+                and now - self._start_age[0] <= M_FIT_S
+                and self._start_age[1] >= SLOW_START_S)
+        if self._b_run >= ON_FITS or (m_late and slow and not b_fresh):
+            self.late_seen = True
+        elif (b is not None and b < OFF_S) or (
+                m is not None and m <= M_LATE_S and not b_late):
+            self.late_seen = False
+
+    def observe(self, now, standing_w, batt_w, *, grid_w=None, exempt=False,
+                idle_w=0.0):
+        """`standing_w` the site command on the wire, `batt_w` the site
+        battery reading (None: unknown, nothing changes), `grid_w` the meter
+        (+ = import), `idle_w` what the batteries read while giving nothing.
+        `exempt`: a battery gives nothing under its ask, or refuses."""
+        if batt_w is None or standing_w is None:
+            return
+        cmd, r = float(standing_w), float(batt_w) - float(idle_w)
+        g = None if grid_w is None else float(grid_w)
+        self.exempt = bool(exempt)
+        if self.exempt:
+            self._exempt_at = now
+        was, self._was = self._was, (cmd, r, g)
+        if self.ask is None:
+            if was is None or cmd == was[0] or abs(cmd - was[1]) < ANSWER_W:
+                return
+            self.ask, self.from_w, self.from_grid = cmd, was[1], was[2]
+            self.since, self.started = now, False
+            self._ask_exempt = False
+        self.ask = cmd
+        # A battery that gives nothing under its ask explains a slow start.
+        self._ask_exempt = self._ask_exempt or self.exempt
+        age = now - self.since
+        gap = self.ask - self.from_w
+        way = 1.0 if gap > 0 else -1.0
+        batt_to = (r - self.from_w) * way
+        grid_to = (-1e9 if g is None or self.from_grid is None
+                   else (self.from_grid - g) * way)
+        if not self.started and max(batt_to, grid_to) >= ANSWER_W:
+            self.started, self.late_at = True, None
+            self._start_age = (now, 0.0 if self._ask_exempt else age)
+        elif (not self.started and age >= SLOW_START_S
+              and not self._ask_exempt):
+            self._start_age = (now, age)
+        if (self.ask - r) * way < ANSWER_W or batt_to >= abs(gap) / 2:
+            self._clear()                         # answered
+        elif abs(gap) < ANSWER_W:
+            self._clear()                         # withdrawn
+        elif exempt:
+            self.late_at = None
+        elif (self.late_at is None and self.late_seen and not self.started
+              and age >= LATE_S):
+            self.late_at = now
+
+    def _clear(self):
+        self.ask = self.from_w = self.from_grid = self.since = None
+        self.started, self.late_at = False, None

goodwe_controller/app/main.py

@@ -64,12 +64,14 @@ from .clamp import (
     shortfall_note, write_clamp_note,
 )
 from . import freshness
+from . import lateness
 from . import dayview, homeview
 from .daycurve import SolarToday
 from . import messages
 from .freeze import (
     FreezeWatchdog, FreezeWatchdogConfig, looks_frozen, rail_unreachable, rail_w,
 )
+from .drivers import GoodWeEsphomeDriver
 from .hass import CORE_API, OUTAGE, HomeAssistant
 # ⚠️ `LINK_STALE_S` IS RE-EXPORTED DELIBERATELY. `live_units()` reasons about it
 # and two checks read `app.main.LINK_STALE_S` to build a stale link, so the
@@ -1281,6 +1283,8 @@ class Controller:
         self.cycle_at = None
         self._arb_action = None
         self.inputs_bad_since = None
+        self.answer = lateness.Answer()           # SAFETY-128
+        self._late_logged = self._late_zero = False
         # SAFETY-03. What the loop's OWN bounds did last cycle - a
         # (engaged, note) pair so the alarm can say WHICH bound bit without
         # re-deriving it from a string. ⚠️ THIS ONE STAYS SITE-LEVEL, and it is
@@ -3118,6 +3122,36 @@ class Controller:
         return (decision if self._peak_needed
                 else dataclasses.replace(decision, within_aim=True))
 
+    def _readings_late(self, standing_w):
+        """SAFETY-128: update the answer gate; seconds the late verdict has
+        stood, or None. Readings found late are logged once per episode.
+        DECISIONS/SAFETY-128-late-readings.md."""
+        a = self.answer
+        if self._now_mono is None:
+            return None
+        a.observe(self._now_mono, standing_w, self.site_batt_w,
+                  grid_w=self.grid, exempt=bool(self.batt_refused) or any(
+                      i.refused or (
+                          i.batt is not None
+                          and abs(i.standing_w()) >= lateness.ANSWER_W
+                          and abs(i.batt - i.idle_w) < lateness.ANSWER_W)
+                      for i in self.inverters),
+                  idle_w=self._site_idle_w())
+        if a.late_seen != self._late_logged:
+            self._late_logged = a.late_seen
+            if a.late_seen:
+                self.log_event("readings late - holding",
+                               hint=messages.hint("readings_late"))
+                _LOG.warning("Home Assistant readings arrive late, so control "
+                             "holds the batteries: READINGS_LATE.")
+                _LOG.debug("READINGS_LATE: the readings show a power request "
+                           "%.0f s after it is sent.", a.delay_s)
+            else:
+                self.log_event("readings on time", hint=messages.hint(
+                    "readings_back"))
+                _LOG.info("Home Assistant readings are on time again.")
+        return a.late_s(self._now_mono)
+
     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."""
@@ -3729,6 +3763,10 @@ class Controller:
                 else:
                     _LOG.debug("Meter readings are back.")
 
+        self.answer.watch(now_mono, [(inv.name, inv.standing_w(), inv.batt)
+                                     for inv in self.inverters],  # SAFETY-128
+                          sum(inv.standing_w() for inv in self.inverters),
+                          self.grid)
         if self.inputs_ok:
             if self.inputs_bad_since is not None:
                 self.log_event("inputs recovered",
@@ -3737,6 +3775,18 @@ class Controller:
         elif self.inputs_bad_since is None:
             self.inputs_bad_since = datetime.now(timezone.utc)
 
+    def _driver(self, inv):
+        """`inv`'s driver, wired to this Controller's Home Assistant on first use.
+
+        SMA-2. Bound HERE rather than when the roster is built, so a unit added
+        to `self.inverters` afterwards is wired too, and the driver follows
+        whatever `self.hass` is at the time (a check may swap it).
+        """
+        drv = inv.driver
+        if not drv.bound():
+            drv.bind_getter(lambda: self.hass)
+        return drv
+
     async def _read_unit(self, inv, now_mono: float) -> None:
         """One inverter's own SoC and battery power, from ITS OWN entities.
 
@@ -3756,8 +3806,10 @@ class Controller:
         second spelling of "what is standing" would let the two disagree about
         the number they are both reasoning about.
         """
-        inv.soc = await self.hass.number(inv.soc_entity)
-        raw = await self.hass.number(inv.batt_entity, inv.batt_invert)
+        # SMA-2. The driver reads, in the order this method always did: SoC,
+        # then power. `extra` is whatever else the driver learned; nothing
+        # consumes it yet.
+        inv.soc, raw, _extra = await self._driver(inv).read()
         was_stale = inv.batt_fresh.stale
         was_releases = inv.batt_fresh.releases
         inv.batt_fresh.submit(raw, inv.standing_w(), now_mono)
@@ -3992,9 +4044,9 @@ class Controller:
                                for inv in targets))
 
     async def _write_unit(self, inv, value: float, *, force: bool = False) -> None:
-        entity = inv.setpoint_entity
-        if not entity:
+        if not inv.driver.configured():
             return
+        entity = inv.driver.actuator_id()       # for the log line below
 
         # --- SAFETY-03: THE CLAMP, AND IT IS ON THE ONLY PATH TO THE WIRE -----
         # Every write in this add-on comes through here - the cycle, the
@@ -4117,7 +4169,7 @@ class Controller:
         # tick by itself: `last_write` is updated only on an ACCEPTED write, so
         # `changed` is still true.
         try:
-            ok = await asyncio.wait_for(self.hass.set_number(entity, value),
+            ok = await asyncio.wait_for(self._driver(inv).write(value),
                                         timeout=WRITE_BUDGET_S)
         except (asyncio.TimeoutError, TimeoutError):
             ok = False
@@ -4649,6 +4701,8 @@ class Controller:
                     "away a partly delivering unit's output.")
 
         stale_after = float(self.o.get("stale_input_s", 15))
+        late_s = self._readings_late(site_standing)          # SAFETY-128
+        self._late_zero = late_s is not None and late_s >= stale_after
         # ⚠️ `any`, NOT the sole unit's. The hold exists so a single missed poll
         # does not become a fault; a LATCHED inverter must still reach the claim
         # list below, because its `failsafe` SET is what parks it. One tripped
@@ -4674,6 +4728,13 @@ class Controller:
                 self.why_words = messages.why_waiting(bad_for)
                 self._why_waiting_since = now - timedelta(seconds=bad_for)
                 return
+        if late_s is not None and late_s < stale_after and self.inputs_ok \
+                and (self.auto or self.shadow) \
+                and not any(i.sign_wd.tripped for i in self.inverters) \
+                and not (n_units > 1 and self.site_sign_wd.tripped):
+            self.reason = f"readings late {late_s:.0f}s"     # SAFETY-128: hold
+            self.why_words = messages.why_late()
+            return
 
         claims = []
 
@@ -4852,6 +4913,9 @@ class Controller:
                                hint=messages.hint("inputs_missing"))
             claims.append(Claim.set("safety", P_SAFETY, 0.0, "inputs missing",
                                     actuator=self.actuator_of("safety")))
+        elif late_s is not None:
+            claims.append(Claim.set("safety", P_SAFETY, 0.0, "readings late",
+                                    actuator=self.actuator_of("safety")))
 
         # --- SAFETY-07: the quarter-peak projection guard --------------------
         # ONE `lo` limit at P_PEAK, and peakguard.py carries the whole argument.
@@ -4975,6 +5039,8 @@ class Controller:
             self.peak_guard = self._peak_on_able(self.peak_guard,
                                                  maint_results)
             self.peak_guard = self._peak_landing(self.peak_guard)
+            self.peak_guard = peakguard.cap_floor(          # SAFETY-128
+                self.peak_guard, self.answer.peak_cap(site_standing))
         # 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
@@ -5439,6 +5505,7 @@ class Controller:
                               if len(self.inverters) == 1 else None),
                 # SAFETY-97: "gives nothing" is centred on the idle reading.
                 idle_w=self._site_idle_w(),
+                hold=self.answer.hold, hold_w=self.answer.hold_w,  # SAFETY-128
                 # OPT-11: None unless battery modes are on. SAFETY-85: or while
                 # maintenance holds a battery at N>=2, so the loop does not
                 # wind past what the others can give and jump when it ends.
@@ -6678,9 +6745,8 @@ class Controller:
         # Concurrently, for `read_inputs()`'s reason: a slow ESPHome on one unit
         # must not delay the controller's start on every other.
         async def _limits(inv):
-            if inv.setpoint_entity:
-                inv.dev_min, inv.dev_max, _ = await self.hass.limits(
-                    inv.setpoint_entity)
+            if inv.driver.configured():
+                inv.dev_min, inv.dev_max = await self._driver(inv).limits()
         await asyncio.gather(*(_limits(inv) for inv in self.inverters))
         entity = self.o.get("setpoint_entity", "")
         # ⚠️ THIS USED TO WARN AND CARRY ON, and that was the bug CFG-01
@@ -7264,9 +7330,10 @@ class Controller:
         rows = []
         for inv in self.inverters:
             unit = None if len(self.inverters) == 1 else inv.name
-            rows.append((messages.LABEL_SOC, unit, inv.soc, inv.soc_entity))
+            rows.append((messages.LABEL_SOC, unit, inv.soc,
+                         inv.driver.soc_source()))
             rows.append((messages.LABEL_BATTERY, unit, inv.batt,
-                         inv.batt_entity))
+                         inv.driver.batt_source()))
         if not self.p1_enabled:
             # In P1 mode the check above replaces this one; leaving both in
             # would report "no entity configured" for a meter_entity that is
@@ -7308,9 +7375,8 @@ class Controller:
                             "text": messages.row_sensor(label, value, unit)})
 
         for inv in self.inverters:
-            sp = inv.setpoint_entity
             unit = None if len(self.inverters) == 1 else inv.name
-            if not sp:
+            if not inv.driver.configured():
                 out.append({"ok": False, "warn": False, "id": "control",
                             "text": messages.row_control_unset(unit)})
             elif inv.dev_max is None:
@@ -7335,6 +7401,10 @@ class Controller:
                               (inv.refusal_note(), False)):
                 if note:
                     out.append({"ok": False, "warn": not red, "text": note})
+        if self.answer.late_seen:                             # SAFETY-128
+            out.append({"ok": False, "warn": True, "id": "late",
+                        "text": messages.row_readings_late(
+                            self.answer.shown_s, self._late_zero)})
 
         # SAFETY-03. Red while an over-rating clamp is engaged (amber for the
         # integrator bound, SAFETY-40), and the engagement COUNT is shown even
@@ -8149,10 +8219,13 @@ async def amain() -> None:
         # validator cannot do for itself; (None, None) when ESPHome has not come
         # up yet is not a refusal - run_control() re-checks once the real rating
         # is known. See validate.py for where the line is drawn and why.
+        # SMA-2. The flat options are the one-inverter shape, so it is the
+        # GoodWe driver's, asked without a Controller (none exists yet).
         _sp = str(opts.get("setpoint_entity", "") or "").strip()
+        _drv = GoodWeEsphomeDriver(setpoint_entity=_sp).bind(hass)
         _dev_min = _dev_max = None
         if _sp:
-            _dev_min, _dev_max, _ = await hass.limits(_sp)
+            _dev_min, _dev_max = await _drv.limits()
             _LOG.info("setpoint device %s reports range %s…%s W", _sp, _dev_min, _dev_max)
         _problems = validate_startup_config(opts, _dev_min, _dev_max)
         # UX-15: a new install names no inverter. When that is the ONLY

goodwe_controller/app/messages.py

@@ -644,6 +644,31 @@ def row_controller_stalled(age_s, veto_s) -> str:
               f"stuurmodule zet de omvormer na {seconden(veto_s)} op 0 W.")
 
 
+def row_readings_late(delay_s, zero=False) -> str:
+    """SAFETY-128: readings show the power request late; `delay_s` the
+    batteries' fitted delay (their own answer included), or None when only
+    the meter has shown it; past the hold, 0 W."""
+    if delay_s is None:
+        if zero:
+            return Bi("Home Assistant readings show requests late, so every "
+                      "inverter is at 0 W.",
+                      "Metingen uit Home Assistant tonen vermogensvraag te "
+                      "laat, omvormers op 0 W.")
+        return Bi("Home Assistant readings show requests late, so control "
+                  "holds the batteries.",
+                  "Metingen uit Home Assistant tonen vermogensvraag te laat, "
+                  "dus de batterijen wachten.")
+    if zero:
+        return Bi(f"Home Assistant readings show requests {seconds(delay_s)} "
+                  f"late, so every inverter is at 0 W.",
+                  f"Metingen uit Home Assistant tonen vermogensvraag "
+                  f"{seconden(delay_s)} te laat, omvormers op 0 W.")
+    return Bi(f"Home Assistant readings show requests about {seconds(delay_s)} "
+              f"late, so control holds the batteries.",
+              f"Metingen uit Home Assistant tonen vermogensvraag zo'n "
+              f"{seconden(delay_s)} te laat, dus de batterijen wachten.")
+
+
 def row_meter_waiting(limit_s) -> str:
     """UX-10: no reading yet since the start, and still inside the limit."""
     return Bi(f"Meter: waiting for the first reading, limit "
@@ -1270,6 +1295,7 @@ WHY_WINNER = {
     "circulation": "Safety stop, inverters worked against each other",
     "stopped": "Control is stopped",
     "inputs missing": "A reading is missing",
+    "readings late": "Home Assistant readings arrive late",
     "no claim was made": "Nothing asked for power",
     # UX-10: the claim reasons main.why_key() can return for a safety or
     # failsafe winner. test_messages.py part 7 finds every one in the code.
@@ -1320,6 +1346,11 @@ def why_missing(what, limit_s) -> str:
     return f"No usable {what} reading for over {seconds(limit_s)}: 0 W"
 
 
+def why_late() -> str:
+    """SAFETY-128: readings arrive late, so control holds the batteries."""
+    return "Home Assistant readings arrive late, control holds"
+
+
 def why_waiting(missing_s) -> str:
     """A reading went missing a moment ago: control holds and waits."""
     return f"A reading is missing for {seconds(missing_s)}, control waits"
@@ -1337,6 +1368,8 @@ HINTS = {
     "roster": "Inverter list read: {n} inverters",
     "maint_history": "Maintenance history did not move over cleanly",
     "stop_restored": "{unit}: an earlier safety stop is back, it stays at 0 W",
+    "readings_late": "Home Assistant readings arrive late, control holds",
+    "readings_back": "Home Assistant readings are on time again",
     "battery_stuck": "{unit}: battery power reading stopped changing",
     "battery_back": "{unit}: battery power reading is used again",
     "battery_refuses": "The battery refuses to give power, the add-on asks 0 W",
@@ -1488,6 +1521,10 @@ def status_samples() -> list:
         ("row_controller_stalled", RED, row_controller_stalled(45, 30)),
         ("row_meter_stale", RED, row_meter_stale(40, 10)),
         ("row_meter_waiting", AMBER, row_meter_waiting(30)),
+        ("row_readings_late", AMBER, row_readings_late(30)),
+        ("row_readings_late", AMBER, row_readings_late(30, True)),
+        ("row_readings_late", AMBER, row_readings_late(None)),
+        ("row_readings_late", AMBER, row_readings_late(None, True)),
         ("row_meter", GREEN, row_meter(-350, 2, 3, 340)),
         ("row_meter_frozen", RED, row_meter_frozen()),
         *(("row_freeze_off", AMBER, row_freeze_off(k)) for k in FREEZE_OFF),
@@ -1646,6 +1683,11 @@ LABELS = {
     "capacity_kwh": "Usable battery capacity",
     "inverters": "Inverter list",
     "name": "Name",
+    "driver": "Inverter type",
+    "host": "Inverter address",
+    "port": "Inverter port",
+    "unit_id": "Inverter unit number",
+    "maintenance": "Battery maintenance",
     "meter_source": "Where the meter reading comes from",
     "meter_phases": "Number of phases",
     "p1_host": "HomeWizard P1 address",
@@ -1727,6 +1769,11 @@ LABELS_NL = {
     "capacity_kwh": "Bruikbare capaciteit",
     "inverters": "Lijst met omvormers",
     "name": "Naam",
+    "driver": "Type omvormer",
+    "host": "Adres van de omvormer",
+    "port": "Poort van de omvormer",
+    "unit_id": "Eenheidsnummer van de omvormer",
+    "maintenance": "Onderhoud van de batterij",
     "meter_source": "Waar de meterstand vandaan komt",
     "meter_phases": "Aantal fasen",
     "p1_host": "Adres van de HomeWizard P1",

goodwe_controller/app/peakguard.py

@@ -446,6 +446,19 @@ def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
     return decision is not None and decision.engaged
 
 
+def cap_floor(decision, cap_w):
+    """SAFETY-128: the floor no higher than `cap_w` (the command standing while
+    the readings have not answered it), or `decision` unchanged when None.
+    DECISIONS/SAFETY-128-late-readings.md."""
+    if (cap_w is None or decision is None or decision.floor_w is None
+            or decision.floor_w <= cap_w):
+        return decision
+    return replace(
+        decision, floor_w=float(cap_w), saturated=False,
+        reason=decision.reason + f", held at {float(cap_w):+.0f} W until the "
+        "readings answer the last power request")
+
+
 def claim(decision: PeakDecision) -> Claim | None:
     """The decision as one arbiter claim (`lo` only, `hi` stays `+inf`), or None."""
     if not decision.engaged or decision.floor_w is None:

goodwe_controller/app/selfconfig.py

@@ -343,10 +343,12 @@ async def problems_and_ranges(opts: dict, hass=None, notes=None):
                      f"disagreement between the two and should be reported."]
         return found, []
     if hass is not None:
+        # SMA-2. Each unit's driver, bound to the panel's own (read-only)
+        # Home Assistant: there is no Controller here.
         async def _limits(unit):
-            if unit.setpoint_entity:
-                unit.dev_min, unit.dev_max, _ = await hass.limits(
-                    unit.setpoint_entity)
+            if unit.driver.configured():
+                unit.dev_min, unit.dev_max = await unit.driver.bind(
+                    hass).limits()
         await asyncio.gather(*(_limits(unit) for unit in units))
 
     dev_min = dev_max = None
@@ -357,8 +359,8 @@ async def problems_and_ranges(opts: dict, hass=None, notes=None):
     problems = list(validate_startup_config(opts, dev_min, dev_max,
                                             notes=notes))
     problems += validate_unit_ranges(units, skip_entity=flat)
-    unread = [unit.setpoint_entity for unit in units
-              if unit.setpoint_entity and unit.dev_min is None
+    unread = [unit.driver.actuator_id() for unit in units
+              if unit.driver.configured() and unit.dev_min is None
               and unit.dev_max is None]
     return problems, unread
 

goodwe_controller/app/solarfc.py

@@ -34,7 +34,9 @@ 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.
+midnight, if it is at most `KEPT_MAX_AGE_S` old when used. A TOMORROW
+reading needs no evening for (b), at any hour (OPT-38: one Forecast.Solar
+sensor stopped at 14:54 and tomorrow vanished from 17:54 to 20:00).
 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`
@@ -330,8 +332,9 @@ class Hold:
 
         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
+        at most `KEPT_MAX_AGE_S` old; a "tomorrow" reading at any hour
+        (OPT-38; `read_sum()` flags it kept only from the end of the bell).
+        `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:
@@ -347,8 +350,8 @@ class Hold:
             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.
+        if kind == "tomorrow":
+            return day, at, True    # OPT-38: no evening needed
         evening = _local_hour(now) >= BELL_TO_H and now < _bounds(day0)[1]
         return (day, at, True) if evening else None
 
@@ -556,6 +559,9 @@ def read_sum(today, tomorrow, now: datetime, hold: Hold | None = None):
     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)
+    # OPT-38: before the bell ends a kept tomorrow reading is no "kept for
+    # tonight": it must not replace today's line or the log.
+    kept = kept or (tday is not None and tkept
+                    and _local_hour(now) >= BELL_TO_H)
     # The oldest member's report is when the sum was last fully known.
     return Forecast(_sum(days), tday, min(ats), kept), None, gaps

goodwe_controller/app/ui_text/en.json

@@ -477,6 +477,7 @@
       "stopped": "Control is stopped. Every inverter is at 0 W."
     },
     "attn": {
+      "late": "Readings arrive late",
       "home_assistant": "Home Assistant is not answering",
       "controller": "Control is not running",
       "meter": "Meter reading",

goodwe_controller/app/ui_text/nl.json

@@ -398,6 +398,7 @@
     "peak_not_covered": "Geen piekgrens: deze meter meet geen kwartieren.",
     "control": {"shadow": "Schaduwmodus: elke omvormer blijft op 0 W.", "running": "De regeling is actief.", "stopped": "De regeling is gestopt. Elke omvormer staat op 0 W."},
     "attn": {
+      "late": "Metingen komen te laat",
       "home_assistant": "Home Assistant antwoordt niet",
       "controller": "Regeling is niet actief",
       "meter": "Meting van de meter",

goodwe_controller/app/uilayout.py

@@ -302,6 +302,19 @@ DERIVED = {
 HIDDEN: dict = {"price_service_token": "a secret, set on the Configuration tab"}
 
 
+# SMA-2. Per-entry keys of the inverter list the page never shows. They pick and
+# address an inverter driver, only `goodwe_esphome` is selectable, and nothing
+# reads the other four yet. An entry's keys the page does not draw travel
+# through a save as stored (uimodel._roster_decode keeps the whole entry).
+ROSTER_HIDDEN: dict = {
+    "driver": "only goodwe_esphome for now; empty means that",
+    "host": "not read yet",
+    "port": "not read yet",
+    "unit_id": "not read yet",
+    "maintenance": "not read yet",
+}
+
+
 def fields():
     """Every field once, in page order, roster fields after `inverters`."""
     for group in GROUPS:

goodwe_controller/app/validate.py

@@ -334,6 +334,7 @@ from typing import NamedTuple
 from . import dayplan, messages, pv, solarfc
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
+from . import drivers
 from .custom_formula import (
     EXPORT_FORMULA_OPTION, FormulaInvalid, implausible_all_in,
     parse_export_formula, parse_price_formula, stale_card)
@@ -457,12 +458,18 @@ def _collect_writers(node, path: str, out: list) -> None:
     however deeply nested and under whatever container.
     """
     if isinstance(node, dict):
+        # SMA-2. THE DRIVER NAMES THE ACTUATOR. An entry's `driver` (default
+        # goodwe_esphome) says which key declares its writer - `setpoint_entity`
+        # for GoodWe, `host` for a driver reached over a socket - and what that
+        # entry's `actuator_id()` is. The walk is as structural as before: it
+        # still finds an entry wherever the options keep it.
+        cls = drivers.driver_class(node)
         for k, v in node.items():
             here = f"{path}.{k}" if path else str(k)
-            if k in ACTUATOR_WRITE_KEYS:
-                entity = str(v or "").strip()
-                if entity:
-                    out.append((here, entity))
+            if k == cls.writer_key:
+                actuator = cls.actuator_id_of(node)
+                if actuator:
+                    out.append((here, actuator))
                 continue
             _collect_writers(v, here, out)
     elif isinstance(node, (list, tuple)):
@@ -498,7 +505,7 @@ def actuator_writers(opts: dict) -> dict:
     _collect_writers(opts, "", found)
     census: dict = {}
     for where, entity in found:
-        census.setdefault(entity.lower(), []).append(where)
+        census.setdefault(drivers.census_key(entity), []).append(where)
     return census
 
 
@@ -729,11 +736,16 @@ def _roster_problems(opts: dict) -> list[str]:
         else:
             seen[name] = where
         who = f"{where} ({name})" if name else where
-        if not str(entry.get("setpoint_entity") or "").strip():
+        # SMA-2. WHETHER THE ENTRY REACHES ITS INVERTER IS THE DRIVER'S TO SAY.
+        # For goodwe_esphome that is a setpoint entity, and the sentence is the
+        # one it always was. An unknown driver is refused by (h) below.
+        _cls = drivers.driver_class(entry)
+        if _cls is not drivers.UnavailableDriver and not _cls.actuator_id_of(entry):
             problems.append(
                 f"{who} has no {S('setpoint_entity')}, so the add-on cannot "
                 "control it. Set its ESPHome number entity, or remove the "
                 "entry.")
+        problems += _driver_problems(entry, who)
         if _number(entry, "max_w", None) is None or (_number(entry, "max_w", None) or 0) <= 0:
             problems.append(
                 f"{who} has no usable {S('max_w')}: it is "
@@ -775,6 +787,47 @@ def _roster_problems(opts: dict) -> list[str]:
     return problems
 
 
+def _whole(raw, lo: int, hi: int):
+    """`raw` as an int in [lo, hi], or None. A bool or a fraction is not one."""
+    if isinstance(raw, bool):
+        return None
+    try:
+        val = float(raw)
+    except (TypeError, ValueError):
+        return None
+    return int(val) if val == int(val) and lo <= val <= hi else None
+
+
+def _driver_problems(entry: dict, who: str) -> list[str]:
+    """Rule 9(h) (SMA-2): the keys that choose and address an inverter driver.
+
+    Only `goodwe_esphome` is selectable for now. `host`, `port`, `unit_id` and
+    `maintenance` are accepted and checked for shape, and nothing reads them
+    yet: a later driver's entry must not be refused for carrying them.
+    """
+    out: list[str] = []
+    raw = entry.get("driver")
+    if raw not in (None, "") and str(raw).strip() not in drivers.SELECTABLE:
+        out.append(
+            f"{who} has {S('driver')} {messages.shown(raw)}. Use "
+            f"{', '.join(drivers.SELECTABLE)}, or leave it empty.")
+    host = entry.get("host")
+    if host not in (None, "") and (not isinstance(host, str)
+                                   or re.search(r"\s", host.strip())):
+        out.append(f"{who} has {S('host')} {messages.shown(host)}, which is "
+                   "not an address. Use a name or an IP address.")
+    for key, lo, hi in (("port", 1, 65535), ("unit_id", 0, 247)):
+        val = entry.get(key)
+        if val not in (None, "") and _whole(val, lo, hi) is None:
+            out.append(f"{who} has {S(key)} {messages.shown(val)}. Use a "
+                       f"whole number from {lo} to {hi}.")
+    maint = entry.get("maintenance")
+    if maint is not None and not isinstance(maint, bool):
+        out.append(f"{who} has {S('maintenance')} {messages.shown(maint)}. "
+                   "Use on or off.")
+    return out
+
+
 def validate_unit_ranges(units, *, skip_entity: str = "") -> list[str]:
     """Rule 2, per inverter, against each unit's OWN reported device range.
 
@@ -787,8 +840,8 @@ def validate_unit_ranges(units, *, skip_entity: str = "") -> list[str]:
     2's own failure mode restored by a config shape: the operator's stated
     ceiling is not the ceiling and nothing says which won.
 
-    `units` is the roster (anything with `.name`, `.setpoint_entity`, `.max_w`,
-    `.dev_min`, `.dev_max`). A unit whose device did not answer is SKIPPED, not
+    `units` is the roster (anything with `.name`, `.driver` or `.setpoint_entity`,
+    `.max_w`, `.dev_min`, `.dev_max`). A unit whose device did not answer is SKIPPED, not
     guessed at, for the reason in this module's docstring: ESPHome is often not
     up when the add-on boots and (None, None) means "not read", not "zero".
 
@@ -800,7 +853,12 @@ def validate_unit_ranges(units, *, skip_entity: str = "") -> list[str]:
     problems: list[str] = []
     skip = str(skip_entity or "").strip().lower()
     for unit in units:
-        entity = str(getattr(unit, "setpoint_entity", "") or "").strip()
+        # SMA-2. THE DRIVER'S ACTUATOR, not a GoodWe key: a unit reached some
+        # other way is graded too. A bare object with only `.setpoint_entity`
+        # (the checks pass some) is read as it always was.
+        drv = getattr(unit, "driver", None)
+        entity = str((drv.actuator_id() if drv is not None
+                      else getattr(unit, "setpoint_entity", "")) or "").strip()
         if not entity or entity.lower() == skip:
             continue
         cap = float(getattr(unit, "max_w", 0.0) or 0.0)

goodwe_controller/config.yaml

@@ -942,11 +942,17 @@ schema:
   # batteries, whereas an absent capacity has an honest answer - no opinion
   # about the split, every unit weighs 1.0, which is what shipped.
   #
-  # ⚠️ FOUR KEYS ARE REQUIRED PER ENTRY AND THAT IS DELIBERATE. An entry with
+  # SMA-2. `driver` empty means goodwe_esphome, the only choice for now.
+  # `host`, `port`, `unit_id` and `maintenance` are accepted and checked for
+  # shape; nothing reads them yet (DECISIONS/SMA-2-driver-seam.md).
+  #
+  # ⚠️ THREE KEYS ARE REQUIRED PER ENTRY AND THAT IS DELIBERATE. An entry with
   # no `name` has no Store namespace and would share another unit's SAFETY-02
-  # latch; one with no `setpoint_entity` is a unit nothing can command; one with
-  # no `max_w` would have to borrow a rating, which is the sibling-grading
-  # defect DEV-02 removed; `bms_soc_floor` is SAFETY-32's (options block above).
+  # latch; one with no `max_w` would have to borrow a rating, which is the
+  # sibling-grading defect DEV-02 removed; `bms_soc_floor` is SAFETY-32's
+  # (options block above). `setpoint_entity` WAS A FOURTH; since SMA-2 it is the
+  # GoodWe driver's own key, so a unit nothing can command is refused by
+  # validate.py rule 9(d) per driver rather than by this schema.
   # The optional keys are the sensors, whose absence honestly means "this unit
   # reports none", and `capacity_kwh`.
   #
@@ -958,13 +964,18 @@ schema:
   # test_inverter.py part 12 asserts the ordering is still hostile.
   inverters:
     - name: str
-      setpoint_entity: str
+      setpoint_entity: str?
       max_w: int(100,5000)
       bms_soc_floor: int(0,50)
       soc_entity: str?
       batt_entity: str?
       batt_invert: bool?
       capacity_kwh: float(0.1,200)?
+      driver: list(goodwe_esphome)?
+      host: str?
+      port: port?
+      unit_id: int(0,247)?
+      maintenance: bool?
 
   estop_fitted: bool
   battery_modes_enabled: bool

goodwe_controller/test_freshness.py

@@ -790,7 +790,7 @@ print(f"    BOUNDS['soc']  subscripted in CODE by: {_uses_soc or 'nothing'}")
 check("⚠️ `wired=True` MEANS SOMETHING CONSUMES IT. A policy table nobody "
       "checks is a comment; this is the row `batt` claims and the module that "
       "claims it",
-      BOUNDS["batt"].wired is True and _uses_batt == ["inverter.py"])
+      BOUNDS["batt"].wired is True and _uses_batt == ["drivers.py"])
 check("⚠️ AND `wired=False` MEANS NOTHING DOES. SoC is TEL-08's and it is "
       "STATED here rather than wired, because its obligation term is energy "
       "through the pack and the constant that needs has never been measured on "

goodwe_controller/test_inverter.py

@@ -1536,8 +1536,9 @@ _decl9 = dict(ln.strip().lstrip("- ").split(": ", 1)
               for ln in _entry9.splitlines()[1:] if ": " in ln)
 print(f"    the shipped per-entry schema: {_decl9}")
 check("...and the schema half declares it as a LIST OF OBJECTS whose `name`, "
-      "`setpoint_entity`, `max_w` and `bms_soc_floor` are REQUIRED - no "
-      "trailing `?` - so the Supervisor refuses a half-written entry before the "
+      "`max_w` and `bms_soc_floor` are REQUIRED - no "
+      "trailing `?` (SMA-2: `setpoint_entity` is the GoodWe driver's own key "
+      "and optional here; rule 9(d) requires it per driver) - so the Supervisor refuses a half-written entry before the "
       "add-on sees it, and an entry can never fall back on a sibling's rating "
       "or on a sibling's BMS cut-out because there is no entry without one. "
       "⚠️ SAFETY-32 ADDED THE FOURTH ONE AS REQUIRED RATHER THAN AS "
@@ -1553,13 +1554,14 @@ check("...and the schema half declares it as a LIST OF OBJECTS whose `name`, "
       "refuses every options blob written before it existed",
       set(_decl9) == {"name", "setpoint_entity", "max_w", "bms_soc_floor",
                       "soc_entity", "batt_entity", "batt_invert",
-                      "capacity_kwh"}
+                      "capacity_kwh", "driver", "host", "port", "unit_id",
+                      "maintenance"}
       and not any(_decl9[k].endswith("?")
-                  for k in ("name", "setpoint_entity", "max_w",
-                            "bms_soc_floor"))
+                  for k in ("name", "max_w", "bms_soc_floor"))
       and all(_decl9[k].endswith("?")
-              for k in ("soc_entity", "batt_entity", "batt_invert",
-                        "capacity_kwh")))
+              for k in ("setpoint_entity", "soc_entity", "batt_entity",
+                        "batt_invert", "capacity_kwh", "driver", "host",
+                        "port", "unit_id", "maintenance")))
 
 # ⚠️ NOTHING IS INHERITED, AND THIS IS DEV-02 RESTATED AS A CONFIG RULE.
 # ⚠️ THE FLAT KEYS ARE SET TO REAL ENTITIES HERE, AND THAT IS THE WHOLE CHECK.

goodwe_controller/test_opt27.py

@@ -144,8 +144,9 @@ 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)
+          "the 09:05 figure covers it, kept (OPT-38: at any hour)",
+          fd is not None and fd.tomorrow is not None
+          and fd.tomorrow.kwh == 12.0 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

goodwe_controller/test_opt34.py

@@ -186,8 +186,9 @@ check("a fresh figure replaces the kept one at once (04:00: 5.0 today, "
       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)
+      "tomorrow is the 03:50 figure for the 5th (9.0, not flagged kept before 20:00: OPT-38), never "
+      "the 3rd's 12.0", fy2 is not None and fy2.today.kwh == 5.0
+      and fy2.tomorrow is not None and fy2.tomorrow.kwh == 9.0 and not fy2.kept)
 
 # Restart: the saved hold keeps the figure.
 for label, now in (("01:00", at(4, 1, 0)), ("04:00", at(4, 4, 0))):

goodwe_controller/test_opt38.py

@@ -0,0 +1,159 @@
+"""Runnable check for OPT-38.  `python3 test_opt38.py`
+
+Live 0.20.1, 2026-11-06: one of three Forecast.Solar tomorrow sensors last
+reported 14:54. From 17:54 (over FRESH_S) to 20:00 (BELL_TO_H) nothing stood in
+for it, the OPT-17 sum was dropped and the Forecast tab had no tomorrow. A kept
+tomorrow reading now stands in at any hour (`Hold.stand_in()`). Today members,
+and the OPT-34 morning rules, are as before.
+
+Mutations (MUTATION.md, purged copies): see the pull request.
+"""
+
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, HERE)
+
+from app import homeview, solarfc                                        # 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):
+    return datetime(2026, 11, day, hh, mm, tzinfo=L).astimezone(timezone.utc)
+
+
+def st(kwh, when):
+    return {"state": f"{kwh}", "attributes": {"unit_of_measurement": "kWh"},
+            "last_updated": when.isoformat(), "last_reported": when.isoformat()}
+
+
+TODAY = [("sensor.t", None)]
+M = ["sensor.m1", "sensor.m2", "sensor.m3"]
+
+
+def run(hold, readings, now, today_at=None):
+    t = [("sensor.t", st(0.5, today_at or now - timedelta(minutes=5)))]
+    return solarfc.read_sum(
+        t, [(e, st(k, w)) for e, (k, w) in zip(M, readings)], now, hold)
+
+
+# The live day: m2 last reported 14:54, the others keep reporting.
+h = solarfc.Hold()
+run(h, [(4.0, at(6, 14, 0)), (5.0, at(6, 14, 54)), (6.0, at(6, 14, 0))],
+    at(6, 14, 55))
+fresh = lambda w: [(4.0, w), (5.0, at(6, 14, 54)), (6.0, w)]  # noqa: E731
+f, why, gaps = run(h, fresh(at(6, 18, 20)), at(6, 18, 30))
+check("18:30, one member last reported 14:54: tomorrow sum is there (not "
+      "flagged kept before 20:00)",
+      f is not None and f.tomorrow is not None and f.tomorrow.kwh == 15.0
+      and not f.kept and gaps == ())
+f, _w, _g = run(h, fresh(at(6, 17, 40)), at(6, 17, 50))
+check("17:50 (just under 3 h): fresh, not kept",
+      f is not None and f.tomorrow.kwh == 15.0 and not f.kept)
+f, _w, _g = run(h, fresh(at(6, 17, 55)), at(6, 18, 0))
+check("18:00 (stale since 17:54): tomorrow there",
+      f is not None and f.tomorrow is not None and not f.kept)
+f, _w, _g = run(h, fresh(at(6, 19, 50)), at(6, 19, 55))
+check("19:55 (before the bell ends): tomorrow there", f.tomorrow is not None)
+
+# Too old: over KEPT_MAX_AGE_S (12 h) when used.
+h2 = solarfc.Hold()
+run(h2, [(4.0, at(6, 5, 0)), (5.0, at(6, 5, 0)), (6.0, at(6, 5, 0))],
+    at(6, 5, 5))
+w = at(6, 16, 50)
+f, why, gaps = run(h2, [(4.0, w), (5.0, at(6, 5, 0)), (6.0, w)],
+                   at(6, 17, 10))
+check("member 12 h 10 min old: no tomorrow sum (OPT-17 rule), today stays",
+      f is not None and f.tomorrow is None
+      and [g[0] for g in gaps] == ["tomorrow"])
+f, _w, _g = run(h2, [(4.0, w), (5.0, at(6, 5, 0)), (6.0, w)],
+                at(6, 16, 50))
+check("... and 11 h 50 min old is still kept",
+      f is not None and f.tomorrow is not None and not f.kept)
+
+# Not a partial sum: a member never read has nothing to stand in.
+f, _w, gaps = run(solarfc.Hold(), [(4.0, at(6, 18, 0)),
+                                   (5.0, at(6, 14, 54)),
+                                   (6.0, at(6, 18, 0))], at(6, 18, 30))
+check("a member with no kept reading: no tomorrow sum, no partial sum",
+      f is not None and f.tomorrow is None and len(gaps) == 1)
+
+# Today members are as before: a stale today member at 18:30 is not kept.
+h3 = solarfc.Hold()
+solarfc.read_sum([("sensor.t", st(1.0, at(6, 14, 54)))],
+                 [(M[0], st(9.0, at(6, 14, 54)))], at(6, 14, 55), h3)
+f, why, _g = solarfc.read_sum([("sensor.t", st(1.0, at(6, 14, 54)))],
+                              [(M[0], st(9.0, at(6, 18, 20)))],
+                              at(6, 18, 30), h3)
+check("stale today member at 18:30: not kept, no forecast",
+      f is None and why == solarfc.STALE)
+f, _w, _g = solarfc.read_sum([("sensor.t", st(1.0, at(6, 14, 54)))],
+                             [(M[0], st(9.0, at(6, 20, 0)))],
+                             at(6, 20, 30), h3)
+check("... and at 20:30 it is kept, as before (the bell has ended)",
+      f is not None and f.kept)
+
+# After midnight: a tomorrow reading from before midnight is never tomorrow's.
+h4 = solarfc.Hold()
+run(h4, [(4.0, at(6, 14, 0)), (5.0, at(6, 14, 0)), (6.0, at(6, 14, 0))],
+    at(6, 14, 5))
+for label, now in (("00:30", at(7, 0, 30)), ("10:00", at(7, 10, 0)),
+                   ("15:00", at(7, 15, 0))):
+    f, _w, _g = solarfc.read_sum(
+        [("sensor.t", st(2.0, now - timedelta(minutes=5)))],
+        [(e, st(k, at(6, 14, 0))) for e, k in zip(M, (4.0, 5.0, 6.0))],
+        now, h4)
+    check(f"{label} on the 7th: the 6th's tomorrow figure is not the "
+          "7th's tomorrow", f is not None and f.tomorrow is None)
+
+# Before 20:00 a kept tomorrow reading is not "kept for tonight": today's
+# line stays the normal one (EN and NL) and the event log (main.py, from
+# `fc.kept`) has no "kept".
+h5 = solarfc.Hold()
+solarfc.read_sum([("t", st(3.0, at(6, 9, 0)))], [("m", st(12.0, at(6, 9, 5)))],
+                 at(6, 9, 6), h5)
+for hh in (14, 18, 19):
+    f, _w, _g = solarfc.read_sum([("t", st(2.5, at(6, hh - 1, 55)))],
+                                 [("m", st(12.0, at(6, 9, 5)))],
+                                 at(6, hh, 0), h5)
+    check(f"{hh}:00, today fresh, tomorrow kept from 09:05: tomorrow there, "
+          "not flagged kept", f is not None and f.tomorrow is not None
+          and f.tomorrow.kwh == 12.0 and f.kept is False)
+f, _w, _g = solarfc.read_sum([("t", st(2.5, at(6, 13, 55)))],
+                             [("m", st(12.0, at(6, 9, 5)))], at(6, 14, 0), h5)
+for lang in ("en", "nl"):
+    with homeview.in_lang(lang):
+        line = homeview.line_solar(f.today.kwh, f.today.kwh * 0.7,
+                                   homeview.hhmm(f.at), kept=f.kept)
+        kept_line = homeview.line_solar(1, 1, homeview.hhmm(f.at), kept=True)
+    print(f"    {lang}: {line!r}")
+    if lang == "en":
+        check("... EN says 'Solar still to come today'",
+              line.startswith("Solar still to come today"))
+    check(f"14:00 Home line ({lang}) is the normal line, not the kept one",
+          line != kept_line and "2,5" in line.replace(".", ",")
+          and "13:55" in line)
+f, _w, _g = solarfc.read_sum([("t", st(0.2, at(6, 20, 55)))],
+                             [("m", st(12.0, at(6, 9, 5)))], at(6, 21, 0), h5)
+check("21:00 as before: tomorrow kept from 09:05 is flagged kept",
+      f is not None and f.kept and f.tomorrow.kwh == 12.0)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print("  -", f)
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_peakguard.py

@@ -3080,13 +3080,13 @@ _unit_sources_unrouted = [
     if CLAIM_SCOPE.get(r[0]) == SCOPE_UNIT and "," not in r[1]]
 print(f"    {len(_direct)} direct appends, each read at its own line: "
       + ", ".join(f"main.py:{ln} {s} -> {a}" for s, a, ln in _routing))
-check("all SEVENTEEN of `Controller.cycle()`'s DIRECT appends route through "
+check("all EIGHTEEN of `Controller.cycle()`'s DIRECT appends route through "
       "`self.actuator_of(<string literal>)`, so this scan can read the routing "
       "of EVERY one of them. An append that computed its actuator, or omitted "
       "the argument, or hand-wrote a string, fails HERE rather than being "
       "silently skipped - which is how a scan like this goes quietly vacuous, "
       "and 10f is in this file because that already happened once",
-      len(_direct) == 17
+      len(_direct) == 18
       and all(a is not None and a.startswith("self.actuator_of('")
               for _s, a, _ln in _routing))
 check("⚠️ AND AT EVERY ONE OF THE ELEVEN THE LITERAL IT ROUTES THROUGH IS THE "

goodwe_controller/test_safety128.py

@@ -0,0 +1,495 @@
+"""Runnable check for SAFETY-128: control does not act on late readings.
+`python3 test_safety128.py`
+
+When Home Assistant runs behind, its readings arrive late but still change, so
+every staleness gate passes them. The loop corrected again, each cycle, an
+error its last command had already fixed, and the evening give run swung with
+growing export (SAFETY-127 rig: 10 s late, commands -450..+3 790 W, grid to
+-1 947 W). The peak guard pushed to the inverter limit on the same late figures
+(OPT-34 rig F-2). Now a command the battery reading has not answered holds the
+loop and caps the peak guard (app/lateness.py), and readings found late hold,
+then go to 0 W. DECISIONS/SAFETY-128-late-readings.md.
+
+The REAL Controller on TEST-23's plant (tools/safety128_rig.py). "Without the
+gate" is the same run with `Controller._readings_late` returning None, which
+is the tree before this card (the rig runs unchanged on 77fe31b).
+
+1. The give run (two batteries, house 1 800 W), readings 10 s late for 150 s
+   and 30 s late for 300 s: without the gate the swing grows to export below
+   -1 kW; with it the command stays near the last good one, no export below
+   -200 W, and it settles once the lag stops. N=1 too.
+2. The peak guard in a quarter's last 30 s (a charge at the peak aim, readings
+   30 s late, the house steps): it does not go to the inverter limit.
+3. Seen: the late hold says so on the page (EN and NL) and logs once per
+   episode.
+4. Nothing else moves: no-lag runs at 1, 2 and 5 s meters, a load step on a
+   battery with a 6 s dead time (SAFETY-75), start-up, a battery at its
+   cut-out level: within the stated tolerance of the run without the gate.
+5. `Answer` and `compute(hold=)` at their edges.
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import logging
+import os
+import sys
+from datetime import timedelta
+
+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 safety128_rig as R                                      # noqa: E402
+import app.main as app_main                                    # noqa: E402
+from app import control, lateness, messages                    # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def no_gate(fn):
+    """`fn()` with the answer gate off: the tree before SAFETY-128."""
+    real = app_main.Controller._readings_late
+    app_main.Controller._readings_late = lambda self, standing_w: None
+    try:
+        return fn()
+    finally:
+        app_main.Controller._readings_late = real
+
+
+def window(rows, t0, t1):
+    return [r for r in rows if t0 <= r[0] < t1]
+
+
+def last_good(rows, t):
+    """The site command standing just before `t`."""
+    return [r for r in rows if r[0] < t][-1][2]
+
+
+def settled_at(rows, t0, band=150.0):
+    """First second from `t0` after which the grid stays within `band` W."""
+    out = None
+    for r in rows:
+        if r[0] < t0:
+            continue
+        if abs(r[1]) > band:
+            out = None
+        elif out is None:
+            out = r[0]
+    return out
+
+
+def swing(rows, t0, t1):
+    w = window(rows, t0, t1)
+    return max(r[1] for r in w) - min(r[1] for r in w)
+
+
+# --------------------------------------------------------------------------- #
+print("1. the give run with readings late")
+ON = 300.0
+CASES = ((10.0, 150.0), (30.0, 300.0))
+for p1, units in ((2.0, ("a", "b")), (2.0, ("a",)), (1.0, ("a", "b")),
+                  (5.0, ("a", "b"))):
+    house = 1800.0 if len(units) == 2 else 1500.0
+    for lag, span in CASES:
+        off = ON + span
+        seen = []
+        new = R.Rig(house=house, lag_s=lag, lag_on=ON, lag_off=off,
+                    units=units, p1_s=p1)
+        new.run(off + 120.0, lambda rig, c, t: seen.append(
+            (t, c.answer.late_seen)) if c.answer.late_seen else None)
+        old = R.Rig(house=house, lag_s=lag, lag_on=ON, lag_off=off,
+                    units=units, p1_s=p1)
+        no_gate(lambda: old.run(off + 120.0))
+        n = f"N={len(units)}, {p1:.0f} s meter, {lag:.0f} s late for {span:.0f} s"
+        wo, wn = window(old.rows, ON, off), window(new.rows, ON, off)
+        good = last_good(new.rows, ON)
+        half = ON + span / 2
+        red = min(r[1] for r in wo) < -1000.0
+        found = min([t for t, _l in seen] or [None])
+        print(f"    {n}: without the gate cmd {min(r[2] for r in wo):.0f}.."
+              f"{max(r[2] for r in wo):.0f} W, grid {min(r[1] for r in wo):.0f}"
+              f"..{max(r[1] for r in wo):.0f} W (swing {swing(old.rows, ON, half):.0f}"
+              f" then {swing(old.rows, half, off):.0f}); with it cmd "
+              f"{min(r[2] for r in wn):.0f}..{max(r[2] for r in wn):.0f} W "
+              f"(last good {good:.0f}), grid {min(r[1] for r in wn):.0f}.."
+              f"{max(r[1] for r in wn):.0f} W, found late "
+              f"{None if found is None else found - ON} s after the start, "
+              f"settled {settled_at(new.rows, off) - off:.0f} s after")
+        if len(units) == 2 and p1 == 2.0:
+            check(f"{n}: without the gate the export goes below -1 kW and the "
+                  f"swing grows (red on 77fe31b)",
+                  red and swing(old.rows, half, off) > swing(old.rows, ON, half))
+        if red:
+            check(f"{n}: found late while the lag lasts", found is not None
+                  and found < off)
+        if p1 < 5.0:
+            # Found within about a minute: at 2 s the brief's bounds; at 1 s
+            # the swing grows faster before it is found, so twice them.
+            lim = 250.0 if p1 == 2.0 else 500.0
+            check(f"{n}: with it the command stays within {lim:.0f} W of the "
+                  f"last good one and no export below -{lim - 50:.0f} W",
+                  all(abs(r[2] - good) <= lim for r in wn)
+                  and min(r[1] for r in wn) >= -(lim - 50.0))
+        elif red:
+            # 5 s meter: only the batteries' fit runs (too few meter values),
+            # so it is found later; the export is cut to under a third.
+            check(f"{n}: with it the export is under a third of the run "
+                  f"without the gate",
+                  min(r[1] for r in wn) >= min(r[1] for r in wo) / 3.0)
+        check(f"{n}: settled within 30 s after the lag stops",
+              settled_at(new.rows, off) is not None
+              and settled_at(new.rows, off) - off <= 30.0)
+
+# --------------------------------------------------------------------------- #
+print("\n2. the peak guard in a quarter's last 30 s")
+# A charge sized to the peak aim (arbitrage on a cheap hour, the shape of the
+# owner's night charge), readings 30 s late from 300 s; the house steps
+# +2 000 W 100 s before the quarter ends (900 s).
+PTS = [(R.BASE + timedelta(hours=h), 3600, 0.02 if h < 2 else 0.40)
+       for h in range(-3, 30)]
+
+
+def peak_run(lag, gate=True, step_at=800.0):
+    seen = []
+
+    def sample(rig, c, t):
+        now = rig.start + timedelta(seconds=t)
+        if int(t) % 300 == 0:
+            c.tariff_plan = rp.plan_at(now, PTS)
+        c.tariff_at = now
+        g = c.peak_guard
+        if g is not None and 870.0 <= t < 900.0 and g.engaged:
+            seen.append((t, g.saturated, float(g.floor_w or 0.0),
+                         float(c.target)))
+    r = R.Rig(house=lambda t: 1000.0 + (2000.0 if t >= step_at else 0.0),
+              lag_s=lag, lag_on=ON, lag_off=2000.0, soc=30.0,
+              extra={"arbitrage_enabled": True,
+                     "cycle_cost_threshold_eur": 0.03})
+    (lambda f: f() if gate else no_gate(f))(lambda: r.run(900.0, sample))
+    return seen, r
+
+
+RATING = sum(R.MAXW.values())
+for lag in (10.0, 30.0):
+    pg_new, _r = peak_run(lag)
+    pg_old, _r = peak_run(lag, gate=False)
+    top_new = max([s[2] for s in pg_new] or [0.0])
+    top_old = max([s[2] for s in pg_old] or [0.0])
+    print(f"    {lag:.0f} s late: the guard's largest ask in the last 30 s "
+          f"without the gate {top_old:.0f} W ({sum(s[1] for s in pg_old)} "
+          f"cycles at the limit), with it {top_new:.0f} W "
+          f"({sum(s[1] for s in pg_new)})")
+    if lag == 30.0:
+        check("without the gate the guard goes to the inverter limit on the "
+              "late projection (red on 77fe31b)",
+              top_old >= RATING and any(s[1] for s in pg_old))
+    check(f"{lag:.0f} s late: with it the guard never goes to the limit and "
+          f"never says it is saturated",
+          top_new < RATING and not any(s[1] for s in pg_new))
+
+# --------------------------------------------------------------------------- #
+print("\n3. the page and the log say so")
+rows_seen = []
+
+
+def watch(rig, c, t):
+    rows_seen.extend((t, r) for r in c.checks() if r.get("id") == "late")
+
+
+late = R.Rig(lag_s=30.0, lag_on=ON, lag_off=ON + 300.0)
+c = late.run(ON + 300.0 + lateness.FIT_GONE_S + 60.0, watch)
+log = [e for e in c.events if "readings late" in e or "readings on time" in e]
+n_late = sum(1 for e in log if "readings late" in e)
+n_back = sum(1 for e in log if "readings on time" in e)
+first = min([t for t, _r in rows_seen] or [None])
+lastr = max([t for t, _r in rows_seen] or [None])
+print(f"    30 s late for 300 s: {n_late} late episode(s), {n_back} end(s), "
+      f"the row from {first} to {lastr} s ({len(rows_seen)} s); "
+      f"{rows_seen[0][1]['text'] if rows_seen else ''}")
+_ok_texts = {str(messages.row_readings_late(None))} | {
+    str(messages.row_readings_late(d)) for d in range(20, 33)}
+check("found late within 70 s of the lag starting, and an amber row says "
+      "so in plain words, EN and NL, with the batteries' delay once they have "
+      "shown it (20-32 s for 30 s late; never a figure from the meter alone)",
+      first is not None and first - ON <= 70.0
+      and all(r["warn"] and not r["ok"] for _t, r in rows_seen)
+      and {str(r["text"]) for _t, r in rows_seen} <= _ok_texts
+      and rows_seen[-1][1]["text"].nl.startswith(
+          "Metingen uit Home Assistant tonen vermogensvraag"))
+rows5 = []
+late5 = R.Rig(lag_s=30.0, lag_on=ON, lag_off=ON + 300.0, p1_s=5.0)
+late5.run(ON + 300.0, lambda rig, c, t: rows5.extend(
+    str(r["text"]) for r in c.checks() if r.get("id") == "late"))
+print(f"    5 s meter, 30 s late: {sorted(set(rows5))}")
+# SAFETY-129: the 5 s meter's fit finds it first (no figure); the hold then
+# leaves the batteries' fit nothing to measure, so the row names no delay.
+check("at a 5 s meter the row says the readings are late, with no figure "
+      "(the meter alone found it)",
+      rows5 and set(rows5) == {str(messages.row_readings_late(None))})
+check("logged once for the episode, and once when it ends, not per cycle",
+      n_late == 1 and n_back == 1)
+check("the row goes once a fit shows the readings on time, or 2 minutes "
+      "after the last fit, at most 160 s after the lag (a steady site shows "
+      "nothing to fit)",
+      lastr is not None
+      and lastr - (ON + 300.0) <= lateness.FIT_S + lateness.FIT_GONE_S
+      and not [r for r in c.checks() if r.get("id") == "late"])
+# The late verdict through the real cycle(): readings found late (30 s), then
+# the gate is frozen with its verdict 5 s old (held) or 20 s old (past
+# stale_input_s, 15 s).
+seen_zero = {}
+
+
+def verdict(after_s):
+    def at(rig, c, t):
+        if t == 500.0:
+            c.answer.observe = lambda *a, **k: None
+            c.answer.late_seen, c.answer.late_at = True, c._now_mono - after_s
+            seen_zero[after_s] = [c.target]
+        if t == 506.0:
+            seen_zero[after_s] += [
+                c.target, c.reason, [r["text"] for r in c.checks()
+                                     if r.get("id") == "late"], c.why_words]
+    v = R.Rig(lag_s=30.0, lag_on=ON, lag_off=2000.0)
+    v.run(507.0, at)
+
+
+verdict(5.0)
+verdict(20.0)
+held, zero = seen_zero[5.0], seen_zero[20.0]
+print(f"    late verdict 5 s old: {held[:3]}; 20 s old: {zero[:3]}")
+check("the late verdict holds the request until stale_input_s, then every "
+      "inverter goes to 0 W, and the row says so (EN and NL)",
+      held[1] == held[0] and held[2].startswith("readings late")
+      and zero[1] == 0.0 and zero[4].startswith(
+          "Home Assistant readings arrive late: 0 W")
+      and len(zero[3]) == 1 and "every inverter is at 0 W" in zero[3][0]
+      and "omvormers op 0 W" in zero[3][0].nl)
+on_time = R.Rig(house=lambda t: 600.0 + (2500.0 if t >= 200.0 else 0.0))
+c = on_time.run(600.0)
+check("readings on time, a load step: no late episode, no row",
+      not [e for e in c.events if "readings late" in e]
+      and not c.answer.late_seen)
+
+# --------------------------------------------------------------------------- #
+print("\n4. nothing else moves")
+STEP = dict(house=lambda t: 600.0 + (2500.0 if t >= 200.0 else 0.0))
+
+
+def compare(name, tol_w, **kw):
+    a = R.Rig(**kw)
+    a.run(500.0)
+    b = R.Rig(**kw)
+    no_gate(lambda: b.run(500.0))
+    diff = max(abs(x[2] - y[2]) for x, y in zip(a.rows, b.rows))
+    sa, sb = settled_at(a.rows, 200.0), settled_at(b.rows, 200.0)
+    print(f"    {name}: largest command difference {diff:.0f} W, settled "
+          f"{sa - 200.0 if sa else None} s after the step (without the gate "
+          f"{sb - 200.0 if sb else None} s)")
+    return diff, sa, sb, a
+
+
+for p1 in (1.0, 2.0, 5.0):
+    for units in (("a", "b"), ("a",)):
+        d, sa, sb, _a = compare(f"no lag, {p1:.0f} s meter, N={len(units)}, "
+                                f"house 600 -> 3 100 W", 0.0, p1_s=p1,
+                                units=units, **STEP)
+        check(f"{p1:.0f} s meter, N={len(units)}: settles within 10 s of the "
+              f"run without the gate",
+              sa is not None and sb is not None and sa - sb <= 10.0)
+d, sa, sb, a75 = compare("SAFETY-75 shape, 6 s dead time", 0.0, dead_s=6.0,
+                         **STEP)
+check("6 s dead time (SAFETY-75): the same commands as without the gate, and "
+      "no late episode (the fit says 5-7 s, under 8 s)",
+      d == 0.0 and not any("readings late" in e for e in a75.c.events))
+d, sa, sb, a0 = compare("start-up, the house at 2 000 W from the first second",
+                        0.0, house=2000.0)
+check("start-up: the first 120 s reach the house within 30 s, as without the "
+      "gate, and no late episode",
+      settled_at(a0.rows, 0.0) is not None and settled_at(a0.rows, 0.0) <= 30.0
+      and not any("readings late" in e for e in a0.c.events))
+for on, off in ((45, 60), (30, 30)):
+    house = (lambda t, on=on, off=off:
+             400.0 + (2000.0 if t % (on + off) < on else 0.0))
+    oven = R.Rig(house=house, noise=80.0)
+    oven.run(1500.0)
+    oven0 = R.Rig(house=house, noise=80.0)
+    no_gate(lambda: oven0.run(1500.0))
+    check(f"an oven cycling 2 kW {on} s on, {off} s off (2 s meter, readings "
+          f"on time): never taken for late readings ({oven.c.answer.fits} "
+          "fits), the same commands as without the gate",
+          oven.c.answer.fits > 100 and not any(
+              "readings late" in e for e in oven.c.events)
+          and [r[2] for r in oven.rows] == [r[2] for r in oven0.rows])
+# One battery that empties to its cut-out level under an oven (1 s meter):
+# its fit lined the old movement up as 85 s late (round 2, before the fix).
+emp = R.Rig(house=lambda t: 400.0 + (2000.0 if t % 105 < 45 else 0.0),
+            noise=150.0, soc=10.6, units=("a",), p1_s=1.0)
+emp.run(1800.0)
+check("one battery emptying to its cut-out level under a cycling oven (1 s "
+      "meter): not taken for late readings",
+      not any("readings late" in e for e in emp.c.events))
+emp2 = R.Rig(house=lambda t: 400.0 + (2000.0 if t % 60 < 30 else 0.0),
+             noise=150.0, soc=10.2, units=("a",), p1_s=2.0)
+emp2.run(1800.0)
+check("one empty battery under an oven cycling 30/30 s (2 s meter): its "
+      "requests do not start, but it gives nothing, so that is no evidence "
+      "for the meter fit",
+      not any("readings late" in e for e in emp2.c.events))
+# The recorded house (2026-09-02, its first 2 hours, modes off) at a 2 s
+# meter: the meter fit alone read it as up to 65 s late here (review, B1).
+from datetime import datetime as _dt, timezone as _tz          # noqa: E402
+_tick, rp.TICK = rp.TICK, 2.0
+_late = []
+try:
+    _st, _rc = rp.run("modes_off", rp.load_house(["2026-09-02"]),
+                      rp.epex_points(),
+                      _dt.fromisoformat("2026-09-02T00:00:00+02:00")
+                      .astimezone(_tz.utc), 7200.0,
+                      check=lambda c, h, now, pr: _late.append(
+                          c.answer.late_seen))
+finally:
+    rp.TICK = _tick
+check(f"the recorded house, 2 hours at a 2 s meter: {_rc.answer.fits} fits, "
+      "never taken for late readings",
+      _rc.answer.fits > 100 and not any(_late))
+import safety94_rig as s94                                     # noqa: E402
+slow = [(n, tau, tick) for n in (1, 2) for tau in (10.0, 20.0)
+        for tick in (1.0, 2.0)
+        if any("readings late" in e for e in s94.run(
+            n, s94.reversal(300.0, -2500.0, 800.0), 600.0, tau=tau,
+            tick=tick)["c"].events)]
+check("a slow battery (10 or 20 s lag, SAFETY-85/94's rig) reversing out of a "
+      "charge, readings on time: never taken for late readings, N=1 and N=2, "
+      f"1 and 2 s meters (taken: {slow})", not slow)
+for name, kw in (("at their cut-out level", dict(soc=10.5)),
+                 ("A refusing from 200 s",
+                  dict(cut=lambda u, t: u == "a" and t >= 200.0))):
+    x = R.Rig(house=1800.0, **kw)
+    x.run(600.0)
+    y = R.Rig(house=1800.0, **kw)
+    no_gate(lambda: y.run(600.0))
+    check(f"readings on time, batteries {name}: not taken for late "
+          f"readings, the same commands as without the gate",
+          not any("readings late" in e for e in x.c.events)
+          and [r[2] for r in x.rows] == [r[2] for r in y.rows])
+
+# --------------------------------------------------------------------------- #
+print("\n5. the rules at their edges")
+check("LATE_S is SAFETY-75's slowest healthy answer: 6 + 6 + 10 + 1 = 23 s",
+      lateness.LATE_S == 23.0)
+check("ANSWER_W is a probe's answer (100 W)",
+      lateness.ANSWER_W == control.PROBE_ANSWER_W == 100.0)
+
+
+check("late from ON_S 9.5 s, on time again under OFF_S 6.5 s",
+      (lateness.ON_S, lateness.OFF_S) == (9.5, 6.5))
+
+
+def fit(delay, *, follows=True, step_every=20, dur=300, tau=0.0, units="ab"):
+    """`Delay` on batteries whose readings, published every 10 s at their own
+    phase, show each request `delay` s late (through a `tau` s lag), or never
+    (`follows` False)."""
+    import math
+    import random
+    rng, d = random.Random(7), lateness.Delay()
+    edges = [0]
+    while edges[-1] < dur:
+        edges.append(edges[-1] + step_every * rng.uniform(0.5, 1.5))
+    cmd = lambda t: 1500.0 + (600.0 if sum(e <= t for e in edges) % 2 else 0.0)
+    act, shown = 1500.0, {}
+    for t in range(0, dur):
+        want = cmd(t - delay) if t >= delay else 1500.0
+        act = want if not tau else act + (want - act) * (1 - math.exp(-1 / tau))
+        for k, u in enumerate(units):
+            if (t + 4 * k) % 10 == 0:
+                shown[u] = round(act + rng.uniform(-3, 3)) if follows else 900
+            d.add(float(t), u, cmd(t), shown.get(u))
+    return d.estimate()
+
+
+got = {k: fit(k) for k in (0, 6, 10, 30, 60)}
+print(f"    fitted delays: {got}; one battery {fit(10, units='a')}")
+check("the fit finds the readings' delay (0, 6, 10, 30, 60 s) to within 2 s "
+      "(it reads the request over the 2 s before), also with one battery",
+      all(v is not None and abs(v - k) <= 2.0 for k, v in got.items())
+      and abs((fit(10, units="a") or 0.0) - 10.0) <= 2.0)
+slow = [fit(0, tau=tau, step_every=s) for tau in (3.0, 10.0, 20.0)
+        for s in (10, 20, 40)]
+check("a battery that does not follow gives no fit, nor does a request that "
+      f"does not move, and a slow battery (3, 10, 20 s lag) is never late "
+      f"({slow})",
+      fit(10, follows=False) is None and fit(10, step_every=10_000) is None
+      and all((d or 0.0) < lateness.ON_S for d in slow))
+
+
+def gate(steps, exempt=(), late_seen=True):
+    """[(t, command, battery reading, meter)] through one Answer, its fit
+    replaced by `late_seen`; after each: (pending, hold, late s, peak cap)."""
+    a = lateness.Answer()
+    a.late_seen = late_seen
+
+    def one(t, cmd, batt, grid):
+        a.observe(float(t), cmd, batt, grid_w=grid, exempt=t in exempt)
+        return (a.ask is not None, a.hold, a.late_s(float(t)),
+                a.peak_cap(cmd))
+    return a, [one(*x) for x in steps]
+
+
+STEP = [(0, 1000, 1000, 500), (2, 1500, 1000, 500)]
+HELD = STEP + [(t, 1500, 1000, 500) for t in range(4, 40, 2)]
+a, out = gate(HELD, late_seen=False)
+check("readings on time: an unanswered ask holds nothing, caps nothing and "
+      "is never late (a battery at its limit)",
+      out[-1][0] and all(o[1] == 0 and o[2] is None and o[3] is None
+                         for o in out))
+a, out = gate(STEP + [(4, 1500, 1000, 500), (6, 1500, 1450, 60)])
+check("readings late: the ask holds the loop up and caps the peak guard at "
+      "what stands until the battery reading answers",
+      out[1][1:] == (1, None, 1500.0) and out[2][1:] == (1, None, 1500.0)
+      and out[3] == (False, 0, None, None))
+a, out = gate(HELD)
+check("...and with no move towards it for 23 s it is late (control holds, "
+      "then 0 W)",
+      [o[2] for o in out].index(0.0) == len([t for t, *_ in HELD
+                                             if t - 2 < 23]))
+a, out = gate(HELD + [(40, 1500, 1000, 380)])
+check("...which ends when a reading starts towards the ask",
+      out[-2][2] is not None and out[-1][2] is None and out[-1][0])
+a, out = gate(HELD, exempt=set(range(2, 40, 2)))
+check("exempt (a battery gives nothing under its ask, or refuses): no hold "
+      "and no late verdict, the cap stays",
+      all(o[1] == 0 and o[2] is None for o in out) and out[-1][3] == 1500.0)
+a, out = gate([(0, 1000, 1000, 500), (2, 1090, 1000, 500),
+               (4, 1000, 1000, 500)])
+check("a move under 100 W is not an ask", not any(o[0] for o in out))
+a, out = gate(STEP + [(4, 1050, 1000, 500)])
+check("an ask taken back within 100 W of the reading is withdrawn",
+      out[2][0] is False)
+T = control.Tuning(max_w=5000.0)
+base = dict(prev_w=1500.0, grid_w=800.0, actual_w=1000.0, tuning=T,
+            i_w=1500.0)
+check("compute(hold=+1): the loop may not push past the standing command, "
+      "but may come back",
+      control.compute(**base).target_w > 1500.0
+      and control.compute(**base, hold=1).target_w == 1500.0
+      and control.compute(**base, hold=1).reason == control.WAITING
+      and control.compute(**dict(base, grid_w=-800.0), hold=1).target_w
+      < 1500.0)
+check("compute(hold=-1) mirrors it, and hold=0 is the law as it was",
+      control.compute(**dict(base, grid_w=-800.0), hold=-1).target_w == 1500.0
+      and control.compute(**base, hold=0) == control.compute(**base))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + ", ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_safety129.py

@@ -0,0 +1,238 @@
+"""Runnable check for SAFETY-129: late Home Assistant readings found at a 5 s meter.
+`python3 test_safety129.py`
+
+SAFETY-128 fitted the meter's delay only at a meter of about 3.5 s or faster
+(16 new values in 60 s). The owner's P1 reports every 5 s, so there only the
+batteries' fit ran: with readings 30 s late the loop swung to -420 W export
+and was found after about 3 minutes (-1 325 W before the hold).
+`lateness.MeterFit` now also runs at a slow meter over 120 s, and calls a
+delay late only over `M_SLOW_LATE_S` on two fits in a row, with the same
+corroboration as before (an ask slow to start, no battery fit on time).
+DECISIONS/SAFETY-128-late-readings.md.
+
+The REAL Controller on TEST-23's plant (tools/safety128_rig.py).
+
+1. 5 s meter, readings 30 s late (N=2 house 1 800 W, N=1 house 1 500 W): found
+   within 100 s, and the export never goes below -200 W (red on c66aa7f: found
+   after 190 s, export to -420 W).
+2. 5 s meter, readings 10 s late: no swing, nothing to hold; and the limit that
+   goes with it: a battery that answers in 10 s (R2-1) is still not read as
+   late at a 5 s meter, which a lower slow-meter threshold would break.
+3. No false holds at a slow meter: the owner's shape at 2, 5 and 10 s, HA
+   restarts and meter pauses at 2 and 5 s, 8-10 s dead times: never
+   late, so the commands are those of the run without the gate.
+4. The slow-meter fit at its edges.
+
+Mutations (MUTATION.md, purged copies) are listed in the pull request.
+"""
+
+import logging
+import os
+import sys
+
+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 safety128_rig as R                                      # noqa: E402
+import app.main as app_main                                    # noqa: E402
+from app import lateness                                       # noqa: E402
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def no_gate(fn):
+    """`fn()` with the answer gate off: the tree before SAFETY-128."""
+    real = app_main.Controller._readings_late
+    app_main.Controller._readings_late = lambda self, standing_w: None
+    try:
+        return fn()
+    finally:
+        app_main.Controller._readings_late = real
+
+
+def run_late(**kw):
+    """Run the rig; (rig, seconds the verdict stood, first second it stood)."""
+    dur = kw.pop("dur")
+    seen = []
+    r = R.Rig(**kw)
+    r.run(dur, lambda rig, c, t: seen.append(t) if c.answer.late_seen
+          else None)
+    return r, len(seen), min(seen) if seen else None
+
+
+def grid_min(rows, t0, t1):
+    return min(r[1] for r in rows if t0 <= r[0] < t1)
+
+
+AB, A = ("a", "b"), ("a",)
+ON = 300.0
+
+# --------------------------------------------------------------------------- #
+print("1. 5 s meter, readings 30 s late for 300 s")
+for units, house in ((AB, 1800.0), (A, 1500.0)):
+    n = f"N={len(units)}"
+    r, secs, first = run_late(house=house, lag_s=30.0, lag_on=ON,
+                              lag_off=ON + 300.0, units=units, p1_s=5.0,
+                              dur=ON + 420.0)
+    low = grid_min(r.rows, ON, ON + 300.0)
+    print(f"    {n}: found {None if first is None else first - ON:.0f} s "
+          f"after the start, export to {low:.0f} W")
+    check(f"{n}: found within 100 s of the lag starting",
+          first is not None and first - ON <= 100.0)
+    check(f"{n}: the export never goes below -200 W", low >= -200.0)
+    if len(units) == 2:
+        old = R.Rig(house=house, lag_s=30.0, lag_on=ON, lag_off=ON + 300.0,
+                    units=units, p1_s=5.0)
+        no_gate(lambda: old.run(ON + 300.0))
+        check(f"{n}: without the gate the export goes below -1 kW",
+              grid_min(old.rows, ON, ON + 300.0) < -1000.0)
+
+# --------------------------------------------------------------------------- #
+print("\n2. 5 s meter, readings 10 s late; a battery that answers in 10 s")
+r, secs, first = run_late(house=1800.0, lag_s=10.0, lag_on=ON,
+                          lag_off=ON + 150.0, units=AB, p1_s=5.0,
+                          dur=ON + 200.0)
+low = grid_min(r.rows, ON, ON + 150.0)
+print(f"    10 s late: export to {low:.0f} W, verdict stood {secs} s")
+check("10 s late: no swing, the export never goes below -200 W", low >= -200.0)
+
+
+def owner(t):
+    w = 400.0
+    if 600 <= t < 780:
+        w += 2200
+    if 1200 <= t < 2400 and ((t - 1200) % 105) < 45:
+        w += 2000
+    return w
+
+
+for dead in (8.0, 10.0):
+    r, secs, first = run_late(house=owner, noise=80.0, units=AB, p1_s=5.0,
+                              dead_s=dead, dur=800.0)
+    print(f"    {dead:.0f} s dead time, 5 s meter: late {secs} s")
+    check(f"{dead:.0f} s dead time at a 5 s meter is not read as late "
+          f"(R2-1 does not get worse)", secs == 0)
+
+# At a 6 s meter an 8 s dead time reads late on the slow fit alone; only the
+# slow-start and battery-fit check keeps it from a verdict (122 s late
+# without the check, from 1 084 s).
+r, secs, first = run_late(house=owner, noise=80.0, units=AB, p1_s=6.0,
+                          dead_s=8.0, dur=1500.0)
+print(f"    8 s dead time, 6 s meter: late {secs} s")
+check("an 8 s dead time at a 6 s meter is never late (the slow fit needs an "
+      "ask slow to start and no battery fit on time)", secs == 0)
+
+# A 12 s dead time is already read as late (R2-1, SAFETY-128); the slow-meter
+# fit must not make that longer. The same run with the slow fit off is the
+# tree before this card.
+_slow = lateness.MeterFit.slow
+secs = {}
+for label in ("with", "without"):  # 12 s dead time: late from about 140 s
+    lateness.MeterFit.slow = _slow if label == "with" else (lambda self: False)
+    try:
+        secs[label] = run_late(house=owner, noise=80.0, units=A, p1_s=5.0,
+                               dead_s=12.0, dur=900.0)[1]
+    finally:
+        lateness.MeterFit.slow = _slow
+print(f"    12 s dead time, N=1, 5 s meter: late {secs['with']} s, with the "
+      f"slow fit off {secs['without']} s")
+check("a 12 s dead time at a 5 s meter is late no longer than before "
+      "(R2-1 does not get worse)", secs["with"] <= secs["without"])
+
+# --------------------------------------------------------------------------- #
+print("\n3. no false holds")
+_view = R.Plant.view
+
+
+def frozen(windows, meter_only):
+    def view(self, t, lag_s, lag_on, lag_off):
+        cur = _view(self, t, lag_s, lag_on, lag_off)
+        for a, b in windows:
+            if a <= t < b:
+                for row in reversed(self.hist):
+                    if row[0] <= a + 1e-9:
+                        old = row[1:]
+                        return (old[0], old[1], cur[2], cur[3]) \
+                            if meter_only else old
+        return cur
+    return view
+
+
+for p1 in (2.0, 5.0, 10.0):
+    kw = dict(house=owner, noise=80.0, units=AB, p1_s=p1)
+    r, secs, first = run_late(dur=800.0, **kw)
+    new = r
+    old = R.Rig(**kw)
+    no_gate(lambda: old.run(800.0))
+    same = max(abs(x[2] - y[2]) for x, y in zip(new.rows, old.rows))
+    print(f"    owner shape, {p1:.0f} s meter: late {secs} s, command "
+          f"difference {same:.0f} W")
+    check(f"{p1:.0f} s meter, owner shape: never late, same commands",
+          secs == 0 and same == 0)
+for label, windows, meter_only in (
+        ("HA restart", ((650.0, 710.0),), False),
+        ("meter pause", ((640.0, 700.0),), True)):
+    for p1 in (2.0, 5.0):
+        R.Plant.view = frozen(windows, meter_only)
+        try:
+            r, secs, first = run_late(house=owner, noise=80.0, units=AB,
+                                      p1_s=p1, dur=800.0)
+        finally:
+            R.Plant.view = _view
+        check(f"{label} at a {p1:.0f} s meter: never late", secs == 0)
+
+# --------------------------------------------------------------------------- #
+print("\n4. the slow-meter fit at its edges")
+
+
+def meter_with(period, pause_after=None, pause_s=40.0, n=24):
+    f = lateness.MeterFit()
+    f.add(0.0, 100.0, 0.0)
+    for k in range(1, n):
+        gap = pause_s if pause_after is not None and k > pause_after else 0.0
+        f.add(period * k + gap, None, float(k))
+    return f
+
+
+check("a 5 s and a 10 s meter are slow",
+      meter_with(5.0).slow() and meter_with(10.0).slow())
+check("a 1 s, a 2 s and a 3 s meter are not slow",
+      not any(meter_with(p, n=60).slow() for p in (1.0, 2.0, 3.0)))
+check("a pause in a 2 s meter does not make it slow",
+      not meter_with(2.0, pause_after=10, n=40).slow())
+def fed(values):
+    """Answer.watch() with the slow fit reading `values`, one per fit."""
+    a = lateness.Answer()
+    a.meter.slow = lambda: True
+    a.meter.estimate = a.delay.estimate = lambda: None
+    it = iter(values)
+    a.meter_slow.estimate = lambda: next(it, None)
+    for k in range(len(values)):
+        a.watch(2.0 * k, [], 0.0, 0.0)
+    return a
+
+
+check("one late slow-meter fit is no fit; two in a row are one, and "
+      "one on time or in between is none",
+      fed([30.0]).fits == 0 and fed([30.0, 30.0]).fits == 1
+      and fed([30.0, None, 30.0]).fits == 0 and fed([30.0, 12.0]).fits == 0
+      and fed([3.0, 3.0]).fits == 0 and not fed([30.0, 30.0]).late_seen)
+check("the slow fit asks for a longer window and a later delay than the "
+      "fast one", lateness.M_SLOW_FIT_S > lateness.M_FIT_S
+      and lateness.M_SLOW_LATE_S > lateness.M_LATE_S)
+check("the slow fit's late limit is above the fast one's and above a "
+      "10 s lag", lateness.M_SLOW_LATE_S >= 16.0)
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + ", ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_safety94.py

@@ -61,6 +61,9 @@ def without_fix(fn):
     """Run `fn` with the gate's old clock and the old refusal evidence."""
     real_f, real_c = app_inverter.Freshness, app_main.compute
     real_p = app_main.REFUSED_PROGRESS_W
+    real_l = app_main.Controller._readings_late
+    # SAFETY-128: that tree had no late-readings gate either.
+    app_main.Controller._readings_late = lambda self, standing_w: None
     app_inverter.Freshness = Before94
     app_main.compute = lambda *a, **k: real_c(*a, **dict(k, gave_nothing=None))
     app_main.REFUSED_PROGRESS_W = float("inf")
@@ -69,6 +72,7 @@ def without_fix(fn):
     finally:
         app_inverter.Freshness, app_main.compute = real_f, real_c
         app_main.REFUSED_PROGRESS_W = real_p
+        app_main.Controller._readings_late = real_l
 
 
 # ============================================================================ #

goodwe_controller/test_safety96.py

@@ -68,10 +68,14 @@ def without(fn):
     Controller._held_out_w = lambda self, live: 0.0
     Controller._reseed_drop = lambda self, live: setattr(
         self, "_live_was", frozenset(live))
+    real_late = Controller._readings_late
+    # SAFETY-128: that tree had no late-readings gate either.
+    Controller._readings_late = lambda self, standing_w: None
     try:
         return fn()
     finally:
         Controller._held_out_w, Controller._reseed_drop = fixed, real_drop
+        Controller._readings_late = real_late
 
 
 def run(n=2, *, house=lambda t: 2400.0, dur=600.0, store=None, opt=None,

goodwe_controller/test_sma2_driver.py

@@ -0,0 +1,626 @@
+"""SMA-2: the inverter driver seam.  `python3 test_sma2_driver.py`
+
+Part 1 grades the GoodWe driver against a Home Assistant that logs every call:
+it must make exactly the calls the code it replaced made, in the same order.
+Part 2 grades what `Inverter` reads from its driver. Part 3 drives a REAL
+Controller with a roster of one fake-driver unit and one GoodWe unit and
+checks that it writes, reads, limits, grades, drops and publishes each by its
+own driver, with a Home Assistant that records every entity it is asked about
+so a call site that goes round the seam is seen. Part 4 is the SAFETY-28
+census and rule 9 on the new keys. Part 5 is the schema.
+
+Mutating a module this file grades? Read MUTATION.md first (purge __pycache__).
+The seam mutants this file was run against are listed at the end.
+"""
+
+import asyncio
+import io
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from app import drivers
+from app.drivers import (DEFAULT_DRIVER, REGISTRY, SELECTABLE, Driver,
+                         DriverNotBound, GoodWeEsphomeDriver, Probe,
+                         UnavailableDriver, build_driver, census_key)
+from app.freshness import BOUNDS, Bound
+from app.inverter import LINK_STALE_S, Inverter, build_roster
+from app.main import Controller
+from app.store import DEFAULTS
+from app.validate import (actuator_writers, validate_startup_config,
+                          validate_unit_ranges)
+
+fails = []
+HERE = Path(__file__).resolve().parent
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+class MemStore:
+    def __init__(self):
+        self.data = dict(DEFAULTS)
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get_time(self, *a):
+        return None
+
+    def set_time(self, *a):
+        pass
+
+
+class Pub:
+    """Keeps the last published values, like test_mqtt.py's."""
+    enabled = False
+
+    def __init__(self):
+        self.last = {}
+
+    def publish(self, values):
+        self.last = dict(values)
+
+    def close(self):
+        pass
+
+
+class LogHass:
+    """Home Assistant for the GoodWe unit. EVERY call is logged with its entity,
+    so a path that talks to Home Assistant about anything else is on record."""
+
+    def __init__(self, numbers=None, limits=None, accept=True):
+        self.numbers = dict(numbers or {})
+        self.limits_by = dict(limits or {})
+        self.accept = accept
+        self.log = []                       # (method, entity, extra)
+
+    async def number(self, entity, invert=False):
+        self.log.append(("number", entity, invert))
+        v = self.numbers.get(entity)
+        return None if v is None else (-v if invert else v)
+
+    async def limits(self, entity):
+        self.log.append(("limits", entity, None))
+        return self.limits_by.get(entity, (None, None, None))
+
+    async def set_number(self, entity, value):
+        self.log.append(("set_number", entity, value))
+        if self.accept:
+            self.numbers[entity.replace("number.sp", "sensor.batt")] = value
+        return self.accept
+
+    async def state(self, entity):
+        self.log.append(("state", entity, None))
+        return None
+
+    async def call(self, *a):
+        self.log.append(("call", repr(a), None))
+        return True
+
+    def entities(self):
+        """Every entity name Home Assistant was asked about (service calls
+        like notifications name none)."""
+        return {e for m, e, _x in self.log if m != "call"}
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+def raises(exc, make):
+    """Does `run(make())` raise `exc`? `make` builds the coroutine."""
+    try:
+        run(make())
+    except exc:
+        return True
+    except Exception:
+        return False
+    return False
+
+
+# ---------------------------------------------------------------------------
+# a fake driver: a unit reached by host:port:unit, no Home Assistant at all
+# ---------------------------------------------------------------------------
+FAKE_BOUND = Bound(signal="fake", unchanged_s=11.0, move_w=100.0,
+                   release_s=5.0, wired=True, derivation="test")
+
+
+class FakeDriver(Driver):
+    name = "fake"
+    writer_key = "host"
+    brand = "Fake"
+    link_stale_s = 7.0
+    batt_bound = FAKE_BOUND
+    settle_s = 3.0
+    words = {"idle": "handed back"}
+
+    def __init__(self, host="", port=502, unit_id=1, rating=1000.0, soc=60.0):
+        self.host, self.port, self.unit_id = host, port, unit_id
+        self.rating, self.soc, self.power = rating, soc, 0.0
+        self.accept = True
+        self.calls = []                     # (what, arg)
+
+    @classmethod
+    def from_entry(cls, entry):
+        return cls(entry.get("host", ""), entry.get("port", 502),
+                   entry.get("unit_id", 1), rating=entry.get("_rating", 1000.0))
+
+    @classmethod
+    def actuator_id_of(cls, entry):
+        host = str(entry.get("host") or "").strip()
+        return (f"{host}:{entry.get('port', 502)}:{entry.get('unit_id', 1)}"
+                if host else "")
+
+    def configured(self):
+        return bool(self.host)
+
+    def actuator_id(self):
+        return f"{self.host}:{self.port}:{self.unit_id}"
+
+    def soc_source(self):
+        return "fake-soc"
+
+    def batt_source(self):
+        return "fake-power"
+
+    async def limits(self):
+        self.calls.append(("limits", None))
+        return -self.rating, self.rating
+
+    async def read(self):
+        self.calls.append(("read", None))
+        return self.soc, self.power, {"state": "ok"}
+
+    async def write(self, w):
+        self.calls.append(("write", w))
+        if self.accept:
+            self.power = w                  # the battery follows its command
+        return self.accept
+
+    async def release(self):
+        self.calls.append(("release", None))
+        return True
+
+    async def probe(self):
+        self.calls.append(("probe", None))
+        return Probe(-self.rating, self.rating, self.soc, self.power, {})
+
+
+def calls(drv, what):
+    return [a for w, a in drv.calls if w == what]
+
+
+print("SMA-2 - the inverter driver seam")
+print()
+# ==============================================================================
+print("1. the GoodWe driver makes the calls the code it replaced made")
+
+GW = dict(setpoint_entity="number.sp_a", soc_entity="sensor.soc_a",
+          batt_entity="sensor.batt_a")
+h1 = LogHass({"sensor.soc_a": 55.0, "sensor.batt_a": 700.0},
+             {"number.sp_a": (-5000.0, 4000.0, 1.0)})
+d1 = GoodWeEsphomeDriver(**GW).bind(h1)
+check("a driver built from an entry names its three entities and is configured",
+      GoodWeEsphomeDriver.from_entry(dict(GW)).setpoint_entity == "number.sp_a"
+      and d1.configured() and d1.actuator_id() == "number.sp_a"
+      and (d1.soc_source(), d1.batt_source())
+      == ("sensor.soc_a", "sensor.batt_a"))
+check("...and one with no setpoint entity is not",
+      not GoodWeEsphomeDriver().configured()
+      and not GoodWeEsphomeDriver(soc_entity="sensor.soc_a").configured())
+check("limits() is hass.limits(setpoint) and hands back (min, max)",
+      run(d1.limits()) == (-5000.0, 4000.0)
+      and h1.log == [("limits", "number.sp_a", None)])
+h1.log.clear()
+check("read() asks for the SoC first, then the power, with the invert flag, "
+      "and nothing else",
+      run(d1.read()) == (55.0, 700.0, {})
+      and h1.log == [("number", "sensor.soc_a", False),
+                     ("number", "sensor.batt_a", False)])
+h1.log.clear()
+d1i = GoodWeEsphomeDriver(batt_invert=True, **GW).bind(h1)
+check("...and a reversed power sensor is reversed by hass.number, as before",
+      run(d1i.read()) == (55.0, -700.0, {})
+      and h1.log[1] == ("number", "sensor.batt_a", True))
+h1.log.clear()
+check("write(w) is hass.set_number(setpoint, w) and says whether it took it",
+      run(d1.write(-250.0)) is True and h1.log == [("set_number", "number.sp_a",
+                                                    -250.0)])
+h1.log.clear()
+h1.accept = False
+check("...and False when Home Assistant refuses",
+      run(d1.write(10.0)) is False)
+h1.accept = True
+h1.log.clear()
+check("release() is write(0): GoodWe is handed back by its board's own watchdog",
+      run(d1.release()) is True
+      and h1.log == [("set_number", "number.sp_a", 0.0)])
+h1.log.clear()
+h1.numbers.update({"sensor.soc_a": 55.0, "sensor.batt_a": 700.0})
+pr = run(d1.probe())
+check("probe() reads the range, the SoC and the power and WRITES NOTHING",
+      pr == Probe(-5000.0, 4000.0, 55.0, 700.0, {})
+      and all(m != "set_number" for m, _e, _x in h1.log))
+check("a driver with no Home Assistant is loud, not a silent 'no answer'",
+      raises(DriverNotBound, GoodWeEsphomeDriver(**GW).limits)
+      and raises(DriverNotBound, GoodWeEsphomeDriver(**GW).read)
+      and raises(DriverNotBound, lambda: GoodWeEsphomeDriver(**GW).write(1.0))
+      and not GoodWeEsphomeDriver(**GW).bound())
+_swap = {"h": h1}
+d1g = GoodWeEsphomeDriver(**GW).bind_getter(lambda: _swap["h"])
+h1b = LogHass({"sensor.soc_a": 1.0, "sensor.batt_a": 2.0})
+_swap["h"] = h1b
+check("bind_getter() looks Home Assistant up at each use, so a Controller whose "
+      ".hass is replaced afterwards is followed",
+      d1g.bound() and run(d1g.read()) == (1.0, 2.0, {}) and h1b.log)
+check("its numbers are the ones the code it replaced used",
+      (d1.link_stale_s, d1.batt_bound, d1.brand)
+      == (LINK_STALE_S, BOUNDS["batt"], "GoodWe") and LINK_STALE_S == 30.0
+      and d1.settle_s == 18.0 and d1.words == {})
+
+# ==============================================================================
+print()
+print("2. what Inverter reads from its driver")
+
+NOW = datetime(2026, 11, 7, 12, 0, tzinfo=timezone.utc)
+fk = FakeDriver(host="10.9.9.9", unit_id=3)
+inv_f = Inverter("fake-a", driver=fk, max_w=2000.0)
+inv_g = Inverter("inverter-b", max_w=3000.0, **{
+    "setpoint_entity": "number.sp_b", "soc_entity": "sensor.soc_b",
+    "batt_entity": "sensor.batt_b"})
+check("an Inverter built from the old keywords gets the GoodWe driver, with "
+      "the same entities on the same attributes",
+      isinstance(inv_g.driver, GoodWeEsphomeDriver)
+      and (inv_g.setpoint_entity, inv_g.soc_entity, inv_g.batt_entity,
+           inv_g.batt_invert) == ("number.sp_b", "sensor.soc_b",
+                                  "sensor.batt_b", False))
+check("...and one given another driver has none of those entities",
+      (inv_f.setpoint_entity, inv_f.soc_entity, inv_f.batt_entity) == ("", "", ""))
+check("has_writer() is the driver's configured()",
+      inv_f.has_writer() and inv_g.has_writer()
+      and not Inverter("x", driver=FakeDriver(host="")).has_writer()
+      and not Inverter("y").has_writer())
+check("the freshness gate is built on the DRIVER's bound",
+      inv_f.batt_fresh.bound is FAKE_BOUND
+      and inv_g.batt_fresh.bound is BOUNDS["batt"])
+for u in (inv_f, inv_g):
+    u.note_write(False, NOW - timedelta(seconds=10))
+check("is_live() takes its window from the driver: 10 s of rejected writes "
+      "drops a 7 s unit and not a GoodWe one",
+      inv_f.is_live(NOW)[0] is False and inv_g.is_live(NOW)[0] is True)
+check("...and an explicit window still wins",
+      inv_f.is_live(NOW, stale_s=60.0)[0] is True
+      and inv_g.is_live(NOW, stale_s=5.0)[0] is False)
+inv_f5 = Inverter("fake-5", driver=FakeDriver(host="h"), max_w=2000.0)
+inv_f5.note_write(False, NOW - timedelta(seconds=5))
+check("link_note() says the driver's window: 'after 7 seconds' for the fake "
+      "unit, 'after 30 seconds' for the GoodWe one, and nothing for a healthy unit",
+      "after 7 seconds" in inv_f5.link_note(NOW)
+      and "after 30 seconds" in inv_g.link_note(NOW)
+      and "cannot be controlled" in inv_f.link_note(NOW)
+      and Inverter("z", driver=FakeDriver(host="h")).link_note(NOW) == "")
+check("an unconfigured unit gets the no-setpoint row, as before",
+      Inverter("x", driver=FakeDriver(host="")).link_note(NOW).startswith("x: ")
+      and Inverter("x", driver=FakeDriver(host="")).link_note(NOW)
+      == Inverter("x").link_note(NOW) != "")
+check("an entry that names a driver this build lacks is an unconfigured unit, "
+      "not a crash and not GoodWe",
+      isinstance(build_driver({"driver": "nope", "setpoint_entity": "number.x"}),
+                 UnavailableDriver)
+      and not build_driver({"driver": "nope"}).configured()
+      and build_roster({"inverters": [{"name": "n", "driver": "nope",
+                                       "setpoint_entity": "number.x",
+                                       "max_w": 1000}]}, None)[0].has_writer()
+      is False)
+
+# ==============================================================================
+print()
+print("3. a roster of one fake unit and one GoodWe unit, in a real Controller")
+
+REGISTRY["fake"] = FakeDriver
+OPTS = dict(meter_source="off", meter_entity="sensor.grid", max_w=5000,
+            gain=0.6, slew_w=0, deadband_w=15, target_grid_w=0, step_w=10,
+            heartbeat_s=10, stale_input_s=15, shadow_mode="off",
+            inverters=[
+                dict(name="fake-a", driver="fake", host="10.9.9.9", port=502,
+                     unit_id=3, max_w=2000, bms_soc_floor=10),
+                dict(name="inverter-b", setpoint_entity="number.sp_b",
+                     soc_entity="sensor.soc_b", batt_entity="sensor.batt_b",
+                     max_w=3000, bms_soc_floor=15)])
+B_ENT = {"number.sp_b", "sensor.soc_b", "sensor.batt_b"}
+
+
+def site(rating_f=1000.0, **over):
+    hass = LogHass({"sensor.grid": 3000.0, "sensor.soc_b": 50.0,
+                    "sensor.batt_b": 0.0},
+                   {"number.sp_b": (-3000.0, 3000.0, 1.0)})
+    pub = Pub()
+    c = Controller(dict(OPTS, **over), hass, MemStore(), pub,
+                   stop=asyncio.Event())
+    f = c.inverters[0].driver
+    f.rating = rating_f
+    c.inverters[0].dev_min, c.inverters[0].dev_max = -rating_f, rating_f
+    c.inverters[1].dev_min, c.inverters[1].dev_max = -3000.0, 3000.0
+    c.auto = True
+    return c, hass, pub, f
+
+
+async def cycles(c, n=6):
+    for _ in range(n):
+        await c.read_inputs()
+        await c.cycle()
+
+
+c3, h3, p3, f3 = site()
+check("the roster is built through the registry: a fake unit and a GoodWe unit",
+      isinstance(c3.inverters[0].driver, FakeDriver)
+      and isinstance(c3.inverters[1].driver, GoodWeEsphomeDriver)
+      and f3.actuator_id() == "10.9.9.9:502:3")
+run(cycles(c3))
+fa, fb = c3.inverters
+print(f"    after 6 cycles: fake-a wrote {calls(f3, 'write')}, GoodWe wrote "
+      f"{[x for m, e, x in h3.log if m == 'set_number']}, shares "
+      f"{c3.allocation.shares if c3.allocation else None}")
+check("READ: the unit's SoC and power come from its driver, the GoodWe unit's "
+      "from its entities",
+      calls(f3, "read") and fa.soc == 60.0 and fb.soc == 50.0
+      and ("number", "sensor.soc_b", False) in h3.log)
+check("WRITE: the fake unit's share went to ITS driver and the GoodWe unit's to "
+      "ITS entity, each non-zero, the same direction",
+      calls(f3, "write") and calls(f3, "write")[-1] > 0
+      and [x for m, e, x in h3.log if m == "set_number" and e == "number.sp_b"][-1] > 0)
+check("ALLOCATE: each unit holds a share inside its own rating, and the shares "
+      "are the site's (3000 W of grid, fake capped at 1000 W by its driver)",
+      c3.allocation is not None
+      and set(c3.allocation.shares) == {"fake-a", "inverter-b"}
+      and 0 < c3.allocation.shares["fake-a"] <= 1000.0
+      and 0 < c3.allocation.shares["inverter-b"] <= 3000.0
+      and calls(f3, "write")[-1] == c3.allocation.shares["fake-a"])
+check("GRADE: the fake unit's rating is the driver's range (1000 W), the "
+      "GoodWe unit's is its entry's (3000 W), each from its own source",
+      (fa.rating_w(), fb.rating_w()) == (1000.0, 3000.0))
+check("the fake's power follows its command, so the freshness gate (the fake's "
+      "own bound) lets the reading through",
+      fa.batt == calls(f3, "write")[-1] and fa.batt_fresh.bound is FAKE_BOUND)
+run(c3.send_heartbeats(10_000.0, 10.0))
+n_before = len(calls(f3, "write"))
+check("HEARTBEAT: it re-emits the fake unit's standing command through its driver",
+      n_before >= 2 and calls(f3, "write")[-1] == calls(f3, "write")[-2])
+run(c3.command_site_zero())
+check("STOP: command_site_zero() reaches the fake unit through its driver, as "
+      "0 W (the hand-back is SMA-10's, and release() has no caller yet)",
+      calls(f3, "write")[-1] == 0.0 and not calls(f3, "release"))
+c3.publish()
+print(f"    published unit rows: "
+      f"{sorted(k for k in p3.last if k.startswith('unit/'))}")
+check("PUBLISH: one set of rows per unit, with that unit's own numbers",
+      p3.last.get("unit/fake_a/soc") == 60.0
+      and p3.last.get("unit/inverter_b/soc") == 50.0
+      and "unit/fake_a/battery" in p3.last and "unit/inverter_b/battery" in p3.last)
+rows = c3.checks()
+check("STATUS: the fake unit's sensor rows are not 'unset' (its driver has a "
+      "source), and it has the control row",
+      not [r for r in rows if r.get("id") == "sensor" and not r["ok"]
+           and "fake" in r["text"]])
+# liveness: the fake's 7 s window, the GoodWe unit's 30 s
+c4, h4, p4, f4 = site()
+run(cycles(c4, 2))
+f4.accept = False                  # the fake's link is down; GoodWe's is fine
+_now = datetime.now(timezone.utc)
+for u in c4.inverters:
+    u.note_write(False, _now - timedelta(seconds=10))
+check("LIVENESS: after 10 s of rejected writes the fake unit is left out of the "
+      "split and the GoodWe unit stays in it, per its driver's window",
+      c4.live_units() == ("inverter-b",))
+run(cycles(c4, 4))
+check("...and the survivor carries the site: the allocation names only it",
+      c4.allocation is not None and set(c4.allocation.shares) == {"inverter-b"}
+      and c4.allocation.shares["inverter-b"] > 1000.0)
+# the tripwire: nothing in the world was asked about the fake unit
+asked = h3.entities() | h4.entities()
+print(f"    Home Assistant was asked about: {sorted(asked)}")
+check("TRIPWIRE: Home Assistant was only ever asked about the GoodWe unit's "
+      "entities and the meter - no empty name, no host - on read, write, "
+      "heartbeat, stop and limits alike",
+      asked <= B_ENT | {"sensor.grid"} and "" not in asked
+      and not any("10.9.9.9" in e or "fake" in e for e in asked))
+check("...and the GoodWe unit was never touched through the fake",
+      not [1 for w, a in f3.calls + f4.calls
+           if isinstance(a, str) and "number.sp_b" in a])
+
+# limits and the per-unit range check, through run_control()
+async def drive(c, secs):
+    try:
+        await asyncio.wait_for(c.run_control(), timeout=secs)
+    except asyncio.TimeoutError:
+        pass
+
+
+c5, h5, p5, f5 = site(rating_f=2500.0)
+f5.rating = 2500.0
+c5.inverters[0].dev_min = c5.inverters[0].dev_max = None
+c5.inverters[1].dev_min = c5.inverters[1].dev_max = None
+run(drive(c5, 3.0))
+check("LIMITS: run_control() reads the fake unit's range from its driver and "
+      "the GoodWe unit's from its entity",
+      calls(f5, "limits")
+      and (c5.inverters[0].dev_min, c5.inverters[0].dev_max) == (-2500.0, 2500.0)
+      and (c5.inverters[1].dev_min, c5.inverters[1].dev_max) == (-3000.0, 3000.0)
+      and [e for m, e, x in h5.log if m == "limits"] == ["number.sp_b"])
+c6, h6, p6, f6 = site()
+f6.rating = 1500.0                         # the entry says 2000 W
+c6.inverters[0].dev_min = c6.inverters[0].dev_max = None
+run(drive(c6, 10.0))
+check("RULE 2 PER UNIT: a fake unit rated above what its driver says it accepts "
+      "is refused by name, as a GoodWe one is",
+      c6.refused and any("fake-a" in p and "10.9.9.9:502:3" in p
+                         for p in c6.refused)
+      and not calls(f6, "write"))
+
+# the settings panel has no Controller: it binds each unit's driver itself
+from app import selfconfig                                    # noqa: E402
+hs = LogHass({}, {"number.sp_b": (-3000.0, 3000.0, 1.0)})
+_ps, _unread = run(selfconfig.problems_and_ranges(
+    dict(OPTS, inverters=[dict(OPTS["inverters"][0], _rating=1500.0),
+                          OPTS["inverters"][1]]), hs))
+check("PANEL: the settings panel reads the fake unit's range from its driver "
+      "and the GoodWe unit's from its entity, and grades the fake unit by name",
+      any("fake-a" in p and "10.9.9.9:502:3 accepts at most 1500" in p
+          for p in _ps)
+      and [e for m, e, x in hs.log if m == "limits"] == ["number.sp_b"]
+      and _unread == [])
+
+# the seam is the only way in: a fake-only roster touches Home Assistant for
+# nothing but the meter
+hz = LogHass({"sensor.grid": 800.0})
+cz = Controller(dict(OPTS, inverters=[OPTS["inverters"][0]]), hz, MemStore(),
+                Pub(), stop=asyncio.Event())
+cz.inverters[0].dev_min, cz.inverters[0].dev_max = -1000.0, 1000.0
+cz.auto = True
+run(cycles(cz, 3))
+check("A FAKE-ONLY ROSTER never asks Home Assistant for anything but the "
+      "meter, and still reads and writes (nothing on the control path is "
+      "keyed on a GoodWe entity)",
+      hz.entities() <= {"sensor.grid"} and calls(cz.inverters[0].driver, "read")
+      and calls(cz.inverters[0].driver, "write"))
+
+# ==============================================================================
+print()
+print("4. SAFETY-28's census counts actuator ids; rule 9 on the new keys")
+
+def entry(**kw):
+    return dict(name="u", max_w=3000, bms_soc_floor=10, **kw)
+
+
+check("GoodWe entries are counted as before: one entity named twice is one "
+      "actuator with two writers, whatever its case",
+      {k: len(v) for k, v in actuator_writers({"inverters": [
+          entry(setpoint_entity="number.X"),
+          entry(setpoint_entity=" number.x ")]}).items()} == {"number.x": 2}
+      and actuator_writers({"setpoint_entity": "number.a", "inverters": [
+          entry(setpoint_entity="number.a")]})["number.a"]
+      == ["setpoint_entity", "inverters[0].setpoint_entity"])
+cen = actuator_writers({"inverters": [
+    entry(driver="fake", host="gw", port=502, unit_id=1),
+    entry(driver="fake", host="gw", port=502, unit_id=2),
+    entry(driver="fake", host="gw", port=503, unit_id=1),
+    entry(driver="fake", host="GW", port=502, unit_id=1)]})
+print(f"    census {cen}")
+check("another driver's actuator is host:port:unit: two units behind one "
+      "gateway are two actuators, and one unit named twice is one",
+      set(cen) == {"gw:502:1", "gw:502:2", "gw:503:1"}
+      and cen["gw:502:1"] == ["inverters[0].host", "inverters[3].host"])
+check("a GoodWe key on a fake entry declares no writer there, and a `host` on "
+      "a GoodWe entry declares none",
+      actuator_writers({"inverters": [entry(driver="fake", host="gw",
+                                            setpoint_entity="number.x")]})
+      == {"gw:502:1": ["inverters[0].host"]}
+      and actuator_writers({"inverters": [entry(setpoint_entity="number.x",
+                                                host="gw")]})
+      == {"number.x": ["inverters[0].setpoint_entity"]})
+check("an entry naming a driver this build lacks still counts its setpoint "
+      "entity - refusing too much is the safe direction",
+      actuator_writers({"inverters": [entry(driver="nope",
+                                            setpoint_entity="number.q")]})
+      == {"number.q": ["inverters[0].setpoint_entity"]})
+check("census_key() folds case and space",
+      census_key(" Number.X ") == "number.x")
+
+GOOD = dict(entry(setpoint_entity="number.sp_a", soc_entity="sensor.soc_a",
+                  batt_entity="sensor.batt_a"))
+BASEOPTS = {"meter_source": "off", "meter_entity": "sensor.grid"}
+base_problems = validate_startup_config(dict(BASEOPTS, inverters=[dict(GOOD)]))
+print(f"    baseline problems for a plain GoodWe roster: {base_problems}")
+
+
+def prob(**kw):
+    return validate_startup_config(dict(BASEOPTS, inverters=[dict(GOOD, **kw)]))
+
+
+check("an existing entry (no new key) is graded exactly as before",
+      prob() == base_problems)
+check("...and so is one that says driver goodwe_esphome, or carries every new "
+      "key in a valid shape",
+      prob(driver="goodwe_esphome") == base_problems
+      and prob(driver="", host="", maintenance=False) == base_problems
+      and prob(host="inv.local", port=502, unit_id=3, maintenance=True)
+      == base_problems)
+def named(problems, key):
+    return [p for p in problems if f"inverters.{key}" in p or f"({key})" in p]
+
+
+check("only goodwe_esphome can be selected for now",
+      named(prob(driver="sma_modbus"), "driver")
+      and named(prob(driver="fake"), "driver")
+      and SELECTABLE == (DEFAULT_DRIVER,))
+check("a host with a space, a bad port or unit number and a non-boolean "
+      "maintenance are each refused by key; the right shapes are not",
+      named(prob(host="a b"), "host")
+      and named(prob(port=0), "port") and named(prob(port=70000), "port")
+      and named(prob(port="x"), "port") and named(prob(port=True), "port")
+      and named(prob(unit_id=248), "unit_id")
+      and named(prob(unit_id=1.5), "unit_id")
+      and named(prob(maintenance="yes"), "maintenance")
+      and not named(prob(port=65535, unit_id=0, host="10.0.0.1"), "port"))
+check("a GoodWe entry with no setpoint entity is refused with the same sentence "
+      "as before",
+      any("has no" in p and "setpoint entity" in p.lower()
+          for p in validate_startup_config(dict(BASEOPTS, inverters=[
+              dict(GOOD, setpoint_entity="")]))))
+fu = FakeDriver(host="gw")
+check("rule 2 grades any unit by its driver's actuator id, so a unit with no "
+      "setpoint entity is no longer skipped",
+      validate_unit_ranges([Inverter("a", driver=fu, max_w=2000.0)])
+      == [] and validate_unit_ranges([_u := Inverter("a", driver=fu,
+                                                      max_w=2000.0)]) == []
+      and (setattr(_u, "dev_max", 1000.0) or True)
+      and len(validate_unit_ranges([_u])) == 1
+      and "gw:502:1" in validate_unit_ranges([_u])[0])
+
+# ==============================================================================
+print()
+print("5. the schema")
+cfg = io.open(HERE / "config.yaml", encoding="utf-8").read()
+sch = cfg[cfg.index("\nschema:"):]
+ent = sch[sch.index("\n  inverters:"):]
+ent = ent[:ent.index("\n\n")]
+decl = dict(ln.strip().lstrip("- ").split(": ", 1)
+            for ln in ent.splitlines()[1:] if ": " in ln)
+check("setpoint_entity is optional per entry, beside driver, host, port, "
+      "unit_id and maintenance; name, max_w and bms_soc_floor stay required",
+      decl["setpoint_entity"] == "str?" and decl["driver"] == "list(goodwe_esphome)?"
+      and decl["host"] == "str?" and decl["port"] == "port?"
+      and decl["unit_id"] == "int(0,247)?" and decl["maintenance"] == "bool?"
+      and not any(decl[k].endswith("?") for k in ("name", "max_w",
+                                                  "bms_soc_floor")))
+check("config.yaml lists exactly the selectable drivers",
+      decl["driver"] == f"list({'|'.join(SELECTABLE)})?")
+
+del REGISTRY["fake"]
+
+# THE SEAM MUTANTS THIS FILE WAS RUN AGAINST (twelve, each one edit to a copy of
+# the tree; all twelve turn it red):
+#   write_unit calls hass.set_number itself           -> part 3 WRITE (and the tripwire)
+#   _read_unit calls hass.number(soc/batt entity)     -> part 3 READ
+#   run_control's limits keyed on setpoint_entity     -> part 3 LIMITS
+#   the panel's range check keyed on setpoint_entity  -> part 3 PANEL
+#   has_writer() back to bool(setpoint_entity)        -> part 2 has_writer
+#   is_live() window back to LINK_STALE_S             -> part 2 is_live
+#   link_note() window back to LINK_STALE_S           -> part 2 link_note
+#   Freshness built on BOUNDS["batt"]                 -> part 2 freshness bound
+#   _write_unit's guard keyed on setpoint_entity      -> part 3 WRITE
+#   the census back to the GoodWe key only            -> part 4 census
+#   rule 2 per unit back to .setpoint_entity          -> part 3 RULE 2 PER UNIT
+#   the status rows' source test back to the entities -> part 3 STATUS
+# NOT COVERED: the call in amain() that reads the flat setpoint entity's range
+# before any Controller exists. It runs only inside amain(), which no check
+# starts; it is two lines and the GoodWe driver's own limits(), graded in part 1.
+print()
+if fails:
+    print(f"{len(fails)} FAILED")
+    sys.exit(1)
+print("all passed")

goodwe_controller/test_translations.py

@@ -75,7 +75,7 @@ check(f"the option surface was actually read - {len(ORDER)} options, not zero",
 check("...and the repeatable `inverters:` section's per-entry keys were read "
       "too, which is the half a top-level-only reader would miss",
       NESTED.get("inverters", [])[:2] == ["name", "setpoint_entity"]
-      and len(NESTED["inverters"]) == 8)
+      and len(NESTED["inverters"]) == 13)         # SMA-2: +5 driver keys
 
 print("\n2. AC: every option and every per-entry key is translated, in BOTH "
       "languages")
@@ -281,7 +281,7 @@ check("...and the accepted subset really does round-trip the shipped files - "
       f"per-entry keys came back out of each, which is what says the "
       f"strictness above is not just refusing everything",
       all(len(TR[lg]["configuration"]) == len(ORDER)
-          and len(TR[lg]["configuration"]["inverters"]["fields"]) == 8
+          and len(TR[lg]["configuration"]["inverters"]["fields"]) == 13
           for lg in LANGS))
 print("    ⚠️ the licence for this hand parser is NOT this file. "
       "tools/supervisor_shape_probe.py section F loads the same two files with "

goodwe_controller/test_uilayout.py

@@ -51,8 +51,10 @@ def coverage_problems(order, nested):
     out += [f"{k} is not in config.yaml" for k in
             set(placed) | set(L.DERIVED) | set(L.HIDDEN) if k not in order]
     sub = [k.split(".", 1)[1] for k in KEYS if k.startswith("inverters.")]
+    # SMA-2: a per-entry key may instead be listed in L.ROSTER_HIDDEN (the
+    # driver keys the page does not draw), and then it must not also be a field.
     out += [f"inverters.{k} has no card field" for k in nested.get("inverters", [])
-            if sub.count(k) != 1]
+            if sub.count(k) + (k in L.ROSTER_HIDDEN) != 1]
     out += [f"inverters.{k} is not in config.yaml" for k in sub
             if k not in nested.get("inverters", [])]
     return out

goodwe_controller/test_ux54.py

@@ -39,7 +39,8 @@ sys.path.insert(0, os.path.join(HERE, "tools"))
 logging.disable(logging.WARNING)
 
 import ux54_scenarios as S                                        # noqa: E402
-from app import arbitrage, dayplan, dayview, homeview, modetrade   # noqa: E402
+from app import arbitrage, cheaproll, dayplan, dayview, homeview  # noqa: E402
+from app import modetrade                                          # noqa: E402
 from app import packmode, packshare, peakguard, solarfc, uitext    # noqa: E402
 from app.main import pack_energy_of                                # noqa: E402
 from app.price import Uncertainty                                  # noqa: E402
@@ -232,11 +233,19 @@ END_S = S.brussels(END).strftime("%H:%M")
 check(f"the cheap run is 01:00 to {END_S} (02:30 for this house)",
       c_n.mode_runs.cheap.start == at(1, 0, 0) and END == at(2, 30, 0))
 nb = tab(c_n, at(0, 18))["days"][0]["batteries"]
-check("in the night before the cheap run both charge from the grid in it "
-      f"(01:00 to {END_S}), then give at 17:00",
-      all([r["kind"] for r in b["blocks"]] == ["grid", "give"] for b in nb)
-      and all(b["blocks"][0]["from"] == "01:00"
-              and b["blocks"][0]["to"] == END_S for b in nb))
+# UX-77: today's block runs to where control stops charging: the 1.5 h run is
+# sized at the full rating, the peak limit leaves 3.1 kW, so control plans the
+# next run when it ends (`cheaproll`), and each battery's block ends at its stop.
+RL = cheaproll.for_today(c_n, c_n.mode_runs, at(0, 18))
+ENDS = [S.brussels(RL.end_for(inv.name, END)).strftime("%H:%M")
+        for inv in c_n.inverters]
+check("in the night before the cheap run both charge from the grid from "
+      f"01:00 to where control stops ({ENDS}, the run rolls on after "
+      f"{END_S}), then give at 17:00",
+      RL is not None and RL.end > END and ENDS[0] < ENDS[1]
+      and all([r["kind"] for r in b["blocks"]] == ["grid", "give"] for b in nb)
+      and all(b["blocks"][0]["from"] == "01:00" for b in nb)
+      and [b["blocks"][0]["to"] for b in nb] == ENDS)
 # UX-53: no grid block while the gate refuses.
 for why in ("peak", "not_worth"):
     c_n.mode_gate = why
@@ -255,12 +264,16 @@ def at_h(b, h):
 
 
 LVL_A = c_n.plan_targets()[c_n.inverters[0].name]
+END_HS = [(S.brussels(RL.end_for(inv.name, END)).replace(tzinfo=None)
+           - S.brussels(DAY0).replace(tzinfo=None)).total_seconds() / 3600.0
+          for inv in c_n.inverters]
 check(f"the curve charges in a grid block: A (planned level {LVL_A:.0f} %) "
-      "and B (Cheap hours, to the end of its run) are well above where they "
-      "were at 01:00, and stay put after the run",
-      all(at_h(b, END_H) - at_h(b, 1.0) > 8.0
-          and abs(at_h(b, END_H + 0.5) - at_h(b, END_H)) < 1e-6
-          for b in nb) and nb[0]["levels"][0][1] == 30.0)
+      "and B (Cheap hours, to the end of its block) are well above where "
+      "they were at 01:00, and stay put after the block",
+      all(at_h(b, eh) - at_h(b, 1.0) > 8.0
+          and all(abs(v - at_h(b, eh)) < 1e-6 for x, v in b["levels"]
+                  if eh + 1e-6 < x < eh + 3.0)
+          for b, eh in zip(nb, END_HS)) and nb[0]["levels"][0][1] == 30.0)
 # Modes off: the verdict's legs.
 c_f = S.make("off", at(10, 7))
 fb = tab(c_f, at(10, 7))

goodwe_controller/test_ux77.py

@@ -0,0 +1,358 @@
+"""UX-77: Home draws today's grid charge for the hours control will charge.
+
+The real `Controller._mode_roles()` and `homeview.build()`, stepped each
+minute over a flat night (the walk of the investigation): at five times, every
+minute control charges battery X in that local day lies inside X's drawn grid
+block, the block does not run past the hour control stops charging X by more
+than one slot, and the chart's cheap bars cover every hour with a charge.
+The peak-bound night is the one that needs the peak limit's room (a mutant that
+rolls at the full rating fails it, part 3); dynamic prices draw what they drew
+before (part 4). Mutations (MUTATION.md, purged copies): listed in the pull
+request. Run: python3 test_ux77.py
+"""
+import json
+import logging
+import os
+import sys
+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 ux54_scenarios as S                                       # noqa: E402
+from app import dayplan, homeview, modetrade, packmode, packshare         # noqa: E402
+from app.main import Controller                                  # noqa: E402
+from app.peakguard import PeakDecision                           # noqa: E402
+from app.static_tariff import static_plan                        # noqa: E402
+from app.store import unit_key                                   # noqa: E402
+from app.tariff import BILLING_TZ                                # noqa: E402
+
+try:                                    # not on the base, where it is red
+    from app import cheaproll
+except ImportError:
+    cheaproll = None
+
+UTC = timezone.utc
+EFF = 0.95
+AIM = 3450.0
+SLOT = timedelta(hours=1)               # the price slot of the day/night tariff
+QUARTER = timedelta(minutes=15)         # the run's own slot
+SAMPLES = ("23:30", "00:30", "01:30", "02:30", "04:30")
+OLD = ("leftover_solar", "cheap_hours")       # the owner's old shape
+NOW = ("leftover_solar", "leftover_solar")    # the current one
+PASS = FAIL = 0
+
+
+def check(name, ok, detail=""):
+    global PASS, FAIL
+    if ok:
+        PASS += 1
+    else:
+        FAIL += 1
+        print(f"FAIL {name} {detail}")
+
+
+def no_ties(h):
+    """Two dips, no two slots at the same price: nothing rolls on."""
+    return (0.05 if 1.0 <= h < 2.0 else 0.08 if 5.0 <= h < 6.0
+            else 0.30) + 0.0001 * h
+
+
+def shape(night=None):
+    d = {h: 0.973 * (600.0 if h < 6 or h >= 22 else 1200.0 if h < 10
+                     else 900.0 if h < 17 else 1800.0) for h in range(24)}
+    if night is not None:
+        for h in list(range(0, 7)) + [22, 23]:
+            d[h] = night
+    return d
+
+
+def profile(sh, now):
+    d = now.astimezone(BILLING_TZ).date()
+    return dayplan.HouseProfile({(d - timedelta(days=k)).isoformat():
+        {str(h): w for h, w in sh.items()} for k in (1, 2, 3)})
+
+
+def loc(t):
+    return t.astimezone(BILLING_TZ)
+
+
+def hm(s, day):
+    h, m = map(int, s.split(":"))
+    return day.replace(hour=h, minute=m)
+
+
+def split_by_room(w, ch, rating, wt, invs):
+    """Control's split of `w` over the chargers `ch`: by `packshare.weights()`,
+    no battery over its rating, the surplus to the others."""
+    p, open_, left = [0.0, 0.0], set(ch), w
+    while open_:
+        tot = sum(wt[invs[i].name] for i in open_)
+        over = [i for i in open_
+                if left * wt[invs[i].name] / tot > rating[i] + 1e-9]
+        if not over:
+            for i in open_:
+                p[i] = left * wt[invs[i].name] / tot
+            break
+        for i in over:
+            p[i] = rating[i]
+            left -= rating[i]
+            open_.discard(i)
+    return p
+
+
+def walk(modes, soc0, house_w, night=None, dynamic=False, samples=SAMPLES,
+         start_h=22, end_h=7, plain=None, by_room=True, fc=(10.2, 10.0)):
+    """Walk 22:00-07:15. Returns (charging, homes, commands):
+    charging[minute] = set of batteries control charges (power > 0),
+    homes[sample] = Home's `/status` plan at that minute, commands = the
+    (minute, unit, role, size) control gave."""
+    opts = dict(S.BASE)
+    opts.update(battery_modes_enabled=True,
+                pv_forecast_entities=[f"{S.FC1}_{i}" for i in range(3)],
+                pv_forecast_tomorrow_entities=[f"{S.FCT1}_{i}"
+                                               for i in range(3)],
+                static_profile=json.dumps(S.DN), arbitrage_enabled=False,
+                arbitrage_soc_floor=20, arbitrage_soc_ceiling=95,
+                cycle_cost_threshold_eur=0.04)
+    c = Controller(opts, S.Hass(), S.Store(), S.Pub(), stop=S.asyncio.Event())
+    c.auto = True
+    soc = list(soc0)
+    caps = [inv.capacity_kwh for inv in c.inverters]
+    rating = [inv.max_w for inv in c.inverters]
+    for i, inv in enumerate(c.inverters):
+        inv.batt, inv.last_write = 0.0, 0.0
+        inv.dev_min, inv.dev_max = -5000.0, 5000.0
+        c.store.data[unit_key(inv.name, packmode.MODE_KEY)] = modes[i]
+    c.pv_w = 0.0
+    c.peak_guard = PeakDecision(engaged=False, floor_w=None, ceiling_w=7000.0,
+                                ceiling_from="cap", projected_w=800.0)
+    start = datetime(2026, 11, 1, start_h, 0, tzinfo=BILLING_TZ).astimezone(UTC)
+    end = datetime(2026, 11, 2, end_h, 15, tzinfo=BILLING_TZ).astimezone(UTC)
+    c.house_profile = profile(shape(night), start)
+    now, plan_at = start, None
+    charging, homes, cmds = {}, {}, []
+    while now < end:
+        lt = loc(now)
+        today, tomorrow = fc if lt.hour < 12 else fc[::-1]
+        c.solar_fc = S.forecast(now, today, tomorrow, members=3)
+        c.solar_fc_why = None
+        if plan_at is None or (now - plan_at).total_seconds() >= 1800:
+            c.tariff_plan = (S.quarters(now, dynamic) if dynamic else
+                             static_plan(opts, now, now + timedelta(hours=48),
+                                         now=now))
+            plan_at = now
+        c.tariff_at = plan_at
+        for i, inv in enumerate(c.inverters):
+            inv.soc = round(soc[i], 1)
+        room = AIM - house_w
+        c.arb_headroom_w = room
+        c.grid = house_w
+        tick = c._mode_roles(now, None)
+        size = modetrade.size(tick, (-sum(rating), sum(rating)), room) \
+            if tick.action else 0.0
+        ch = [i for i, inv in enumerate(c.inverters)
+              if tick.roles.get(inv.name) == modetrade.CHARGE]
+        p = [0.0, 0.0]
+        if size < 0 and ch:
+            if by_room:     # as control: room left to full, rating caps
+                wt = packshare.weights(c.pack_energy, -1.0)
+                p = split_by_room(-size, ch, rating, wt, c.inverters)
+            else:
+                tot = sum(rating[i] for i in ch)
+                for i in ch:
+                    p[i] = -size * rating[i] / tot
+        for i in range(2):
+            soc[i] = min(100.0, soc[i] + p[i] / 1000.0 / 60.0 * EFF
+                         / caps[i] * 100.0)
+        charging[lt.replace(second=0, microsecond=0)] = {
+            i for i in range(2) if p[i] > 0.0}
+        cmds.append((lt.strftime("%H:%M"), tick.action,
+                     tuple(sorted(tick.roles.items())), round(size)))
+        if lt.strftime("%H:%M") in samples:
+            homes[lt.replace(second=0, microsecond=0)] = homeview.build(
+                c, level="ok", checks=[], now=now, lang="en")
+            if plain is not None:           # the same, with no roll
+                real = cheaproll.for_today
+                cheaproll.for_today = lambda *_a: None
+                try:
+                    plain[lt.replace(second=0, microsecond=0)] = \
+                        homeview.build(c, level="ok", checks=[], now=now,
+                                       lang="en")
+                finally:
+                    cheaproll.for_today = real
+        now += timedelta(minutes=1)
+    return charging, homes, cmds
+
+
+def blocks_of(st, i):
+    """Battery i's drawn grid blocks as (start, end) local datetimes."""
+    return [(loc(datetime.fromisoformat(r["start"])),
+             loc(datetime.fromisoformat(r["end"])))
+            for r in st["plan"]["runs"]
+            if r["kind"] == "grid" and r["battery"] == i]
+
+
+def today_of(st, i):
+    return [(t["from"], t["to"]) for t in st["batteries"][i]["today"]]
+
+
+def violations(charging, homes, slot=SLOT):
+    """What is wrong with Home's drawing at each sample."""
+    bad = []
+    for t, st in sorted(homes.items()):
+        day_end = (t.replace(hour=0, minute=0) + timedelta(days=1))
+        mins = {m: who for m, who in charging.items() if t <= m < day_end}
+        for i in range(2):
+            mine = sorted(m for m, who in mins.items() if i in who)
+            bl = blocks_of(st, i)
+            for m in mine:
+                if not any(a <= m < z for a, z in bl):
+                    bad.append(f"{t:%H:%M} battery {i}: charges at "
+                               f"{m:%H:%M}, not in a block {bl}")
+                    break
+            if mine:
+                stop = mine[-1] + timedelta(minutes=1)
+                if slot == QUARTER:         # the last charging quarter's end
+                    stop += timedelta(minutes=-stop.minute % 15)
+                for a, z in bl:
+                    if z > stop + slot:
+                        bad.append(f"{t:%H:%M} battery {i}: block to "
+                                   f"{z:%H:%M}, stops {stop:%H:%M}")
+            # the Today line says the same as the block
+            tl = today_of(st, i)
+            for m in mine:
+                if not any(f <= m.strftime("%H:%M") < (z if z != "24:00"
+                           else "99") for f, z in tl):
+                    bad.append(f"{t:%H:%M} battery {i}: Today line {tl} "
+                               f"has no {m:%H:%M}")
+                    break
+        cheap = {b["label"][:2] for b in st["plan"]["prices"]
+                 if b["kind"] == "cheap"}
+        for m in mins:
+            if mins[m] and m.strftime("%H") not in cheap:
+                bad.append(f"{t:%H:%M}: charge at {m:%H:%M}, hour not cheap")
+                break
+    return bad
+
+
+# --------------------------------------------------------------------------- #
+# Run
+# --------------------------------------------------------------------------- #
+def show(tag, ch, homes, want_bad, slot=SLOT):
+    bad = violations(ch, homes, slot)
+    if want_bad:
+        check(f"{tag}: red", bool(bad), "no violation found")
+    else:
+        check(f"{tag}: every charging minute is drawn, no block runs on",
+              not bad, "\n  " + "\n  ".join(bad))
+    return bad
+
+
+def charged(ch, i, after):
+    return [m for m, who in ch.items() if i in who and m >= after]
+
+
+def main():
+    global cheaproll
+    if cheaproll is None:
+        print("no app/cheaproll.py: the base; the walk is red there")
+        cheaproll = type("Off", (), {"for_today": staticmethod(lambda *a: None)})
+
+    print("1. the walk: no-bind (0.6 kW house) and peak-bound (2.85 kW house)")
+    CASES = (("old shape, no bind", OLD, (20.0, 20.0), 584.0, None),
+             ("current shape, no bind", NOW, (20.0, 20.0), 584.0, None),
+             ("old shape, peak-bound", OLD, (40.0, 90.0), 2850.0, 2850.0),
+             ("current shape, peak-bound", NOW, (40.0, 90.0), 2850.0, 2850.0))
+    # the rig's checks 2 and 3 (UX-77 round 2): room left and rating disagree
+    UNEQUAL = (("unequal levels, A+B Leftover solar, no bind", NOW,
+                (30.0, 20.0), 584.0, None, (5.0, 5.0)),
+               ("unequal levels, A Leftover solar + B Cheap hours", OLD,
+                (40.0, 88.0), 2850.0, 2850.0, (10.2, 10.0)))
+    walked = {}
+    for tag, modes, soc, hw, night in CASES:
+        ch, homes, _cmds = walk(modes, soc, hw, night=night)
+        walked[tag] = (ch, homes)
+        show(tag, ch, homes, False)
+        # the check has something to check: charging goes on past 00:30
+        day = datetime(2026, 11, 2, 0, 30, tzinfo=BILLING_TZ)
+        check(f"{tag}: control charges after 00:30", bool(
+            charged(ch, 0, day) or charged(ch, 1, day)))
+
+    print("2. a battery with nothing to charge gets no block")
+    ch, homes, _c = walk(OLD, (40.0, 94.0), 2850.0, night=2850.0)
+    st = homes[datetime(2026, 11, 2, 2, 30, tzinfo=BILLING_TZ)]
+    check("B is at its level at 02:30: no block", blocks_of(st, 1) == [],
+          str(blocks_of(st, 1)))
+    check("A still has one at 02:30", bool(blocks_of(st, 0)))
+
+    print("3. a roll at the full rating fails the peak-bound night")
+    if hasattr(cheaproll, "_Charge"):
+        real = cheaproll._Charge._room_w
+        cheaproll._Charge._room_w = lambda self, hour, total: total
+        try:
+            for tag, modes, soc, hw, night in CASES[2:]:
+                ch, homes, _c = walk(modes, soc, hw, night=night)
+                show(f"mutant, {tag}", ch, homes, True)
+        finally:
+            cheaproll._Charge._room_w = real
+
+    print("4. dynamic prices: Home is what it was")
+    for tag, modes, soc, hw, night in (CASES[2], CASES[3], CASES[1]):
+        plain = {}
+        ch, homes, _c = walk(modes, soc, hw, night=night, dynamic=no_ties,
+                             plain=plain)
+        same = all(json.dumps(homes[t], sort_keys=True, default=str)
+                   == json.dumps(plain[t], sort_keys=True, default=str)
+                   for t in homes)
+        check(f"dynamic, {tag}: same as with no roll", same)
+        check(f"dynamic, {tag}: and there are grid blocks to compare",
+              any(r["kind"] == "grid" for st in homes.values()
+                  for r in st["plan"]["runs"]))
+
+    print("5. unequal levels: the roll shares the room as control does")
+    for tag, modes, soc, hw, night, fc in UNEQUAL:
+        ch, homes, _c = walk(modes, soc, hw, night=night, fc=fc)
+        show(tag, ch, homes, False, QUARTER)
+        day = datetime(2026, 11, 2, 0, 30, tzinfo=BILLING_TZ)
+        check(f"{tag}: control charges after 00:30", bool(
+            charged(ch, 0, day) or charged(ch, 1, day)))
+    if hasattr(cheaproll, "_Charge") \
+            and hasattr(cheaproll._Charge, "_shares"):
+        real = cheaproll._Charge._shares
+        cheaproll._Charge._shares = lambda self, ch, w: {
+            p.name: w * abs(p.rating_w) / sum(abs(q.rating_w) for q in ch)
+            for p in ch}
+        try:
+            for tag, modes, soc, hw, night, fc in UNEQUAL:
+                ch, homes, _c = walk(modes, soc, hw, night=night, fc=fc)
+                show(f"mutant by rating, {tag}", ch, homes, True, QUARTER)
+        finally:
+            cheaproll._Charge._shares = real
+
+    print("6. the pieces")
+    if hasattr(cheaproll, "Roll"):
+        t = datetime(2026, 11, 2, 1, 46, tzinfo=UTC)
+        check("a stop is rounded up to the slot", cheaproll._ceil_slot(t)
+              == datetime(2026, 11, 2, 2, 0, tzinfo=UTC))
+        t = datetime(2026, 11, 2, 1, 45, tzinfo=UTC)
+        check("a stop on a slot stays", cheaproll._ceil_slot(t) == t)
+        e0 = datetime(2026, 11, 2, 0, 0, tzinfo=UTC)
+        e1 = datetime(2026, 11, 2, 6, 0, tzinfo=UTC)
+        r = cheaproll.Roll(e1, {"a": None, "b": datetime(2026, 11, 2, 2, 0,
+                                                         tzinfo=UTC)})
+        check("a battery still charging ends at the roll", r.end_for("a", e0) == e1)
+        check("a battery at its level ends at its stop",
+              r.end_for("b", e0) == datetime(2026, 11, 2, 2, 0, tzinfo=UTC))
+        check("a battery that does not charge keeps the run's end",
+              r.end_for("c", e0) == e0)
+        check("the chart's bar runs to the last block", r.last(e0) == e1)
+
+    print(f"\n{PASS} passed, {FAIL} failed")
+    return FAIL
+
+
+if __name__ == "__main__":
+    sys.exit(1 if main() else 0)

goodwe_controller/tools/safety128_rig.py

@@ -0,0 +1,284 @@
+#!/usr/bin/env python3
+"""SAFETY-128: the REAL Controller with Home Assistant readings arriving late.
+
+    python3 tools/safety128_rig.py            # prints a few runs' summaries
+
+The plant is TEST-23's (SAFETY-127 rig, t127_plant.py): two batteries
+(A 5 000 W, B 4 600 W) that ramp at 5 000 W/s and then follow a 1 s lag; each
+battery reading is published every 10 s (A at :x6, B at :x1.6); the meter every
+2 s; the house is `house` W plus seeded +-`noise` W, new each second.
+
+`p1_s` sets the meter's period, `dead_s` a command dead time (SAFETY-75's
+laggy battery), `units` one battery ("a") or two.
+
+Home Assistant runs `lag_s` seconds behind (a number, or a function of t) between `lag_on` and `lag_off`:
+every reading the add-on gets (meter, battery power, battery level) is the
+one published `lag_s` seconds earlier. When the lag starts, nothing new comes
+for `lag_s` seconds, then the backlog; when it stops, the readings jump to
+now. Commands reach the plant at once (t127_shim.py's lag mode).
+
+The add-on reads every 1 s and runs a cycle on a new meter value or after
+`cycle_floor_s`, as `run_control()` does. Uses only the Controller API that
+release/1.0 77fe31b has, so the same file runs on the tree before SAFETY-128.
+"""
+
+import asyncio
+import math
+import os
+import random
+import sys
+import tempfile
+import time
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import app.main as m                                      # noqa: E402
+from app.main import Controller                           # noqa: E402
+from app.p1 import make_sample, split_signed              # noqa: E402
+
+# 18:00 local (CET) on a weekday: the evening give run.
+BASE = datetime(2026, 11, 4, 17, 0, tzinfo=timezone.utc)
+UNITS = ("a", "b")
+MAXW = {"a": 5000.0, "b": 4600.0}
+CAPWH = {"a": 15360.0, "b": 20480.0}
+PHASE = {"a": 6.0, "b": 1.6}
+BPER = 10.0
+P1PER = 2.0
+RAMP = 5000.0
+LAG = 1.0
+
+def options(units=UNITS):
+    o = dict(OPTIONS)
+    o["inverters"] = [
+        {"name": f"inverter-{u}", "setpoint_entity": f"number.sp_{u}",
+         "soc_entity": f"sensor.soc_{u}", "batt_entity": f"sensor.batt_{u}",
+         "max_w": int(MAXW[u]), "bms_soc_floor": 10,
+         "capacity_kwh": CAPWH[u] / 1000.0} for u in units]
+    return o
+
+
+OPTIONS = {
+    "meter_entity": "sensor.grid", "meter_source": "ha_signed",
+    "p1_net_entity": "sensor.grid", "meter_phases": 1, "meter_max_age_s": 30,
+    "peak_cap_w": 3500, "peak_margin_w": 50, "peak_soc_floor": 20,
+    "gain": 0.6, "slew_w": 0, "target_grid_w": -10, "deadband_w": 15,
+    "step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
+    "cycle_floor_s": 15, "saturation_w": 500, "saturation_cycles": 3,
+    "auto_start": True, "battery_modes_enabled": False,
+    "arbitrage_enabled": False, "bms_soc_floor": 10,
+}
+
+
+class _Store:
+    def __init__(self):
+        from app.store import DEFAULTS
+        self.data = dict(DEFAULTS)
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get_time(self, k):
+        v = self.data.get(k)
+        return datetime.fromisoformat(v) if v else None
+
+    def set_time(self, k, when):
+        self.data[k] = when.isoformat() if when else None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+class Plant:
+    """The batteries, their registers and the meter, in 0.1 s steps."""
+
+    def __init__(self, house, noise, seed, soc, cut=None, units=UNITS,
+                 p1_s=P1PER, dead_s=0.0):
+        self.house_fn, self.noise, self.seed = house, noise, seed
+        self.units, self.p1_s, self.dead_s = units, p1_s, dead_s
+        self.cut = cut or (lambda u, t: False)
+        self.cmd = {u: 0.0 for u in units}
+        self.queue = []                       # (t, unit, command), dead time
+        self.tgt = {u: 0.0 for u in units}
+        self.act = {u: 0.0 for u in units}
+        self.soc = {u: float(soc) for u in units}
+        self.reg = {u: 0.0 for u in units}
+        self.slot = {u: None for u in units}
+        self.p1 = None
+        self.p1_n = 0
+        self.t = 0.0
+        self.house = float(house(0.0))
+        self.hist = []          # (t, p1 value, p1 index, {reg}, {soc})
+
+    def grid(self):
+        return self.house - sum(self.act.values())
+
+    def advance(self, t):
+        while self.t < t - 1e-9:
+            self.t = round(self.t + 0.1, 6)
+            sec = int(math.floor(self.t + 1e-9))
+            rs = random.Random(self.seed * 1000003 + sec)
+            self.house = (float(self.house_fn(self.t))
+                          + rs.uniform(-self.noise, self.noise))
+            while self.queue and self.queue[0][0] <= self.t + 1e-9:
+                _t, u, v = self.queue.pop(0)
+                self.cmd[u] = v
+            for u in self.units:
+                want = max(-MAXW[u], min(MAXW[u], self.cmd[u]))
+                if self.cut(u, self.t):
+                    want = 0.0
+                if self.soc[u] <= 10.0 and want > 0:
+                    want = 0.0
+                if self.soc[u] >= 100.0 and want < 0:
+                    want = 0.0
+                d = want - self.tgt[u]
+                self.tgt[u] += math.copysign(min(abs(d), RAMP * 0.1), d)
+                self.act[u] += ((self.tgt[u] - self.act[u])
+                                * (1 - math.exp(-0.1 / LAG)))
+                self.soc[u] = max(0.0, min(100.0, self.soc[u] - self.act[u]
+                                           * 0.1 / 3600.0 / CAPWH[u] * 100.0))
+                slot = math.floor((self.t - PHASE[u]) / BPER + 1e-9)
+                if slot != self.slot[u]:
+                    self.slot[u] = slot
+                    self.reg[u] = float(round(self.act[u]))
+            if abs(self.t / self.p1_s - round(self.t / self.p1_s)) < 1e-6:
+                self.p1 = round(self.grid(), 1)
+                self.p1_n += 1
+            self.hist.append((self.t, self.p1, self.p1_n, dict(self.reg),
+                              {u: round(v, 2) for u, v in self.soc.items()}))
+        del self.hist[:-3000]
+
+    def view(self, t, lag_s, lag_on, lag_off):
+        """What Home Assistant shows at `t`: (p1, p1 index, regs, socs)."""
+        lag_s = lag_s(t) if callable(lag_s) else lag_s
+        if lag_s and lag_on <= t < lag_off:
+            want = max(lag_on, t - lag_s)
+            for row in reversed(self.hist):
+                if row[0] <= want + 1e-9:
+                    return row[1:]
+            return self.hist[0][1:]
+        return (self.p1, self.p1_n, dict(self.reg),
+                {u: round(v, 2) for u, v in self.soc.items()})
+
+
+class _Hass:
+    def __init__(self, rig):
+        self.rig = rig
+
+    async def limits(self, e):
+        return (-MAXW[e[-1]], MAXW[e[-1]], 1.0)
+
+    async def call(self, *a):
+        return True
+
+    async def state(self, e):
+        return None
+
+    async def number(self, e, invert=False):
+        _p1, _n, regs, socs = self.rig.seen
+        u = e[-1]
+        if e.startswith("sensor.soc"):
+            return socs[u]
+        if e.startswith("sensor.batt"):
+            return regs[u]
+        return None
+
+    async def set_number(self, e, v):
+        p = self.rig.plant
+        p.queue.append((p.t + p.dead_s, e[-1], float(v)))
+        self.rig.writes.append((self.rig.plant.t, e[-1], float(v)))
+        return True
+
+
+class Rig:
+    def __init__(self, house=1800.0, noise=50.0, seed=90, soc=60.0,
+                 lag_s=0.0, lag_on=0.0, lag_off=0.0, extra=None, cut=None,
+                 start=BASE, units=UNITS, p1_s=P1PER, dead_s=0.0):
+        house_fn = house if callable(house) else (lambda t, h=house: h)
+        self.plant = Plant(house_fn, noise, seed, soc, cut, units, p1_s,
+                           dead_s)
+        self.lag = (lag_s, lag_on, lag_off)
+        self.o = dict(options(units), **(extra or {}))
+        self.start = start
+        self.writes = []
+        self.rows = []
+        self.seen = None
+
+    def run(self, dur, sample=None):
+        """Run `dur` s. Rows: (t, true grid, site command, site actual,
+        loop reason, controller reason). `sample(rig, c, t)` per second."""
+        async def go():
+            db = os.path.join(tempfile.mkdtemp(prefix="s128-"), "tariff.db")
+            c = Controller(self.o, _Hass(self), _Store(), _Pub(),
+                           stop=asyncio.Event(), peak_db_path=db)
+            for i in c.inverters:
+                i.dev_min, i.dev_max = -MAXW[i.name[-1]], MAXW[i.name[-1]]
+            c.auto = True
+            self.c = c
+            real_dt = m.datetime
+            clock = [self.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 = _DT
+            floor = float(self.o.get("cycle_floor_s", 15))
+            last_grid, last_cycle, last_n = object(), None, None
+            try:
+                t = 0.0
+                while t < dur:
+                    self.plant.advance(t)
+                    now = self.start + timedelta(seconds=t)
+                    clock[0] = now
+                    self.seen = self.plant.view(t, *self.lag)
+                    p1, n = self.seen[0], self.seen[1]
+                    if p1 is not None and n != last_n:
+                        last_n = n
+                        imp, exp = split_signed(p1)
+                        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)
+                    if (c.grid != last_grid or last_cycle is None
+                            or t - last_cycle >= floor):
+                        last_grid, last_cycle = c.grid, t
+                        await c.cycle()
+                    self.rows.append((
+                        t, self.plant.grid(), sum(self.plant.cmd.values()),
+                        sum(self.plant.act.values()), c.loop_reason,
+                        c.reason))
+                    if sample is not None:
+                        sample(self, c, t)
+                    t += 1.0
+            finally:
+                m.datetime = real_dt
+            return c
+        return asyncio.run(go())
+
+
+def summary(rows, t0, t1):
+    """Over [t0, t1): (min cmd, max cmd, min grid, max grid, s of export
+    below -200 W, s below -1 000 W)."""
+    sel = [r for r in rows if t0 <= r[0] < t1]
+    return (min(r[2] for r in sel), max(r[2] for r in sel),
+            min(r[1] for r in sel), max(r[1] for r in sel),
+            sum(1 for r in sel if r[1] < -200), sum(1 for r in sel
+                                                   if r[1] < -1000))
+
+
+if __name__ == "__main__":
+    for lag in (0.0, 10.0, 30.0):
+        r = Rig(lag_s=lag, lag_on=300.0, lag_off=450.0)
+        r.run(600.0)
+        print(f"lag {lag:4.0f} s: before {summary(r.rows, 200, 300)}")
+        print(f"            during {summary(r.rows, 300, 450)}")
+        print(f"            after  {summary(r.rows, 480, 600)}")

goodwe_controller/tools/supervisor_shape_probe.py

@@ -243,8 +243,6 @@ show("the per-entry BASELINE is ACCEPTED, so every refusal below has nowhere "
      "else to come from", ok, json.dumps(out.get("inverters")) if ok else out)
 for title, entry, expect in (
         ("no name", {k: v for k, v in D_FULL.items() if k != "name"}, "name"),
-        ("no setpoint_entity",
-         {k: v for k, v in D_FULL.items() if k != "setpoint_entity"}, "setpoint_entity"),
         ("no max_w", {k: v for k, v in D_FULL.items() if k != "max_w"}, "max_w"),
         ("no bms_soc_floor (SAFETY-32)",
          {k: v for k, v in D_FULL.items() if k != "bms_soc_floor"}, "bms_soc_floor"),
@@ -257,6 +255,40 @@ for title, entry, expect in (
 ok, out = validate(dict(D_BASE, inverters="[]"))
 show("a JSON STRING where the list belongs is refused", not ok, out)
 
+print("\n== K. SMA-2: the driver keys on an inverter entry ==")
+# `setpoint_entity` is OPTIONAL per entry since SMA-2 (it is the GoodWe driver's
+# own key; validate.py rule 9(d) requires it for GoodWe), beside `driver`,
+# `host`, `port`, `unit_id` and `maintenance`. Same method as §D: an ACCEPTED
+# baseline, ONE value varied, the refusal asserted on the KEY'S NAME.
+K_FULL = dict(D_FULL, driver="goodwe_esphome", host="inverter.local", port=502,
+              unit_id=1, maintenance=False)
+ok, out = validate(dict(D_BASE, inverters=[K_FULL]))
+show("an entry carrying every new key is ACCEPTED, and the keys survive",
+     ok and all(out["inverters"][0].get(k) == K_FULL[k]
+                for k in ("driver", "host", "port", "unit_id", "maintenance")),
+     json.dumps(out.get("inverters")) if ok else out)
+ok, out = validate(dict(D_BASE, inverters=[D_FULL]))
+show("an entry from before SMA-2 (none of the new keys) is ACCEPTED unchanged",
+     ok and out["inverters"] == [D_FULL], out)
+ok, out = validate(dict(D_BASE, inverters=[
+    {k: v for k, v in D_FULL.items() if k != "setpoint_entity"}]))
+show("an entry with NO setpoint_entity is now accepted by the schema "
+     "(rule 9(d) refuses it for GoodWe, at startup)", ok, out)
+# ⚠️ THE SUPERVISOR'S REFUSAL NAMES THE VALUE'S RULE, NOT THE KEY, FOR A NESTED
+# ENTRY (§D's "at most 5000"), so the expectation is that rule's own words.
+for title, entry, expect in (
+        ("driver other than goodwe_esphome", dict(K_FULL, driver="sma"),
+         "one of ['goodwe_esphome']"),
+        ("port 0", dict(K_FULL, port=0), "at least 1"),
+        ("port 70000", dict(K_FULL, port=70000), "at most 65535"),
+        ("unit_id 248", dict(K_FULL, unit_id=248), "at most 247"),
+        ("host a number", dict(K_FULL, host=5), "expected str"),
+        ("maintenance a word that is not a boolean",
+         dict(K_FULL, maintenance="banana"), "boolean")):
+    ok, out = validate(dict(D_BASE, inverters=[entry]))
+    show(f"an entry with {title} is refused, with the rule's own words",
+         (not ok) and expect in str(out), out)
+
 
 print("\n== E. the ROLLBACK direction, and the operator's UI ==")
 # The old (flat) schema, i.e. what an operator would be running after a

goodwe_controller/translations/en.yaml

@@ -79,6 +79,21 @@ configuration:
       capacity_kwh:
         name: "Usable battery capacity (kWh) (optional)"
         description: "This battery's usable capacity from its datasheet. Fill it in on every inverter or on none. The add-on then shares the work by the energy each battery has left."
+      driver:
+        name: "Inverter type (optional)"
+        description: "The kind of inverter. Leave it empty for a GoodWe."
+      host:
+        name: "Inverter address (optional)"
+        description: "Not used yet. Leave it empty."
+      port:
+        name: "Inverter port (optional)"
+        description: "Not used yet. Leave it empty."
+      unit_id:
+        name: "Inverter unit number (optional)"
+        description: "Not used yet. Leave it empty."
+      maintenance:
+        name: "Battery maintenance (optional)"
+        description: "Not used yet. Leave it empty."
   estop_fitted:
     name: "Hardware · RS485 emergency stop is fitted"
     description: "Switch this on if the emergency stop is installed. It only changes a warning on the status page."

goodwe_controller/translations/nl.yaml

@@ -60,6 +60,21 @@ configuration:
       capacity_kwh:
         name: "Bruikbare capaciteit (kWh) (optioneel)"
         description: "De bruikbare capaciteit van deze batterij, van het datablad. Vul ze bij elke omvormer in of bij geen. Dan verdeelt de add-on het werk volgens de energie in elke batterij."
+      driver:
+        name: "Type omvormer (optioneel)"
+        description: "Het soort omvormer. Laat leeg voor een GoodWe."
+      host:
+        name: "Adres van de omvormer (optioneel)"
+        description: "Nog niet in gebruik. Laat leeg."
+      port:
+        name: "Poort van de omvormer (optioneel)"
+        description: "Nog niet in gebruik. Laat leeg."
+      unit_id:
+        name: "Eenheidsnummer van de omvormer (optioneel)"
+        description: "Nog niet in gebruik. Laat leeg."
+      maintenance:
+        name: "Onderhoud van de batterij (optioneel)"
+        description: "Nog niet in gebruik. Laat leeg."
   estop_fitted:
     name: "Hardware · RS485-noodstop is geplaatst"
     description: "Zet dit aan als de noodstop geïnstalleerd is. Het verandert alleen een waarschuwing op de statuspagina."