goodwe-addon/goodwe_controller/DECISIONS/UX-02-two-config-surfaces.md

# UX-02 — two configuration surfaces, one blob, and which one is authoritative

**Status: DECIDED 2026-09-06 — the STORED OPTIONS BLOB is authoritative and
neither user interface is.** The ingress panel is the surface an operator
should normally use, because it is the only one that can show the add-on's
cross-field refusals *before* a save. The Supervisor's Configuration tab stays,
unchanged, and is the **recovery** surface: it is the only one of the two that
still exists when the add-on is not running.

Filed with UX-02. Card 6a9afc52d4e3662463274e9d. Depends on [[UX-01]], which is
not superseded by this — see §4.

---

## 1. The question

The owner asked, 2026-09-04: *"can't we use some kind of webUI in HA to have a
cleaner config with custom styling?"* Yes — `config.yaml` already declares
`ingress: true`, `ingress_port: 8099` and `hassio_api: true`, and the panel is
live. But building a second editor for the same settings creates a question the
first one never had: **when two surfaces can write one blob, which one is
right?**

Getting that wrong is not a cosmetic problem. `POST /addons/self/options`
*replaces* the stored user options, so a page that writes a blob it read five
minutes ago silently reverts whatever the other surface did in between.

## 2. What was measured, not assumed

All of it out of `ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0` —
the version this site runs — by `tools/supervisor_selfapi_probe.py`, which runs
Supervisor's own code rather than re-reading it. It touches nothing: no
Supervisor is contacted, no options are posted and nothing is restarted.

**(a) An add-on may read and write its own options, and needs no role.**
`_V1_PATTERNS.api_bypass` was run against the exact paths. `/addons/self/info`,
`/addons/self/options` and `/addons/self/restart` all match; `security` and
`update` do not. `token_validation()` tests that bypass *before* it consults
`access_hassio_api` or any role, so no `hassio_role` is involved.

Two results the card did not predict, and both changed the design:

* `/addons/self/options/validate` — Supervisor's **own** options validator — is
  **not** reachable: it is two path segments after `self`, so `[^/]+` cannot
  match it, and it is not one of the listed literals. There is exactly one
  validator an add-on can call from inside itself, and it is `app/validate.py`.
  Which is the one we want: Supervisor's knows only types and ranges.
* `/addons/self/info` is admitted by the `default` role *as well as* by the
  bypass (`/.+/info`), while `/addons/self/options` and `/addons/self/restart`
  are admitted by the **bypass only**. The two *writing* paths rest on that one
  list. The first draft of the probe asserted that the role admitted none of
  the three, and it went red — which is why the split is written down here.

**(b) `POST …/options` replaces; an omitted key reverts to the config.yaml
default.** `App.options` is `deepmerge(config defaults, persisted user
options)`, and the setter is `persist[options] = deepcopy(value)`. Run on real
objects: with `max_w: 4200` stored, a POST that simply omits `max_w` leaves the
effective value at **2000**, config.yaml's default — not at 4200.

That is why the panel posts the **whole** blob it read, and why it refuses to
post one built on a stale read.

**(c) Validation does not coerce.** The full merged blob goes through
`AppOptions` unchanged, key for key. That is what makes the panel's *"stored
but not running"* comparison honest: a difference shown is a difference that
exists.

**(d) The Configuration tab *can* be removed — and doing so destroys every
setting on the site.** The card said it cannot be. It can: `schema:` is
optional, a manifest without it is accepted, and `schema_ui` is then `[]`, so
the tab renders nothing. What goes with it is the add-on. `AppOptions` drops
every option the schema does not declare — **0 of 71 survive** — so
`/data/options.json` becomes `{}`, the controller starts with no actuator, the
startup gate refuses it (exit 78), and the ingress panel goes down with the
process serving it.

So the tab stays **by decision, not by constraint**. That distinction matters:
a constraint nobody re-examines is not a decision, and this one has a cost
(§4) that has to be paid knowingly.

## 3. The decision

> **The authoritative configuration is the options blob the Supervisor stores.
> Both surfaces are editors of it. Neither is a cache of the other, and neither
> owns a copy of anything.**

Consequences, in the order they bind:

1. **The panel never holds state.** Every page load re-reads
   `GET /addons/self/info`. There is no local copy of the options, the schema
   or the labels — the form is *built* from that response by
   `app/configui.py`, which contains no option key, no label and no rule.
2. **A save is a compare-and-swap.** The read hands the page a
   `fingerprint()` (a sha256 of the canonical blob); the save hands it back;
   `selfconfig.save()` re-reads the stored blob **immediately before writing**
   and refuses if the digest moved. The window in which the other surface can
   slip a change past is one HTTP round trip, not the length of an editing
   session.
3. **Validation happens before the compare, and a refused blob is never
   written.** Not warned about — not written.
4. **Saving never restarts.** Applying options costs a control interruption
   (§5), so it is a separate, explicitly confirmed act.

### Why a digest and not a version number

The Supervisor exposes no revision or ETag for an add-on's options. The only
thing a page can hold between reading and writing is the *content* it read —
and that is enough, because the question is not "how many times has this
changed" but "is what I am about to overwrite still what I was shown".
Identical content is by definition safe to overwrite.

### This is [[SAFETY-28]]'s discipline, applied to configuration

`arbiter.py` and `Controller.write_refusal()` enforce *exactly one writer per
actuator* not by convention but by a check on the write path:

> A NUMBER REACHES THE WIRE ONLY IF THE SINGLE ALLOCATOR PLACED IT, ON THIS
> TICK, FOR THIS UNIT.

The configuration analogue is written the same way and for the same reason:

> A BLOB REACHES THE SUPERVISOR ONLY IF IT WAS DERIVED FROM THE BLOB THAT IS
> STORED RIGHT NOW.

Note what is *not* claimed. SAFETY-28's rule makes a second writer
inexpressible; this one does not — the Supervisor's tab is a second writer and
stays one. What this gets is the weaker, honest property: **a second writer is
detected rather than silently overwritten.** That is the most a
compare-and-swap can give, and pretending otherwise would be the "check that
observes something other than what it claims to observe" this repository keeps
finding.

## 4. What this costs, stated plainly

**Two surfaces means two places to be confused.** The Configuration tab still
renders all 71 keys as a flat list, and it can still store a configuration the
add-on will refuse to start on — it knows only types and ranges. UX-01's
translations are therefore **not** superseded by this card: they are the only
thing standing between that tab and raw key names, and they are also where this
panel's labels, descriptions and section headings come from. The two surfaces
share one set of words on purpose; two vocabularies for one setting would be
worse than one plain list.

**The panel is not available when it is most needed.** If a configuration that
refuses to start is ever stored — from the Configuration tab, or by a hand-edit,
or by this panel in some future state it does not currently permit — the add-on
exits 78 and the panel goes with it. Recovery is the Configuration tab. That is
the reason it stays, and the reason the panel refuses to write a blob the
validator rejected: this surface must never be the thing that removes itself.

*Amended by [[UX-15-setup-only-mode]] (2026-09-28):* one refused configuration
keeps the panel: options that name no inverter at all and have no other
refusal, which is what a new install ships. The add-on then serves the page in
setup-only mode and commands nothing. Every other refusal still exits 78.

**The panel shows fewer refusals than the startup gate can, never more.** Two
of `validate.py`'s rules compare a configured ceiling against the setpoint
device's *own* reported range, which is only knowable by asking Home Assistant.
When ESPHome is asleep the range is `None` and those two rules are skipped —
here and at startup, identically. The page says so rather than looking green
for a reason the operator cannot see.

## 5. The restart cost, and why it is a separate button

Applying options needs a restart, and `Controller.shutdown()` commands **0 W on
every inverter** on the way out ("shutting down - commanding 0 W on every
inverter", main.py). A configuration save is therefore a real, if brief, loss
of control of the battery — and the operator is told that *before* they commit,
in the page's own markup, not in a message that appears afterwards.

So the panel splits the act in two:

* **Save** stores the blob. Nothing restarts, nothing is applied, and the page
  then says which settings are stored but not running.
* **Restart to apply** asks again, names the 0 W again, and only then posts
  `/addons/self/restart`. The request carries an intent token, so a reload, a
  retry or a stray POST cannot spend a control interruption on the operator's
  behalf.

A restart does **not** clear anything: SAFETY-02's latches are restored from
the Store on the way back up, which is what `Inverter.__init__` is written to
do and what [[SAFETY-38]] depends on.

## 6. The scope line, and it is a safety line

**Nothing on this surface commands an inverter, clears a latch or bypasses a
safety rule.** The set of things an operator can do to the hardware through the
panel is exactly what `/action` offered before this card. `app/selfconfig.py`
talks to the Supervisor about a JSON blob and to `validate.py` about whether
that blob is startable; the only actuator-shaped verb in it is `restart()`,
which restarts *this add-on* and whose 0 W is the existing, documented
wind-down.

test_selfconfig.py part 7 asserts that mechanically — it lists the routes, and
it greps `selfconfig.py` and the page for `set_number`, `write_setpoint`,
`handle_action`, `command_site_zero`, `sign_wd` and `reset(`. Adding "and also
set the setpoint while we are here" would put a second writer on the actuator
through the configuration surface, which is the non-goal this add-on is built
around.

## 7. How "every message comes from the shipped validator" is proven

Not by inspection. `test_selfconfig.py` part 6 copies the package, inserts **one
new rule** into `validate_startup_config()` in the copy, hashes every file under
`app/` to show that **validate.py is the only one that differs**, and then
serves the real `/config/validate` route out of that copy in a subprocess. The
new sentence arrives on the page, filed under the option key it names, with no
UI file touched.

That is the acceptance criterion run rather than argued, and it is what makes
"do not reimplement any rule in JavaScript" a property of the build instead of
a promise in a comment.