goodwe-addon/goodwe_controller/DECISIONS/UX-04-the-configuration-tab-and-the-defaults-pin.md

# UX-04 — what the Configuration tab renders, and the pin that was never built

**Status: DECIDED 2026-09-07.** Three decisions and one confirmation, in the
order [[UX-01]]'s unmet acceptance criteria are numbered:

1. **UX-01 AC 3 (hide the optional fields behind HA's toggle) is WITHDRAWN as
   unsatisfiable**, not deferred. The target was arithmetically unreachable, and
   the part of it that *was* reachable would be bought with the upgrade path.
   The measurement is now **graded** in `tools/supervisor_shape_probe.py` §F
   rather than printed, so the withdrawal cannot be quietly reversed.
2. **UX-01 AC 4's third clause is now BUILT**: `test_defaults_pin.py`, an AST
   check, with its red direction executed on every run.
3. **UX-01 AC 5 / the CFG-04 double-literal hole is CONFIRMED CLOSED on
   `release/1.0`, by [[UX-02]]'s `bcee235`, not by UX-01's `fef6ef2`.** The
   attribution is corrected here; no work was re-done.
4. **The 8 per-entry `inverters:` translations STAY.** They do not reach the
   Supervisor tab and cannot be made to; [[UX-02]]'s ingress panel is where they
   become visible.

Filed with UX-04. Card `6a9ec94617e9c48ed74ca5dd`. Every number below was
measured on `release/1.0` at `6e7b233` on 2026-09-07, against
`ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0` — the version
`ha info` reports on the live install — and against the 26-file check suite in
`goodwe-addon-checks:1`. Nothing here contacted the live Supervisor at
192.168.2.158, posted options, or restarted anything.

---

## 1. Hiding: withdrawn, and why that is the *safe* answer

### 1.1 What AC 3 claimed

> "The visible count drops to ~15, with the rest behind HA's *show unused
> optional configuration options* toggle."

### 1.2 What the tab actually renders

`config.yaml` declares **71 keys under `options:` and the same 71 under
`schema:`**. The set that HA's toggle is *able* to hide — schema-only keys — is
therefore **empty**:

```
    hideable = set(schema) - set(options)  ->  []        (0 of 71)
```

On the deployed 0.7.0 tree the same measurement is 70/70. Nothing was hidden
before UX-01, nothing is hidden after it, and no line of `fef6ef2` moved a key
either way. AC 3 is not partially met; it is unstarted.

### 1.3 The rule that decides it, replayed rather than paraphrased

From the frontend bundle shipped **in this image**,
`api/panel/frontend_latest/5680.*.js` (frontend 20250925.1):

```js
_filteredSchema = (opts, schema) => schema.filter(e => e.name in opts || e.required)
```

`opts` is the add-on's options **as Supervisor serves them** — the operator's
stored blob after `options:` has been deep-merged into it. So a field is hidden
only when it is **both** absent from `options:` **and** not `required`. The
probe now runs that filter on this manifest rather than quoting it.

### 1.4 Reason one: the target was never reachable

Supervisor's own `UiOptions` marks `required` on **59** of the 71 fields; 12 are
optional. The filter above shows a required field unconditionally. So the
**floor** — what the tab renders with `options:` emptied *altogether*, which is
the most hiding that is even expressible — is 59 fields.

| `options:` block | fields rendered |
|---|---|
| as shipped (71 keys) | **71** |
| emptied entirely (0 keys) | **59** |
| AC 3's target | ~15 |

AC 3 asked for a number roughly four times below the floor. No arrangement of
`options:` reaches it. The criterion could not have been met by any
implementation; it was mis-specified, and the honest disposal of a
mis-specified criterion is withdrawal, not a partial gesture toward it.

### 1.5 Reason two: the 12 hides that *are* expressible cost the deep-merge

Moving a key out of `options:` is not free. `App.options` is
`deepmerge(config.yaml defaults, the stored user options)`, so **a key absent
from `options:` has no default for the Supervisor to merge**.

That is exactly the mechanism the 0.9.0 upgrade rests on. From `CHANGELOG.md`,
the pre-deploy check run against this release on 2026-09-07:

> The reference install's stored blob has **70 keys, not 71**.
> `delivery_hold_s` arrived with SAFETY-42 in 0.8.0, so an install running
> 0.7.0 has never stored it — and it is REQUIRED in the schema, no trailing
> `?`, which is the shape that becomes **exit 78**. It resolves to its
> `options:` default of **185** because the Supervisor deep-merges.

Hiding a key is done by taking it *out* of `options:` and marking it `?`. That
is, precisely, the edit that removes a key's merge default — the thing standing
between a 0.7.0 box and exit 78 on upgrade. It would be traded for at most 12
fewer rows on a form, on a site where the add-on is holding a real house's grid
exchange at zero.

### 1.6 Reason three: it would promote 27 unpinned literals to load-bearing

And the cost compounds with §2 of this document. `test_defaults_pin.py` part 4
ledgers **27 (module, key) pairs** in `app/` that still answer a missing option
with an in-code literal. Today those literals are unreachable on a Supervisor
install, because the deep-merge guarantees every `options:` key is present in
the served blob. Remove keys from `options:` to hide them and those literals
stop being dead code: they become **the actual source of the defaults on a live
install** — the CFG-03 defect the same card's AC 4 exists to police, made
load-bearing by the card's own AC 3.

### 1.7 What now grades this

`tools/supervisor_shape_probe.py` §F. The count was printed there from the day
it was written — *"the Configuration tab renders 71 fields"* — and the probe
exited 0 through UX-01's whole review while displaying the number that
contradicted the criterion it was evidence for. **A measurement that is
displayed but not asserted is how this passed review.** Three assertions
replace the bare print:

```
PASS  every one of the 71 `schema:` keys is ALSO in `options:`, so schema-only
      - the only set HA's toggle can hide - is EMPTY. Hideable: []
PASS  ...so replaying the frontend's own _filteredSchema on the served options
      hides NOTHING: 71 of 71 fields render
PASS  ...and with `options:` EMPTIED ENTIRELY - the maximum hiding that is
      expressible - the tab still renders 59 required fields. THAT is the
      floor, and AC 3 asked for ~15.
```

Every number in them is computed from the manifest and from Supervisor's own
`required` flag; none is typed. **The red direction was run**: deleting one key
(`price_feed_url`) from `options:` and nothing else turns the first two to FAIL
— `Hideable: ['price_feed_url']`, `70 of 71 fields render` — and the probe
exits 1. The counterfactual is isolated: one key varied, nothing else.

So if a future editor empties `options:` to shorten the form, this goes red and
somebody has to read §1.5 before merging.

---

## 2. The defaults pin: `test_defaults_pin.py`

### 2.1 What AC 4 asked for and what shipped

AC 4 has three clauses.

| clause | state before UX-04 |
|---|---|
| "every `schema:` key absent from `options:` has exactly one defaults-table entry" | **vacuous** — that set is empty (§1.2), so the clause is true of any tree, including one with no defaults at all |
| "the table changed → red" | **works**, six times over, once per mirror in its own suite |
| "no module carries its own literal fallback for a schema default — an AST check, not a grep" | **never built** |

The only literal scan in the repository before this card is
`test_validate.py:1025`: a `re.findall` restricted to eight `maintenance_*`
keys across three named files. It is a grep, it predates UX-01, and it was not
written for this.

### 2.2 What an "in-code literal fallback" is, structurally

A call in `app/` taking a string literal that names a `schema:` key, with a
constant in the next positional slot:

```python
opts.get("max_w", 2000)            _number(opts, "max_w", 2000.0)
```

Found by walking `ast.Call` nodes — so a multi-line call and a renamed `opts`
are found, and the same text inside a comment or docstring is not. Two
exclusions, both structural and both argued at the site:

* **`getattr(obj, "max_w", 0.0)`** reads an attribute off an object, not an
  option off a blob. Excluded by callee name.
* **the empty string.** `opts.get("static_profile", "")` is Python's "not
  stated", and all six such sites in `validate.py` normalise it immediately —
  `str(opts.get(k, "") or "").strip()`. It cannot be a stale copy of a *number*,
  which is the whole of the CFG-04 defect class. Excluded by value. **`0` is
  not excluded**: `slew_w: 0` and `integrator_max_w: 0` are real shipped
  defaults with real meanings.

### 2.3 What it grades, measured on `release/1.0` @ `6e7b233`

```
2. the mirrors, DISCOVERED from the tree rather than listed here
    6 table(s): circulation.py:CIRC_OPTION_DEFAULTS, delivery.py:DELIVERY_OPTION_DEFAULTS,
                maintenance.py:MAINT_OPTION_DEFAULTS, peakguard.py:PEAK_OPTION_DEFAULTS,
                price.py:PRICE_OPTION_DEFAULTS, watchdog.py:SIGN_OPTION_DEFAULTS
    30 mirrored key(s) of 71 in `schema:`
3. the AST scan
    scanned 29 modules, 34 literal fallback site(s): 0 over mirrored keys,
    34 over unmirrored ones
4. the CFG-03 ledger
    27 (module, key) pair(s) carry a literal for a key no mirror answers for
```

Four properties, none of them vacuous:

1. **The mirrors are discovered, not listed.** Six suites already pin their own
   table to `config.yaml` — and every one of those pins names its table by
   hand, so a *seventh* table added tomorrow would be pinned by nobody and
   nothing would say so. This walks `app/` for module-level `*_OPTION_DEFAULTS`
   assignments and grades whatever it finds against `config.yaml`. That is the
   property the six hand-written pins cannot have.
2. **No literal survives for a key a mirror already answers for.** 30 keys,
   0 violations.
3. **The CFG-03 ledger is FROZEN, by (module, key) pair, not by count.** A
   count goes green again the moment somebody deletes one site and adds
   another. Line numbers are deliberately *not* in the key: a ledger that goes
   red on an unrelated reformat is a ledger people learn to re-bless without
   reading. The 27 pairs are the open CFG-03 backlog; they are **not** removed
   here, because that is behaviour change across `main.py`, `p1.py`,
   `inverter.py` and `validate.py` that no single card should make in passing.
   The set can now only shrink.
4. **Every remaining literal is graded against `config.yaml`** — the half that
   catches CFG-04's actual failure mode, two copies of one number and one moves.

### 2.4 One divergence found, and it is new

```
      main.py  target_grid_w: code 0 vs config.yaml -10
```

`main.py:290` reads `target_grid_w=float(opts.get("target_grid_w", 0))` while
`config.yaml` ships **-10**. A dict handed to `Controller` without the key holds
net exchange at 0 W instead of the shipped -10 W bias into import. **It cannot
reach an operator**: on a Supervisor install the deep-merge guarantees the key
is present, and the only paths that hand over a partial dict are
`sim/inject.py` and this repository's own fixtures. It is recorded in the check
as the single permitted divergence, with the reason, rather than corrected —
changing it alters the control loop's target and belongs to a card that grades
the loop. A *second* divergence goes red.

### 2.5 ⭐ The red direction, shown rather than claimed

A check that has never been shown failing is not a check — which is exactly
what clause one of this AC was. Two things follow from that:

**(a) The red direction runs on every invocation.** Part 5 feeds the scanner a
synthetic module containing a deliberate violation of each rule and *requires*
it to be flagged, in-process, through the same `literal_fallbacks()` the graded
parts call. A scanner that goes blind — a renamed helper, an `ast` change, a
`SCHEMA` that comes back empty — stops working here too, and the total site
count is additionally graded against a floor.

**(b) A literal was planted in the real tree and the check went red.** Planted
at `main.py:290`, `float(opts.get("maintenance_charge_w", 2000))` — a mirrored
key:

```
3. the AST scan: no module carries its own literal fallback for a MIRRORED schema default
    scanned 29 modules, 35 literal fallback site(s): 1 over mirrored keys, 34 over unmirrored ones
  ok   the scanner is not blind: it found 35 sites (floor 20)
      main.py:290  get('maintenance_charge_w', 2000)
  FAIL no literal fallback survives for any of the 30 keys a mirror already
       answers for - those sites must index the mirror

1 FAILED     (exit 1)
```

And part 4's two directions, planted the same way with
`opts.get("p1_host", "x")` and `opts.get("slew_w", 999)`:

```
4. the CFG-03 ledger
    28 (module, key) pair(s) carry a literal for a key no mirror answers for
  FAIL no NEW module/key pair has started carrying a literal fallback [('main.py', 'p1_host')]
      main.py  p1_host: code 'x' vs config.yaml ''
      main.py  slew_w: code 999 vs config.yaml 0
      main.py  target_grid_w: code 0 vs config.yaml -10
  FAIL every remaining literal still AGREES with config.yaml, except the 1
       divergence(s) recorded above it

     (exit 1)
```

The second of those is the CFG-04 defect class itself: a literal that has
drifted away from `config.yaml` while the file still says something else. Both
plants were removed; the tree is byte-identical to `6e7b233` apart from this
card's own files.

---

## 3. CFG-04: closed on `release/1.0`, by UX-02, not by UX-01

UX-01's AC 5 claimed the double-literal `max_w` hole. It did not close it.
`fef6ef2` touched `config.yaml`, `translations/`, `test_translations.py` and the
probe — **no defaults code at all** — and on the 0.7.0 tree the triple mutation
survives: 21 files, 0 RED.

**Confirmed on current `release/1.0` @ `6e7b233`, 2026-09-07.** The same triple
mutation, `2000 -> 2500` at the three descendants of 0.7.0's
`inverter.py:438` / `validate.py:383` / `validate.py:684`:

| 0.7.0 | `release/1.0` @ `6e7b233` |
|---|---|
| `inverter.py:438` `max_w=float(opts.get("max_w", 2000))` | `inverter.py:640` `raw = opts.get("max_w", 2000)` |
| `validate.py:383` `cap = _number(opts, "max_w", 2000.0)` | `validate.py:466`, same line |
| `validate.py:684` `max_w = _number(opts, "max_w", 2000.0)` | `validate.py:836`, same line |

Result — 26 files, **RED at `test_selfconfig.py`**, exit 1:

```
1 FAILED: ⚠️ CLEARING max_w ON THE LIVE SHAPE IS REFUSED - rule 10 catches the
rail collapsing to the 2000 default under an explicit 400 W slew, so the box
cannot be emptied into a quietly halved rail
```

`git log -L 310,325:goodwe_controller/test_selfconfig.py` attributes that check
to **`bcee235`, "UX-02: pin both halves of the max_w fix, because neither was
graded", glenn schrooyen, 2026-09-06** — not to UX-01. The hole ships closed
with the pending 0.9.0 deploy. **The AC is met by UX-02.** No work was re-done
here; the mutation was run once, on a throwaway copy, to confirm it.

---

## 4. The 8 per-entry translations: they stay

### 4.1 The measurement, and it is negative

`translations/{en,nl}.yaml` carry a name and a description for all 8 per-entry
keys of the repeatable `inverters:` section. They are loaded by Supervisor's own
loader, they pass `SCHEMA_APP_TRANSLATIONS`, and `test_translations.py` grades
their coverage. **They do not reach the screen**, and this is not a defect in
them. `UiOptions` gives `inverters` `type: "schema"` with `multiple: True`, and
the frontend's `_convertSchemaElement` sends exactly that case to a selector
rather than to a nested `ha-form`:

```js
if ("schema" === t.type && !t.multiple) return {...type:"expandable"...}   // not us
if ("schema" === t.type) { const o = {}; for (const a of t.schema)
    o[a.name] = {required: a.required, selector: ...}; return {object:{multiple:t.multiple, fields:o}} }
```

and `ha-selector-object` labels those fields `fields[name].label || name`, while
`_convertSchemaElementToSelector` sets **neither `label` nor `translation_key`**.
So an operator sees raw `name`, `setpoint_entity`, `max_w`, `bms_soc_floor`. The
probe already asserts this, negatively and by name.

### 4.2 Decision: keep them. Four reasons.

1. **The Supervisor tab cannot be made to render them.** The gap is in
   somebody else's converter, not in this repository. There is no change here
   that fixes it; deleting the translations does not fix it either.
2. **[[UX-02]]'s ingress panel is where they become visible**, and it renders
   the roster itself rather than handing it to `ha-selector-object`. The
   `fields:` block is the shape Supervisor's own schema defines for exactly
   this, and it is what a surface that wires `label` through consumes.
3. **They cost nothing.** No runtime path reads them; they are two YAML blocks
   in files the Supervisor already parses, and the parse is graded green.
4. **Deleting them would remove the only thing that catches a per-entry key
   added without a translation.** `test_translations.py` grades top-level and
   per-entry coverage symmetrically; drop the per-entry half and SAFETY-32's
   `bms_soc_floor` — a *required* per-entry key added after UX-01 — would have
   joined the roster with no label and nothing to say so.

This is a written decision, not a change. The tree is unmodified in
`translations/`.

### 4.3 Not re-filed

`tools/supervisor_selfapi_probe.py` has been known red since OPT-09 — it
hardcodes `len(_sub) == 7` against 8 per-entry keys. That is **TOOL-04**,
already filed, and it is not re-filed or fixed here. It is named only so a
reader of §4.1 knows why the *other* probe is the one quoted.

---

## 5. What this card did not do

* It did not remove a key from `options:`. See §1.5 — the deep-merge default is
  what makes the pending 0.9.0 upgrade safe on a 0.7.0 box.
* It did not pay down the 27-pair CFG-03 ledger. See §2.3.
* It did not correct `main.py`'s `target_grid_w` fallback. See §2.4.
* It did not touch `translations/`. See §4.2.
* It did not re-do CFG-04. See §3.
* It did not touch hardware, the live Home Assistant at 192.168.2.158, or
  `sim/`. Both probe runs were throwaway containers over a read-only mount.