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

Merged

admin merged 2 commits from CFG-04 into release/1.0 2026-09-04 11:51:58 +02:00

Conversation 1 Commits 2 Files Changed 13

+2090 -120

2 Commits

Author	SHA1	Message	Date
glenn schrooyenandClaude Opus 5	22c016fadd	CFG-04 fix round: the probe now measures the key it is cited for ... Review blocked this on ONE finding, and it was in the EVIDENCE, not the code. The design and the shipped behaviour are unchanged. THE INSTRUMENT DID NOT MEASURE WHAT FOUR DOCUMENTS SAID IT MEASURED tools/supervisor_shape_probe.py section B validated the RECONSTRUCTED LIVE options blob - which is missing many required keys that have nothing to do with this card. Its refusal therefore named whichever of THOSE the validator reached first: the committed transcript recorded `meter_freeze_s`, the reviewer's run printed `p1_phase_export_entities`, and a run today printed `sign_disagree_w`. The string those documents quoted - `Missing option 'inverters' in root` - was never produced by the instrument. And section B asserted a bare `not ok`. Any refusal at all satisfied it, so deleting `inverters: []` from config.yaml left it printing PASS: the probe could not detect the one regression it is the committed evidence for. THE UNDERLYING CLAIM IS TRUE AND IS NOW MEASURED PROPERLY Section B is an ISOLATED COUNTERFACTUAL now: the full shipped `options:` block (expect accept), and the SAME block with `inverters` removed and nothing else varying (expect refusal). One key differs, so the refusal has nowhere else to come from - and the assertion is on the KEY NAME IN THE REFUSAL STRING, so the line goes red if the refusal is ever about a different key. The probe also exits non-zero when any case fails; without that a transcript is only evidence to someone who reads it. The old live-blob case survives as section B2, relabelled for what it is: an incomplete reconstruction whose RAW half is refused for unrelated missing keys, kept because its MERGED half genuinely demonstrates what App.options is. VERIFIED BY BREAKING IT, WHICH IS THE WHOLE POINT `inverters: []` deleted from config.yaml, probe re-run against ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0: == B. THE LOAD-BEARING ONE: an options blob with no `inverters` key == FAIL the shipped `options:` block validates AS IT STANDS - ... Missing option 'inverters' in root in GoodWe RS485 Controller ... == 2 CASE(S) FAILED == exit 1. Key restored, same image, same command: `== all cases passed ==`, exit 0. The transcript in DECISIONS is that restored run, re-run today, not the old one. THE FOUR MIS-CITATIONS DECISIONS/CFG-04-inverter-roster.md section 4's "section B shows both halves" sentence and its line-103 transcript; CHANGELOG.md; test_inverter.py's part-9 comment and its part-12 mutation row; and the PR description. All now attribute the string to section B and say plainly what section B2 does not show. The part-12 row additionally records that the probe was blind to that mutation until review, because a mutation table that lists a defeat nothing catches is the failure this repository keeps finding. MUTATION.md gains it as the sixth instance of "the check's data cannot reach the failure it names" - the first found OUTSIDE the suite, in a committed evidence artifact, because nothing in that document had ever been pointed at tools/. Three habits with it: assert on the CONTENT of a refusal rather than that one happened; vary ONE thing, from an ACCEPTED baseline; and treat a committed transcript as a check subject to the mutation battery. TWO NON-BLOCKING FINDINGS, ALSO FIXED validate.py rules 5 and 6 NAMED THE WRONG INVERTER. `unit_caps()` SKIPS an entry with no usable `max_w`, so caps position i stops being roster position i the moment one entry is malformed - and rule 5 fed `caps.index(weakest)` to `_unit_label()`, which indexes the roster, while rule 6 paired `caps[0]` with a hard-wired `_unit_label(opts, 0)`. Right number, another inverter's name: an operator sent to the wrong device by the message that exists to stop that. New `unit_caps_indexed()` carries the roster index with the cap. It is latent - rule 9(d) refuses such a config in the same pass - but that was a property of today's rule ordering, not of the code, and validate_startup_config() is also sim/inject.py's entry point. Part 10 gains a check that asserts the fixture really does desynchronise the two lists, then that both messages name the right unit, then the counterfactual: the OLD expressions, on that same config, still evaluate to the wrong names. DOCS.md called a downgrade "safe". True of the SCHEMA - the older schema drops the key with a warning - and incomplete about the ADD-ON: rule 9(e) requires the flat `setpoint_entity` be cleared when a roster is declared, so a config that downgrades cleanly is by construction one whose flat actuator is blank, and the older version has nothing to write to. Confirmed by running release/1.0's own validate_startup_config() on that blob: one refusal, naming setpoint_entity. Recoverable and loud, but an outage until a field is refilled. The note says so now, and tells the operator to write the entity down before downgrading. 19/19 green in the goodwe-addon-ci image. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-04 10:33:51 +02:00
adminandClaude Opus 5	6b85acb0f1	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	2026-09-04 04:29:45 +02:00