goodwe-addon/goodwe_controller/DECISIONS/MAINT-05-per-pack-maintenance.md

MAINT-05 — one recalibration per pack, one at a time, and what the card left open

Status: DECIDED 2026-09-04. There is one Maintenance per roster entry, each with its own schedule, phase and history. The site holds exactly one maintenance slot: at most one pack may be in a power-moving phase, the slot is derived from the packs' own stored phases rather than persisted separately, and when several packs are due in the same hour it goes to the one that has gone longest without a completed cycle. The schedule is not staggered by construction — the interlock defers, and the stagger emerges from it.

Fix round 2026-09-04. The store migration is now graded against the roster rather than against the unit name it was handed — see §2's "The read-back postcondition is graded against the ROSTER" — and the same hole in SAFETY-02's latch migration is recorded in §7.

Filed with MAINT-05. Card 6a9a9e8503872905f298d80a.

---

0. What the card asked to be decided, and the answers

the card's open question	the decision
§2 the arbitration	one pack at a time; the other stays under the loop. Nothing preempts a cycle in flight.
§2 who wins when several are due	the longest-waiting pack, last_completed oldest first, inf for never-recalibrated. Roster order breaks a numeric tie and nothing else.
§4 staggering	not by construction. The interlock defers the second pack; the stagger is what comes out of it. §3 below.
AC 7 rule 6's maint_unit comment	no, the first entry's cap is no longer right. It grades against the weakest cap on the roster now, like rule 5. §4 below.
the store layout at N=1	flat, unchanged. The namespace appears the day the roster grows. §2 below.

1. Why the slot is derived and not persisted

The holder is "whichever pack's stored phase is not idle" — a fact already on disk, written by the packs themselves in the per-pack history this card introduces. A maint_slot_holder key would be a second opinion about the same thing, and the two would disagree the first time the add-on was killed between writing the phase and writing the holder. Derived, a controller that comes back up mid-drain reads the drain and re-derives the holder from it; there is no recovery path to get wrong because there is no second fact.

CHARGE is in POWER_MOVING even though the control loop owns the setpoint in that phase, and that is the decision most likely to be "simplified" later. Pack A charging from the grid at 2000 W while pack B drains 2000 W to export is 4 kW going round in a circle with the meter reading zero and both packs believing they are behaving — the circulating power SAFETY-31 exists to detect, arriving as something this module can simply not do. HOLD is in the tuple for the other half of the sentence: it moves nothing, and it owns the actuator, so a second cycle starting under it would still be two recalibrations at once.

2. Why the store layout at a roster of one does not change

The maintenance keys are flat — phase, phase_started, last_completed, last_start_attempt — on every install since the add-on shipped. At one pack there is nothing for a namespace to distinguish that pack from: §6.2's identity, the same one arbiter.actuator_for() leans on when it routes every claim to the site actuator at N=1. So Maintenance is constructed with unit=None there, reads and writes the flat keys directly, and migrate_maint_keys() returns without writing anything. A one-inverter state file comes out of this card byte-identical, which is AC 6 and which test_maintenance.py part 10 asserts by driving a whole cycle and comparing the key set.

The migration has its own marker, and that is not tidiness

SCHEMA_VERSION / schema_version is DEV-02's, and it is monotone: every install runs that migration exactly once. This one runs only where the roster has more than one pack, so a single counter could not express "migrated on this site, deliberately not migrated on that one" without lying to the next version that reads it — a one-inverter store would have to be pinned at the old number forever, and a genuine future v2 migration could then never be told apart from a site that simply never grew. maint_schema_version answers one question and answers it honestly.

The three rules are shared in code, not restated: _move_flat_keys() is rule 1 (never overwrite an existing namespaced value) and rule 2 (the flat keys stay in the file), _verify_moves() is the read-back postcondition, and the marker is written last. A second transcription of a migration is a second opinion about what "it landed" means.

The read-back postcondition is graded against the ROSTER (fix round)

A postcondition that reads back the namespace it was handed cannot detect being handed the wrong one. That sentence is the whole finding, and this card shipped it broken.

_verify_moves() iterated rep.moved — the keys it had just written — and asked whether each read back equal. On a store where the write lands, it always does. So a migration handed a unit that is on no roster wrote four keys, read four keys back, set verified = True, and the caller stamped maint_schema_version. Every symptom of a clean migration, and an install's whole maintenance history parked under a name nothing will ever look up. And because the marker was stamped, the next start skipped the migration too — which is precisely the state store.py's header says must never happen: a failed migration a later version treats as done.

Reproduced on the reviewer's roster, a house with a garage pack and a shed pack, carrying a flat last_completed of 2026-08-07:

	unit the migration was handed	key written	pack 0 reads back	due now?
correct	self.inverters[0].name = garage	unit/garage/last_completed	2026-08-07	False
wrong	inverter.UNIT_A = inverter-a	unit/inverter-a/last_completed	None	True

build_roster() names a declared roster's entries from the config, and its fallback for a nameless entry is a positional inverter-1 — so inverter-a is not the name of anything on a declared roster, not even by default.

The remedy, and why this one. migrate_maint_keys() now takes the roster in place of an n_units count (the count was len(self.inverters) at the only call site, so the roster carries it, and a count passed beside the names is a second opinion about how many packs there are). _verify_moves() grades the namespace it wrote against those names, and a unit that is not among them is reported as misdirected — a different failure from lost:

• lost is the store took the write and dropped it — a storage fault, and it has a harmless-default case (a write of last_completed: None loses nothing, because "absent" and "never recalibrated" are the same statement).
• misdirected is the store did exactly as it was told, by a caller that was wrong. There is no harmless-default version of it: a write nobody reads is not information, whatever its value. So anything in it fails ok on its own.

And ok gates the marker, so a misdirected migration is not stamped and the next start runs it again. The argument for it is asymmetric: a re-run is recoverable — rule 1 makes it a no-op where keys did land, and rule 2 left the flat keys in the file to recover from — while a silent skip is not recoverable at all, because the store now claims the migration happened.

⚠️ THE PARAGRAPH ABOVE USED TO END HERE, AND AS IT STOOD IT WAS FALSE

The refusal lasted exactly one start. The second start stamped the marker. That is a correction to what the first fix round wrote down, not a new qualification of it, and it is recorded here because a decision document that states a guarantee the code does not provide is worse than one that says nothing.

_verify_moves() graded only rep.moved. Measured at Controller level over one persisted store, roster ["garage", "shed"], flat last_completed 2026-08-07, with the call site still handing inverter-a on both starts:

construction 1: ok=False misdirected=4 moved=4 kept=0   marker=<absent>   (withheld)
construction 2: ok=True  misdirected=0 moved=0 kept=4   marker=1          (STAMPED)
history parked under unit/inverter-a/…; marker stamped after ONE restart.

On start 2 the same wrong call site finds the four keys it wrote already present, so rule 1 — never overwrite a namespaced value — routes every one of them to rep.kept. rep.moved is empty, the roster-grading loop iterates over nothing, misdirected is empty, ok is True, the marker is stamped, and start 3 takes the from_version >= MAINT_SCHEMA_VERSION early return forever — including after the call site is fixed. Loud-and-recoverable became silent-and-permanent after one restart: exactly the state store.py's header says must never happen, reached by the fix written to prevent it.

The remedy is one line, and it is sound by construction rather than by argument: grade set(rep.moved) | set(rep.kept). Every entry in both lists is a unit_key(unit, legacy) built from the same unit argument, so grading kept grades the same namespace decision moved does. A correct call site's kept entries are under a roster name and pass; a wrong one cannot launder its namespace by having already written it. migrate_unit_keys() passes roster=None and returns before the loop, so it is unaffected.

Why the check missed it, which is the part worth keeping. Part 9b's recovery check was migrate_maint_keys(_m5, ROSTER[0], ROSTER) — the corrected name. It measures recovery along the one path where the operator has already fixed the bug. The real failure is a call site that is still wrong on the next start, and nothing in the 19 files called migrate_maint_keys() twice with the same wrong unit. The check was true, passed, and could not reach the failure its sentence named — MUTATION.md's third defect, this time sitting inside the fix written to close it. Part 9c now drives two starts with the same wrong unit over one store, asserts the marker is still withheld on the second, and asserts the shape of the second report (moved empty, kept full) so it cannot quietly revert to 9b's path.

The marker gate is rep.ok and nothing weaker — both guards, each pinned

if rep.ok: is not lost and not misdirected, and until this round only the misdirected half was reachable by a check that also had a non-empty kept. The mutation

if rep.ok:      ->      if rep.ok or rep.kept:

stamps the marker on a migration that lost a month of history — defeating the older, settled lost guard as well as the new one — and all 19 suites were green on it. Part 9d is the fixture that separates them: two keys already namespaced (kept non-empty, so the mutant's or fires) and two keys whose write the store drops (lost non-empty, so ok is False), with misdirected empty throughout so the section cannot pass on the other guard by accident. Measured differential on it: shipped → marker absent; mutant → marker 1, both reporting ok=False lost=2 kept=2.

Why the fixtures had to change, and this is the part that got the card rejected. Nothing in the repository could see whether any of the above was true, because inverter.UNIT_A is the string "inverter-a" and every two-pack fixture in test_maintenance.py named its first roster entry inverter-a. self.inverters[0].name and UNIT_A were therefore the same value in every check that existed, and swapping one for the other at the call site left all 19 suites green. MUTATION.md's third defect exactly — a check whose data cannot reach the failure it names — and the fifth consecutive card to carry it. Parts 9 and 11 now run on ["garage", "shed"], each behind a precondition check asserting that the first name is not UNIT_A, so an edit that makes them equal again goes red instead of making the claims vacuous.

And the flat keys are kept LIVE, which is the half DEV-02 had to add later

Rule 2 originally said the flat keys are left in place and go stale. DEV-02 amended it, for the sign latch, to "left in place is not enough" — and the same sentence holds for history. A fossil dated the day the second inverter was declared would hand a rolled-back single-FSM add-on a last_completed months old (it recalibrates a pack that does not need it) or a stale phase with a phase_started old enough to abort on the 12 h timeout the moment it comes up. So UnitHistory mirrors the first pack's writes back onto the flat keys for as long as the roster has more than one entry. Only the first pack: the flat spelling means inverters[0] on every install that has one, and a mirror from pack B would overwrite pack A's rollback view with pack B's phase.

3. Staggering: the interlock defers, and the stagger is the residue

Two packs on one monthly schedule are due in the same hour every month. The options were a stagger by construction — offset each pack's first cycle by interval_days / N — or deferral. Deferral, for three reasons:

1. A constructed stagger cannot remove the need for the interlock. A forced start, a commissioning cycle, an abort-and-retry, or a pack added mid-month desynchronises any static offset immediately, so the interlock has to be there anyway — and then the stagger is a second mechanism that must also be correct, for a case the first one already handles.
2. A deferral is observable and a stagger is not. The deferred pack says, in the action log and on the status page, that it is waiting, which pack it is waiting for, and that it will run at the next start hour. A silent offset moves an operator's configured start day and explains nothing.
3. The stagger comes out of the deferral for free and then persists. Pack A completes on day 1 and is next due on day 29; pack B, deferred, completes on day 2 and is next due on day 30. One contested month separates them by one cycle length and they stay separated.

Starvation was the risk and it is closed at two points. A deferral does not stamp last_start_attempt — that key is the post-abort cooldown, and at 90 minutes inside a 60-minute start hour, stamping it would lock the deferred pack out of exactly the hour it is waiting for. And the winner is the longest-waiting pack rather than the first in the roster, so a pack that keeps aborting cannot monopolise the slot month after month while its sibling drifts — which is this card's own defect wearing a different costume.

The deferral must not read as a fault. §12's 12 h and 36 h phase timeouts mean "the battery is not following commands". A deferred pack stays IDLE with phase_started untouched, so no timeout is reachable by waiting, and the line it logs says WAITING, names the pack it waits for and says it will run next — none of which any failure path in maintenance.py says.

4. Rule 6 (the card calls it rule 8): the first entry's cap is no longer right

validate.py's rule 6 comment said, in as many words, that maintenance_charge_w was graded against inverters[0]'s cap because there was exactly one Maintenance and it could only ever recalibrate the first pack — and that taking min() would be an over-refusal, because it would refuse "a 5000 W pack being recalibrated beside a 2000 W sibling the cycle never touches". It closed: "when maint_unit stops being inverters[0], this line moves with it."

It has stopped. Every pack is recalibrated on its own schedule, so the sibling the cycle never touches does not exist and the over-refusal argument has no subject. The shaping claim is filed on whichever pack is charging, so the cap that can contradict it is any cap on the roster and the one that contradicts it first is the smallest.

This refuses configurations that used to start, and that is the point rather than a side effect: max_w 5000 on pack A beside 2000 on pack B with maintenance_charge_w 3000 was correct while only pack A was ever recalibrated, and is now a cheap-window charge asking the arbiter for hi = -3000 against a supervised lo = -2000 — lo > hi, arbiter clause 3, 0 W, on the pack nobody was watching. Refused when it is written, which is rule 6's whole job. At a roster of one min() over one cap is that cap: same comparison, same message, same boundary.

5. The claim stays per-unit, and nothing here files a site claim

arbiter.CLAIM_SCOPE has classified maintenance as SCOPE_UNIT since it was written. Two FSMs mean two claims on two actuators, which the allocator consumes as per-unit intervals. ARCH-01 is explicit that this must never become a site claim, because per-inverter constraints filed site-wide are the cross-inverter lo > hi contradiction at arbiter.py:114. The only line this card changed there is which roster entry the claim is filed on: the one whose state machine produced the result, rather than inverters[0].

6. FOUND AND NOT FIXED: the site loop still contradicts a drain at N>=2

Measured while wiring this card, and pre-existing on release/1.0 at 2d025ee — the same drain filed on inverters[0] produces the identical refusal with the two unit names swapped.

The maintenance SET pins its pack. The loop's target is a site claim. When the site target is below the pin — a 2000 W drain while the house imports less than that, which is most of a night — the only split that sums to the site target asks the sibling to charge while the maintained pack discharges, and allocator.plan() refuses it by name as circulating power. The refusal is correct and fails safe: the whole site goes to 0 W with an ARBITER: REFUSED line in the action log.

The consequence an operator would see is a misdiagnosis. The pack is held at 0 W while its state machine believes it is draining, so after 12 h the DRAIN timeout fires and reports "drain stuck" — §12's words for a battery that is not following commands. The battery is fine; the site refused to allocate.

Why it is not fixed here. The fix is to change what the site loop's target means while a unit is pinned — regulate the meter using only the unpinned packs — which is loop and allocator territory and changes the integrator's subject. MAINT-05 moves which pack is pinned and nothing else about it. It is pinned as a running check (test_maintenance.py part 12) rather than left as a comment, so it cannot be forgotten or quietly tuned away, and it wants a card of its own.

7. FOUND AND NOT FIXED: migrate_unit_keys() has the same hole, and it is a LATCH

Found while fixing §2's instance. It is the same defect one module over and it costs a disarmed safety guard rather than a lost history.

Controller.__init__ calls migrate_unit_keys(store, UNIT_A) — a hardcoded constant where the maintenance migration now passes the roster's own first name. It has to run before build_roster(), because each Inverter restores its sign latch in its constructor, so there is no roster to name yet and _verify_moves() is passed roster=None. On a declared roster a pre-DEV-02 sign_tripped: true therefore lands under unit/inverter-a/sign_tripped, which no unit on that site reads.

And the guard that exists for exactly this is defeated by the key the defect wrote. _grade_store_migration() re-arms the latch when the flat key says tripped and nothing namespaced is latched. The misdirected write is namespaced and is latched, so namespaced_latched is True, the guard returns, and no inverter on the roster comes up tripped — on an install whose /data/state.json still reads sign_tripped: true. That is DEV-02's own sentence for the worst case: the state file says protected, the banner is green, and the controller resumes commanding into the fault that tripped it.

Measured, on the same ["garage", "shed"] roster:

pre-DEV-02 flat latch + declared roster ['garage', 'shed'] ->
    migrated 2 flat key(s): unit/inverter-a/sign_reason, unit/inverter-a/sign_tripped
latch keys in the store: ['sign_tripped', 'site_sign_tripped', 'unit/inverter-a/sign_tripped']
roster came up tripped:  [('garage', False), ('shed', False)]
the same store on the FLAT config -> [('inverter-a', True)]

The last line is the counterfactual: on the flat shape, where UNIT_A really is the roster's only name, the same store migrates and comes up latched. So this is a defect of the declared roster, not of the migration as such.

Why it is not fixed here. The remedy is to name the migration's target from the config before any Inverter exists, which means factoring build_roster()'s naming rule out of build_roster() so there is still only one spelling of it — inverter.py and SAFETY-02's latch semantics, with its own mutation battery over test_inverter.py and test_watchdog.py. MAINT-05 moves the maintenance history and nothing about the sign latch, and a silent expansion into a safety latch is how a rejected PR becomes a broken one.

It is pinned as a running check (test_maintenance.py part 13) rather than left as a comment. ⚠️ Its assertions state the WRONG behaviour on purpose — read them as the specification of a defect; the card that fixes it should expect them to go red and should replace them.

And its MARKER GATE had the round-3 hole too — found here, closed here

Separate from the namespace hole above, and fixed rather than recorded, because closing it cost one test fixture and no source change. migrate_unit_keys() gates schema_version on rep.ok exactly as migrate_maint_keys() gates its own marker, and every check that reached that gate ran on a store where nothing was namespaced yet — so rep.kept was empty in all of them and

if rep.ok:      ->      if rep.ok or rep.kept:

survived all 19 files. What it does is stamp the schema marker on a migration that DROPPED THE LATCH: the guard is off, the state file still reads sign_tripped: true, and because the store now says the migration finished, the next start skips the one thing that would have re-armed it. DEV-02's own worst case, filed under done.

test_inverter.py part 10 now drops the sign_tripped write beside an already-namespaced sign_reason — lost non-empty and kept non-empty, which is the one shape none of the existing fixtures had — and asserts the marker is withheld, with the accepted-baseline counterfactual beside it (habit 7). The shipped gate was correct throughout; what changed is that a check can now see it.