ARCH-02: rehearse the flat-to-roster switch, and it comes up disarmed

Nothing had ever run the real `Controller` through the transition inverter B's
commissioning performs on 2026-09-12. `tools/rehearse_roster.py` does, over a
COPY of a state file given as an input path, and reports the difference: every
store key that moved, appeared, vanished or was STRANDED under a name no
machine reads; every entity id before and after with orphans named; and whether
the maintenance history MAINT-05 moved once survived being moved again.

⭐ WHAT IT FOUND, AND IT IS SAFETY-44's ANSWER. A store that ran pre-DEV-02 flat
and declares a multi-inverter roster comes up with its SAFETY-02 latch DISARMED
unless the first roster entry happens to be called `inverter-a`.
`Controller.__init__` hands `migrate_unit_keys()` the hardcoded `UNIT_A`, so the
latch lands in `unit/inverter-a/sign_tripped`; a roster of ["garage","shed"]
reads `unit/garage/sign_tripped`, which is absent. And `_grade_store_migration()`
- the guard written for exactly this - sees the migration's OWN misdirected key
satisfy its `namespaced_latched` test and returns without re-arming. Measured,
not argued: the file says `sign_tripped: true`, no inverter is latched, nothing
is held at 0 W. The same state file onto a roster whose first entry IS
`inverter-a` comes up latched, so the finding is attributable to the name.

The staged upgrade reaches it too: the flat start stamps `schema_version`, and
the roster start's migration then takes its early return.

⚠️ NO RUNTIME CODE IS CHANGED HERE. The fix to `migrate_unit_keys()` belongs to
SAFETY-44 reopened as a defect, shown red before it; this commit is the
instrument that shows it red.

THE CHECK CAN FAIL, AND WAS SEEN TO. `test_rehearse.py` establishes two CLEAN
CONTROLS first - two transitions the shipped code gets right, on which the
harness must say nothing - and then breaks the shipped migration and the
entity-id composition six ways in a private copy of the tree, requiring each to
turn its control from green to red WITH THE RIGHT FINDING NAMED. One mutation
is required to SURVIVE, with the reason written down. The synthetic state
carries maintenance history and a legacy-shaped latched `sign_tripped` with no
`schema_version` beside it, because state built by the happy path cannot detect
a migration that only mishandles legacy shapes.

⚠️ THE FIRST DRAFT OF THE HARNESS HAD HABIT 4 IN IT and its own battery caught
it - MUTATION.md's thirteenth instance, third in an instrument. The entity diff
composed both sides with the same build, so renaming the MQTT device moved every
id equally and it reported "no orphans" about a change that orphans everything.
`--live-entities` is the fix: a reference that does not move with the code.

THE RETREAT is supported and does not corrupt state - the flat rollback view
keeps the latch and the first pack's history live - but it orphans eight HA
entities, and the ROUND TRIP is not supported: a maintenance cycle completed
while rolled back is discarded on re-advance. Stated in DOCS.md as a decision.

Fetching /data/state.json, the options blob and the entity list are OWNER STEPS
and are written down. ⚠️ Nothing here was run against real state and nothing
here claims to have been.

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

goodwe_controller/DOCS.md

@@ -1574,6 +1574,112 @@ battery power, circulating power, state of charge, maintenance phase and
 controller status by MQTT discovery. This is observability only — the controller works fine without a
 broker, and MQTT problems can never affect control.
 
+## Before you commission inverter B: `tools/rehearse_roster.py` (ARCH-02)
+
+The day the `inverters:` roster is declared, two things change that are
+**one-way on a live box and invisible until after the restart that applies
+them**: the store migration renames the keys that hold the SAFETY-02 latch and
+the maintenance history, and the entity ids Home Assistant composes change
+shape. This tool runs the **real `Controller`** through that transition against
+a **copy** of the state file and reports the difference.
+
+    docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -v <repo>:/w:ro \
+      goodwe-addon-checks:1 sh -c 'cd /w/goodwe_controller && \
+      python3 tools/rehearse_roster.py \
+        --state /w/state-copy.json \
+        --before /w/live-options.json \
+        --after  /w/roster-options.json \
+        --live-entities /w/live-entities.txt \
+        --reverse --round-trip'
+
+Exit `0` clean · `1` at least one finding · `2` could not run. ⚠️ **`2` is not a
+pass.**
+
+### The owner steps, because this session could not take them
+
+⚠️ **The rehearsal is only as good as the state it is pointed at, and nothing in
+this repository can fetch that.** SSH to the live box is blocked by policy and
+that is correct — `/data/state.json` is the file the running add-on is writing.
+So three things have to be exported by hand, onto the machine that runs the
+check, **before** the roster is declared:
+
+1. **The state file.** From the Supervisor host:
+
+       ha addons info local_goodwe_controller     # confirm the slug first
+       docker cp addon_local_goodwe_controller:/data/state.json ./state-copy.json
+
+   or take it out of a full add-on backup, which is the same bytes. ⚠️ **Copy
+   it, never move it, and never write to the original.** The tool opens the path
+   it is given exactly once and does all of its writing on a scratch copy — but
+   the safe habit is to hand it a file the add-on has never heard of.
+
+2. **The options blob**, as `--before`. It is not reachable through the Home
+   Assistant REST API and no entity carries it; export it from the Supervisor,
+   the same way `tools/predeploy_check.py` needs it. Write the roster you intend
+   to deploy into a second file and pass it as `--after`.
+
+3. **The entity list**, as `--live-entities` — one entity id per line:
+
+       Developer tools -> Template:
+       {{ states | map(attribute='entity_id') | select('search','goodwe') | join('\n') }}
+
+   ⚠️ **Without it the tool cannot see a change to the id composition at all**,
+   because both sides of its own before/after diff are composed by the same
+   build: rename the MQTT device and every id moves equally on both sides, and
+   the diff reports "nothing orphaned" about a change that orphans everything.
+   `tools/rehearsal/live-entities-recorded.txt` is the recorded stand-in that
+   keeps the check live in CI; the real export is what makes it true of *this*
+   install. The install carries roughly 49 `goodwe*` entities and this add-on
+   announces eight of them — the tool separates the ids it owns from the ids it
+   does not, rather than claiming orphans it cannot cause.
+
+⚠️ **No result in this repository was produced against real state.** Everything
+recorded here and in `test_rehearse.py` was measured on the synthetic fixtures
+in `tools/rehearsal/`.
+
+### What it found on the synthetic fixtures
+
+⚠️ **A pre-DEV-02 flat store that declares a multi-inverter roster comes up with
+its SAFETY-02 latch DISARMED, unless the first roster entry happens to be named
+`inverter-a`.** `Controller.__init__` calls `migrate_unit_keys(store, UNIT_A)`
+with a hardcoded constant, so the latch lands in `unit/inverter-a/sign_tripped`;
+a roster of `["garage", "shed"]` reads `unit/garage/sign_tripped`, which is
+absent. And `_grade_store_migration()` — the guard written for exactly this —
+sees the migration's own misdirected key satisfy its `namespaced_latched` test
+and returns without re-arming. The file says `sign_tripped: true`, the banner is
+green, and nothing is held at 0 W. **This is SAFETY-44, and the answer to it is
+that the asymmetry is not safe on that path.** It is reported here and pinned by
+`test_rehearse.py` part 5; the fix belongs to its own card, shown red first.
+
+The same end state is reached whether the roster is declared in the same step as
+the upgrade or a restart later — in the staged case because the flat start
+stamps `schema_version` and the roster start's migration then returns early.
+
+### The reverse direction: the retreat is supported, the round trip is not
+
+If commissioning B goes wrong, **backing out to the flat single-inverter config
+is supported and does not corrupt state.** Measured on the fixtures:
+
+* the SAFETY-02 latch and the first pack's maintenance history both survive,
+  because `store.py` rule 2 keeps the flat spellings **live** rather than merely
+  present — `maintenance.UnitHistory.mirror_flat` writes them on every change,
+  so a single-FSM add-on finds a current history rather than one dated the day
+  the roster was declared;
+* **it orphans eight Home Assistant entities** — the four per-unit rows for each
+  of the two units. Their history stops and any automation naming them stops
+  firing, silently. That is the price of the retreat and it is not recoverable
+  by advancing again: HA keeps the id it composed at first discovery.
+
+⚠️ **What is NOT supported is the round trip.** A maintenance cycle that
+completes *while the install is rolled back* is **discarded** when it
+re-advances: `maint_schema_version` is already stamped, so `migrate_maint_keys()`
+takes its early return and the pack reads the namespaced history from before the
+retreat. The pack is then recalibrated on a schedule that does not know it
+already was. **So: retreat freely, but treat a retreat as ending the current
+maintenance bookkeeping — and if a cycle ran during it, correct
+`unit/<first>/last_completed` by hand before advancing again.** This is a stated
+decision, not a discovery made at the inverter.
+
 ## Before you deploy: `tools/predeploy_check.py` (PKG-09)
 
 Two ways a deploy has gone wrong on this system, both of which the Supervisor