CFG-04: an operator can declare a second inverter, and the shape was measured

DEV-02 made every per-device value per-instance - rating, SoC, watchdogs,
heartbeat, store keys - so the code stopped assuming one inverter. The options
schema did not. `build_roster()` returned a list of exactly one and said so in
its own docstring, and there was no `inverters:` key for an operator to write,
so the roster could only ever be a roster of one.

THE SHAPE, AND WHY IT WAS MEASURED RATHER THAN CHOSEN

config.yaml had no list-of-objects anywhere, and `static_profile` carries a
whole tariff structure as a JSON string in a `str?` precisely because a nested
schema was doubted. That is a question about somebody else's software, so it was
answered by running it: `tools/supervisor_shape_probe.py` (committed) runs
Supervisor 2026.08.0's OWN `AppOptions` validator and `SCHEMA_APP_CONFIG`, out
of the release image, against this repository's config.yaml. 2026.08.0 is the
version the live install reports. The full transcript and the argument are in
DECISIONS/CFG-04-inverter-roster.md.

It accepts the list, enforces per-entry types, refuses a missing `name` /
`setpoint_entity` / `max_w` BY NAME, renders the option in the UI as a
repeatable section, and drops the key with a warning under an older schema - so
a downgrade is not the forward trap in reverse.

⚠️ AND THE `inverters: []` DEFAULT IS LOAD-BEARING, WHICH IS THE MEASUREMENT
THAT MATTERED MOST. Supervisor answers `Missing option 'inverters' in root` for
an options blob that has no such key - which every existing install's has, since
the key did not exist when they were written. `App.options` is the shipped
`options:` block deep-merged with the operator's stored one, so the empty
default is the difference between an upgrade nobody notices and an add-on that
cannot start with a schema pinned to the version that would fix it. That is
docs/deploy-rollback.md §4's trap in the FORWARD direction, found before it was
sprung. The merger was checked too: lists override rather than concatenate, so a
non-empty default could not have grown a roster behind the operator's back.

NOTHING IS INHERITED, WHICH IS DEV-02 RESTATED AS A CONFIG RULE

`name`, `setpoint_entity` and `max_w` are required of every entry. An entry that
omits `soc_entity` has no SoC sensor; it does not borrow the flat one. A
three-line fallback would have rebuilt the sibling-grading defect DEV-02 spent a
card removing, in YAML. Defaults still live in exactly one place (CFG-03):
there is no per-entry default anywhere, because there is no optional per-entry
number. A flat `setpoint_entity` left set beside a declared roster is refused
rather than ignored - it names an actuator nothing will write.

TWO PERMISSIVE READERS IN SHIPPED CODE, AND THREE MORE IN THE CHECKS

  validate.py rules 5 and 6 compared their thresholds against the FLAT `max_w`.
  At a roster of two 2000 W units with `max_w: 5000` left over from a
  single-inverter install, `sign_disagree_w: 3000` passed rule 5 while
  SAFETY-02's watchdog could fire on NEITHER unit - rule 5's own failure mode,
  reached through rule 5. They read `unit_caps()` now, which at one inverter is
  `[max_w]` exactly.

  main.py's `run_control()` re-ran the device-rating check behind
  `if self.o.get("setpoint_entity")` - the flat key, which a roster leaves blank
  - so on a two-inverter site no inverter's `max_w` was graded against the
  device it is written to, and the skip was silent. `validate_unit_ranges()`
  grades each unit against its own ESPHome and runs unconditionally.

  test_peakguard.py's `read_option()` and `_schema_bound()` and
  test_inverter.py's `read_schema_max()` matched a STRIPPED line and took the
  first hit, so the nested per-inverter `max_w:` began outranking the flat one -
  silently, and correctly, because the two bounds are the same int(100,5000)
  today. A reader that is right by coincidence is this project's named failure
  mode. All three are anchored at exactly two spaces now; the file's two halves
  disambiguate `peak_cap_w` instead of first-match, and an ambiguous key raises
  rather than picking one. test_tariff.py's copy of the idiom went with them.

THE AUDIT IS A CHECK, NOT A PROMISE

test_inverter.py part 11 finds every config.yaml-reading function in the suite -
transitively, because two of the readers CFG-04 had to change never name the
file - EXECUTES each against a synthetic two-inverter config.yaml whose
per-inverter numbers differ from its flat ones, and fails if any answers with
the per-inverter value. The table is not maintained by hand: the signature
decides, so the eleventh reader is named on its first run. config.yaml declares
`inverters:` BEFORE `max_w:` on purpose and part 11 asserts that ordering, so
the trap stays baited.

SAFETY-28's `actuator_writers()` needed no change - it was already a structural,
case-folding census - but until now there was no configuration in which two
writers on one actuator could be WRITTEN DOWN. There is now, and it is refused.

VERIFIED BY BREAKING IT

Ten mutations run through tools/mutation_run.sh and observed red, listed in
test_inverter.py part 12 with the check that bites each. Two survived the first
run and the CHECKS were changed, not the table: the inheritance check had blank
flat keys, so "inherited" and "not inherited" were the same empty string; and
the `run_control()` check asserted a SOURCE LINE was present, which re-indenting
it does not remove. Both are recorded in MUTATION.md's "the check's data cannot
reach the failure it names" section, which now carries two more habits: assert
on behaviour rather than on source text, and give a check whose failure mode is
a hang a deadline.

19/19 green in the goodwe-addon-ci image. The one-inverter path is byte-
identical: the whole existing suite runs unmodified against it.

Version bumped to 0.6.0 - the Supervisor keys the built image by `version:`, so
a schema change without a bump is a schema nobody reads.

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

goodwe_controller/app/main.py

@@ -52,7 +52,8 @@ from .hass import 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
 # window an operator would look up here is the one the roster actually uses.
-from .inverter import LINK_STALE_S, UNIT_A, build_roster
+from .inverter import (LINK_STALE_S, UNIT_A, build_roster,
+                       roster_entries)
 from .maintenance import IDLE, MaintConfig, Maintenance
 from .mqtt import MqttPublisher
 from . import peakguard
@@ -61,7 +62,8 @@ from .price import Uncertainty, price_option
 from .static_tariff import resolve_tariff, static_status
 from .tariff import PeakStore, PeakTracker
 from .store import migrate_unit_keys
-from .validate import ConfigRefused, refuse, validate_startup_config
+from .validate import (ConfigRefused, refuse, validate_startup_config,
+                       validate_unit_ranges)
 from .watchdog import SignWatchdogConfig, loop_is_following
 from . import web
 
@@ -177,6 +179,24 @@ class Controller:
         )
         self.store_migration = migrate_unit_keys(store, UNIT_A)
         self.inverters = build_roster(opts, store, sign_cfg)
+        # ⚠️ CFG-04. SAY WHICH SHAPE IS IN FORCE, BECAUSE THE OTHER ONE'S KEYS
+        # ARE STILL SITTING IN THE UI. A declared `inverters:` roster reads none
+        # of `soc_entity`, `batt_entity`, `batt_invert` or `max_w`, and an
+        # operator looking at the Configuration page sees all four with values
+        # in them. validate.py rule 9(e) refuses the one that is genuinely
+        # dangerous - a flat `setpoint_entity` naming an actuator nothing will
+        # write - and the rest cannot be refused (the schema gives them no blank
+        # value), so they are DISCLOSED instead: one line in §15's action log,
+        # at every start, naming the roster it built and the keys it ignored.
+        # Silence here is how "the site is running at half the rating I typed"
+        # takes a week to notice.
+        if roster_entries(opts):
+            self.log_event(
+                "roster: %d inverters from `inverters:` - %s. The flat "
+                "soc_entity / batt_entity / batt_invert / max_w keys are NOT "
+                "read in this shape; each entry carries its own."
+                % (len(self.inverters),
+                   ", ".join(f"{i.name} {i.max_w:.0f} W" for i in self.inverters)))
 
         self.tuning = Tuning(
             gain=float(opts.get("gain", 0.6)),
@@ -2386,37 +2406,47 @@ class Controller:
                     inv.setpoint_entity)
         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
+        # exists to remove: a max_w above the device's rating meant
+        # write_setpoint() silently clamped and the configured ceiling was
+        # never the real one.
+        #
+        # amain() already ran this gate before anything started. It runs
+        # AGAIN here for one case the gate cannot cover: ESPHome is often
+        # not up yet when the add-on boots, so hass.limits() returned
+        # (None, None) and the range checks were skipped rather than
+        # guessed at. This is the first moment the device's real rating is
+        # known. If it conflicts, refuse now - stopping deterministically
+        # through the normal shutdown, which commands 0 W on the way out.
+        #
+        # ⚠️⚠️ AND THE `if entity:` THAT USED TO WRAP THE WHOLE BLOCK WAS A
+        # READER THAT FAILED PERMISSIVE - CFG-04's own hazard, in this file.
+        # `entity` is the FLAT `setpoint_entity`, which a per-inverter config
+        # leaves blank (validate rule 9(e) requires it), so on the very config
+        # this add-on now supports the entire re-check was SKIPPED: no
+        # inverter's `max_w` was ever graded against the device it is written
+        # to, and the skip was silent. The flat gate still guards the flat
+        # rules, because they read flat options and one device's range; the
+        # per-unit rule runs unconditionally, off the roster, and grades each
+        # unit against ITS OWN ESPHome. At one inverter `validate_unit_ranges()`
+        # skips the unit the flat call already graded, so nothing is reported
+        # twice and the N=1 path is unchanged.
+        problems = []
         if entity:
-            # ⚠️ THIS USED TO WARN AND CARRY ON, and that was the bug CFG-01
-            # exists to remove: a max_w above the device's rating meant
-            # write_setpoint() silently clamped and the configured ceiling was
-            # never the real one.
-            #
-            # amain() already ran this gate before anything started. It runs
-            # AGAIN here for one case the gate cannot cover: ESPHome is often
-            # not up yet when the add-on boots, so hass.limits() returned
-            # (None, None) and the range checks were skipped rather than
-            # guessed at. This is the first moment the device's real rating is
-            # known. If it conflicts, refuse now - stopping deterministically
-            # through the normal shutdown, which commands 0 W on the way out.
-            # ⚠️ GRADED AGAINST THE FIRST UNIT'S RANGE, because `validate.py`
-            # grades the FLAT options - `max_w`, `setpoint_entity` - which are
-            # unit A's. A per-unit validator arrives with CFG-04's per-unit
-            # options; inventing one here would be this file asserting a schema
-            # for a config that does not exist yet.
             _first = self.inverters[0]
-            problems = validate_startup_config(self.o, _first.dev_min,
-                                               _first.dev_max)
-            if problems:
-                refuse(problems)
-                self.refused = problems
-                self.log_event("REFUSED: " + problems[0])
-                # Signal, then return WITHOUT entering the loop. amain() wakes
-                # on this, runs the normal wind-down (which commands 0 W) and
-                # re-raises ConfigRefused afterwards, so the exit code is 78 and
-                # the inverter is left at zero rather than latched.
-                self.stop_event.set()
-                return
+            problems += validate_startup_config(self.o, _first.dev_min,
+                                                _first.dev_max)
+        problems += validate_unit_ranges(self.inverters, skip_entity=entity)
+        if problems:
+            refuse(problems)
+            self.refused = problems
+            self.log_event("REFUSED: " + problems[0])
+            # Signal, then return WITHOUT entering the loop. amain() wakes
+            # on this, runs the normal wind-down (which commands 0 W) and
+            # re-raises ConfigRefused afterwards, so the exit code is 78 and
+            # the inverter is left at zero rather than latched.
+            self.stop_event.set()
+            return
 
         last_grid = object()
         heartbeat = float(self.o.get("heartbeat_s", 10))