goodwe-addon/goodwe_controller/DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md

SAFETY-47 — what a shadow run can show, and what it cannot

Status: decided and implemented on branch SAFETY-47. Card: SAFETY-47 — "shadow mode's claims, and the number on the status row". Nothing here reached the inverter. No deployment, no ha addons update, no contact with 192.168.2.158 or 192.168.2.221. Everything below was measured in the CI image and on TEST-23 stage 3's closed-loop rig.

⚠️ This is not a write-path defect and nothing in the write path was touched. SAFETY-10's substitution, re-seed, authorisation gate and clamp are unchanged. What was wrong is what three merged documents say a shadow run can show you, and a number on the status row that can be 6.61× what a live controller would command.

---

0. The four things a reader should take away

1. Shadow mode cannot surface a closed-loop defect. Not partially — not at all, and by the same construction that makes it safe. §1.
2. The "strategies are unaffected" exemption was true until SAFETY-45 merged, one commit before SAFETY-10. Sizing the buy leg to the billed-quarter headroom made the strategy closed-loop. §2.
3. The recorded watts are the right answer to a question nobody asked, and they are CAVEATED rather than re-computed. Re-computing would mean the recorded decision was no longer the decision the shipped path reached, which is the one thing shadow mode has to be able to say. §3 records what was rejected.
4. SAFETY-10 §6's committed evidence could never have failed, for two independent reasons, and closing either one alone closes nothing. §4.

---

1. Why the answer is "not at all", and not "not very well"

Shadow mode holds every actuator at shadow.WIRE_W and re-seeds the carried command to it at the end of each cycle. So every measured input — the meter, the billed-quarter accumulator behind it, the battery power, the state of charge — describes a plant that did not respond.

A closed-loop defect is, by definition, one whose stimulus is the plant's response to the controller. No response, no stimulus, nothing to see. This is not an implementation gap:

• feeding the guards a simulated plant instead is exactly what SAFETY-10 §4 refuses for the sign watchdogs, and the reason generalises — a controller reacting to a plant that does not exist drifts further from reality every tick, and three cycles in its numbers describe nothing;
• and SAFETY-10 §5 already conceded the same fact for the grid-following loop ("one slew step, not a trajectory"). That was never a property of the loop. It is the general case, and the loop leg was simply where it had already been noticed.

So the closed-loop answer comes from a closed-loop rig (TEST-23 stage 3) or from a live run. There is no third place, and saying that plainly is worth more than the three sentences it replaces.

Measured, on the rig, at a cap that binds

peak_cap_w 1500 / house 1200 / max_w 2000, one hour at a 5 s cycle. Of the three defects SAFETY-10 was written for:

	visible?	measured
SAFETY-45's limit cycle	no	28 charge onsets live, 1 in shadow. Grid −455.5 … +3200.0 W live, flat at the 1200 W house in shadow. Guard engaged 410/720 cycles live, 0/720 in shadow. (Taken with SAFETY-45 reverted — that is the defect being looked for.)
SAFETY-46's SoC churn	no	the SoC moves 0.000000000 pp in a shadow run. The SoC is the pack's integral of what the pack was commanded, and it was commanded 0 W. No SoC limit can be reached in a shadow run at all
TARIFF-14's wrong quarter-hour	yes, and it is the only one	the price lookup's inputs are the clock and the price series, neither a function of the battery. Which hour, at what price, clearing what spread: identical live and shadow on 720 of 720 charging cycles, at a binding cap

What a shadow run genuinely is for

Which strategy wins, on which hour, at which price, for which reason, against which limits — the wrong-quarter-hour class, a trade armed on a day it should not be, a refusal whose sentence names the wrong subsystem, a clamp that would have engaged, a standing failsafe latch. That is a real and useful set, and it is the set the documents now claim.

---

2. The exemption, and exactly how much of it survives

All three documents carried a version of:

The strategies are unaffected — price arbitrage, the capacity guard and maintenance all ask for a fixed power from inputs that do not depend on what the battery did.

True before SAFETY-45, false after it. SAFETY-45 makes the buy leg min(asked, headroom), and

headroom = (900 / remaining) x (ceiling - projected)

where projected reads the open quarter's accumulator — the meter — which is a function of what the battery did earlier in that same quarter. SAFETY-45 merged one commit before SAFETY-10, so the exemption was stale on the day it was written.

What survives, and it is now graded rather than asserted:

Which hour a strategy picks, and why, are unaffected — the clock and the price series are not functions of the battery. How hard it trades is not.

⚠️ The peak guard is not in the surviving half either. Every term of wanted = batt_w + excess is measured, so in a shadow run the guard engages only if the house alone would put the quarter over the ceiling. Its ceiling and its reasons are worth reading from a shadow run; its engagements are not evidence of anything.

---

3. The number on the status row — decided, and what was rejected

At peak_cap_w 1500 under a 1200 W house the status row read "WOULD HAVE COMMANDED −2 000 W". A live controller commands −302.4 W. Measured on the shipped build:

cap / house	live commanded	shadow recorded	over by
1500 / 1200	−302.4 W	−2000.0 W	6.61×
3500 / 3000	−502.6 W	−2000.0 W	3.98×
3500 / 2000 (shipped cap)	−1502.6 W	−2000.0 W	1.33×
3500 / 1800	−1702.6 W	−2000.0 W	1.17×
15000 / 350	−2000.0 W	−2000.0 W	1.00×

⚠️ The arithmetic is not wrong. 900/remaining is correct for a meter that is genuinely under the ceiling, and in a shadow run the meter genuinely is under it, because the battery is not charging. The recorded number is the right answer to a question nobody asked — and the last row of that table is the fixture SAFETY-10's own evidence was taken on, which is why nothing reported it.

What shipped

1. Unconditionally, the row and the log line stop forecasting: the watts are introduced as what would have been commanded ON THIS CYCLE. No number a shadow run records is a prediction of a live run, so no state should read like one.

2. Conditionally, whenever a measured billed quarter sized the number being recorded, both surfaces carry shadow.SIZED_FROM_METER:

   ⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W. A live run sizes the same trade against a meter the battery is moving, so this is an UPPER BOUND and not a prediction; how far under it a live run lands is a closed-loop question and a shadow run cannot answer it.

⚠️ "Upper bound", and not "smaller", and the difference was measured. Charging only adds offtake, so a live projected is never below a shadow one and the headroom never above it — with equality at the start of every quarter, where 900/remaining is 1.0 and neither plant has moved. Measured pairwise over 3600 charging cycles in five configurations: 0 cycles below, 730 exactly equal. A sentence reading "smaller" would have been false on every one of those 730, and the first draft of this card said "smaller".

⚠️ And it names no factor. How far under the bound a live run lands is a property of the site. A number invented for the row would be a second helping of the defect the sentence exists to disclose.

⚠️ The predicate is NOT keyed on whether the trade was capped, and that is the trap this card nearly walked into. arbitrage's own sentence says "SIZED BY THE CAPACITY-TARIFF GUARD" only when the headroom came out below the ask — which in a shadow run is the start of the quarter, where the two runs still agree to the float. By the end, 900/remaining has multiplied the headroom past the ask, the trade is not capped, the sentence is silent, and the recorded number is at its most wrong. A caveat keyed on it would be quietest exactly where it is needed loudest. arbitrage.sized_from_meter() is keyed on the headroom having been measured, so it fires on both. test_arbitrage.py part 3d-8 drives the inversion.

Rejected, and why

• Re-compute the number so it does not amplify — e.g. record ceiling − projected (gain 1.0) instead of the sized figure. It matches the live answer almost exactly at this cap, and it is the worst of the options. It would be a shadow-only sizing: the recorded decision would no longer be the decision the shipped path reached, while the arbiter, the clamp, SAFETY-28's gate, the action log and MQTT all ran on the real one. A second copy of the sizing arithmetic living in the display layer is MUTATION.md's transcribed-predicate defect on an operator-facing surface, and it generalises to no other strategy. SAFETY-10's whole safety argument is that shadow mode is a substitution at the wire, not a second controller; this would have made it a second controller everywhere except the wire.
• Record nothing where the sizing depends on measured state. Tempting — "no number beats a number 6.61× out". Rejected on three counts: it blanks the row exactly when arbitrage is trading, which is when a commissioning engineer most wants it; the action log's edge key is the rounded watts, so blanking them either floods or silences the log; and a surface that flickers between a number and a dash is harder to read than a number with a standing caveat. The narrow version of this — dropping the watts only — was the closest runner-up.
• Record the unsized ask alongside the sized one. It adds a number without adding a warning. The unsized ask is max_w, a constant the operator configured; on the shipped 3500/2000 row both figures are 2000 W, so the pair is exactly as misleading as the single figure was.
• A caveat on every cycle in every state. Rejected as the whole answer, accepted as half of it: the unconditional part is a two-word narrowing of the verb ("on this cycle"), not a warning, and the warning proper is conditional so that it still means something when it appears.

---

4. SAFETY-10 §6's evidence, and why it could not fail

§6 tabulated arb_power_w −2000 W "identical", arb_reason "identical, verbatim", arbiter winner "identical". Two independent reasons it could never have gone red:

1. the fixture is peak_cap_w: 15000 against a 350 W house, so the guard never engages and SAFETY-45's sizing is in the run and inert. ⚠️ The harness's own comment says so — "at this scenario's peak_cap_w: 15000 it is not binding anyway" — which is MUTATION.md habit 4 written down beside the check it disables;
2. every identity row reads the FIRST charging sample. At elapsed = 0 the projection is the held level, so the two runs agree to the float there even at a cap that does bind.

⚠️ AND THAT SECOND REASON IS THE ONE A REVIEWER CANNOT SEE FROM A DIFF. Widening the fixture alone — the obvious fix — leaves the [0] comparison passing. Measured, not reasoned: at 1500/1200 the first charging cycle is −300.0000 W in both runs while 716 of the 720 cycles differ. Part 3d-2 grades that agreement as an expectation, so nobody rebuilds a check on [0] believing it covers something.

This is habit 4's twelfth instance in this repository, its second inside a committed evidence artifact, and — like the seventh and the eleventh — it was in a measuring instrument rather than in a check.

§6 is re-taken at peak_cap_w 1500 / house 1200 / max_w 2000, across the whole run. Harness /home/homelab/s47-mut/shadowloop47.py.

---

5. The grader, so this class cannot recur

test_arbitrage.py part 3d — placed beside part 3c, which is SAFETY-45's own closed-loop regression, and built on the same s45_loop() harness so the two runs share every line of shipped code and differ in one argument:

s45_loop(sized=True)                  the live hour
s45_loop(sized=True,  shadow=True)    the same hour, battery held at WIRE_W
s45_loop(sized=False, shadow=True)    SAFETY-45's own defect, watched from
                                      inside shadow mode

Three lines of s45_loop() stand in for Controller._write_unit()'s substitution and _shadow_settle()'s record and re-seed. They are marked as a transcription; test_clamp.py part 8 is the check on the shipped placement, and it drives the real Controller. Everything that produces a number — the averager, the projection, the guard, the headroom, the strategy, the arbiter, the row and the log sentence — is the shipped one.

What 3d grades, in order: that the cap binds (the precondition the old evidence lacked); that the first charging cycle agrees anyway; that the whole run diverges, and by how much; that the record is an upper bound, and the two-point arithmetic that makes it one; what survives of the exemption; that SAFETY-45's limit cycle and the guard's engagements are not visible; the four rungs of sized_from_meter(), each reached with the other three clear (TEST-16); both operator surfaces; the capped-keying trap; and main.py's three call sites, pinned on the AST.

⚠️ The section carries its own precondition into every check. A mutation that stops either run trading left the lists empty, the first min() raised, the file died before part 4 and the run reported zero reds — which reads exactly like a survivor. That is FCST-06's shape and it was driven, not imagined. s47check() now fails every check in the section when the stimulus was not produced, and the one division in it answers nan rather than raising.

---

6. The mutation battery — 14 mutations, no survivors

Harness /home/homelab/s47-mut/run.py, backups inside it. Each run restores from backup, purges __pycache__ on the host, and grades through the CI image with the tree bind-mounted :ro, so the interpreter cannot write a cache into the tree under test (TEST-15). Fingerprints are printed before the first run and re-checked after the last restore.

#	mutation	file	Δ	reds
M1	the row drops the caveat branch	shadow.py	−63 B	2
M2	the trap: sized_from_meter() keyed on the trade being CAPPED — silent where the record is multiples out	arbitrage.py	+33 B	5
M3	the CHARGE rung dropped — a sell carries a caveat §9.1 makes false	arbitrage.py	−30 B	1
M4	the measured-headroom rung dropped	arbitrage.py	−18 B	1
M5	the arbiter-winner rung dropped — a caveat on somebody else's number	arbitrage.py	−33 B	1
M6	main.py renders the row with sized_from_meter=False	main.py	−23 B	1
M7	main.py drops winner= — the rung exists and is never reached	main.py	−1 B	1
M8	main.py sizes the trade from a literal — SAFETY-45 out of the shipped path, which the hoist put at risk	main.py	−41 B	2
M9	the headroom assignment moves out of cycle()	main.py	−39 B	1
M10	sized_from_meter gains a False default (TEST-14)	shadow.py	+8 B	1
M11	ON THIS CYCLE deleted — the row forecasts again	shadow.py	−14 B	1
M12	log_line() drops the caveat — the page discloses, the record does not	shadow.py	−63 B	2
M13 ⚠️	main.py re-assembles the log sentence at the call site	main.py	+0 B	1
M14 ⚠️	wanted = batt_w − excess — the headroom stops being monotone in the battery and the row's UPPER BOUND sentence becomes false	peakguard.py	+0 B	38

Survivors: none.

⚠️ M13 and M14 are +0 B, which MUTATION.md names as the risky delta. Both were confirmed on disk by sha256 before the run started — the harness prints the fingerprint of every graded file and the hash moved for each — and every run is purged, so neither is at risk of the stale-.pyc failure.

⚠️ Two findings from driving it, both reported rather than tidied away.

• M14's first form was aimed at the wrong direction and correctly survived. min → max in the buy leg's sizing makes the shadow record larger, which is still an upper bound, so 3d-3b was right not to fail. The mutation that actually inverts the bound is the sign of the excess term in wanted. A survivor that is right is worth more than a red aimed at the wrong claim.
• M12 was a survivor before the fix it forced. Deleting the caveat from the action-log line left all 29 files green: the only check that could see that line drives a fixture with meter_source: off, where no arbitrage decision — and therefore no caveat — is reachable. The sentence was an f-string inside Controller._shadow_settle(), i.e. a surface no check could grade. It is shadow.log_line() now, for the reason words() is a function, and M13 is the mutation that puts it back at the call site.