CI-9: correct the guard comment's grading claim, and name the third blind spot

Documentation only - no change to the guard, the trigger, or any step.

The guard's comment block contradicted itself. It said the pull request that
reintroduces a filter "is still graded by the unfiltered workflow which is on
the base today", while the checkout step's note a few lines below says grading
uses the HEAD's workflow. The head's is correct, and the review measured it on
PR #101: head carrying a filter that excludes the base, base carrying the
unfiltered workflow -> no run, context posted `skipped`, rollup `success`, gate
cleared (409). The wrong version made the step sound like an unconditional
ratchet. What is actually true is narrower: it bites whenever the reintroduced
filter still names the pull request's own base, which is the ordinary case.

That correction exposes a third blind spot, worse than the two already listed.
A reintroduced `branches:` filter that simply does not name the base escapes
the guard entirely, because the pull request carrying it is itself skipped. It
needs no craft - `branches: [main]` from a template, or a tidy-up to `[master]`,
which nothing in this repository's history has ever targeted - and it lands as a
skipped, laundered, untested merge into release/1.0. After that every subsequent
pull request is skipped as well: the gate off completely, not merely the stacked
case leaking.

It is documented, not fixed, and deliberately so. No in-repo guard can close it,
because any such guard lives inside the workflow that gets skipped. Closing it
needs a second permanently unfiltered workflow whose context is added to
release/1.0's `status_check_contexts` - a forge change, the owner's decision,
being put to them separately, and explicitly not a blocker on CI-9.

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

.gitea/workflows/checks.yml

@@ -3,12 +3,35 @@
 # of real coverage including a wall-clock cadence test, and not one machine ever
 # ran them. Every merge here was a human reading a diff.
 #
-# ⚠️ NO `paths:` FILTER, AND ITS ABSENCE IS LOAD-BEARING. Branch protection on
-# release/1.0 requires the context `checks / unit (pull_request)`. Gitea leaves a
-# required context it never receives PENDING forever, so the moment this workflow
-# learns to sit a PR out, that PR becomes unmergeable. Condition a STEP if you
+# ⚠️ NO EVENT FILTER OF ANY KIND - NO `paths:`, AND SINCE CI-9 NO `branches:`
+# EITHER - AND THAT ABSENCE IS LOAD-BEARING. Branch protection on release/1.0
+# requires the context `checks / unit (pull_request)`. Condition a STEP if you
 # must; never the workflow.
 #
+# ⚠️ CI-01 WROTE THE REASON DOWN WRONG, AND THE WRONG REASON WAS THE SAFE-
+# SOUNDING ONE. It said an unreceived required context sits PENDING forever, so
+# a sat-out pull request becomes unmergeable - annoying, but fail-safe. That is
+# not what this Gitea does. MEASURED on Gitea 1.27.3, 2026-09-19, throwaway
+# PR #94: when a workflow exists but its event filter does not match, Gitea does
+# not stay silent. It POSTS the required context itself, with state `skipped`:
+#
+#   GET /api/v1/repos/admin/goodwe-addon/commits/<head sha>/statuses
+#     [{"status":"skipped","context":"checks / unit (pull_request)",
+#       "description":"Skipped","target_url":""}]      <- no run, no job, no url
+#
+#   GET /api/v1/repos/admin/goodwe-addon/commits/<head sha>/status
+#     {"state":"success","total_count":1}              <- the rollup LAUNDERS it
+#
+# and Gitea's merge gate accepts it. Same PR, same head sha, one status on it
+# and that status a skip, POST .../pulls/94/merge answered 409 `head out of
+# date` - the 409 being a deliberately wrong `head_commit_id` in the probe, i.e.
+# the request had ALREADY CLEARED BRANCH PROTECTION. The control, a required
+# context with no status at all, answered 405 `Not all required status checks
+# successful`. So the true failure mode is the exact inverse of the one written
+# here before: sitting a pull request out does not make it unmergeable, it makes
+# it MERGEABLE WITHOUT EVER BEING TESTED, and the badge says success while it
+# happens. Fail-open, not fail-closed. Do not reintroduce a filter here.
+#
 # ⚠️ THE RUNNER IS SHARED WITH THE OTHER REPO'S RIG. `goodwe-runner` on
 # 192.168.2.147 carries the labels `self-hosted` and `goodwe-rig` and is
 # registered `:host`, and it is the only runner there is - so this job wears the
@@ -23,9 +46,85 @@
 # that step; a green from this workflow is a claim about content that can land.
 name: checks
 
+# ⚠️ CI-9: `pull_request:` TAKES NO `branches:` LIST, ON PURPOSE. It used to
+# read `branches: [release/1.0, master]`, which meant a STACKED pull request -
+# one whose base is another feature branch rather than a release branch - did
+# not match, and so was skipped, laundered to `success`, and mergeable untested
+# by the mechanism described at the top of this file.
+#
+# ⚠️ AND RETARGETING DID NOT REPAIR IT, WHICH IS WHAT MADE THIS P1. The skip is
+# a COMMIT STATUS ON THE HEAD SHA, not a property of the pull request, so moving
+# the base afterwards leaves it exactly where it was. Observed live on PR #93
+# (2026-09-19): retargeted TEL-10 -> release/1.0, and the 10:05:00 `skipped`
+# stayed attached to head a6af332 with the rollup still reading success. It was
+# caught by a human who forced a real execution by reopening the pull request
+# (run 799, 10:56). Reproduced deliberately on throwaway PR #94: retargeted onto
+# a branch carrying a byte-identical copy of release/1.0's protection rule, and
+# the single `skipped` status survived the retarget unchanged - no new run, no
+# new status - and still cleared the gate.
+#
+# ⚠️ WHY NOT FIX THIS AT THE GATE INSTEAD, which would be the better place. It
+# cannot be done. Gitea's branch protection cannot express "this context must be
+# SUCCESS" as opposed to "this context must be PRESENT AND NOT FAILING". The
+# whole of its status-check vocabulary is two fields - `enable_status_check`
+# (bool) and `status_check_contexts` (a list of globs MATCHING CONTEXT NAMES) -
+# confirmed against this server's own schema at /swagger.v1.json, definitions
+# EditBranchProtectionOption and CreateBranchProtectionOption. There is no field
+# for the required STATE anywhere in either. The success/skip comparison lives
+# in Gitea's compiled code, so the only lever left is upstream of it: make sure
+# the context is never a skip in the first place. Hence this block.
+#
+# ⚠️ WHAT THIS COSTS, stated honestly, because it is a real trade. Every pull
+# request now runs the full suite, including the intermediate steps of a stack
+# that nobody intends to merge on its own. A run is ~8 minutes wall clock
+# (run 799: 7m55s) on a runner that is `capacity: 1` and shared with the other
+# repo's rig, so each extra run is ~8 minutes of slot that a rig campaign then
+# queues behind.
+#
+# SCALE OF THE NEW WORK, re-derived from the API and stated with its denominator,
+# because the first version of this paragraph had a made-up one. Counting the 93
+# pull requests that predate this ticket (#1..#93; CI-9's own #94..#98 excluded,
+# and note /pulls caps a page at 50, so this needs paging to see at all): 92 were
+# opened against release/1.0 and would have run anyway, and exactly ONE was
+# stacked - #2, TEL-01 -> SAFETY-04, closed unmerged, 2026-08-24. No pull request
+# has ever targeted `master`, so half the old filter was dead from the start.
+#
+# ⚠️ THAT 92 IS AN UPPER BOUND, NOT A CENSUS, and the reason is this very bug.
+# The API reports a pull request's CURRENT base, so one that was opened stacked
+# and later retargeted is recorded against its final base and is invisible here.
+# #93 is precisely that case - opened 2026-09-19T10:05:00 on TEL-10, retargeted,
+# merged into release/1.0 at 11:05:26 the same morning, under three hours before
+# CI-9 was opened - and it counts in the 92. So the true historical stacking rate
+# is somewhere above 1/93, and unmeasurable from here.
+#
+# The bill is therefore small today and grows with however much stacking the team
+# adopts. It is worth paying: the alternative is that the cheap case stays
+# untested and indistinguishable from the tested one.
+#
+# ⚠️ THIS DOES NOT CHANGE GITEA'S ACCEPTANCE OF A `skipped` REQUIRED CONTEXT -
+# that half is in its compiled code and is not reachable from this repository.
+# The CONSEQUENCE, though, is very largely closeable from here, and is closed:
+# after this edit there is nothing in this repository that produces a skip -
+# there is exactly one workflow file, it now has no event filter of any kind,
+# and the other candidate cause was MEASURED and is not one. The `guard the
+# trigger` step below then keeps it that way mechanically rather than by asking
+# the next editor to read this comment.
+#
+# THE MEASUREMENT, because the obvious guess is wrong and was nearly written
+# here as fact. A skip-ci keyword in a commit message (`[skip ci]`, `[ci skip]`,
+# `[no ci]`, `[skip actions]`, `[actions skip]`) does NOT behave like a filter
+# miss. On throwaway PR #94, head b36effb, commit subject ending `[skip ci]`:
+#
+#   .../commits/b36effb/statuses   ->  []                  <- NO status, not a skip
+#   .../commits/b36effb/status     ->  {"state":"pending"} <- so the rollup is pending
+#   POST .../pulls/94/merge        ->  405 Not all required status checks successful
+#
+# i.e. skip-ci is FAIL-CLOSED - it withholds the context entirely, which is the
+# pending-forever behaviour CI-01's header wrongly attributed to a filter miss.
+# It blocks the merge rather than laundering it, so it needs no fix and no
+# app.ini change. Only the filter miss ever posted a `skipped`.
 on:
   pull_request:
-    branches: [release/1.0, master]
   workflow_dispatch:
 
 # ⚠️ NO `concurrency:` BLOCK, AND ITS ABSENCE IS AS LOAD-BEARING AS THE MISSING
@@ -224,6 +323,140 @@ jobs:
             exit 1
           fi
 
+      # ⚠️ THE GUARD ON THE TRIGGER. THIS STEP EXISTS BECAUSE PROSE ALREADY
+      # FAILED IN THIS FILE, ONCE, FOR TWENTY DAYS.
+      #
+      # `git show 9c1a23328a` is CI-01's first commit. It shipped the header
+      # "⚠️ NO `paths:` FILTER, AND ITS ABSENCE IS LOAD-BEARING" and the line
+      # `branches: [release/1.0, master]` IN THE SAME COMMIT, EIGHTEEN LINES
+      # APART. The comment forbade one kind of event filter while the code
+      # directly above the job carried another, and nobody caught it through 84
+      # merges until the gate let a stacked pull request through. So the whole of
+      # CI-9's fix rests on an invariant - "checks.yml has no event filter" -
+      # that has already been silently violated in this exact file by the person
+      # who wrote the warning against violating it. A louder comment is not a
+      # remedy for that. A red step is.
+      #
+      # WHY THIS CAN WORK AT ALL, given CI-9 rejected the card's option 3 (a step
+      # that detects its own workflow having been skipped) as impossible. That
+      # option is impossible because a skipped workflow runs no steps, so there
+      # is nothing alive to notice. This is the different, tractable case: it
+      # fires on the pull request that REINTRODUCES a filter, and it does so
+      # whenever the filter being reintroduced STILL NAMES THAT PULL REQUEST'S
+      # OWN BASE - the ordinary case, because a filter put back by hand names
+      # the release branch people are actually targeting. The edit then has to
+      # get past this step before it can start causing skips. It is a ratchet,
+      # not a skip detector.
+      #
+      # ⚠️ AND IT IS THE HEAD'S WORKFLOW THAT DECIDES WHETHER ANYTHING RUNS, NOT
+      # THE BASE'S. An earlier draft of this comment claimed the reintroducing
+      # pull request "is still graded by the unfiltered workflow which is on the
+      # base today". That was wrong, it contradicted the checkout step's own note
+      # a few lines below, and the error was not cosmetic: it made this step
+      # sound like an unconditional ratchet, which is exactly the false comfort
+      # CI-9 exists to stamp out. MEASURED on PR #101 - head carrying a filter
+      # that excludes the base, base carrying the unfiltered workflow - and the
+      # result was no run at all, the context posted `skipped`, the rollup
+      # reading `success`, and the gate CLEARED (409). Gitea takes the workflow
+      # file from refs/pull/<n>/head, so a head that filters itself out is simply
+      # never graded, and nothing on the base can reach out and stop it. That is
+      # what blind spot 3 below is made of.
+      #
+      # WHAT IT INSPECTS is the MERGED tree in $WS - the content that would
+      # actually land on the base - not the branch tip and not the copy of this
+      # file that Gitea used to decide whether to run. Those are three different
+      # trees here (see the long note on the checkout step) and only the merged
+      # one is the thing being authorised.
+      #
+      # ⚠️ THREE ACKNOWLEDGED BLIND SPOTS. NOT ONE OF THEM IS CLOSEABLE FROM
+      # INSIDE THIS FILE, and the reason is the same in all three: each is a case
+      # where THIS WORKFLOW IS ITSELF THE THING THAT GETS SKIPPED, and a guard
+      # that lives inside a skipped workflow does not run. Closing them needs a
+      # SECOND, permanently unfiltered workflow whose own context is added to
+      # release/1.0's `status_check_contexts`, so that something survives to
+      # report when this file is sat out. That is a forge change and the
+      # repository owner's decision; it is being put to them separately and is
+      # deliberately NOT held as a blocker on CI-9.
+      #
+      #   1. A reintroduced `paths:` filter crafted to exclude the reintroducing
+      #      pull request's OWN diff would skip that pull request, so this step
+      #      would not run to object to it.
+      #
+      #   2. An edit that lands on a feature branch through a stacked pull
+      #      request is graded by the HEAD's workflow, so a filter already
+      #      present in the head hides the edit from this step - until that
+      #      branch is proposed for release/1.0, where (unless it is case 3) the
+      #      base matches the reintroduced filter and this step runs and bites.
+      #      Caught at the release boundary, which is the boundary that matters.
+      #
+      #   3. ⚠️ THE WORST OF THE THREE, AND WORSE THAN BOTH OF THE OTHERS PUT
+      #      TOGETHER: a reintroduced `branches:` filter that simply DOES NOT
+      #      NAME THE BASE escapes this step entirely, because the pull request
+      #      carrying it is itself skipped. It takes no craft and no malice to
+      #      write - `branches: [main]` copied out of a GitHub template, or a
+      #      tidy-up to `[master]`, a branch that NO pull request in this
+      #      repository's history has ever targeted - and it arrives as a
+      #      skipped, laundered, untested merge into release/1.0.
+      #
+      #      What makes it categorically worse is what happens the moment after.
+      #      Once that file is ON release/1.0, every subsequent pull request is
+      #      graded against it and every one of them is skipped too. This is not
+      #      the stacked case leaking through a crack; it is the gate off
+      #      completely, for everything, silently, with every badge green. The
+      #      only thing standing between the repository and that state today is
+      #      a human reading this file - which is precisely the kind of defence
+      #      this step exists because it has already failed once (9c1a23328a).
+      #
+      # It is deliberately a FAILURE and not a warning: a warning would leave
+      # the required context green, which is the precise defect CI-9 is about.
+      - name: guard the trigger - refuse a checks.yml that has regained an event filter
+        run: |
+          set -eu
+          f="$WS/goodwe-addon/.gitea/workflows/checks.yml"
+          test -f "$f" || { echo "checks.yml is missing from the merged tree."; exit 1; }
+          # Walk the top-level `on:` block of the MERGED file. Full-line comments
+          # at column 0 are skipped outright - this file's own prose quotes
+          # `paths:` and `branches:` many times and must not trip its own guard -
+          # and an inline `#` is trimmed from any line that is kept.
+          bad=$(awk '
+            function scan(t) {
+              sub(/#.*/, "", t)
+              if (t ~ /(^|[^A-Za-z0-9_-])(branches|branches-ignore|paths|paths-ignore|tags|tags-ignore|types)[[:space:]]*:/)
+                return 1
+              return 0
+            }
+            /^[[:space:]]*#/ { next }
+            /^("on"|'"'"'on'"'"'|on)[[:space:]]*:/ {
+              inon = 1
+              rest = $0; sub(/^[^:]*:/, "", rest)
+              if (scan(rest)) print NR ": " $0
+              next
+            }
+            inon == 1 {
+              if ($0 ~ /^[[:space:]]*$/) next
+              if ($0 ~ /^[[:space:]]/) { if (scan($0)) print NR ": " $0; next }
+              inon = 0
+            }
+          ' "$f")
+          if [ -n "$bad" ]; then
+            echo "REFUSED: checks.yml has regained an event filter in its \`on:\` block."
+            echo "$bad"
+            echo
+            echo "  A filter means some pull request stops matching this workflow. Gitea does"
+            echo "  not stay silent about a workflow it sits out - it posts the required context"
+            echo "  \`checks / unit (pull_request)\` itself with state \`skipped\`, the combined"
+            echo "  status rolls that up as \`success\`, and the merge gate ACCEPTS it. That is"
+            echo "  CI-9: a pull request merged on a workflow that never ran a step. It was"
+            echo "  reproduced by merging PR #96 for real through a protected branch."
+            echo
+            echo "  Branch protection cannot save you here - it can require that a context is"
+            echo "  PRESENT, never that it is SUCCESS - so the filter is the whole defence."
+            echo "  If you genuinely need to narrow what runs, condition a STEP, never the"
+            echo "  workflow. See the \`on:\` block's comments for the measurements."
+            exit 1
+          fi
+          echo "OK: the \`on:\` block of the merged checks.yml carries no event filter."
+
       - name: build the test image (shipped deps, from apk - see .gitea/ci/Dockerfile)
         run: |
           set -eu

goodwe_controller/CHANGELOG.md

@@ -1,34 +1,262 @@
 # Changelog
 
-## Unreleased
+## 0.10.0
 
-⚠️ **THIS HAS NO VERSION AND CANNOT REACH AN INSTALL UNTIL IT GETS ONE.**
-PKG-06's and PKG-07's rule: the Supervisor keys the built image by `version:`,
-so `ha apps update` is a silent no-op on an unbumped change. This branch
-deliberately does **not** pick the number, because the right one depends on a
-fact the branch cannot observe - whether 0.9.0's image has already been built
-and pulled. If it has not, this belongs inside 0.9.0's section before it ships;
-if it has, it needs 0.10.0. Whoever deploys decides.
+⚠️ **A CONFIG THAT IS LEGAL ON 0.9.0 IS REFUSED ON 0.10.0, AND THAT - NOT THE
+NUMBER OF TICKETS - IS WHY THIS IS A MINOR BUMP RATHER THAN A PATCH.** Same
+shape as 0.8.0's `slew_w` rule and the same test: is there a stored options
+blob the previous version started on and this one will not? There is. A refusal
+is `SystemExit(78)` (`EX_CONFIG`) - the add-on does not start, ⚠️ **and the
+ingress panel goes with it**, because the add-on serving it is not running, so
+recovery means the Supervisor UI.
+
+Measured on the reference install's own exported blob (70 keys), merged over
+this version's 75 defaults the way the Supervisor merges it, inside the CI
+image. The three below are what a reader who checks only one thing should
+check.
+
+* ⚠️ **[[TARIFF-07]] - THREE `price_provider` IDS ARE RETIRED, AND A SITE SET
+  TO ONE OF THEM IS REFUSED BY NAME AT STARTUP.** `engie_dynamic`,
+  `totalenergies_dynamic` and `eneco_eddy` are gone from `PROVIDERS`. Each was
+  accepted, silently, at every startup on 0.9.0 and earlier; on 0.10.0 each is
+  a refusal that names the id, the endpoint, what that endpoint actually
+  answers - a 404 from a gateway with no route, a TLS handshake against a
+  hostname the certificate does not cover, a 404 with an empty body - which
+  tariff the site has really been running since the id was entered, and what to
+  set instead. **The refusal IS the migration.** Every fetch any of the three
+  ever made ended in `SourceUnavailable`, and §11.4 turns that into a SILENT
+  fall back to the static profile, so there is no working behaviour to preserve
+  and nothing on the status page ever differed from a provider that simply
+  never found a cheap hour. ⚠️ **All three ids stay in `config.yaml`'s
+  `price_provider` enum on purpose**: drop one and the Supervisor rejects the
+  options file *before the add-on runs*, the operator gets an opaque `expected
+  one of ...`, and `validate.py`'s message is never seen - on exactly the sites
+  that need it. `PROVIDERS` is three; the enum is seven.
+  ⚠️ **The reference install is on `price_provider: off` and is unaffected.**
+
+* **[[TARIFF-18]] - `price_taxes_eur_kwh` moves from `0.06` to `0.11736`, and
+  the non-obvious half is the refusal that deliberately does NOT happen.** A
+  site that *stored* `0.06` is unaffected in both directions. It keeps `0.06`,
+  because `App.options` is `deepmerge(config.yaml defaults, stored options)`
+  and a moved default reaches only keys the blob does not carry - so the new
+  figure arrives at a **fresh** install, and at an existing one only when its
+  options are re-saved. ⚠️ **AND IT DOES NOT BECOME A STARTUP REFUSAL EITHER,
+  WHICH TOOK A MECHANISM.** [[TARIFF-17]] made a `price_taxes_profile` period
+  table beside a **non-default** `price_taxes_eur_kwh` a refusal, comparing
+  against the shipped default precisely because the Supervisor writes the key
+  whether the operator typed it or not. Moving the default turns every stored
+  `0.06` into "non-default" **with nobody editing anything**, so a working
+  Walloon or Brussels site with a period table would have stopped starting on
+  this upgrade, over an inert number the table overrides anyway.
+  `price.py` carries `SUPERSEDED_TAXES_DEFAULTS_EUR_KWH = (0.06,)` and
+  `validate.py` reads a superseded default as *untouched*. **The rung is not
+  weakened**: the same table beside a figure that is neither the shipped nor a
+  superseded default - ORES's `0.1198` - is still refused, by name, and the
+  refusal now says which two figures it will accept.
+
+* **[[SAFETY-10]] - a new `shadow_mode` option, shipped `auto`, and BOTH halves
+  of what that does matter.** ⚠️ **AN EXISTING INSTALL THAT IS CONTROLLING DOES
+  NOT CHANGE BY ONE WATT.** `auto` is not a constant the Supervisor merges; it
+  is a value the add-on **resolves**, and it resolves to `not control_started`
+  - `shadow.engaged()` reads `Controller.auto`, the persisted start/stop state.
+  An install with `auto_start: true`, or whose operator has pressed *Start /
+  stop control*, is started, so `auto` resolves to live. An install that is
+  **stopped** keeps its actuator at 0 W exactly as before, from the same writer
+  on the same heartbeat; what changes is what the status page says and that the
+  decision path now runs and is recorded. ⚠️ **A FRESH INSTALL COMES UP
+  OBSERVING**: it ships `auto_start: false`, has no stored `auto` key, and
+  therefore runs its whole decision path in shadow before it is ever allowed to
+  command anything. That is the "default-on" the card asked for, delivered
+  where it is safe and withheld where it is not - there is no mechanism in the
+  add-on options system by which one key can default differently for a new
+  install and an existing one, so a literal `shadow_mode: true` default would
+  have stopped the battery at the reference site on the next update.
+  **Measured cross-revision** - the same stimulus through the shipped
+  `Controller.cycle()` on `8f82dd4` (the merge before SAFETY-10) and on
+  `e6da478` (SAFETY-10 itself), start button ON: the write streams are
+  **byte-identical**, 13 / 13 / 25 writes on a 6000 W import, a 4000 W export
+  and a 300 W trickle, same values in the same order. An install that is
+  **stopped** is byte-identical across the same pair too, at one 0 W write.
+  ⚠️ The positive control is what makes that readable: the same driver with
+  `shadow_mode: on` and the button ON gets 13 writes up to 5000 W on the older
+  tree and **one 0 W write** on the newer, so the driver does reach shadow mode
+  and an identical pair is a result rather than a silence. The shadow case is
+  also graded in `test_clamp.py` part 8 on what reached `set_number()`, against
+  a precondition run that puts 30 non-zero writes on the wire. ⚠️ An
+  unrecognised `shadow_mode` fails toward inaction
+  **and** is refused by name (rule 11), so the reinterpretation is never
+  silent; no blob written before 0.10.0 can carry one.
+
+⚠️ **AND IF YOU ARE UPGRADING FROM 0.7.0 - WHICH THE REFERENCE INSTALL IS -
+THE REFUSAL THAT CAN STOP YOU IS IN 0.8.0'S SECTION, NOT IN THIS ONE.** `ha
+addons update` does not walk the versions; it installs 0.10.0 in one step, so
+**every validator rule added in 0.8.0 and 0.9.0 lands at the same moment as
+0.10.0's own**, and a config that has not been looked at since 0.7.0 meets all
+of them at once. Of those, exactly one can refuse a config nobody has edited:
+
+> [[SAFETY-39]]'s **rule 10**, added in 0.8.0, refuses an explicit `slew_w`
+> above `SLEW_RAIL_FRAC x` the site rail, where `SLEW_RAIL_FRAC` is
+> `LOOP_TICK_S / PLANT_SETTLE_S` = 2/18. On a 5000 W rail that ceiling is
+> **555.6 W** - and ⚠️ **0.7.0's own shipped default was `slew_w: 1000`**, so
+> an install that never touched the key and simply took the default does not
+> start on 0.10.0 until the value is lowered.
+
+Measured on this tree: the reference blob with `slew_w: 1000` is refused, by
+name, and the same blob at its actual `slew_w: 400` is accepted. 0.9.0's own
+additions cannot reach a pre-0.9.0 config at all - [[OPT-09]]'s two refusals
+fire only on a roster entry that USES `capacity_kwh`, a key that did not exist
+- so 0.8.0's is the whole of the crossing. **Read the live options and check
+`slew_w` against the ceiling and `price_provider` against the withdrawn list
+BEFORE `ha addons update`**, with `tools/predeploy_check.py`, which does both.
+
+✅ **RUN AGAINST THIS RELEASE: CLEARED, exit 0.**
+
+    docker run --rm -v <repo>:/w:ro -v <dir>:/opt:ro goodwe-addon-checks:1 \
+      python3 /w/goodwe_controller/tools/predeploy_check.py \
+      --deployed-version 0.7.0 --options /opt/live-options.json
+
+      deployed on the box : 0.7.0
+      shipped in this tree: 0.10.0
+      live options pass this version's validator
+      CLEARED for deploy.
+
+**The option surface: 71 keys -> 75, `options:` and `schema:` in step.** Four
+new keys, and none of them can refuse a blob written before it existed:
+`price_formula`, `price_export_formula` and `price_taxes_profile` are `str?` -
+**note the trailing `?`, they are OPTIONAL** - defaulting to `""`;
+`shadow_mode` is `list(auto|on|off)` with no `?`, which is the shape that
+becomes exit 78, and it is safe for the same reason 0.9.0's `delivery_hold_s`
+was: it carries an `options:` default, so the Supervisor's merge supplies it to
+every stored blob that lacks it. Nothing was removed. One default moved
+(`price_taxes_eur_kwh`, above) and one enum widened (`price_provider` gains
+`custom_formula`).
+
+⚠️ **WHY 0.10.0 AND NOT 0.9.0, SINCE 0.9.0'S IMAGE NEVER REACHED THE BOX.**
+The block this section closes used to say the choice depended on whether
+0.9.0 had been built and pulled, and that if it had not, this work belonged
+*inside* 0.9.0's section. That was written before 0.9.0's section was cut. It
+has been cut since `86bdf49`, on 2026-09-07, and **28 runtime commits** have
+landed behind it; folding them in would make the string `0.9.0` name two
+different trees, and the Supervisor keys the built image on exactly that
+string. Reusing it is the PKG-06/PKG-07 no-op in its worst form - a cached
+image the Supervisor is entitled to serve while reporting success. The version
+a tree has already shipped under is not available to be re-cut.
+
+⚠️ **AND THIS SECTION IS NOT THE WHOLE OF WHAT 0.10.0 SHIPS. THREE TICKETS
+WITH RUNTIME CHANGES LANDED AFTER `86bdf49` AND ARE NOT IN THE TABLE BELOW.**
+Saying so is cheaper than moving them, and moving them is [[PKG-08]]'s card,
+not this one:
+
+| ticket | runtime files | where it is written down |
+|---|---|---|
+| [[SAFETY-43]] | `app/delivery.py`, `app/packshare.py`, `config.yaml` | the `## Unreleased` block **below `## 0.9.0`**, which is misfiled |
+| [[TEST-21]] | `app/delivery.py`, `config.yaml`, `translations/` | the same block |
+| [[SAFETY-44]] | `app/main.py`, `app/store.py` | ⚠️ **nowhere in this file** |
+
+Five more landed that touch no runtime file and so cannot change what the
+image does - PKG-13, UX-04, SAFETY-31, ARCH-02, INSTR-01. The count that
+matters for the no-op check is `tools/predeploy_check.py`'s own: **28 runtime
+commits since `86bdf49`**, of which the table below accounts for 21.
+
+Contents of this release, in merge order since 0.9.0 (`86bdf49`):
 
 | | |
 |---|---|
-| _this branch_ | FCST-04 - the carry-forward fill reaches the plan, and the day it carries survives a restart |
-| _this branch_ | FCST-05 - one byte stops stopping the add-on, and the write path gets the read path's standard |
-| _this branch_ | FCST-06 - "cannot persist" stops meaning "has no /data" and starts meaning what it says |
-| _this branch_ | TARIFF-08 - the day-ahead feed is read in the shape it actually publishes, and the fixtures stop agreeing with the parser |
-| _this branch_ | TARIFF-09 - the day-ahead feed is asked for the horizon it was given, so tomorrow arrives firm instead of carried |
-| _this branch_ | TARIFF-10 - configuring a price provider is what fetches prices; trading stays its own switch |
-| _this branch_ | TARIFF-12 - a supplier outage stops deleting the plan on its first failed fetch, and TARIFF_MAX_AGE_S starts governing |
-| _this branch_ | TARIFF-14 - the price a trade is decided against is the price of the interval being traded |
-| _this branch_ | TARIFF-07 - three plugins that never fetched a price are withdrawn, and a site configured on one is told so **⚠️ BACKWARD-INCOMPATIBLE** |
-| _this branch_ | TARIFF-15 - `custom_formula`: your own tariff card's two coefficients, graded against the card's own printed price |
-| _this branch_ | TARIFF-13 - the capacity-tariff row's "quarter(s) banked" stops resetting to 0 at every restart, and a tied peak's quarter stops moving |
-| _this branch_ | TARIFF-11 - the add-on's account of the tariff plan stops flattering it, and the status page is graded as a surface |
-| _this branch_ | TARIFF-17 - a price component that varies by hour has somewhere to live, so a Walloon day/night network tariff can change which hour is cheapest |
-| _this branch_ | TARIFF-18 - `price_taxes_eur_kwh` stops shipping at half the real Flemish figure **⚠️ CHANGED DEFAULT** |
-| _this branch_ | TARIFF-16 - the injection leg stops being one number: an injection formula with its own coefficients, its own VAT and no floor under zero |
-| _this branch_ | SAFETY-45 - a price-driven charge is SIZED by the capacity-tariff guard instead of being switched on and off by it **⚠️ CONTROL STABILITY** |
-| _this branch_ | SAFETY-10 - shadow mode: the whole decision path runs and nothing reaches the inverter **⚠️ NEW OPTION, DEFAULT-ON FOR A NEW INSTALL** |
+| `c2787da` | FCST-04 - the carry-forward fill reaches the plan, and the day it carries survives a restart |
+| `5059e28` | FCST-05 - one byte stops stopping the add-on, and the write path gets the read path's standard |
+| `958f5cd` | FCST-06 - "cannot persist" stops meaning "has no /data" and starts meaning what it says |
+| `4257e38` | TARIFF-08 - the day-ahead feed is read in the shape it actually publishes, and the fixtures stop agreeing with the parser |
+| `88c59a9` | TARIFF-09 - the day-ahead feed is asked for the horizon it was given, so tomorrow arrives firm instead of carried |
+| `559f0eb` | TARIFF-10 - configuring a price provider is what fetches prices; trading stays its own switch |
+| `a6e64fb` | TARIFF-12 - a supplier outage stops deleting the plan on its first failed fetch, and TARIFF_MAX_AGE_S starts governing |
+| `8d09b30` | TARIFF-14 - the price a trade is decided against is the price of the interval being traded |
+| `aade2c7` | TARIFF-07 - three plugins that never fetched a price are withdrawn, and a site configured on one is told so **⚠️ BACKWARD-INCOMPATIBLE** |
+| `068b83f` | TARIFF-15 - `custom_formula`: your own tariff card's two coefficients, graded against the card's own printed price |
+| `b4a3801` | TARIFF-13 - the capacity-tariff row's "quarter(s) banked" stops resetting to 0 at every restart, and a tied peak's quarter stops moving |
+| `c518007` | TARIFF-11 - the add-on's account of the tariff plan stops flattering it, and the status page is graded as a surface |
+| `7796f16` | TARIFF-17 - a price component that varies by hour has somewhere to live, so a Walloon day/night network tariff can change which hour is cheapest |
+| `4dcd9b0` | TARIFF-18 - `price_taxes_eur_kwh` stops shipping at half the real Flemish figure **⚠️ CHANGED DEFAULT** |
+| `478ba93` | TARIFF-16 - the injection leg stops being one number: an injection formula with its own coefficients, its own VAT and no floor under zero |
+| `8f82dd4` | SAFETY-45 - a price-driven charge is SIZED by the capacity-tariff guard instead of being switched on and off by it **⚠️ CONTROL STABILITY** |
+| `e6da478` | SAFETY-10 - shadow mode: the whole decision path runs and nothing reaches the inverter **⚠️ NEW OPTION, DEFAULT-ON FOR A NEW INSTALL** |
+| `587495e` | SAFETY-47 - what a shadow run can show you, and the watts on its status row **⚠️ CORRECTS THREE CLAIMS SAFETY-10 SHIPPED** |
+
+### SAFETY-47 — what a shadow run can show you, and the watts on its status row
+
+⚠️ **Nothing about the write path changed, and nothing needed to.** Shadow
+mode still holds every inverter at 0 W through the one writer. What was wrong
+is what three merged documents **said** a shadow run can show you, and a number
+on the status page that could be **6.61×** what a live controller would
+command.
+
+**A shadow run cannot show you a closed-loop defect. Not partially — not at
+all.** The battery is held at 0 W, 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, and a closed-loop defect is one whose
+stimulus *is* the plant's response. That is the same property that makes shadow
+mode safe, so it is not a gap to be closed later: **the closed-loop answer
+comes from the closed-loop rig or from a live run.**
+
+SAFETY-10 promised otherwise, because of a sentence that was true when it was
+written and false one commit later:
+
+> the **strategies** are unaffected — they ask for a fixed power from inputs
+> that do not depend on what the battery did — so a shadow run does show you
+> the trades, the peak-guard engagements and the SoC-limit behaviour.
+
+SAFETY-45 (above) sizes the buy leg to the billed quarter's charging headroom,
+and that headroom is `(900 / seconds remaining) × (ceiling − projected)` with
+the projection read off the **open quarter's meter**. The strategy became
+closed-loop the day that landed. Measured on the rig, one hour at `peak_cap_w`
+1500 under a 1200 W house:
+
+| | live | shadow |
+|---|---|---|
+| charge onsets | 28 | **1** |
+| grid | −455.5 … +3200.0 W | **1200.0 W flat — the house** |
+| capacity guard engaged | 410 / 720 cycles | **0 / 720** |
+| state of charge | 50.000019 → 51.856789 % | **50.000000 → 50.000000 %** |
+
+**What the documents now say.** The exemption narrows to exactly what is still
+true — **which** hour a strategy picks and **why** are unaffected, because the
+clock and the price series are not functions of the battery; **how hard** it
+trades is not. Of the three defects shadow mode was written for, one —
+TARIFF-14's wrong quarter-hour — is genuinely visible from a shadow run, and it
+is graded that way: identical live and shadow on 720 of 720 charging cycles at
+a binding cap.
+
+**What you will see on the status page.** The `Shadow mode` row and the action
+log now introduce the watts as what the controller would have commanded **on
+this cycle** — in every state, because no number a shadow run records is a
+forecast of a live run. And when a **measured** billed quarter sized those
+watts, both surfaces carry:
+
+> ⚠️ 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.
+
+⚠️ **The number is caveated, not re-computed, and that was the decision.**
+Re-computing it to "look right" would mean the recorded decision was no longer
+the decision the shipped path reached — while the arbiter, the clamp, the
+write-authorisation gate, the action log and MQTT all ran on the real one. A
+shadow run's whole worth is that what it records is what the controller
+actually decided. `DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md` §3
+records the three alternatives that were rejected and why.
+
+⚠️ **On a site whose cap does not bind, nothing changes by one watt.** At
+`peak_cap_w` 15000 against a 350 W house the recorded figure is the live one
+exactly, and no caveat is a lie there either — the row still says the size came
+off a meter with no battery in it, which is true and is the point.
+
+**And SAFETY-10's own committed evidence could never have failed.** Its
+comparison table ran at a cap the guard never reaches, *and* read only the
+first charging sample — the one instant at which the two runs agree even at a
+cap that does bind. Both had to be closed; closing either alone closes nothing.
+The table is re-taken across the whole run at a binding cap, and
+`test_arbitrage.py` part 3d is the CI-side grader so this class cannot recur.
+14 mutations, no survivors; all 29 check files green.
 
 ### SAFETY-10 — shadow mode, and what its default does to YOUR install
 
@@ -1557,12 +1785,30 @@ and pulled. If it has not, this belongs inside 0.8.0's section before it ships;
 if it has, it needs 0.8.1. Whoever deploys decides, and PKG-07 is the record of
 what happens when nobody does.
 
+⚠️ **ANNOTATED BY PKG-14, 2026-09-16 - EVERY ROW BELOW HAS SHIPPED, AND THE
+PARAGRAPH ABOVE IS NO LONGER TRUE OF ANY OF THEM.** It is annotated rather
+than rewritten, and nothing is moved out of it, because re-filing this file's
+misplaced entries is [[PKG-08]]'s card and guessing a boundary is what that
+card exists to stop. What is measurable, and what PKG-14 measured:
+
+* **UX-02 shipped in 0.9.0.** Its merge `3d29993` is an ancestor of the 0.9.0
+  bump `86bdf49` and it is already listed in `## 0.9.0`'s own contents table,
+  so this row is a duplicate of a released one.
+* **UX-04, TEST-21 and SAFETY-43 shipped in 0.10.0.** All three merged after
+  `86bdf49`. TEST-21 (`app/delivery.py`, `config.yaml`, `translations/`) and
+  SAFETY-43 (`app/delivery.py`, `app/packshare.py`, `config.yaml`) are runtime
+  changes and are named in `## 0.10.0`'s preamble as shipping there and being
+  written down here; UX-04 touches no runtime file.
+* ⚠️ **[[SAFETY-44]] also shipped in 0.10.0 and is nowhere in this file** -
+  `app/main.py` and `app/store.py`, three commits. It is named in
+  `## 0.10.0`'s preamble for the same reason.
+
 | | |
 |---|---|
-| _this branch_ | UX-02 - a configuration page in the ingress panel, where the validator's refusals can be seen |
-| _this branch_ | UX-04 - UX-01's three unmet acceptance criteria: one withdrawn, one built, one re-attributed |
-| _this branch_ | TEST-21 - `delivery_hold_s`'s floor re-derived from a harness that is now committed, and the recorded 30.0 s did not reproduce |
-| _this branch_ | SAFETY-43 - delinquency measured against the ask as well as against a flat 500 W, closing OPT-09's disclosed detection regression |
+| `3d29993` | UX-02 - a configuration page in the ingress panel, where the validator's refusals can be seen **⚠️ SHIPPED IN 0.9.0, see that section** |
+| `bb46916` | UX-04 - UX-01's three unmet acceptance criteria: one withdrawn, one built, one re-attributed **⚠️ SHIPPED IN 0.10.0** |
+| `6719bd8` | TEST-21 - `delivery_hold_s`'s floor re-derived from a harness that is now committed, and the recorded 30.0 s did not reproduce **⚠️ SHIPPED IN 0.10.0** |
+| `37dd0f0` | SAFETY-43 - delinquency measured against the ask as well as against a flat 500 W, closing OPT-09's disclosed detection regression **⚠️ SHIPPED IN 0.10.0** |
 
 ⚠️ **SAFETY-43 CLOSES THE DETECTION REGRESSION OPT-09 DISCLOSED, AND IT IS A
 TWO-INVERTER FIX. N=1 IS BYTE-IDENTICAL.** `delivery.delinquent()` named a unit

goodwe_controller/DECISIONS/SAFETY-10-shadow-mode.md

@@ -1,6 +1,12 @@
 # SAFETY-10 — shadow mode, and why "default-on" is not `true`
 
 **Status:** decided and implemented on branch `SAFETY-10`.
+⚠️ **AMENDED BY SAFETY-47, and three of the claims below were false when this
+was merged.** §5's "the strategies are unaffected" exemption, §4's peak-guard
+row and §6's evidence table are corrected in place and each correction is
+marked. The amendments are marked rather than rewritten silently, because what
+this card believed is part of why the defect shipped. See
+`DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md`.
 **Card:** SAFETY-10 — *"Shadow mode (default-on, log-only decisions)"*.
 **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
@@ -26,6 +32,12 @@ the CI image and on TEST-23 stage 3's closed-loop rig.
    and **latch a trip that survives into live operation and a restart**. §4.
 4. **The loop leg's shadow decision is one slew step, not a trajectory, and
    that is a real limitation of this feature.** §5.
+5. ⚠️ **SAFETY-47: and neither is anything else that depends on the plant
+   answering back. A shadow run cannot surface a closed-loop defect at all**,
+   by the same construction that makes it safe — the battery is held at 0 W, so
+   every measured input describes a plant that did not respond. Of the three
+   defects §"WHAT DEFECT THIS PREVENTS" was written for, exactly one —
+   TARIFF-14's wrong quarter-hour — is visible from a shadow run. §5, §6.
 
 ---
 
@@ -130,9 +142,9 @@ shadow run can report *"it would have hit the rating here"*.
 | surface | what it carries |
 |---|---|
 | status banner | `SHADOW MODE - the battery is NOT being controlled...`, **first in the cascade**, amber — red, with the latch named, if one is standing |
-| status row `Shadow mode` | which rung decided, the watts it **would have commanded**, where the inverter actually is, and `Resolution.explain()` |
+| status row `Shadow mode` | which rung decided, the watts it **would have commanded on this cycle**, where the inverter actually is, and `Resolution.explain()` — plus, when a measured billed quarter sized those watts, SAFETY-47's caveat saying so (`shadow.SIZED_FROM_METER`) |
 | status row `Commanded` | `0 W` — the truth, which the row above reconciles with the `Why` row below it |
-| action log | one line when shadow mode comes on; one line per **change of decision** (winner or rounded watts), carrying the arbiter's own sentence |
+| action log | one line when shadow mode comes on; one line per **change of decision** (winner, rounded watts, or SAFETY-47's caveat state), carrying the arbiter's own sentence and the same caveat the row carries — `shadow.log_line()` is the one sentence both read |
 | MQTT | `status: shadow`, its own value, below `failsafe` |
 
 The action log is **edge**-logged, not level-logged: the log holds 40 rows, and
@@ -149,7 +161,7 @@ minutes at the 15 s cycle floor.
 | SAFETY-03 clamp | **OBSERVES** | Runs on the decision, sets `clamp_last`, logs every engagement. Changes no command |
 | SAFETY-28 write gate | **OBSERVES** | Same placement, same reason: the question is who chose the number |
 | SAFETY-18 meter freeze | **OBSERVES**, unchanged | It takes no action live either; both halves of its conjunction are as true in shadow |
-| SAFETY-07/24/25 peak guard | **OBSERVES** | Level-triggered, unlatched, files its claim as usual — SAFETY-45's limit cycle is visible from a shadow run, which is the point |
+| SAFETY-07/24/25 peak guard | **OBSERVES, AND SEES ONLY THE HOUSE** | Level-triggered, unlatched, files its claim as usual, so the recorded decision is the real one *for this meter*. ⚠️ **AMENDED BY SAFETY-47.** This row used to end "SAFETY-45's limit cycle is visible from a shadow run, which is the point". It is not: every term of `wanted = batt_w + excess` is measured, and in shadow mode the battery contributes nothing to either. Measured on the rig, same hour, same unsized code — **410 of 720 cycles engaged live, 0 of 720 in shadow** |
 | SAFETY-31 circulation | **OBSERVES AND MAY LATCH** | Its evidence is *measured* power. Packs pushing against each other while all are told 0 W is a real fault |
 | SAFETY-42 delivery | **OBSERVES AND MAY LATCH** | Same, against a share that is 0 W |
 | operator stop | **SUPPRESSED AS A CLAIM, ENFORCED AT THE WIRE** | The one deliberate change. Its `P_SAFETY` 0 W claim out-ranks everything, so leaving it in makes the recorded decision `"stopped"` on every cycle and the run answers the wrong question. The actuator ends at the same number either way, and the wire substitution is **strictly stronger**: a claim can be out-ranked, and it cannot |
@@ -186,12 +198,47 @@ is a closed-loop property, it did not happen, and reporting it would be a
 simulation of a plant that does not exist; three cycles in, such a number
 describes nothing.
 
-The strategies are unaffected: arbitrage, the peak guard and maintenance all
-file `SET` claims at a fixed power from level-triggered inputs. That is why the
-three defects this card was written for — SAFETY-45's 28 onsets an hour,
-TARIFF-14's wrong quarter-hour, SAFETY-46's ceiling churn — are all visible from
-a shadow run, and the loop's ramp is not. Graded, named, in
-`test_watchdog.py` part 10 as `RECORDED LIMITATION`.
+⚠️ **AMENDED BY SAFETY-47 — THE PARAGRAPH THAT STOOD HERE WAS THE DEFECT.**
+It read:
+
+> The strategies are unaffected: arbitrage, the peak guard and maintenance all
+> file `SET` claims at a fixed power from level-triggered inputs. That is why
+> the three defects this card was written for — SAFETY-45's 28 onsets an hour,
+> TARIFF-14's wrong quarter-hour, SAFETY-46's ceiling churn — are all visible
+> from a shadow run, and the loop's ramp is not.
+
+It was true until **SAFETY-45 merged, one commit before this card**. That
+change makes the buy leg `min(asked, headroom)` with
+
+```
+headroom = (900 / remaining) x (ceiling - projected)
+```
+
+and `projected` reads the **open quarter's accumulator** — the meter — which is
+a function of what the battery did earlier in that same quarter. The strategy
+is closed-loop, and the loop's one-slew-step limitation above is not a special
+case of anything: **it is the general case**, and the limitation is the whole
+feature's, not the loop leg's.
+
+**The correct statement, and it is now graded rather than asserted:**
+
+> A shadow run cannot surface a **closed-loop** defect — one whose stimulus is
+> the plant's response to the controller — because the battery is held at 0 W
+> and there is no response to be the stimulus. **Which** hour a strategy picks
+> and **why** are unaffected, because the clock and the price series are not
+> functions of the battery. **How hard** it trades is not.
+
+Of the three defects this card was written for:
+
+| | visible from a shadow run? | 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 live, **0/720** in shadow |
+| SAFETY-46's SoC churn | **no** | the SoC moves **0.000000000 pp** in a shadow run. No SoC limit can be *reached* in one |
+| TARIFF-14's wrong quarter-hour | **yes**, and it is the one | which hour, at what price, clearing what spread: identical live and shadow on **720 of 720** charging cycles, at a binding cap |
+
+Graded in `test_arbitrage.py` part **3d** — the same closed loop part 3c uses,
+run once live and once in shadow — and the loop leg's own limitation stays
+named in `test_watchdog.py` part 10 as `RECORDED LIMITATION`.
 
 ---
 
@@ -218,22 +265,60 @@ The closed-loop half is `/home/homelab/s10-mut/shadowloop.py` on TEST-23 stage
 3's rig: the same hour, twice, against `plantsim.Plant` through the firmware's
 own frame encoder.
 
+⚠️ **SUPERSEDED BY SAFETY-47 — THE TABLE THAT STOOD HERE COULD NEVER HAVE GONE
+RED, FOR TWO INDEPENDENT REASONS.** It read `arb_power_w` −2000 W *"identical"*,
+`arb_reason` *"identical, verbatim"*, arbiter winner *"identical"*, and
+concluded *"the decision happened, at the same instant, for the same reason, at
+the same signed power — and the battery did not move."* The battery half is
+true and is unchanged. The **decision** half was decoration:
+
+1. **the fixture is `peak_cap_w: 15000` against a 350 W house**, so the
+   capacity 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**. Measured: closing reason (1) alone leaves
+   that comparison passing.
+
+Both had to be closed. Re-taken below at **`peak_cap_w` 1500 / house 1200 /
+`max_w` 2000**, one hour at a 5 s cycle, **across the whole run** — harness
+`/home/homelab/s47-mut/shadowloop47.py`, same rig, same three transcribed
+lines.
+
 | | live | shadow |
 |---|---|---|
-| `plant_cmd_w` | −2000 W throughout | **0 W throughout** |
-| `batt_w` | −2000 .. −40.6 W | **0.0 W, exactly** |
-| SoC | 50.000 → **62.331 %** | 50.0 → **50.0 %** |
-| grid | 390.6 .. 2350 W | **350 W = the house, exactly** |
-| `ARBITRAGE_CHARGE` samples | 3600 | **3600** |
-| first charge instant | 2026-01-15T00:00:00+00:00 | **identical** |
-| `arb_power_w` | −2000 W | **identical** |
-| `arb_reason` | the strategy's own sentence | **identical, verbatim** |
+| grid | 1224.1 … 1506.0 W — **held up at the ceiling** | **1200.0 W flat = the house, exactly** |
+| SoC | 50.000019 → **51.856789 %** | 50.000000 → **50.000000 %** |
+| `ARBITRAGE_CHARGE` cycles | 720 / 720 | **720 / 720** |
+| first charging cycle, `arb_power_w` | −300.0000 W | **identical — and this is why the old table passed** |
+| `arb_power_w`, **whole run** | −307.799 … −299.930 W | **−2000.000 … −300.000 W** |
+| …cycles where the two differ | — | **716 of 720** |
+| `arb_reason`, whole run | the strategy's own sentence | **differs on 719 of 720** |
+| measured charging headroom | 299.93 … 307.80 W | **300.0 … 54 000.0 W** |
+| final recorded command | **−302.4 W** | **−2000.0 W — 6.61× the live figure** |
+| price / spread / which hour | | **identical on 720 of 720** |
 | arbiter winner | `arbitrage` | **identical** |
 
-The decision happened, at the same instant, for the same reason, at the same
-signed power — and the battery did not move.
+**What the re-taken table says.** The decision still *happens*, at the same
+instant, on the same hour, at the same price, for the same *kind* of reason,
+and the battery still does not move — those were the card's real claims and
+they hold. What does **not** hold is that the decision is the *same decision*:
+its **size** is a function of a meter the battery never moved, and at this cap
+the recorded figure is 6.61× what a live controller commands. 54 000 W of
+"headroom" under a 1500 W ceiling is `900/remaining` multiplying a gap the
+battery never closed.
 
-⚠️ **Three lines of that harness are a TRANSCRIPTION and are marked as one.**
+⚠️ **And the SoC row is the second half of it.** 0.000000000 pp of movement is
+not a curiosity: it is the proof that **no SoC-limit behaviour is reachable
+from a shadow run at all**, which §5 used to promise.
+
+SAFETY-47 puts the caveat on both surfaces that carry the number and narrows
+the three documents' claims; `test_arbitrage.py` part 3d is the CI-side grader
+so this class cannot recur.
+
+⚠️ **Three lines of each harness are a TRANSCRIPTION and are marked as one.**
 `priceloop.Rig` has no `_write_unit()`, no clamp and no failsafe machine
 (divergence 2 of its README), so the substitution's **placement** is
 transcribed there. The shipped placement is graded by `test_clamp.py` part 8,

goodwe_controller/DECISIONS/SAFETY-39-slew-against-the-rail.md

@@ -187,6 +187,23 @@ over-absorption. So the rig does not choose the number — **the constraint
 chooses it, and the rig says what the constraint does and does not buy.** That
 is the same relationship the 2026-08-22 table had to its own three columns.
 
+⚠️ **FORWARD REFERENCE, ADDED BY SAFETY-48 — THIS TABLE AND THIS SENTENCE ARE
+TRUE OF release/1.0's LAW AND FALSE OF THE ONE THAT REPLACED IT.** Nothing above
+is retracted: re-run on release/1.0 today the same rig prints the same column
+(958 / 1107 / 1133 / 1058 / 987 / 1029 / 1150 / 1143 / 1081 W), flat,
+non-monotone, 800 better than 556. Under SAFETY-48's lead cap the **same script
+on the same plant** prints 777 / 734 / 663 / 563 / 553 / 507 / 435 / 358 / 321 W
+— falling monotonically, so a slower slew is now *better* and the sentence above
+inverts. The mechanism SAFETY-39 identified is exactly why: `slew_w` bounds the
+OUTPUT while the integrator goes on accumulating `gain · error`, so slowing the
+slew used to buy nothing; bound the integrator's lead and it starts to.
+`tools/slew_sim.py --slew` now names which of the two laws it is running under
+before it narrates the column, and
+`DECISIONS/SAFETY-48-bounding-the-integrator-lead.md` §6 carries both tables and
+the independent confirmation from `test_control.py`'s own plant model. ⚠️ **This
+does NOT re-open the choice of 556**: the constraint picks the number, the rig
+does not, and that is unchanged in both laws.
+
 ⚠️ **A single step is not evidence here.** The deadband, the 10 W quantisation
 and the phase of the step against the tick move the result by hundreds of watts,
 non-monotonically. The first cut of this derivation was a single step and ranked

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

@@ -0,0 +1,319 @@
+# 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.

goodwe_controller/DECISIONS/SAFETY-48-bounding-the-integrator-lead.md

@@ -0,0 +1,551 @@
+# SAFETY-48 — the slew step ceiling reaches the integrator, and what it bounds is the LEAD
+
+**Status:** decided and implemented on branch `SAFETY-48`, on top of `TEL-10`.
+**Card:** SAFETY-48 — *"the integrator goes on winding while the command is
+slew-limited"*.
+**Nothing here reached the inverter.** The live install still runs `slew_w: 400`
+applied by hand on 2026-09-05 12:00 and `release/1.0`'s control law. This branch
+does not deploy and does not bump the version.
+
+---
+
+## 0. The four things a reader should take away
+
+1. **It is a missing case, not a wrong constant, and the arithmetic says so.**
+   The integrator moves `gain * error` a cycle and the command moves at most
+   `slew_w`, so the integrator outruns the command whenever
+   `|error| > slew_w / gain` — 667 W at the live shape. SAFETY-39's retune made
+   `slew_w` **smaller**, which makes that threshold **lower**. §1.
+2. ⚠️ **THE FORM THE CARD ASKED FOR RAISES THE BILLED QUANTITY, AND THAT IS WHY
+   IT IS NOT WHAT SHIPPED.** Reusing the asymmetric freeze on a carried slew
+   flag cuts export 13 % and moves the worst quarter-hour average **offtake**
+   from 3739 W to **3935 W**, with the mean quarter +2.7 W — and on the billed
+   quarter it is worse at **every plant lag where release/1.0 produces a peak
+   at all** (a tie at lag 0, worse at 2.5 / 5.0 / 7.5 / 10.0 s) and at **every
+   top-N cut of the quarters**, which makes this the least lag-sensitive result
+   in the card. The harm is a tail redistribution inside quarters that already
+   net to offtake, not a weaker answer to import in aggregate. §3, §3a.
+3. **What ships bounds the LEAD at one slew step, only where the slew is what
+   stopped the command, and only in the leading direction.** The robust result
+   is the **export reduction — 39.6 → 34.1 kWh, and it falls at every plant and
+   tuning tried** — with wasted throughput 4.67 → 3.19 kWh, sign reversals
+   2992 → 2770 and median recovery 232 → 199 s. ⚠️ **The billed quarter is not
+   something this card can claim.** It reads 3739 → **3434 W** at the fitted
+   plant lag of 7.5 s; at every lag ≤ 5.0 s — including the one that best
+   reproduces the recorded export — release/1.0 is *already* at 3434 W and this
+   card moves it by exactly zero. The lag is not identified by the data. §4,
+   §3a.
+4. **Two committed numbers moved and neither is a silent edit.** SAFETY-13's
+   released command settles lower, because there is less wound integrator to
+   settle onto; and SAFETY-39's *"the slew does not own the over-absorption"* is
+   now **false — inverted, on its own independent plant model.** §5, §6.
+
+---
+
+## 1. The defect, in the terms the code uses
+
+`compute()` freezes the integrator with an asymmetric rule, and the comment
+beside it states the requirement outright:
+
+> the requirement is that the INTEGRATOR stop accumulating, not only the command
+
+But `frozen` is computed from **one** signal:
+
+```python
+saturated_now = abs(prev_w - actual_w) > tuning.saturation_w   # not tracking
+```
+
+Slew-limiting never enters it. When the command hits the step ceiling the
+integrator keeps winding at `gain * error` until it reaches `integrator_max_w`,
+and the unwind afterwards is `integrator_max_w / slew_w` cycles — 12.5 at the
+live shape, about a minute at the meter's measured tick.
+
+⚠️ **AND THE RETUNE MADE IT MORE FREQUENT, NOT LESS.** `|error| > slew_w / gain`
+is 1667 W at `slew_w: 1000` and **667 W** at `slew_w: 400`. The measured median
+grid error at the onset of a recorded episode is 1114 W — above the second
+threshold and below the first. This is why SAFETY-39 did not fix it, and the
+mechanism is the same one §6 shows inverting.
+
+## 2. How it was measured, and what the measurement cannot say
+
+`tools/replay_recorded_loop.py`, over **16.00 days / 256 252 meter instants** of
+the live install's own recorder, exported read-only.
+
+**Real:** the disturbance (`D = grid + batt` at every recorded meter instant —
+the house with this loop's own battery taken back out, which is exogenous and
+therefore valid to drive a counterfactual with); the tick (the meter's own
+recorded instants, median **5.01 s**); and the control law, imported out of the
+checkout. The "before" law is the **same file** with the SAFETY-48 block removed
+by a named substitution and exec'd into a fresh namespace — never a
+transcription — and a missing or duplicated anchor is a **refusal** with
+`NOTHING HAS BEEN MEASURED` on it, because an instrument that quietly compared
+the shipped law with itself would report the card as changing nothing.
+
+**Modelled:** the inverter (pure delay 7.5 s + first-order lag 2.0 s +
+`batt = 0.973 × cmd − 22.4 W`, fitted on this same recording above the SoC
+floor, residual **375 W RMS**); the pack (SoC integrated, discharge refused at
+or below the floor); and **everything else the arbiter does** — the recorded
+setpoint is the arbiter's output after the peak guard, the SoC clamps,
+maintenance and arbitrage, while the replay runs `compute()` alone.
+
+⚠️ **THE ABSOLUTE FIGURES ARE PESSIMISTIC BY ABOUT A THIRD AND THE TOOL PRINTS
+IT ON EVERY RUN.** Replaying the before-law reproduces 39.6 kWh of export where
+the install actually exported **29.4 kWh** over the same window. The delta is
+what this instrument is for: both laws run on the same ticks, the same
+disturbance, the same plant and the same seed.
+
+⚠️ **THE SoC FILTER ON THE PLANT FIT IS THE WHOLE FIT, AND IT IS A FINDING IN
+ITS OWN RIGHT.** This install spends **36 % of its ticks at or below a 10 % SoC
+with the command standing near 2 kW and the battery delivering nothing.** Fitted
+over all ticks the recording says `batt = 0.50 × cmd − 396 W, r = 0.70` — a
+plant that follows half the command, which no inverter does. Above the floor the
+same data says `batt = 1.00 × cmd − 28 W, r = 0.977`. The floor is the PACK and
+is modelled separately.
+
+## 3. The form the card asked for, and the number that refused it
+
+The card asked for the asymmetric rule already in service for saturation, on a
+flag carried across cycles the way `sat_count` is. It was built — from
+release/1.0's own source, one substitution per change — and measured on the same
+16 days through the same pipeline:
+
+| | release/1.0 | **form A** — carried slew flag + the asymmetric freeze | **SAFETY-48** — the lead cap |
+|---|---:|---:|---:|
+| export kWh | 39.61 | 34.43 | **34.07** |
+| import kWh | 116.07 | 110.62 | 111.20 |
+| battery sign reversals | 2992 | **2656** | 2770 |
+| wasted throughput kWh | 4.67 | **2.99** | 3.19 |
+| **worst 15-min offtake W** | 3739 | ⚠️ **3935** | **3434** |
+| mean quarter-hour offtake delta | — | ⚠️ **+2.73 W** | **−2.39 W** |
+| worst quarter-hour delta | — | +992 W | +532 W |
+| recovery median s | 232 | **184** | 199 |
+| recovery p99 s | 849 | **781** | 850 |
+| recovery max s | 901 | 890 | 898 |
+| unrecovered (> 900 s) | 53 | **26** | 31 |
+| \|i_w − prev_w\| p99 W | 3361 | 1534 | **800** |
+| \|i_w − prev_w\| max W | 9200 | 6912 | **800** |
+
+**Form A wins on four rows and loses on the one that is billed.** The capacity
+tariff (*capaciteitstarief*) bills the month's worst quarter-hour average
+offtake, and form A raises it by **196 W** — and raises the MEAN quarter by
+2.7 W, so this is systematic and not one unlucky quarter. It does so in **five
+of the six** plant and tuning variants in `--sensitivity`; the sixth is a tie.
+
+The per-cycle mechanism is that a frozen integrator stops at
+`prev + gain·error(first cycle)`, which is `(1 − gain)` short of what the site
+needs — 40 % short at `gain: 0.6`.
+
+⚠️ **AND THE SENTENCE THAT USED TO FOLLOW THAT ONE WAS TOO BIG FOR THE DATA.**
+It read *"for an IMPORT it is offtake, so a large import is answered too weakly
+for as long as the ramp lasts"*. The aggregate does not show a weaker answer to
+import: form A cuts total import by **5.45 kWh** and export by **5.18 kWh**
+against release/1.0, and paired tick by tick it delivers **8.56 kWh LESS**
+offtake energy on the ticks release/1.0 spent importing (lower on 38 229 such
+ticks, higher on 19 669). What form A moves is the **TAIL, within quarters that
+already net to offtake** — the worst quarter goes 3739 → 3935 W, the top five
+3260 → 3300 W, the top fifty 1880.0 → 1882.7 W. The capacity tariff bills the
+worst quarter and nothing else, so a redistribution that leaves the mean alone
+and lifts the maximum is exactly the trade that is refused here. The conclusion
+is unchanged; the causal sentence is now the one the data supports.
+
+⚠️ **THE CARD SAID "do not invent a second rule", AND THE MEASUREMENT SAYS TO.**
+That instruction is recorded here rather than quietly dropped. What ships is a
+different rule; the paragraph above is why.
+
+## 3a. ⚠️ The plant lag is NOT identified by this recording, and the billed quarter is the claim that depends on it
+
+`fit_plant()` picks `lag 7.5 s` because it minimises **battery-power RMS**. That
+objective barely distinguishes the candidates — 375.3 W at 7.5 s against 376.4 W
+at 2.5 s, **0.3 %** — while the tool's *own* printed fidelity measure, replayed
+export against the **29.43 kWh this install actually exported**, prefers 2.5 s by
+the whole of the 35 % gap the header warns about. Two measures on the same data
+disagree, and nothing here breaks the tie.
+
+So the sweep has to be read as a sensitivity, not as a confirmation:
+
+| plant lag | fit RMS W | replayed export kWh (release/1.0) | **worst 15-min offtake W:** release/1.0 | form A | SAFETY-48 | mean quarter ΔW |
+|---:|---:|---:|---:|---:|---:|---:|
+| 0.0 | 392.3 | 23.5 | **3434** | 3434 | **3434** | +0.53 |
+| 2.5 | **376.4** | **28.9** ← nearest 29.43 | **3434** | ⚠️ 3732 | **3434** | −0.59 |
+| 5.0 | 378.0 | 32.1 | **3434** | ⚠️ 3711 | **3434** | −1.02 |
+| 7.5 | **375.3** ← chosen | 39.6 | 3739 | ⚠️ 3935 | **3434** | −2.39 |
+| 10.0 | 384.2 | 75.4 | 3954 | ⚠️ 4326 | **3434** | −4.65 |
+
+(The RMS column is `fit_plant()`'s own inner sweep pinned to one lag — best `tau`
+and a re-fitted gain/offset at that lag. The export and quarter columns follow
+`--sensitivity`'s convention instead: only the lag is substituted into the
+global fit, everything else held. That is why the lag 5.0 and 10.0 export
+figures are the ones already printed in §7b.)
+
+⚠️ **AT EVERY LAG ≤ 5.0 s THE IMPROVEMENT IS NOT AN IMPROVEMENT — IT IS AN
+ABSENCE.** release/1.0's worst quarter is *already* 3434 W there and SAFETY-48
+changes it by **exactly zero**. §7b's paragraph used to read the `3434 → 3434`
+rows as "the direction does not move"; that is the wrong reading. The direction
+has nothing to move: at those plants release/1.0 never produces a quarter worse
+than 3434 W in the first place, and the 3739 → 3434 W headline exists only at
+the single longest lag `fit_plant()` happens to select. **The peak claim is a
+property of the plant model, not of the card.** What the card can claim on the
+billed quantity is that it does not make it worse, at any lag.
+
+⚠️ **AND THE ONE RESULT HERE THAT IS NOT LAG-SENSITIVE IS THE FORM-A
+REJECTION.** Form A's worst quarter is the worst of the three at **every lag
+where release/1.0 produces a peak at all** — 3732, 3711, 3935, 4326 against
+release/1.0's 3434, 3434, 3739, 3954 at lags 2.5 / 5.0 / 7.5 / 10.0, and a tie
+at lag 0.0 where both sit at 3434. It is worse at every top-N cut of the
+quarters at the fitted plant (top-1 3934.6 against 3738.7, top-5 3299.7 against
+3260.5, top-10 2890.6 against 2871.0, top-50 1882.7 against 1880.0, top-100
+1481.7 against 1479.0), and it raises the mean quarter. §3 understated this: the rejection does not rest on one unlucky
+quarter at one plant, which is exactly the objection a lag-sensitive result
+invites.
+
+⚠️ **WHAT WOULD SETTLE IT IS NOT IN THIS RECORDING.** Both objectives above are
+computed from the same four recorded entities, and they disagree; nothing else
+in the capture breaks the tie, and this card did not go looking for a third
+objective after seeing which lag each of the first two preferred. A driven step
+response — the command timestamped where it is written rather than where Home
+Assistant recorded it — is what identifies a lag. That is a rig measurement and
+it is not this card. Until it exists, the export reduction is what this card
+delivers and the peak figure is a plant-model artefact.
+
+## 4. What ships
+
+```python
+    slew = slew_limit_w(tuning)
+    slewed = max(prev_w - slew, min(prev_w + slew, target))
+    if slewed != target:
+        reason = "slew-limited"
+        _lead_cap = SLEW_LEAD_STEPS * slew
+        if target > slewed:
+            i_w = min(i_w, slewed + _lead_cap)
+        elif target < slewed:
+            i_w = max(i_w, slewed - _lead_cap)
+    target = slewed
+```
+
+Four properties, and each of them is a decision:
+
+* **It is inside the branch**, and ⚠️ **that placement was a SURVIVOR of all
+  thirty files until a check was written for it.** Applying it to every cycle
+  instead — `i_w = max(target - cap, min(target + cap, i_w))` after
+  `target = slewed`, −92 B — is **bit-identical on the shipped configuration**:
+  0 of 256 246 ticks differ over the 16-day recording. The two separate **only**
+  where `integrator_max_w` is set ABOVE `max_w` — the configuration `control.py`
+  says is the only way its `clamped` reason is reachable. There the integrator
+  is *deliberately* allowed above the rail, and an unconditional cap would drag
+  it back to the command every cycle and make the option inert.
+  `test_telemetry.py` part 4 drives that configuration, and the unconditional
+  form is red on it.
+
+  ⚠️ **THE COUNT OF SEPARABLE STATES IS DECORATION AND THREE SWEEPS DISAGREE
+  ABOUT IT.** This card's grid gave **2050 of 257 400**; an independent review
+  measured **1220 of 246 064**; a third, smaller grid (four tunings × 7 `prev_w`
+  × 9 `grid_w` × 5 `actual_w` × 8 `i_w` including `None` × 4 `sat_count`) gives
+  **776 of 40 320** — and that third one is spelled out here precisely because
+  the first two are not, which is the whole reason they cannot be reconciled.
+  No count here should be read as exact without the grid beside it. All three
+  agree on the load-bearing part, which is **where**: every separable state sits
+  in the `integrator_max_w > max_w` tuning and nowhere else.
+
+  ⚠️ **AND AN EARLIER DRAFT OF THIS BULLET GAVE THE WRONG REASON AND THE WRONG
+  NUMBER.** It said the two forms differ on 118 ticks because an unconditional
+  cap would pull the integrator toward a command the SATURATION freeze is
+  pinning. That 118 was measured against a *different* pair — a band applied
+  after quantisation, at the very end of `compute()` — and the saturation story
+  does not apply to the placement actually being compared, which sits before
+  the freeze. The figures above are the ones that were measured on the pair the
+  sentence names.
+
+  ⚠️ **AND THE SATURATION STORY IS NOT MERELY INAPPLICABLE — IT IS BACKWARDS.
+  THE NARROW CAP THAT SHIPPED *DOES* MOVE A SATURATION-FROZEN INTEGRATOR.** It
+  sits before the freeze block and is not gated on `frozen`. Measured on the
+  same 16 days at the live shape: of **79 160** frozen ticks the cap changed
+  `i_w` on **1095**, and on **679** of those it moved it further out on the side
+  it was already on — putting back magnitude the freeze had just let fall, which
+  is the one direction the freeze's rule ("may fall, never rise") exists to
+  forbid. Worst case **2424 W**, at
+  `prev_w −3400 W, grid +4697 W, actual −4144 W, sat_count 2 → 3`: the freeze
+  leaves the integrator at **−176 W**, the slew binds, and the cap drags it to
+  **−2600 W**. It never overrides a *same-cycle* refusal — the freeze clipped
+  `moved` on 75 512 ticks and the slew bound on none of them — but the claim
+  that this placement leaves the frozen path alone is false, and §5 is where
+  that shows up in a committed number.
+* **It is written one-sided, and that is a CLARITY choice, not a correctness
+  one.** ⚠️ **An earlier draft of this file and of the comment in `control.py`
+  said the two-sided band `max(slewed - cap, min(slewed + cap, i_w))` was a bug
+  that would drag a TRAILING integrator up toward the command. That was
+  invented, and the sweep said so: the two spellings agree on 205 920 of
+  205 920 cases** across four tunings, every sign of `prev_w`, `grid_w`,
+  `actual_w` and `i_w`, and the `i_w=None` path. `target` is monotone in `i_w`,
+  so when the slew binds `i_w` lies on the same side of `slewed` as `target`
+  does and the other clamp cannot reach. The one-sided form stays because it
+  NAMES the side the lead is on; the equivalence is recorded so the next reader
+  finds a measurement instead of an argument.
+* **It moves `i_w` and not `target`.** This cycle's command is already decided;
+  what is bounded is what gets CARRIED. That is also why the exhaustive
+  `i_w=None` equivalence sweep in `test_control.py` is untouched — it compares
+  `(target_w, sat_count, frozen, reason)`, none of which this moves.
+* **The cap is in STEPS, not watts**, for SAFETY-39's reason: a watt figure is a
+  constant that outlives the `slew_w` it was derived against. `SLEW_LEAD_STEPS`
+  moves with `slew_limit_w()` and therefore with the rail.
+
+⚠️ **ONE STEP, AND NOT ZERO.** `i_w = slewed` is full back-calculation, and
+`control.py`'s own docstring says what that costs: passing `i_w=None` *"reduces
+this function to the exact velocity form it replaced"*. A zero cap makes `i_w`
+identically the command on every cycle, which is that collapse written from the
+other end. Measured, it is **better** — export 32.02 kWh against 34.07, mean
+quarter −3.69 W against −2.39 — and it is still refused, because it throws away
+the reason the accumulator was split out at all. That 2 kWh is the price of
+keeping the bounded form, and it is stated rather than hidden.
+
+⚠️ **TWO LEADS, AND CONFUSING THEM IS HOW A CHECK GETS WRITTEN WRONG.** The cap
+bounds `i_w − target`, the command this cycle EMITS, at one step — which is what
+makes the unwind one cycle. `Decision.i_w − prev_w`, which is what TEL-10's
+`loop_lead` publishes, is measured against the command the PREVIOUS cycle left
+standing, and the emitted command is itself one step further on: the published
+figure is bounded by **two** steps. Both bounds are asserted, each against its
+own number.
+
+### The two recorded deadlocks, driven rather than argued
+
+`control.py` names two encodings that produce a permanently stuck loop, and a
+gate written on the integrator is exactly the edit that brings them back.
+Neither is reachable here and both are test cases in `test_telemetry.py` part 4:
+
+* **the shrink-only encoding** — *"only corrections that shrink |i_w|"* is
+  unsatisfiable for both signs whenever the correction is larger than twice the
+  integrator, and the loop then sits at its last value forever (measured before
+  the fix: 0 W held indefinitely into a 2 kW import). SAFETY-48 is not a shrink
+  rule; it caps the lead beyond one slew step and only while the slew binds.
+* **`i_w == 0.0`** — `main.py` resets the integrator to exactly 0.0 on every
+  stop and every reseed, and *"may not wind further in the direction it is
+  already pushing"* has no referent there. SAFETY-48 does not touch that gate;
+  the first push from zero is driven and asserted to move.
+
+And a third, specific to this card: **the cap cannot latch.** The flag is not
+carried, and after the cap `|i_w − slewed| = cap`, so the next cycle's command
+covers it in one step and the slew stops binding — after which the integrator
+accumulates freely again. The driven check asserts the command still walks all
+the way to the rail on a railed export.
+
+## 5. What this card COSTS, stated rather than smoothed
+
+**SAFETY-13's release buys back less.** That card's own scenario — a second
+writer holding the pack at +700 W, the command pinned, then released — settles
+at **−800 W** where release/1.0 settled at −1190 W against an integrator of
+−1194 W; and its sibling run settles at **−1200 W** where release/1.0 settled at
+−2390 W. The property AC 4 asserts is unchanged: the released command stops at
+the frozen integrator and not at the rail.
+
+⚠️ **AND THE TWO MOVED FOR TWO DIFFERENT REASONS, WHICH THE ONE-LINE EXPLANATION
+"how far that integrator had been allowed to wind" COVERS ONLY HALF OF.** Gating
+the cap on `not frozen` — one line, `if frozen: _lead_cap = float("inf")`, so
+the cap becomes a no-op while frozen — puts **part 5 back at release/1.0's
+−1190 W exactly**. That run moved because the cap **fires on frozen cycles**
+(§4). **Part 4(b) does not come back**: it is −1200 W gated and −1200 W shipped,
+against release/1.0's −2390 W, because *that* one moved for the winding reason.
+Both literals in `test_control.py` were re-baselined **with the reason beside
+them**, and the second is now asserted against `i_w` rather than against a
+number.
+
+**The alternative that avoids it was measured and rejected.** Gating the cap on
+`not frozen` as above gives export **34.71 kWh** (against 34.07), worst quarter
+**3434 W** (the same as shipped), wasted **3.49 kWh** (against 3.19) — and a
+worst observed lead of **4961 W**, i.e. no bound at all on the quantity this
+card exists to bound. A bound with an exception large enough to drive a truck
+through is not a bound. ⚠️ These four figures replace an earlier set (34.9,
+3461 W, 3.5 kWh, 4966 W) that does not reproduce on this tree with the gate
+spelled as above; the gate spelling is written out here so the next reader can
+re-run it rather than re-derive it.
+
+**One quarter-hour in 1534 is 532 W worse.** The billed figure is a MAXIMUM, and
+at the fitted plant lag the maximum improves (3739 → 3434 W); no quarter under
+SAFETY-48 reaches release/1.0's own worst. The mean moves the right way. The
+tail is reported because a maximum over 1534 quarters is decided by one of them
+— and §3a is the reason that improvement is not claimed as a benefit of the
+card: at every shorter plant lag release/1.0's own maximum is already 3434 W.
+
+## 6. The independent confirmation, which arrived as a failing check
+
+`test_control.py`'s SAFETY-39 section drives a family of 51 synthetic export
+steps through a **first-order plant this file writes itself** — no relation to
+the replay, no recorded data in it at all. It carried this assertion:
+
+> ⚠️ THE SLEW DOES NOT OWN THE OVER-ABSORPTION … Quartering the slew from 1000
+> to 250 does not reduce the over-absorption at all
+
+and it was right about the mechanism and therefore wrong about the conclusion:
+`slew_w` bounds the OUTPUT while the integrator accumulates `gain · error`, so a
+slower slew left the integrator winding for longer. Worst case over the family:
+
+| `slew_w` | release/1.0 | this branch |
+|---|---:|---:|
+| 1000 | 1005 W | **729 W** |
+| 0 (the rail, 556) | 1109 W | **550 W** |
+| 400 (the live interim) | 1285 W | **424 W** |
+| 250 | 1330 W | **326 W** |
+
+**The ranking inverts.** Before: slower is worse, monotonically. After: slower is
+better, monotonically. Two plant models that share nothing agree on the sign,
+which is worth more than either alone — and it means SAFETY-39's *"gain is the
+next constant to re-derive"* is now only half true: with the lead bounded, the
+slew owns a share of the over-absorption it did not own before. `gain` is still
+not touched here, for SAFETY-39's own reason: two live control-law constants
+moving in one release makes the next measurement uninterpretable.
+
+⚠️ **AND THE RIG SAYS THE SAME THING, WHICH MEANS TWO COMMITTED TRANSCRIPTS
+CHANGED MEANING UNDER THIS CARD.** `tools/slew_sim.py --slew` runs the same
+derivation on admin/goodwe's `plantsim.Plant`, a third model again. Worst-case
+over-absorption over its 51-step family, `slew_w` from 1000 down to 250:
+
+| `slew_w` | 1000 | 800 | 700 | 600 | 556 | 500 | 400 | 300 | 250 |
+|---|---:|---:|---:|---:|---:|---:|---:|---:|---:|
+| release/1.0 | 958 | 1107 | 1133 | 1058 | 987 | 1029 | 1150 | 1143 | 1081 |
+| **this branch** | 777 | 734 | 663 | 563 | 553 | 507 | 435 | 358 | 321 |
+
+release/1.0's row is flat and non-monotone and **800 really is better than 556**
+on that column — SAFETY-39 measured it correctly and its §3 sentence is true of
+the law it was written against. This branch's row falls monotonically. So
+SAFETY-39's record is not retracted; it is given a **forward reference**, and
+`slew_sim.py`'s own narration now reads `SLEW_LEAD_STEPS` out of the control law
+it imported and says which of the two tables it is printing. MUTATION.md habit 8
+— a committed transcript is a check, and a transcript whose prose contradicts
+its own table is a failing one.
+
+## 7. Verified by breaking it
+
+**The law.** `test_telemetry.py` part 4 and `test_control.py`'s SAFETY-39
+section. The mutation table is in `test_telemetry.py`'s header.
+
+**The instrument** (MUTATION.md habit 8 — anything under `tools/` that a
+document quotes is subject to the battery):
+
+| # | mutation to `app/control.py` | what the instrument did |
+|---|---|---|
+| I2 | the whole SAFETY-48 block deleted | **REFUSED**, exit 1, `NOTHING HAS BEEN MEASURED` — not a zero delta |
+| I3 | the anchor line itself edited | **REFUSED**, same message |
+| I3b | `SLEW_LEAD_STEPS = 1000` — the cap present but inert | **every row +0.00**, which is the honest report that the block is doing nothing |
+| I4 | `SLEW_LEAD_STEPS = 0` — full back-calculation | every row moves further; this is the rejected form's number in §4 |
+
+I3b is the one that matters: it proves the delta in §3 is caused by the block
+and not by the two runs differing for some other reason.
+
+**The law**, driven in the CI image on a purged tree, fingerprinted before,
+after and after the revert:
+
+| # | mutation to `app/control.py` | bytes | reds |
+|---|---|---:|---|
+| L1 | the whole SAFETY-48 block deleted | −195 B | 5 in `test_telemetry.py`, 4 in `test_control.py` |
+| L2 | `SLEW_LEAD_STEPS = 0` — the velocity form | +0 B | 4 + 3 |
+| L3 | `SLEW_LEAD_STEPS = 12` — a cap above the rail | +1 B | 4 + 3 |
+| L4 | the cap applied unconditionally, outside the slew branch | −92 B | 1 + 0 — **and it was a SURVIVOR of all thirty files before that check existed** |
+| L5a | the `min`/`max` FUNCTION names exchanged | +0 B | 5 + 5, one of them `test_control.py`'s own "frozen integrator never deadlocks" over 13 041 states |
+| L5b | the two BRANCH BODIES exchanged — the other reading of "the cap on the wrong side" | +0 B | 5 + 4, and it does **not** reach the deadlock sweep |
+| L6 | the lead measured against `prev_w` rather than the command emitted | +0 B | 6 + 3 |
+
+⚠️ **L5 AND L6 ARE BOTH ZERO BYTES** — `min`/`max` and `slewed`/`prev_w` are
+each the same length — so no fingerprint and no byte delta can see either, and
+one of L5a's reds is `test_control.py`'s own *"frozen integrator never
+deadlocks"* sweep over 13 041 states, written by SAFETY-13 for a different
+reason.
+
+⚠️ **THREE OF THESE COUNTS WERE WRONG AND ARE RE-MEASURED ABOVE, WHICH IS
+MUTATION.md's REPORTING RULE 3 APPLIED TO THIS CARD'S OWN TABLE.** The earlier
+row gave L5 as 2 + 5 and L6 as 4 + 3; driven again in the CI image on a `cp -a`
+of this tree, purged, `:ro`, one file at a time, they are **5 + 5** and
+**6 + 3**. ⚠️ **AND "L5" NAMED TWO DIFFERENT MUTATIONS.** "`min`/`max` swapped"
+can mean the function names exchanged or the branch bodies exchanged; they are
+both red, they are both the cap on the wrong side, and they give different
+counts (5 + 5 against 5 + 4) and reach different checks. A row that writes one
+number for a mutation a reader cannot re-derive from its own description is a
+row that cannot be re-run, so both spellings are listed. The directions in the
+original table were all correct; the counts were decoration, and decoration in
+a mutation table reads as evidence.
+
+## 7b. The transcript, quoted rather than summarised
+
+`python3 tools/replay_recorded_loop.py --sensitivity`, on this branch, 58 s:
+
+```
+THE RECORDING: 256252 meter instants over 16.00 days, loop-2026-09-02_2026-09-17
+    tick   p5 4.77 s   median 5.01 s   p95 7.86 s   (control.LOOP_TICK_S says 2.0)
+    the recorded command: extremes -5000 / +5000 W  ->  max_w 5000;  most common step above 100 W is 400 W, 9924 times  ->  slew_w 400
+    the fitted inverter: lag 7.5 s, tau 2.0 s, batt = 0.9731 x cmd -22.4 W, residual 375 W RMS above the SoC floor
+
+FIDELITY - the BEFORE law replayed against the recording it came from
+    setpoint  r=0.887  mean     +601 W simulated vs     +739 W recorded
+    grid      r=0.682  mean     +195 W simulated vs     +239 W recorded
+    export       39.61 kWh simulated vs    29.43 kWh recorded  ->  the model is +35 % PESSIMISTIC about the loop's tracking
+
+THE A/B, same ticks, same disturbance, same plant, same seed
+                                 release/1.0     SAFETY-48       delta
+    export kWh                         39.61         34.07       -5.54   the cost
+    import kWh                        116.07        111.20       -4.86
+    battery sign reversals           2992.00       2770.00     -222.00
+    wasted throughput kWh               4.67          3.19       -1.48
+    worst 15-min offtake W           3738.67       3433.94     -304.74   ⚠️ THE BILLED ONE
+    recovery events                   549.00        612.00      +63.00
+    recovery median s                 232.06        199.04      -33.01
+    recovery p99 s                    849.00        849.94       +0.94
+    recovery max s                    901.06        898.40       -2.66
+    unrecovered (>900 s)               53.00         31.00      -22.00
+    |i_w - prev_w| p99 W             3361.12        800.00    -2561.12
+    |i_w - prev_w| max W             9200.00        800.00    -8400.00
+    slew-limited ticks              16392.00      11654.00    -4738.00
+    mean quarter delta W                                         -2.39   over 1534 quarters
+    worst quarter delta W                                      +532.27
+
+SENSITIVITY - the ranking, not the watts
+      variant                               export kWh           worst quarter W   mean quarter dW
+      plant lag 5.0 s                32.1 ->     27.2         3434 ->     3434             -1.02
+      plant lag 10.0 s               75.4 ->     68.3         3954 ->     3434             -4.65
+      plant tau 8 s                  56.5 ->     49.8         3995 ->     3605             -3.30
+      gain 1.0135, offset -26        46.8 ->     39.3         3713 ->     3434             -3.27
+      slew_w 555.6 (the rail)        36.5 ->     34.4         3434 ->     3434             -0.17
+      gain 0.3                       28.1 ->     27.0         3434 ->     3434             +0.16
+
+    (58 s)
+```
+
+⚠️ **`--sensitivity` IS THE RANKING AND NOT THE WATTS.** The export figure moves
+by a factor of two across these plants; what does not move is the direction —
+**on export**. ⚠️ **THE `worst quarter W` COLUMN IS NOT THE SAME KIND OF
+EVIDENCE AND THIS PARAGRAPH USED TO TREAT IT AS IF IT WERE.** Three of its six
+rows read `3434 -> 3434`, and that is not "the direction holds": it is
+release/1.0 *already sitting at 3434 W* on those plants, with nothing for the
+card to improve. §3a sweeps the lag properly and finds the same thing at every
+lag ≤ 5.0 s. The billed-quarter improvement in the A/B table above exists at one
+plant, the one `fit_plant()` selects by an objective that separates it from its
+neighbour by 0.3 %.
+
+Two rows deserve naming rather than rounding: at `slew_w: 555.6` (the rail) and
+at `gain: 0.3` the mean quarter-hour delta is −0.17 W and **+0.16 W** — ties,
+not improvements. Both are regimes where `|error| > slew_w / gain` is rarely
+satisfied (1333 W at `gain: 0.3`, 926 W at the rail against a measured median
+onset error of 1114 W), so there is little for the card to bite on. That is the
+mechanism agreeing with itself, and it is also the honest answer to "would this
+still be worth shipping if the tuning moved": at `gain: 0.3` it would not be.
+
+## 8. What this card does NOT establish
+
+* **Nothing here drives an inverter.** The replay is a model with a 375 W
+  residual and no arbiter in it. The closed-loop answer comes from the rig or
+  from a live run — SAFETY-47 records why a shadow run cannot give it.
+* **The live tick is 5.0 s, not `LOOP_TICK_S`'s 2.0 s**, measured off 9924
+  recorded 400 W steps and off the meter's own cadence. It is wrong in the SAFE
+  direction (a slower meter makes `validate.py` rule 10 conservative) and is NOT
+  changed here — re-deriving `SLEW_RAIL_FRAC` is a refusal boundary on a live
+  install and belongs to its own card. It is recorded in the tool's header and
+  printed on every run.
+* **The brief's plant figure was close but not exact.** It quoted
+  `delivered = 1.0135 × command − 26 W, r = 0.992` at a 4–6 s publish lag. On
+  this 16-day window, above the SoC floor, the same relation measures
+  `1.00 × command − 28 W, r = 0.977` at a best-fit pure delay of **7.5 s**. The
+  conclusion — the inverter is a pure follower and the plant is not the problem
+  — survives; the coefficients are the ones in §2.
+* **The brief's cost figure is larger than this measurement.** It quoted ~14 kWh
+  of avoidable export and 65 % of site export inside 7.9 % of the time. Measured
+  here: **5.5 kWh** avoidable of 39.6 kWh modelled (29.4 kWh recorded), with
+  42 % of export inside the 6.3 % of ticks that are slew-limited and 69 % within
+  ±60 s of one, over 15.3 % of the time. The concentration claim holds; the
+  avoidable-kWh figure does not, and the difference is not reconcilable from
+  here because the reconstruction it came from was discarded.

goodwe_controller/DECISIONS/TEL-10-publishing-the-integrator.md

@@ -0,0 +1,182 @@
+# TEL-10 — the loop's integrator is published, as three site rows
+
+**Status:** decided and implemented on branch `TEL-10`.
+**Card:** TEL-10 — *"`self.i_w` is carried between cycles and published nowhere"*.
+**Nothing here reached the inverter, and nothing here can.** `app/control.py`
+is not touched by this branch; `compute()`, its returned `Decision` and every
+constant it reads are byte-identical to `release/1.0`. The diff is a controller
+recording three values it already had, and a publisher announcing three rows.
+
+---
+
+## 0. The three things a reader should take away
+
+1. **The row that matters is the one that is usually indistinguishable from
+   `Setpoint`.** With nothing binding, the command *is* the integrator rounded
+   to 10 W, so on a quiet day publishing the wrong one looks correct. §2 is
+   the fixture that separates them by kilowatts, and §4 is the mutation that
+   proves the separation is what the check reads.
+2. **`Loop reason` is a genuinely new sentence, not a second copy of one.** The
+   status page's `Why` row and `sensor.goodwe_controller_status` both carry the
+   *arbiter's* line (`loop -> -5000 W`), which prints the winning claim's NAME.
+   `compute()`'s own reason has never left the process, and `slew-limited` — the
+   value SAFETY-48 is about — appears in neither of the other two. §3.
+3. ⚠️ **Three entities are three entities.** This is an addition to a live
+   install's entity list, which TEL-07 refused to make for four per-unit rows
+   at a roster of one. The argument for making it here is in §5, and so is the
+   argument that keeps it to three rather than to one per inverter.
+
+---
+
+## 1. Why this is a card at all
+
+`self.i_w` has been a separate quantity from the command since SAFETY-04, which
+split the accumulator out of the velocity form precisely so the two could be
+bounded apart. Since then it has been:
+
+* carried between cycles by `Controller.cycle()`,
+* read by nothing outside `compute()`,
+* and written to no entity, no MQTT topic, no attribute and no log line.
+
+The consequence is not theoretical. The investigation behind SAFETY-48 needed to
+know what the integrator was doing during the export episodes and could only
+**reconstruct** it, from the grid trace plus a replay of the real `compute()`.
+The reconstruction reproduced about a third of the engagements it was checked
+against and was **discarded entirely** — so the card it was gathered for had to
+be argued from a measurement nobody could stand behind.
+
+⚠️ **And the reconstruction could not have been made to work.** `i_w` at a given
+instant depends on every cycle before it, including every one in which the
+arbiter overrode the loop and `main.py` re-seeded `self.i_w = self.target`. That
+re-seed is invisible in the grid trace. A replay can only recover the integrator
+on a run where the loop won every arbitration, which is not the run anybody is
+investigating.
+
+## 2. What is published, and against what
+
+Three rows, on the SITE device, appended after `release/1.0`'s eight sensors:
+
+| key | entity | what it is |
+|---|---|---|
+| `loop_i` | `sensor.goodwe_loop_integrator` | `Decision.i_w` — the accumulator AFTER this cycle, BEFORE the output clamp, the slew limit and quantisation, which is what its own docstring says it is |
+| `loop_lead` | `sensor.goodwe_loop_integrator_lead` | `decision.i_w - prev_w`, where `prev_w` is the command `compute()` was handed |
+| `loop_reason` | `sensor.goodwe_loop_reason` | `Decision.reason`, unmodified |
+
+⚠️ **`loop_lead` IS NOT A SUBTRACTION OF THE OTHER TWO ROWS, WHICH IS WHY IT IS
+A ROW.** `Setpoint` is the ARBITER's output, after every other strategy has had
+its say, and it is THIS cycle's; the lead is measured against the command the
+PREVIOUS cycle left standing. On any cycle where the arbiter overrode the loop,
+subtracting the two published rows gives a different number — and that is
+exactly the cycle on which `main.py` re-seeds the integrator, i.e. the cycle a
+reader most needs the real figure for.
+
+`cycle()` therefore records all three from the one `compute()` call, and names
+the command it passes (`loop_prev`) rather than re-reading `self.target` at
+publish time. `self.target` is reassigned later in the same method, so a lead
+computed at publish time would subtract a different cycle's command and call the
+answer a lead. ⚠️ **At the line as written the two expressions are the same
+value, and the mutation that swaps them is a recorded SURVIVOR** — see §4 M2.
+The name is kept for the coupling, not for a behaviour it currently buys.
+
+### The not-running branch
+
+`cycle()`'s `else` arm — stopped AND shadow mode off — already zeroes
+`self.i_w`, because no accumulation may survive the outage. The three rows are
+zeroed and `loop_reason` becomes `not-running` on the same branch. A row that
+kept repeating the last integrator there would say the loop was winding while
+nothing is being controlled.
+
+⚠️ **`auto: false` ALONE IS NOT THAT BRANCH.** The shipped `shadow_mode: auto`
+means a stopped controller still runs the whole decision path and records it
+(SAFETY-10), so the loop is live and the integrator is real. The first draft of
+the check asserted `not-running` about a loop that was running; it reads the
+shadow case as its own claim now.
+
+## 3. Why `loop_reason` is not the row that already exists
+
+`self.reason` is `Resolution.explain()`:
+
+```
+"loop -> -5000 W"                     # winner, watts
+"loop -> -5000 W, limited by soc"     # ...and which limit bit
+"CONTRADICTION between limits - commanding 0 W (loop)"
+```
+
+`Claim.set("loop", P_LOOP, decision.target_w, decision.reason, ...)` does carry
+the loop's reason INTO the arbiter — and `explain()` prints the winner's
+**source name**, never the claim's reason. So the loop's own word has always
+been built, handed over, and dropped one line later.
+
+Measured on the fixture in `test_telemetry.py` part 2, same cycle:
+
+```
+the arbiter's sentence: 'loop -> -5000 W'
+the loop's own word   : 'i-clamped'
+```
+
+## 4. Verified by breaking it
+
+Nine mutations, run in the CI image on a purged tree, each fingerprinted before,
+after, and again after the revert. The table with byte deltas and red counts is
+in `test_telemetry.py`'s header; two entries are worth repeating here.
+
+**M1 — `self.loop_i_w = loop_prev` (−3 B), the card's own named mutation:
+publish the COMMAND under the integrator's name.** The first draft of the
+acceptance check was *"the published integrator reaches its bound"*, and that
+check was **GREEN** under M1 — because the command reaches the bound too, twelve
+cycles later. MUTATION.md habit 4 in the check written to close the card. It
+asserts the **lead time** now (the integrator is at the bound at least ten
+cycles before the command is), and is red on 5 named checks.
+
+**M2 — `decision.i_w - self.target` (+2 B) is a SURVIVOR, and is reported as
+one.** At that line `cycle()` has not yet executed `self.target =
+resolution.target_w`, so the two expressions denote the same value and the
+mutation changes nothing that runs. The run was purged, which is not the
+direction stale bytecode fabricates. M2b (`decision.i_w - decision.target_w`,
++8 B) is the mutation that does change the value and is red.
+
+## 5. What was rejected
+
+**Publishing as an MQTT attribute on an existing entity.** There is no
+`json_attributes_topic` anywhere in this add-on; adding one would be a second
+convention for one card, and HA's recorder keeps long-term statistics for a
+state with `state_class`, not for an attribute. The reason this card exists is
+that nobody had history to read.
+
+**A status-page row instead.** The page is not recorded. `Why` already carries
+the arbiter's sentence and stays that way; DOCS.md gains the section that says
+how to read the three entities.
+
+**One integrator row per inverter.** §6.2's architecture is ONE integrator on
+the P1 meter whose output is then SPLIT. A per-unit copy would invent N of a
+thing there is one of, and the two copies would disagree the moment the
+allocator gave the units different shares. `test_mqtt.py` part 5 grades this at
+every roster length from 1 to 6, and the mutation that moves `loop_i` into
+`UNIT_SENSORS` is red on 8 named checks.
+
+**Adding the rows at N≥2 only, the way TEL-07 gates its per-unit rows.**
+TEL-07's gate exists because at a roster of one its four rows carry information
+the site rows already carry exactly. These three carry information NOTHING
+carries, at every roster length, including one.
+
+**A `## Unreleased` block in `CHANGELOG.md`.** `test_version_gate.py` part 11b
+refuses a changelog whose newest `## ` heading is not `config.yaml`'s
+`version:` — PKG-14's rule that the bump and the closed section are one act.
+Opening a section here would mean bumping the version, which is a packaging
+decision this card does not get to take. The operator-facing account is in
+DOCS.md; the release note belongs to whichever PKG ticket cuts the next
+version, and this file is what it should be written from.
+
+## 6. What this card does NOT establish
+
+* **It says nothing about whether the integrator's behaviour is right.** That is
+  SAFETY-48. This branch adds an observable and changes no decision; the
+  15.7-day replay that grades the behaviour is in that card.
+* **The three rows do not exist on the live install until the add-on is
+  updated**, and this branch does not update it. `tools/rehearsal/announced-
+  reference.txt` (what the BUILD announces) records them; `live-entities-
+  recorded.txt` (what the INSTALL has) deliberately does not, because an id the
+  build announces and the install lacks is a new entity, not an orphan.
+* **`loop_lead` is signed and is not a distance.** Where the integrator and the
+  command have opposite signs it is the sum of two magnitudes. A reader wanting
+  "how far behind is the command" should take the magnitude and say so.

goodwe_controller/DOCS.md

@@ -287,8 +287,10 @@ it always has.
 published — `Setpoint`, `Grid power`, `Battery power`, `Battery SoC`,
 `Circulating power`, `Maintenance phase`, `Controller status`, `P1 sample age` —
 keep their device, their `unique_id`s and therefore their **entity ids and their
-whole recorded history**. At a roster of one, nothing new is announced at all:
-no second device, no renamed entity, not one added topic.
+whole recorded history**. At a roster of one, nothing new is announced by the
+per-unit machinery at all: no second device, no renamed entity, not one added
+topic. (TEL-10's three loop rows, below, are site rows and are added at every
+roster length, including one.)
 
 Declare a second inverter and **four rows per unit** appear beside them:
 
@@ -321,7 +323,90 @@ arrives, and it fails silently and looks correct.
 There is one P1 meter and one grid connection; a per-inverter copy would invent
 two of a thing there is one of, and `P1 sample age` is a safety input. Same for
 `Circulating power` (it is a property of the *set* of inverters), the controller
-status, the maintenance phase and the capacity-tariff peak.
+status, the maintenance phase, the capacity-tariff peak and the three loop rows
+below.
+
+### Reading the grid-following loop: `Loop integrator`, `Loop integrator lead`, `Loop reason`
+
+The control law is a bounded integrator: an accumulator that is **not** the
+command. Each cycle it moves by `gain × error`; the command is then derived
+from it and passed through the output clamp, the slew limit and a 10 W
+quantisation before anything is written. Three entities publish what the
+accumulator is doing:
+
+| entity | unit | what it is |
+|---|---|---|
+| `Loop integrator` | W | the accumulator **after** this cycle — the value *before* the clamp, the slew limit and quantisation |
+| `Loop integrator lead` | W | that value minus **the command it was computed against**, i.e. the command the previous cycle left standing |
+| `Loop reason` | — | the law's own word for this cycle |
+
+`Loop reason` takes one of eight values:
+
+| value | what happened |
+|---|---|
+| `tracking` | ordinary regulation |
+| `deadband` | the error is inside `deadband_w`; the loop is holding |
+| `i-clamped` | the integrator hit `integrator_max_w` (which follows `max_w` by default) |
+| `clamped` | the *command* came out over `max_w` — only reachable if `integrator_max_w` is deliberately set above the rail |
+| `slew-limited` | the command could not move as far as the integrator asked for; `slew_w` is what stopped it |
+| `saturated-freeze` | the inverter is not following, so the command's magnitude may fall but not rise |
+| `freeze-released` | the freeze had run out of plant-shaped explanations and the command was let move again |
+| `not-running` | control is stopped **and** shadow mode is off, so the loop did not run |
+
+⚠️ **`Loop reason` is not the `Why` row on the status page, and the two will
+often disagree.** `Why` is the *arbiter's* sentence — `loop -> -1200 W` — which
+names the strategy that won and the watts it won with. It has never carried the
+strategy's own reason, so a loop that is slew-limited or frozen says so **only**
+here.
+
+⚠️ **`Loop integrator` is not `Setpoint`, even though it usually looks like
+it.** With nothing binding, the command *is* the integrator rounded to 10 W, so
+on a quiet day the two rows track each other and the difference is a rounding
+step. They separate exactly when something is wrong: a large disturbance sends
+the integrator to its bound in one or two cycles while the command may only
+travel `slew_w` per cycle, and `Loop integrator lead` is the gap. A standing,
+large lead means the loop has wound up further than the command can follow, and
+the number of cycles needed to unwind it is that lead divided by `slew_w`.
+
+Both numbers are `state_class: measurement`, so Home Assistant's recorder keeps
+long-term statistics for them.
+
+⚠️ **`Loop integrator lead` is BOUNDED, and the bound is two slew steps.** While
+the slew limit is what is holding the command back, the integrator may not stand
+more than **one** `slew_w` ahead of the command it emits — so the command always
+covers the gap in one cycle, and a reversal costs one cycle of unwind rather
+than `integrator_max_w / slew_w` (12.5 at `max_w: 5000`, `slew_w: 400`).
+Measured against the *previous* cycle's command, which is what this row
+publishes, that is two steps: 800 W at the live shape. **A published lead
+persistently above two slew steps means something is wrong** — either the
+saturation freeze is holding the command (`Loop reason` says
+`saturated-freeze`), or the bound is not doing its job.
+
+Before this bound existed, the same 6 kW export drove the lead to 4600 W and the
+integrator to its 5000 W rail, and the command then needed twelve cycles — about
+a minute at this install's meter rate — to walk back down once the disturbance
+cleared.
+
+⚠️ **What the bound buys — and how much of it is a model rather than a meter
+reading.** Sixteen days of the reference install's own recorded disturbances
+were replayed through both laws (`tools/replay_recorded_loop.py`). The result
+that survives every plant and tuning tried is the **export reduction: about an
+eighth of the modelled export** — 5.5 kWh of 39.6 at the plant lag the replay
+fits, 3.8 kWh of 28.9 at the shorter lag that best reproduces what this install
+actually exported — with wasted battery throughput falling alongside it, 4.67 to
+3.19 kWh at the fitted plant. ⚠️ **Those are simulated watt-hours.** The
+replay's fitted inverter carries a ~375 W RMS residual and prints `+35 %
+PESSIMISTIC` beside its own export figure on every run; the *direction* is what
+it establishes, not the absolute kWh.
+
+⚠️ **And it does NOT promise you a lower capacity-tariff peak.** The worst
+quarter-hour average offtake — the billed quantity — improves from 3739 W to
+3434 W **only at the longest plant lag the replay fits**. At every shorter lag,
+including the one that best reproduces the recorded export, release/1.0 already
+sits at 3434 W and this bound changes it by exactly zero. The plant lag is not
+identified by the recording, so treat the peak as unchanged and the export as
+the reason this exists. `DECISIONS/SAFETY-48-bounding-the-integrator-lead.md`
+§3a has the table.
 
 ⚠️ **Two roster names that differ only in punctuation or case** — `inverter-b`
 and `Inverter B` — are two names to the validator and one id once slugged. The
@@ -650,8 +735,9 @@ decisions recorded while the loop runs.
 
 **What you get out of it.** The status page carries a red-amber banner saying
 the battery is not being controlled, a `Shadow mode` row saying which rung
-decided, what it **would have commanded** and why, and the `Why` row with the
-arbiter's own sentence. The action log gets one line each time the decision
+decided, what it **would have commanded on that cycle** and why — with the
+caveat below, where the number was sized from a meter the battery never
+moved — and the `Why` row with the arbiter's own sentence. The action log gets one line each time the decision
 changes — the winner or the watts — rather than one per cycle, so a 40-row log
 still contains the context of what it found. MQTT reports `status: shadow`.
 
@@ -663,7 +749,12 @@ never saw it, and **latch a trip that survives into live operation and a
 restart**. The clamp (SAFETY-03), the write-authorisation gate (SAFETY-28), the
 frozen-meter alarm (SAFETY-18) and the capacity guard all **observe**: they run
 on the number the decision path produced, so a shadow run can tell you the
-clamp would have engaged. The circulation (SAFETY-31) and delivery (SAFETY-42)
+clamp would have engaged. ⚠️ **The capacity guard observes a meter with no
+battery in it.** Every term of the quantity it thresholds is measured, so it
+engages in a shadow run only if the *house alone* would have put the quarter
+over the ceiling — 410 engaged cycles live against 0 in shadow, on the hour
+tabulated below. Its *ceiling* and its *reasons* are worth reading from a
+shadow run; its *engagements* are not evidence of anything. The circulation (SAFETY-31) and delivery (SAFETY-42)
 watchdogs observe and may legitimately latch, because their evidence is
 *measured* power, not a command. The operator stop is enforced at the wire
 instead of as a claim, so that the recorded decision is the real one.
@@ -678,17 +769,85 @@ every cycle whether control is started or not, so they already run against a
 battery that does not move on a stopped install. Shadow mode inherits that
 exactly; it neither improves it nor makes it worse.
 
-⚠️ **What a shadow run will NOT tell you.** The controller's carried command is
-re-seeded to the 0 W standing on the wire at the end of every shadow cycle —
-that is what makes turning shadow mode off safe, because the loop then resumes
-from where the battery actually is. The consequence is that the
-**grid-following loop's** recorded decision is **one slew step** and stays
-there: a shadow run answers *"what would it command now"*, not *"what
-trajectory would it have followed"*, because the trajectory depends on a
-battery responding and none did. 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 — so a shadow run does show
-you the trades, the peak-guard engagements and the SoC-limit behaviour.
+⚠️ **What a shadow run will NOT tell you — and it is a whole category, not a
+footnote.** The controller's carried command is re-seeded to the 0 W standing
+on the wire at the end of every shadow cycle — that is what makes turning
+shadow mode off safe, because the loop then resumes from where the battery
+actually is. Everything below follows from the same fact.
+
+**A shadow run cannot show you a closed-loop defect. Not partially — not at
+all.** The battery is held at 0 W, 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 one whose
+stimulus **is** the plant's response, and there is no response to be the
+stimulus. This is not a gap waiting to be closed: feeding the guards a
+simulated plant instead is exactly what the sign-watchdog decision below
+refuses, and for the same reason — a controller reacting to a plant that does
+not exist drifts further from reality every tick. **The closed-loop answer
+comes from the closed-loop rig or from a live run, and there is no third
+place.**
+
+Concretely, measured on the rig at `peak_cap_w` 1500 under a 1200 W house,
+`max_w` 2000, one hour at a 5 s cycle — the same hour run twice, live and in
+shadow, on the same code:
+
+| | live | shadow |
+|---|---|---|
+| charge onsets in the hour | **28** | **1** |
+| grid | **−455.5 … +3200.0 W** | **1200.0 W flat — the house** |
+| capacity guard engaged | **410 / 720 cycles** | **0 / 720** |
+| state of charge | 50.000019 → 51.856789 % | **50.000000 → 50.000000 %** |
+
+(The onset and engagement figures are taken with the trade-sizing fix reverted,
+because that is the defect being looked for; the SoC and grid figures are the
+shipped build.)
+
+⚠️ **The "strategies are unaffected" exemption that used to stand here was true
+until the trade-sizing fix landed, and is now false by hours.** That fix makes
+the buy leg `min(asked, headroom)`, where the headroom is
+`(900 / seconds remaining) × (ceiling − projected quarter average)` — and the
+projection reads the **open quarter's accumulator**, i.e. the meter, i.e. a
+function of what the battery did earlier in that same quarter. What survives
+of the exemption is exactly this much:
+
+> **Which** hour a strategy picks, and **why**, are unaffected — the clock and
+> the price series are not functions of the battery. Measured: identical live
+> and shadow on 720 of 720 charging cycles at a binding cap. **How hard** it
+> trades is not.
+
+⚠️ **So the watts on the `Shadow mode` row are the right answer to a question
+nobody asked, and the row now says so.** In a shadow run the billed quarter
+really *is* under its ceiling, because the battery really *is* not charging, so
+`900 / remaining` multiplies a gap a live run would have closed. On the same
+rig, shipped code:
+
+| 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× |
+
+Whenever a measured billed quarter sized the number, the row and the action log
+carry **⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE
+HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W** — and the watts are introduced
+as what it would have commanded **on this cycle**, in every state, because no
+number a shadow run records is a forecast of a live one. The figure is **not**
+re-computed to look right: a shadow-only sizing would mean the recorded
+decision was no longer the decision the shipped path reached, which is the one
+thing this feature has to be able to say.
+
+The **grid-following loop** is the same story told first: its recorded decision
+is **one slew step** and stays there, because a trajectory depends on a battery
+responding and none did.
+
+**What a shadow run genuinely is for**, then: *which* strategy wins, on *which*
+hour, at *which* price, for *which* reason, against which limits — the
+wrong-quarter-hour class of defect, 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 this feature covers.
 
 #### The sign-disagreement failsafe
 

goodwe_controller/MUTATION.md

@@ -172,7 +172,7 @@ manufactures them from a **fixture**: the check runs, the assertion is
 evaluated, the sentence above it is true — and the numbers it compares are
 arranged so that the failure it describes could not have changed the answer.
 
-It is not hypothetical and it is not rare. ELEVEN instances in two weeks; four
+It is not hypothetical and it is not rare. TWELVE instances in two weeks; four
 were found by review, two - CFG-04's fixture pair - by an author's own mutation
 battery, which is the cheaper place, one by review again, in the one
 place nobody had thought to point the rule at: not a check in the suite, but a
@@ -414,6 +414,44 @@ same place twice, the check is decoration.
 
   The general habits are **14** and **15** below.
 
+* ⚠️ **SAFETY-47 IS THE TWELFTH, AND IT IS THE SECOND INSIDE A COMMITTED
+  EVIDENCE ARTIFACT.** `DECISIONS/SAFETY-10-shadow-mode.md` §6 tabulated a live
+  run and a shadow run agreeing on `arb_power_w`, on the reason **verbatim**
+  and on the arbiter's winner, and concluded that shadow mode reaches the same
+  decision. **Two independent reasons it could not have gone red, and closing
+  either one alone closes nothing:**
+  * its fixture is `peak_cap_w: 15000` against a 350 W house, so the capacity
+    guard never engages and the thing whose invariance is being claimed —
+    SAFETY-45's sizing of the buy leg from the billed-quarter meter — 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"*. The rule was
+    written down beside the check it disabled and nobody read it as a
+    disclosure;
+  * and every identity row reads `_sa[0]`/`_la[0]` — **the first charging
+    sample**. At `elapsed = 0` the projection **is** the held level, so the two
+    runs agree **to the float even at a cap that does bind**. Measured:
+    widening the fixture alone — the obvious fix — leaves that comparison
+    passing.
+
+  ⚠️ **THE SECOND REASON IS A NEW SHAPE FOR THIS LIST: AN INDEX, NOT A
+  FIXTURE.** Ask of every identity claim not only *"could this data differ"*
+  but *"**at the point I sampled it**, could it differ yet"*. A comparison
+  taken at `t = 0` between two runs that diverge **because one of them acts**
+  is a comparison of a plant with itself, and no amount of widening the fixture
+  changes that. The replacement, `test_arbitrage.py` part 3d, grades the whole
+  run — 716 of 720 charging cycles differ — and grades the `[0]` agreement **as
+  an expectation**, so nobody rebuilds a check on it believing it covers
+  something.
+
+  ⚠️ **AND THE FIX'S OWN FIRST DRAFT CARRIED A THIRTEENTH.** The new part's
+  action-log check could not reach the log line at all: the sentence was an
+  f-string inside `Controller._shadow_settle()`, and the only suite that drives
+  that method uses a `meter_source: off` fixture where no arbitrage decision —
+  and therefore no caveat — exists. Deleting the caveat from it left **all 29
+  files green**. It is `shadow.log_line()` now. *A sentence assembled at a call
+  site is a sentence no check can grade*, which is CFG-04's substring lesson
+  arriving from the other direction.
+
 Note what these have in common with a masked rung: the mutation *runs*, and the
 suite is *honestly* green. Nothing in a purge, a fingerprint or a disassembly
 can see it, because the code under test really did behave identically on the
@@ -773,6 +811,47 @@ Cheap habits fall out of it, and all of them are now used in this repository:
     retrofitted: guarding another card's section is a change to what its
     checks report, and it belongs to whoever next touches it.
 
+21. ⚠️ **A CHECK CAN BE GREEN UNDER ITS OWN CARD'S NAMED MUTATION, AND TWICE
+    IN ONE FILE THE REASON WAS THAT THE WRONG QUANTITY EVENTUALLY REACHES THE
+    RIGHT VALUE.** TEL-10's acceptance was *"a run that winds the integrator
+    into the bound must show the published number reaching the bound"*, and its
+    named mutation was *"publish `prev_w` instead of `i_w`"*. The check was
+    **GREEN** on the mutant: the command reaches the same bound too, twelve
+    cycles later, and a check that only reads the VALUE cannot tell the two
+    apart. The same file's *"a stopped controller publishes `not-running`"* was
+    green under deleting that branch's assignments outright (−45 B and −67 B),
+    because the fixture STARTED stopped and `__init__` writes the same values.
+    Both are habit 4 - the data could not reach the failure - and both were
+    found by the card's own battery. The fixes are the shape to copy:
+    * where two quantities CONVERGE, grade the **order or the interval**, not
+      the value: "the integrator reaches the bound BEFORE the command does",
+      and a PLATEAU (the lead sits at exactly −800 W for eight consecutive
+      cycles) rather than a maximum, because a maximum is one tick and a
+      plateau is the shape;
+    * where a branch WRITES a value the constructor also writes, the fixture
+      has to pass THROUGH the other state first. Stop the controller part-way
+      through a run that has already wound the integrator to −5000 W, so a row
+      left standing is a WRONG row and not merely an unset one.
+
+22. ⚠️ **AN EXPLANATION IN A COMMENT IS A CLAIM, AND SAFETY-48 SHIPPED TWO THAT
+    WERE INVENTED.** A gate was written one-sided (`if target > slewed: min(...)
+    elif target < slewed: max(...)`) under a comment saying the two-sided band
+    `max(lo, min(hi, i_w))` was a BUG that would drag a trailing integrator
+    toward the command, with a worked example. It is not a bug and the example
+    was wrong: `target` is monotone in `i_w`, so the other clamp cannot reach,
+    and the two spellings agree on **205 920 of 205 920** swept states. A second
+    bullet said two placements of the same cap *"differ on 118 of 256 252
+    ticks"*; that 118 had been measured against a **different pair** and the
+    placement actually being compared is bit-identical on the shipped
+    configuration - 0 of 256 246 ticks. Both sentences were plausible, both were
+    load-bearing for a design choice, and neither had been run.
+    **The rule: a comment that says "X would be wrong" is subject to the same
+    battery as a check - BUILD X AND MEASURE IT.** Where the answer is
+    "equivalent", say so with the sweep size and keep the spelling for what it
+    NAMES; where the answer is a number, quote the run it came from. An
+    invented justification for a correct decision is still a defect, and it is
+    the kind a reviewer cannot see because the code is right.
+
 And the mutation-table consequence: **a variant is not covered because a
 near-miss of it is.** DEV-02's table listed the *actuator* variant of the
 per-unit claim defect (`device`/`supervised` filed without `inv`), which the

goodwe_controller/app/arbitrage.py

@@ -471,6 +471,67 @@ def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct,
         price_now_eur_kwh=price)
 
 
+def sized_from_meter(decision: ArbitrageDecision, headroom_w, *,
+                     winner: str | None) -> bool:
+    """SAFETY-47. Was the number a shadow run just recorded SIZED FROM THE
+    BILLED QUARTER - i.e. from a measurement of what the battery itself did?
+
+    THE ONE PLACE THIS QUESTION IS ANSWERED, and it is public for the reason
+    `peakguard.charge_headroom_w()`, `discharge_permitted()` and
+    `freeze.looks_frozen()` are: the check that grades it has to assert on THE
+    SHIPPED EXPRESSION. A predicate transcribed into its own test is one copy
+    plus a future disagreement about what the check means.
+
+    ------------------------------------------------------------------------
+    THE DEFECT IT PREVENTS
+
+    `shadow.words()` and the action log carry "would have commanded N W". In
+    SHADOW MODE the battery is held at `shadow.WIRE_W`, so the billed quarter
+    the buy leg was sized against contains THE HOUSE AND NOTHING ELSE - while
+    a live run's meter rises as the trade charges. The same code, the same
+    hour, `peak_cap_w` 1500 under a 1200 W house: live commands -302.4 W and a
+    shadow run records -2000.0 W. 6.61x, on the status row, with no caveat.
+    This is the flag that puts the caveat there.
+
+    ⚠️ IT IS TRUE WHENEVER A MEASURED HEADROOM ENTERED THE ARITHMETIC, NOT
+    ONLY WHEN IT BOUND. `_act()` sizes the buy leg as `min(asked, headroom)`,
+    and "the headroom did not bind" is ITSELF a measured fact about a quarter
+    the battery never entered. Keying this on `capped` - on whether the
+    shipped sentence says "SIZED BY THE CAPACITY-TARIFF GUARD" - would answer
+    True at the START of the quarter, where a shadow run and a live run still
+    agree to the watt, and False at the END, where `(900/remaining)` has
+    multiplied the headroom past the ask and the recorded number is at its
+    most wrong. The quietest caveat exactly where it is needed loudest.
+
+    ⚠️ THE BUY LEG ONLY. §9.1: "Discharge and export are never capped by the
+    peak guard; only charging and import are." A sell is sized from
+    `discharge_w`, which is the roster's own rating and not a measurement of
+    the quarter, so a sell's recorded watts are NOT subject to this and must
+    not carry a caveat that would then be false.
+
+    ⚠️ AND THE ARBITER'S WINNER IS THE THIRD RUNG, NOT AN AFTERTHOUGHT. A trade
+    that was sized from the meter and then OUT-RANKED is not the number being
+    recorded - `Resolution.target_w` belongs to somebody else - and a caveat
+    filed against somebody else's number is a false sentence on the status row,
+    which is the defect class this whole card is about. It is in HERE and not
+    in `main.py` for the reason the two rungs above are: all three answer one
+    question, a check has to be able to reach each of them with the other two
+    clear (TEST-16), and a rung that lives at a call site is a rung no check
+    can drive.
+
+    `headroom_w` is whatever `peakguard.charge_headroom_w()` answered for the
+    cycle this decision was taken on. ⚠️ None IS "NOTHING MEASURED IT", and
+    `decide()` REFUSES the trade there (IDLE_HEADROOM_UNMEASURED), so a None
+    can only ever arrive here beside a non-trading decision - but it is tested
+    rather than assumed, because the caller is `main.py` and not this module.
+
+    `winner` is `Resolution.winner`: the source that actually set the watts.
+    """
+    return (winner == SOURCE
+            and decision is not None and decision.action == CHARGE
+            and headroom_w is not None)
+
+
 def claim(decision: ArbitrageDecision) -> Claim | None:
     """The decision as one arbiter claim, or None when nothing is to be traded.
 

goodwe_controller/app/control.py

@@ -191,6 +191,80 @@ SETTLE_CYCLES = math.ceil(PLANT_SETTLE_DOWN_S / LOOP_TICK_S)  # 12
 # edge rather than in prose, because it is a property of two files agreeing.
 _SAT_COUNT_CAP = SETTLE_CYCLES + 1                           # 13
 
+# ---------------------------------------------------------------------------
+# SAFETY-48. HOW FAR THE INTEGRATOR MAY STAND AHEAD OF THE COMMAND.
+#
+# ⚠️ THE MISSING CASE, AND IT IS A CASE AND NOT A CONSTANT. The freeze below
+# stops the integrator accumulating, and the comment beside it says what the
+# requirement is: "the INTEGRATOR stop accumulating, not only the command". But
+# `frozen` is computed from ONE signal - `abs(prev_w - actual_w) >
+# saturation_w`, the inverter not tracking - and SLEW-LIMITING NEVER ENTERS IT.
+# When the command hits the step ceiling, the integrator goes on winding at
+# `gain * error` until it reaches `integrator_max_w`.
+#
+# The arithmetic, and it is the whole card:
+#
+#     the integrator moves   gain * error   per cycle
+#     the command moves at most      slew   per cycle
+#     so the integrator outruns the command whenever
+#
+#         |error|  >  slew / gain
+#
+# At the live install's shape (gain 0.6, slew_w 400) that is 667 W. The median
+# grid error at the onset of a recorded episode is 1114 W. This is why
+# SAFETY-39's `slew_w` retune did not fix it: a smaller step makes the
+# threshold LOWER, so the case fires more often, not less.
+#
+# ⚠️ WHAT IS BOUNDED IS THE LEAD, NOT THE INTEGRATOR. Two forms were measured
+# over 16.0 days of the live install's own recorded disturbances
+# (`tools/replay_recorded_loop.py`, and DECISIONS/SAFETY-48 has the table):
+#
+#   (a) reuse the asymmetric freeze on a carried slew flag - "may not wind
+#       further in the direction it is already pushing", exactly as saturation
+#       does. It cuts export 13 % AND RAISES THE BILLED QUANTITY: the worst
+#       quarter-hour average OFFTAKE goes 3739 -> 3935 W and the mean quarter
+#       moves +2.7 W, in five of six plant and tuning variants, and on the
+#       billed quarter it is worse at every plant lag where release/1.0
+#       produces a peak at all (a tie at lag 0, worse at 2.5/5/7.5/10 s)
+#       and at every top-N cut of the quarters.
+#
+#       ⚠️ AND THE MECHANISM IS A REDISTRIBUTION, NOT A WEAKER ANSWER. An
+#       earlier draft of this line said a frozen integrator undershoots by
+#       (1 - gain) "so a large import is answered too weakly". The aggregate
+#       does not show that: form A cuts total import by 5.45 kWh, and paired
+#       tick by tick against release/1.0 it delivers 8.56 kWh LESS offtake
+#       energy on the ticks release/1.0 was importing. What it moves is the
+#       TAIL - within quarters that already net to offtake, the worst of them
+#       gets worse - and the capacity tariff bills the worst quarter and
+#       nothing else. That is the wrong trade here and the reason this is not
+#       the fix that ships.
+#
+#   (b) cap how far the integrator may LEAD the command, one slew step. Export
+#       39.6 -> 34.1 kWh, wasted throughput 4.7 -> 3.2 kWh, sign reversals
+#       2992 -> 2770, worst quarter-hour offtake 3739 -> 3434 W at the fitted
+#       plant lag (⚠️ AND AT NO SHORTER ONE: at every lag <= 5.0 s release/1.0
+#       is already at 3434 W and this changes it by zero - DECISIONS/SAFETY-48
+#       §3a), median recovery 232 -> 199 s. It is what ships.
+#
+# ⚠️ AND THE CAP IS NOT ZERO. `i_w = slewed` is full back-calculation, and this
+# module's own docstring says what that costs: passing `i_w=None` "reduces this
+# function to the exact velocity form it replaced". A zero cap makes `i_w`
+# identically the command on every cycle, which is that same collapse written
+# from the other end - it measures 32.0 kWh, better than (b) by 2 kWh, and it
+# throws away the reason the accumulator was split out at all. One step is the
+# smallest cap that is not that.
+#
+# WHAT THE NUMBER MEANS: the command can cover a one-step lead in ONE cycle, so
+# the worst-case unwind after a reversal is one cycle instead of
+# `integrator_max_w / slew_w` - 12.5 cycles at the live shape, ~60 s at the
+# meter's measured 5.0 s tick.
+#
+# ⚠️ IT IS IN STEPS RATHER THAN IN WATTS FOR SAFETY-39's REASON, WHICH IS THE
+# REASON THIS FILE KEEPS RE-LEARNING. A watt figure is a constant that outlives
+# the `slew_w` it was derived against; expressed in steps it moves with
+# `slew_limit_w()` and therefore with the rail.
+SLEW_LEAD_STEPS = 1
+
 
 @dataclass(frozen=True)
 class Tuning:
@@ -507,6 +581,83 @@ def compute(
     slewed = max(prev_w - slew, min(prev_w + slew, target))
     if slewed != target:
         reason = "slew-limited"
+        # --- SAFETY-48: the step ceiling reaches the integrator too ---------
+        # ⚠️ INSIDE THIS BRANCH AND NOWHERE ELSE - AND THE REASON IS NOT THE
+        # SATURATION FREEZE. An earlier draft of this comment said that applied
+        # unconditionally the cap "would also pull the integrator toward a
+        # command the SATURATION freeze is pinning", and priced that at 118 of
+        # 256 250 ticks. Both halves were invented, and MUTATION.md habit 22 is
+        # what fell out of it. The 118 had been measured against a DIFFERENT
+        # pair - a band applied after quantisation, at the very end of
+        # `compute()`. On the pair the sentence actually names - this same cap
+        # moved out of this branch to just after `target = slewed` - the two
+        # forms are BIT-IDENTICAL on the shipped configuration: 0 of 256 246
+        # ticks differ over the 16-day recording. They separate only where
+        # `integrator_max_w` is deliberately set ABOVE `max_w`, the one
+        # configuration this file says can reach its `clamped` reason; there
+        # the integrator is meant to run above the rail and an unconditional
+        # cap would drag it back to the command every cycle and make the option
+        # inert. THAT is why the cap stays in the branch, and
+        # `test_telemetry.py` part 4 drives it. (The separable-state COUNT is a
+        # property of whatever grid was swept - 2050 of 257 400 on this card's,
+        # 1220 of 246 064 on the review's, 776 of 40 320 on a third - so the
+        # claim to carry forward is WHERE they separate, not how many.)
+        #
+        # ⚠️ AND THE HALF A READER WILL OTHERWISE ASSUME AWAY: THIS CAP DOES
+        # MOVE A SATURATION-FROZEN INTEGRATOR. It runs BEFORE the freeze block
+        # below and is not gated on `frozen`. Measured over the same recording
+        # at the live shape: of 79 160 frozen ticks the cap changed `i_w` on
+        # 1095 of them, and on 679 of those it moved it FURTHER OUT on the side
+        # it was already on - putting back magnitude the freeze had just let
+        # fall, which is the one direction the freeze's own rule ("may fall,
+        # never rise") exists to forbid. Worst case 2424 W, and the worked tick
+        # is `prev_w -3400 W, grid +4697 W, actual -4144 W, sat_count 2 -> 3`:
+        # the freeze leaves the integrator at -176 W, the slew binds, and the
+        # cap drags it to -2600 W. It never overrides a SAME-CYCLE refusal -
+        # the freeze clipped `moved` on 75 512 ticks and the slew bound on none
+        # of them - but it does not leave the frozen path alone either.
+        #
+        # ⚠️ AND THAT IS WHERE SAFETY-13's SETTLE VALUES WENT. Gating this cap
+        # on `not frozen` puts `test_control.py` part 5 back at release/1.0's
+        # -1190 W exactly; part 4(b)'s -2390 -> -1200 W does NOT come back,
+        # because that one moved for the other reason - the winding BEFORE the
+        # freeze is bounded now. The gate is refused anyway: measured the same
+        # way it leaves a worst observed lead of 4961 W, i.e. no bound at all
+        # on the quantity this card exists to bound. DECISIONS/SAFETY-48 §5
+        # carries the rest of the price.
+        #
+        # ⚠️ WRITTEN ONE-SIDED, AND IT IS **EQUIVALENT** TO THE TWO-SIDED BAND
+        # `max(slewed - cap, min(slewed + cap, i_w))` - MEASURED, NOT REASONED.
+        # An earlier draft of this comment claimed the two-sided spelling was a
+        # bug that would drag a TRAILING integrator up toward the command. That
+        # is false and the sweep said so: `target` is monotone in `i_w`
+        # (`target = clamp(clamp(i_w, +-limit), +-max_w)`) and `slewed` is
+        # `target` pulled toward `prev_w`, so whenever the slew binds, `i_w`
+        # lies on the same side of `slewed` as `target` does and the other
+        # clamp cannot reach. The two spellings agree on **205 920 of 205 920**
+        # cases across four tunings, every sign of `prev_w`, `grid_w`,
+        # `actual_w` and `i_w`, and the `i_w=None` path.
+        #
+        # It stays one-sided because it SAYS which side the lead is on - the
+        # side the command wanted to move and could not - and because a reader
+        # reaching for the band spelling should find the sweep rather than an
+        # argument. ⚠️ The "descending" case is NOT an exception to the rule: a
+        # command falling from +2400 W toward an integrator at +100 W has an
+        # integrator 2300 W ahead of it IN THE DIRECTION OF TRAVEL, and it is
+        # pulled back to one step beyond the emitted command exactly as a
+        # rising one is.
+        #
+        # ⚠️ `i_w` IS CHANGED AND `target` IS NOT. This cycle's command is
+        # already decided; what is bounded is what gets CARRIED. That is also
+        # why the exhaustive `i_w=None` equivalence sweep in test_control.py is
+        # untouched by this card: it compares `(target_w, sat_count, frozen,
+        # reason)`, none of which this moves, and the seeded path re-seeds from
+        # `prev_w` next cycle anyway.
+        _lead_cap = SLEW_LEAD_STEPS * slew
+        if target > slewed:
+            i_w = min(i_w, slewed + _lead_cap)
+        elif target < slewed:
+            i_w = max(i_w, slewed - _lead_cap)
     target = slewed
 
     if frozen:

goodwe_controller/app/main.py

@@ -842,6 +842,18 @@ class Controller:
         # how a shadow run starts telling an operator a number nothing is
         # doing.
         self.shadow_would_w = None
+        # SAFETY-47. Was the number above SIZED FROM THE BILLED-QUARTER METER
+        # on the cycle it was recorded? ⚠️ IT IS RECORDED WHERE THE DECISION
+        # WAS TAKEN, NOT RE-DERIVED WHERE THE PAGE IS RENDERED. The status page
+        # runs on its own task and `self.peak_guard` has moved on by then, so a
+        # page that asked the question again would be answering it about a
+        # different cycle from the one whose watts it is displaying - which is
+        # the same two-facts-one-field defect the comment above this one is
+        # about. ⚠️ False AND NOT None BEFORE THE FIRST SHADOW CYCLE, unlike
+        # the field above: this one is a claim ABOUT a number, and there is no
+        # number yet, so the honest value is "nothing to disclose". The row's
+        # `would_w is None` branch renders no watts at all there.
+        self.shadow_sized_from_meter = False
         # Edge state for the action log, both of them. `_shadow_was` is None
         # until the first cycle, so an install that comes up IN shadow mode
         # says so in the log it will be read from rather than leaving the
@@ -852,6 +864,13 @@ class Controller:
         self.target = 0.0
         self.sat_count = 0
         self.i_w = 0.0        # the loop's integrator, carried between cycles
+        # TEL-10. What the last cycle's loop did, kept for publication. Seeded
+        # to the SAME values the "stopped or blind" branch of `cycle()` writes,
+        # because before the first cycle the loop has not run - which is the
+        # thing that branch is for.
+        self.loop_i_w = 0.0
+        self.loop_i_lead = 0.0
+        self.loop_reason = "not-running"
         self.loop_w = None    # what the loop asked for last cycle, or None
         # Did the grid-following loop actually win the LAST arbitration? That is
         # the question SAFETY-02 has to ask about the command standing on the
@@ -923,6 +942,12 @@ class Controller:
         # None (startup) or the PREVIOUS cycle's decision (an input hold), and
         # the status row rendered all three identically.
         self.arb_at = None
+        # SAFETY-45/47. The billed-quarter charging headroom the arbitrage step
+        # was handed on the cycle above, or None when nothing measured it. It
+        # is CARRIED rather than recomputed for `arbitrage.sized_from_meter()`,
+        # because `self.peak_guard` is a different cycle's decision by the time
+        # the status page renders.
+        self.arb_headroom_w = None
         # TARIFF-11. When the most recent cycle() STARTED. `arb_at < cycle_at`
         # is the exact, derived statement of "the latest cycle did not get as
         # far as the arbitrage step", which is the fact the *Arbitrage* row
@@ -2818,9 +2843,16 @@ class Controller:
         # `arb_at` is then the age the status row reports rather than a
         # decision presented as current.
         self.arb, self.arb_at = None, now
+        self.arb_headroom_w = None
         if arbitrage.enabled(self.o):
             floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
             charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
+            # SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of
+            # the shipped expression feeds both the sizing below and
+            # `arbitrage.sized_from_meter()` in `_shadow_settle()`, so the
+            # caveat on the recorded watts can never be answered from a
+            # different cycle's guard than the watts were.
+            self.arb_headroom_w = peakguard.charge_headroom_w(self.peak_guard)
             self.arb = arbitrage.decide(
                 self.fresh_tariff_plan(now), now,
                 peak_guard_active=arbitrage.guard_state(self.peak_guard),
@@ -2839,7 +2871,7 @@ class Controller:
                 # peak block's conclusion, ~50 lines up, so it must stay after
                 # it. Evaluated earlier it would size this quarter's trade from
                 # the previous cycle's quarter.
-                charge_headroom_w=peakguard.charge_headroom_w(self.peak_guard),
+                charge_headroom_w=self.arb_headroom_w,
                 # The emptiest pack again, and for the sell side that is the
                 # right reduction. ⚠️ THE BUY SIDE WANTS THE FULLEST, and there
                 # is one `soc` argument - `pack_floor_soc` names that residual
@@ -3029,8 +3061,15 @@ class Controller:
             # level: the two halves of §6.2's identity break in opposite
             # directions. See `site_batt_w` and test_alloc.py part 8.
             site_batt = self.site_batt_w
+            # TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED
+            # AGAINST. `self.target` is reassigned further down this method, so
+            # a `decision.i_w - self.target` written at publish time would
+            # subtract a DIFFERENT cycle's command and call the answer a lead.
+            # The published lead is built from the value `compute()` was
+            # actually handed, on the line that hands it over.
+            loop_prev = self.target
             decision = compute(
-                prev_w=self.target,
+                prev_w=loop_prev,
                 grid_w=self.grid,
                 actual_w=site_batt,
                 tuning=self.tuning,
@@ -3043,6 +3082,41 @@ class Controller:
             self.sat_count = decision.sat_count
             self.i_w = decision.i_w
             self.loop_w = decision.target_w
+            # --- TEL-10 ------------------------------------------------------
+            # ⚠️ THE INTEGRATOR HAS NEVER LEFT THIS PROCESS, AND THAT IS WHAT
+            # THE CARD IS. `self.i_w` is carried between cycles and published
+            # nowhere - no entity, no attribute, no log line - so the only way
+            # anyone has ever asked what it was doing is to RECONSTRUCT it from
+            # the grid trace and a replay. That reconstruction reproduced about
+            # a third of the engagements it was checked against and was thrown
+            # away; a card that has to be argued from a discarded reconstruction
+            # is a card that cannot be argued.
+            #
+            # Three rows, and the third is not derivable from the first two by
+            # anyone reading the dashboard afterwards:
+            #
+            #   `loop_i`      the integrator AFTER this cycle - `Decision.i_w`,
+            #                 which its own docstring says is the value BEFORE
+            #                 the output clamp, the slew limit and quantisation.
+            #                 It is therefore NOT `setpoint` and must never be
+            #                 published from it.
+            #   `loop_lead`   how far the integrator stands AHEAD of the command
+            #                 it was computed against. This is the quantity
+            #                 SAFETY-48 bounds, and `integrator_max_w / slew_w`
+            #                 is the number of cycles it takes to unwind.
+            #   `loop_reason` `compute()`'s OWN reason string - `deadband`,
+            #                 `i-clamped`, `clamped`, `slew-limited`,
+            #                 `saturated-freeze`, `freeze-released`, `tracking`.
+            #
+            # ⚠️ AND `loop_reason` IS NOT `self.reason`. `self.reason` is the
+            # ARBITER's sentence (`resolution.explain()`, e.g. "loop -> 1200 W")
+            # and it does not carry the loop's own word at all: the Claim filed
+            # below takes `decision.reason` and `Resolution.explain()` prints the
+            # winner's NAME, not the winner's reason. The status page's "Why"
+            # row is the arbiter's sentence and stays that way.
+            self.loop_i_w = decision.i_w
+            self.loop_i_lead = decision.i_w - loop_prev
+            self.loop_reason = decision.reason
             # --- SAFETY-03 ---------------------------------------------------
             # ⚠️ READ THE BOOLEANS, NOT `decision.reason`. On a default install
             # the integrator bound is what bites and the output clamp is
@@ -3067,6 +3141,15 @@ class Controller:
             # Stopped or blind: no accumulation may survive the outage.
             self.i_w = 0.0
             self.loop_w = None
+            # TEL-10, and it is the same zero the line above writes rather than
+            # a second opinion about it. ⚠️ `not-running` rather than a stale
+            # `tracking`: a reason row that keeps repeating the last word the
+            # loop said while the loop is not running is a row that reads as
+            # health, which is the failure `publish()`'s own None-dropping note
+            # is about one field over.
+            self.loop_i_w = 0.0
+            self.loop_i_lead = 0.0
+            self.loop_reason = "not-running"
             # A loop that is not running cannot be winding. Clearing this here
             # rather than letting the last value stand is what makes the alarm
             # de-assert when control is stopped.
@@ -3424,20 +3507,37 @@ class Controller:
                     "%+.0f W that was standing on the wire.", shadow.WIRE_W)
         if not engaged:
             self.shadow_would_w = None
+            self.shadow_sized_from_meter = False
             self._shadow_winner = None
             return
         self.shadow_would_w = float(resolution.target_w)
+        # SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY. All three rungs - the
+        # arbiter's winner, the leg being a CHARGE, and the headroom having
+        # been MEASURED - live inside `arbitrage.sized_from_meter()`, which
+        # says why, including why it is NOT keyed on whether the trade was
+        # capped. A rung written at a call site is a rung no check can reach
+        # with the other two clear, which is TEST-16's rule.
+        self.shadow_sized_from_meter = arbitrage.sized_from_meter(
+            self.arb, self.arb_headroom_w, winner=resolution.winner)
         # ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision
         # that moves from the loop to the peak guard at the same number is a
         # different decision and the operator needs the line; a loop target
         # that wanders by a watt is not, and 15 s of those would be the whole
         # log.
-        edge = (resolution.winner, round(float(resolution.target_w)))
+        # ⚠️ SAFETY-47 ADDS THE CAVEAT FLAG TO THE EDGE. The same winner at the
+        # same watts with and without the caveat are two different claims about
+        # the same number, and an edge key blind to that would print the first
+        # one and silently keep it standing. It cannot flood: the flag only
+        # moves when arbitrage starts or stops owning the resolution, or when
+        # the guard starts or stops measuring the quarter, and both of those
+        # move the winner or the watts as well on every cycle measured.
+        edge = (resolution.winner, round(float(resolution.target_w)),
+                self.shadow_sized_from_meter)
         if edge != self._shadow_winner:
             self._shadow_winner = edge
-            self.log_event(
-                f"SHADOW: would have commanded {resolution.target_w:+.0f} W - "
-                + resolution.explain())
+            self.log_event(shadow.log_line(
+                would_w=resolution.target_w, reason=resolution.explain(),
+                sized_from_meter=self.shadow_sized_from_meter))
         self.target = shadow.WIRE_W
         for inv in self.inverters:
             inv.target = shadow.WIRE_W
@@ -4246,6 +4346,14 @@ class Controller:
             # rather than publishing a zero that would read as health.
             "circulation": (None if self.site_circulating_w is None
                             else round(self.site_circulating_w)),
+            # TEL-10. The loop's own three, written from the fields `cycle()`
+            # recorded and not re-derived here - the page and the publisher run
+            # on their own tasks and `self.target` has moved on by the time
+            # either of them looks (SAFETY-47's note on `sized_from_meter`, one
+            # field up, is the same hazard).
+            "loop_i": round(self.loop_i_w, 1),
+            "loop_lead": round(self.loop_i_lead, 1),
+            "loop_reason": self.loop_reason,
         }
         # ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input
         # watchdog subscribes to sensor.goodwe_p1_sample_age - see the entity-id
@@ -4865,7 +4973,12 @@ class Controller:
             # learn something is a surface you have to already know about.
             ("Shadow mode", shadow.words(
                 self.o, control_started=self.auto,
-                would_w=self.shadow_would_w, reason=self.reason)),
+                would_w=self.shadow_would_w,
+                # SAFETY-47. THE FLAG THE CYCLE RECORDED, NOT ONE DERIVED HERE
+                # - the page runs on its own task and `self.peak_guard` has
+                # moved on. See `Controller.__init__`.
+                sized_from_meter=self.shadow_sized_from_meter,
+                reason=self.reason)),
             ("Why", self.reason),
             ("Maintenance phase", self.maint.phase if len(self.inverters) <= 1
              else f"{self.maint.phase} ({self.maint_unit.name})"),

goodwe_controller/app/mqtt.py

@@ -85,6 +85,36 @@ SENSORS = [
     # sensor's VALUE rather than its arrival, so a dead publisher freezes the
     # number and reads permanently fresh. Filed as TEL-06.
     ("p1_age", "p1_sample_age_s", "P1 sample age", "s", "duration", "measurement", None),
+    # --- TEL-10: the loop's integrator, published for the first time ---------
+    #
+    # ⚠️ APPENDED, AND THE POSITION IS THE POINT. `discovery_payloads()` walks
+    # this list in order and `_announce()` publishes what it returns, so a row
+    # inserted ABOVE would move every later entity's place in the announcement.
+    # Nothing existing is renamed, re-typed or re-ordered by these three; they
+    # are three NEW retained topics after the nine that are already there, and
+    # test_mqtt.py part 1 grades exactly that claim.
+    #
+    # ⚠️ AND THEY ARE SITE ROWS, NOT PER-UNIT ONES. There is one integrator -
+    # §6.2's architecture is ONE integrator on the P1 meter whose output is then
+    # SPLIT - so a per-unit copy would invent N of a thing there is one of, the
+    # same argument `grid` and `p1_age` are site rows for.
+    #
+    # `state_class: measurement` on the two numbers is what puts them in the
+    # recorder's statistics, which is the whole point: the reason this card
+    # exists is that the last investigation had no history to read.
+    ("loop_i", "goodwe_loop_integrator", "Loop integrator", "W", "power", "measurement", None),
+    # ⚠️ NOT DERIVABLE FROM THE TWO ROWS EITHER SIDE OF IT, which is why it is
+    # its own row rather than a subtraction a dashboard could do. `setpoint` is
+    # the ARBITER's output after every other strategy has had its say, and it is
+    # also THIS cycle's; the lead is measured against the command `compute()`
+    # was handed, which is the PREVIOUS one. Subtracting the published rows
+    # gives a different number on every cycle the arbiter overrode the loop.
+    ("loop_lead", "goodwe_loop_integrator_lead", "Loop integrator lead", "W", "power", "measurement", None),
+    # ⚠️ NOT `sensor.goodwe_controller_status` AND NOT THE "Why" ROW. Both of
+    # those carry the ARBITER's sentence; this is `compute()`'s own word for
+    # what the control law did with this cycle - `slew-limited` is the value
+    # SAFETY-48 is about and it appears in neither of the other two.
+    ("loop_reason", "goodwe_loop_reason", "Loop reason", None, None, None, "mdi:sigma"),
 ]
 
 BASE = "goodwe_ctl"

goodwe_controller/app/shadow.py

@@ -19,6 +19,83 @@ learn nothing. Shadow mode is the third option: strategies, arbiter, clamps and
 guards all run, the decision is recorded with its reason, and NOTHING THE
 CONTROLLER DECIDES REACHES THE INVERTER.
 
+⚠️ AND OF THOSE THREE, A SHADOW RUN CAN SHOW YOU EXACTLY ONE - SEE THE NEXT
+   SECTION. This header used to name SAFETY-45's limit cycle as the example
+   of what shadow mode surfaces. That was false, and SAFETY-47 measured it.
+
+⚠️ WHAT A SHADOW RUN CAN AND CANNOT SHOW  (SAFETY-47)
+=====================================================
+SHADOW MODE CANNOT SURFACE A CLOSED-LOOP DEFECT. Not badly, not partially -
+NOT AT ALL, and by the same construction that makes it safe. The actuator is
+held at WIRE_W and the carried command is re-seeded to WIRE_W, so every
+MEASURED input - the meter, the 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, no defect to see.
+
+That is not a gap to be closed later. Feeding the guards a simulated plant
+instead is what SAFETY-10 §4 refuses for the sign watchdogs, for a reason that
+applies to all of this: a controller reacting to a plant that does not exist
+drifts further from reality every tick, and three cycles in its numbers
+describe nothing. THE CLOSED-LOOP ANSWER COMES FROM A CLOSED-LOOP RIG
+(TEST-23 stage 3) OR FROM A LIVE RUN. There is no third place.
+
+So, of the three defects above, measured on that rig at `peak_cap_w` 1500 /
+house 1200 / `max_w` 2000, one hour at a 5 s cycle:
+
+  * SAFETY-45's limit cycle    NOT VISIBLE. Live: 28 charge onsets, the grid
+                               swinging -455.5 .. +3200.0 W, the guard engaged
+                               on 410 of 720 cycles. Shadow, same hour, same
+                               code: 1 onset, the grid flat at the 1200 W
+                               house, the guard engaged on 0 of 720. Every
+                               term of `wanted = batt_w + excess` is measured.
+  * SAFETY-46's SoC churn      NOT VISIBLE. The SoC moves 0.000000000 pp in a
+                               shadow run, because it is the pack's integral of
+                               what the pack was commanded and the pack was
+                               commanded 0 W. No SoC limit can be REACHED in a
+                               shadow run; the ones already crossed when it
+                               started are reported, and that is all.
+  * TARIFF-14's wrong quarter  VISIBLE, and it is the one. The price lookup's
+                               inputs are the CLOCK and the PRICE SERIES, and
+                               neither is a function of what the battery did.
+                               Measured: which hour the strategy picked, its
+                               price and the spread it cleared are identical
+                               live and shadow on 720 of 720 charging cycles,
+                               AT A BINDING CAP.
+
+⚠️ THE EXEMPTION THAT USED TO BE HERE WAS TRUE UNTIL SAFETY-45 MERGED. This
+module, DOCS.md and DECISIONS/SAFETY-10-shadow-mode.md all said "the strategies
+are unaffected - they ask for a fixed power from inputs that do not depend on
+what the battery did". SAFETY-45 made the buy leg `min(asked, headroom)` with
+
+    headroom = (900 / remaining) x (ceiling - projected)
+
+and `projected` reads the OPEN QUARTER'S ACCUMULATOR - the meter - which is a
+function of what the battery did earlier in that same quarter. The strategy
+became closed-loop the day that landed. What survives of the exemption, and
+only this:
+
+    WHICH hour a strategy picks, and WHY, are unaffected.
+    HOW HARD it trades is not.
+
+⚠️ AND THE SIZE A SHADOW RUN RECORDS IS THE RIGHT ANSWER TO A QUESTION NOBODY
+   ASKED. `900/remaining` is correct arithmetic for a meter that is genuinely
+under the ceiling - and in shadow the meter genuinely IS under it, because the
+battery is not charging. So the number is not a bug; it is an answer computed
+for a plant that did not exist. Measured on the same rig, shipped code:
+
+    cap / house      live commanded      shadow recorded      over
+    1500 / 1200         -302.4 W            -2000.0 W         6.61x
+    3500 / 3000         -502.6 W            -2000.0 W         3.98x
+    3500 / 2000        -1502.6 W            -2000.0 W         1.33x
+    3500 / 1800        -1702.6 W            -2000.0 W         1.17x
+   15000 /  350        -2000.0 W            -2000.0 W         1.00x
+
+The last row is the fixture SAFETY-10's own evidence was taken on, which is why
+nothing reported this. `words()` carries the caveat rather than a re-computed
+number, and `DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md` §3 records the
+three alternatives that were rejected and why.
+
 ⚠️ "REACHES NOTHING" IS NOT "WRITES NOTHING", AND THE DIFFERENCE IS THE WHOLE
    SAFETY ARGUMENT
 =======================================================================
@@ -138,11 +215,18 @@ THE FAILSAFES, ONE BY ONE (the card asks for each to be decided and recorded)
 |                                | resolved intent against a meter that has  |
 |                                | stopped moving, and both halves are as    |
 |                                | true in shadow as out of it.              |
-| SAFETY-07/24/25 peak guard     | OBSERVES. Level-triggered, unlatched, and |
-|                                | it files its claim as usual so the        |
-|                                | recorded decision is the real one.        |
-|                                | SAFETY-45's limit cycle is visible from a |
-|                                | shadow run; that is the point.            |
+| SAFETY-07/24/25 peak guard     | OBSERVES, AND SEES ONLY THE HOUSE. It is  |
+|                                | level-triggered and unlatched and it files|
+|                                | its claim as usual, so the recorded       |
+|                                | decision is the real one FOR THIS METER - |
+|                                | but every term of `wanted = batt_w +      |
+|                                | excess` is measured, and in shadow mode   |
+|                                | the battery contributes nothing to either.|
+|                                | ⚠️ SAFETY-47: this row used to claim      |
+|                                | SAFETY-45's limit cycle was visible from a|
+|                                | shadow run. It is not - 410/720 engaged   |
+|                                | cycles live against 0/720 in shadow, on   |
+|                                | the same hour and the same code.          |
 | SAFETY-31 circulation          | OBSERVES AND MAY LATCH, legitimately. Its |
 | SAFETY-42 delivery             | evidence is MEASURED power, not a         |
 |                                | command: packs pushing against each other |
@@ -215,6 +299,29 @@ MODES = ("auto", "on", "off")
 #: commanding it so the inverter cannot be left latched on anything else.
 WIRE_W = 0.0
 
+#: SAFETY-47. What the recorded watts mean when a MEASURED billed quarter sized
+#: them.
+#:
+#: ⚠️ "UPPER BOUND" AND NOT "SMALLER", AND THE DIFFERENCE WAS MEASURED RATHER
+#: THAN ARGUED. Charging only ADDS offtake, so a live meter's `projected` is
+#: never below a shadow meter's and the headroom is never above it: the shadow
+#: size is >= the live size, 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 IT NAMES NO FACTOR. How far under the bound a live run lands is a
+#: property of the site - 6.61x at a 1500 W cap under a 1200 W house, 1.00x at
+#: a cap that does not bind - and a number invented for the row would be a
+#: second helping of the defect this constant exists to disclose.
+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")
+
 
 def mode(opts: dict) -> str:
     """The configured `shadow_mode`, normalised to one of `MODES`.
@@ -279,7 +386,7 @@ def why(opts: dict, *, control_started: bool) -> str:
 
 
 def words(opts: dict, *, control_started: bool, would_w: float | None,
-          reason: str = "") -> str:
+          sized_from_meter: bool, reason: str = "") -> str:
     """The status page's `Shadow mode` row.
 
     ⚠️ THE ROW IS RENDERED IN EVERY STATE, INCLUDING `off`. A surface whose
@@ -288,10 +395,35 @@ def words(opts: dict, *, control_started: bool, would_w: float | None,
     what gets graded, so there has to be text in both states.
 
     `would_w` is the decision the path reached this cycle - what a live
-    controller would have put on the wire - and `reason` is
-    `Resolution.explain()`, the same sentence the `Why` row carries. Together
-    they are the whole of "what would it have done, and why"; without them the
-    row would say a shadow run happened and nothing about what it found.
+    controller would have put on the wire GIVEN THIS METER AND A BATTERY AT
+    0 W - and `reason` is `Resolution.explain()`, the same sentence the `Why`
+    row carries. Together they are the whole of "what would it have done, and
+    why"; without them the row would say a shadow run happened and nothing
+    about what it found.
+
+    ⚠️ `sized_from_meter` HAS NO DEFAULT, AND THAT IS SAFETY-47's WHOLE POINT.
+    It is True when a MEASURED billed-quarter headroom sized the number being
+    recorded - `arbitrage.sized_from_meter()` answers it, and it is the one
+    place the question is asked. A default of False here would be a caller
+    that forgot the caveat rendering a row that reads exactly like a caller
+    that decided it did not apply, which is the shape of defect this card is
+    about. TEST-14's rule with a new name on it.
+
+    ⚠️ AND THE PHRASE IS "ON THIS CYCLE", UNCONDITIONALLY, NOT ONLY WHEN THE
+    CAVEAT FIRES. Every number a shadow run records was reached from a plant
+    that did not respond; "WOULD HAVE COMMANDED -2 000 W" reads as a forecast
+    of a live run and no number here is one. The ⚠️ below is the STRONGER,
+    conditional statement about the cycles where the answer can be multiples
+    out - see this module's header for the measured table.
+
+    ⚠️ AND IT IS NOT KEYED ON WHETHER THE TRADE WAS CAPPED. `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. By the end of the quarter
+    `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 that sentence would be quietest exactly where it
+    is needed loudest. `test_arbitrage.py` part 3d-8 drives that.
     """
     head = why(opts, control_started=control_started)
     if not engaged(opts, control_started=control_started):
@@ -304,13 +436,38 @@ def words(opts: dict, *, control_started: bool, would_w: float | None,
     # half that says WHICH RUNG decided, which is the claim MUTATION.md's
     # masking rule says must survive.
     num = f"{float(would_w):+,.0f}".replace(",", " ")
-    out = (f"{head}; WOULD HAVE COMMANDED {num} W, inverter held at "
-           f"{WIRE_W:.0f} W")
+    out = (f"{head}; ON THIS CYCLE WOULD HAVE COMMANDED {num} W, inverter "
+           f"held at {WIRE_W:.0f} W")
+    if sized_from_meter:
+        out += f" {SIZED_FROM_METER}"
     if reason:
         out += f" - {reason}"
     return out
 
 
+def log_line(*, would_w: float, reason: str, sized_from_meter: bool) -> str:
+    """The action-log line for one change of shadow decision.
+
+    ⚠️ IT IS A FUNCTION FOR THE REASON `words()` IS ONE, AND SAFETY-47 LEARNED
+    IT THE EXPENSIVE WAY. This sentence used to be an f-string inside
+    `Controller._shadow_settle()`. Deleting the caveat from it there left all
+    29 files GREEN - the only check that could see the line drove a fixture
+    with `meter_source: off`, where no arbitrage decision and therefore no
+    caveat can ever be reached. A sentence assembled at a call site is a
+    sentence no check can grade, and the page would have said one thing while
+    the record a later analysis reads said another.
+
+    ⚠️ AND IT IS THE SAME `SIZED_FROM_METER` CONSTANT THE ROW CARRIES, not a
+    second wording of it. Two sentences meaning one thing is how the two
+    surfaces start disagreeing about which cycles are caveated.
+    """
+    out = (f"SHADOW: would have commanded {float(would_w):+.0f} W ON THIS "
+           f"CYCLE - {reason}")
+    if sized_from_meter:
+        out += f" {SIZED_FROM_METER}"
+    return out
+
+
 def banner(opts: dict, *, control_started: bool, latched: tuple = ()) -> tuple:
     """`(level, text)` for the top of the status page, or `None` when live.
 

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.9.0"
+version: "0.10.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart

goodwe_controller/scenarios/loop-2026-09-02_2026-09-17/manifest.json

@@ -0,0 +1,799 @@
+{
+ "generated": "2026-09-18T23:52:32.622227+02:00",
+ "generator": "tools/replay_recorded_loop.py --export",
+ "source": "http://192.168.2.158:8123/api/history/period",
+ "timezone": "Europe/Brussels",
+ "entities": {
+  "grid": "sensor.p1_meter_active_power",
+  "batt": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+  "setpoint": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+  "soc": "sensor.goodwe_rs485_controller_goodwe_battery_soc"
+ },
+ "format": "{\"t\": <ISO-8601 with offset>, \"v\": <state string>} per line, gzip, mtime 0",
+ "days": [
+  {
+   "date": "2026-09-02",
+   "window": [
+    "2026-09-02T00:00:00+02:00",
+    "2026-09-03T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16515,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-02-grid.jsonl.gz",
+     "bytes_raw": 922104,
+     "sha256_raw": "8e61b964fd9ebe047dfcc70f32f08ce2bebe7ac3ffe6f97000e3526a5637e9c4"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3299,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-02-batt.jsonl.gz",
+     "bytes_raw": 187888,
+     "sha256_raw": "0e2f392158a7fd2dc77287d3f94de1edab81c6a9a7e16b0f59f525145fe6a61b"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 4683,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-02-setpoint.jsonl.gz",
+     "bytes_raw": 267407,
+     "sha256_raw": "2f486e27bffdce82f16d20104fcdbbe7057ebd4c025c9ac00eb59531a44d1ea1"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 130,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-02-soc.jsonl.gz",
+     "bytes_raw": 7141,
+     "sha256_raw": "090d14866552b4dc27cf0c0505cfb5c4d7e7223b25a5af504598618aeba317ed"
+    }
+   }
+  },
+  {
+   "date": "2026-09-03",
+   "window": [
+    "2026-09-03T00:00:00+02:00",
+    "2026-09-04T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16419,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-03-grid.jsonl.gz",
+     "bytes_raw": 919508,
+     "sha256_raw": "fd4230b864a2f789fcac6da7bbe87f0445fedbc81818d3c4a1c1a41655ed5b4f"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3434,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-03-batt.jsonl.gz",
+     "bytes_raw": 194783,
+     "sha256_raw": "3a12c37dfe33a571b68f27a68d88b38170f4acd39f4c9574f58de7a9c358fe8e"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5145,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-03-setpoint.jsonl.gz",
+     "bytes_raw": 292456,
+     "sha256_raw": "c8c70155151c44ef92cd7048dd5642838e2fcd5dfa4989db30d39f91e9031aa2"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 69,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-03-soc.jsonl.gz",
+     "bytes_raw": 3786,
+     "sha256_raw": "a34ccf6a175d0b60b0852a305be69457c0e0a42f3f9a1c777ab100039cc57c24"
+    }
+   }
+  },
+  {
+   "date": "2026-09-04",
+   "window": [
+    "2026-09-04T00:00:00+02:00",
+    "2026-09-05T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16098,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-04-grid.jsonl.gz",
+     "bytes_raw": 897558,
+     "sha256_raw": "4c1528faa35778a3fe6a7b613482af4ef854e6b1b92ba8a6c72aa231158cf93f"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3009,
+     "non_numeric_states": 1,
+     "attempts": 1,
+     "file": "2026-09-04-batt.jsonl.gz",
+     "bytes_raw": 170410,
+     "sha256_raw": "2ee54e9c6670ebc87bb120bb98a572dbe6b129c3a2e3aa7802c5993ecab03500"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 4300,
+     "non_numeric_states": 1,
+     "attempts": 1,
+     "file": "2026-09-04-setpoint.jsonl.gz",
+     "bytes_raw": 244058,
+     "sha256_raw": "7130b266efe61447276183a8da1b79e14e1e2a56b92b9884c5cb3c1d277cf002"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 47,
+     "non_numeric_states": 1,
+     "attempts": 1,
+     "file": "2026-09-04-soc.jsonl.gz",
+     "bytes_raw": 2583,
+     "sha256_raw": "833ed5f48b3fac83beb65cb1c1b00ed66597505bcab37813997c3f3f908b72bd"
+    }
+   }
+  },
+  {
+   "date": "2026-09-05",
+   "window": [
+    "2026-09-05T00:00:00+02:00",
+    "2026-09-06T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16448,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-05-grid.jsonl.gz",
+     "bytes_raw": 920613,
+     "sha256_raw": "03cb4e2b3e075b060a47bf5d3cb83d5c55d0055512dcec800a4aaf5bbae91b3e"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4409,
+     "non_numeric_states": 6,
+     "attempts": 1,
+     "file": "2026-09-05-batt.jsonl.gz",
+     "bytes_raw": 251332,
+     "sha256_raw": "a11c722ff106df1675e57e9d98af37ec22bf61d509fa847c30c31a50165c07a1"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 6339,
+     "non_numeric_states": 6,
+     "attempts": 1,
+     "file": "2026-09-05-setpoint.jsonl.gz",
+     "bytes_raw": 361644,
+     "sha256_raw": "7929161bfaf654dab097d02219b3a1c83d1530e78a0e38776115792afd45fb8d"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 132,
+     "non_numeric_states": 6,
+     "attempts": 1,
+     "file": "2026-09-05-soc.jsonl.gz",
+     "bytes_raw": 7289,
+     "sha256_raw": "139d883516de462655fe34902c30cc09a329ace6fbb248b06f8ffd8b1d6edaa2"
+    }
+   }
+  },
+  {
+   "date": "2026-09-06",
+   "window": [
+    "2026-09-06T00:00:00+02:00",
+    "2026-09-07T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16060,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-06-grid.jsonl.gz",
+     "bytes_raw": 899105,
+     "sha256_raw": "7d3e92c36834aeb1992d611cea6d256967585b45c3c9251b00dac676befebbea"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3569,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-06-batt.jsonl.gz",
+     "bytes_raw": 202858,
+     "sha256_raw": "5030a36a36b9ae6867c582c70fb7cf57b6fe762aa1e52993ab48d4f5c4269ef4"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5190,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-06-setpoint.jsonl.gz",
+     "bytes_raw": 295576,
+     "sha256_raw": "d361daab3fa61bae75779d574e3619d3cc0908501187f054b16643caa2e0f231"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 83,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-06-soc.jsonl.gz",
+     "bytes_raw": 4556,
+     "sha256_raw": "6ee9813016c7a1bdb62f6f4e892e8c3351491e1c5324c67862c068cebee8c2d1"
+    }
+   }
+  },
+  {
+   "date": "2026-09-07",
+   "window": [
+    "2026-09-07T00:00:00+02:00",
+    "2026-09-08T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15512,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-07-grid.jsonl.gz",
+     "bytes_raw": 868060,
+     "sha256_raw": "69ff04ecc0df7faa11824b3a4f2e4bd5a84167aa260386380d842da84da4f152"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3646,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-07-batt.jsonl.gz",
+     "bytes_raw": 207432,
+     "sha256_raw": "37a68612eadcecf80d6e796f653ae8e4ec9ff98a40a8d560ca18df995b47ad14"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 3521,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-07-setpoint.jsonl.gz",
+     "bytes_raw": 201333,
+     "sha256_raw": "1c0a93b59c46f7338e81a1a8f0609db7e140793bc28c9a66d2087eaf2360eb2b"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 138,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-07-soc.jsonl.gz",
+     "bytes_raw": 7584,
+     "sha256_raw": "bea3599b83e280a11a3a6b83b2626db15acaf04c2d7db16734a1acc76f691bf8"
+    }
+   }
+  },
+  {
+   "date": "2026-09-08",
+   "window": [
+    "2026-09-08T00:00:00+02:00",
+    "2026-09-09T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15691,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-08-grid.jsonl.gz",
+     "bytes_raw": 872562,
+     "sha256_raw": "632c58235dde62178358a72c445945829dfbb580cf9dbd1eef32c545ea29154b"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4451,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-08-batt.jsonl.gz",
+     "bytes_raw": 251748,
+     "sha256_raw": "0d94ce9c4e41e33094fb7a3ffafbec15c9d9ad1b741aaa0b77e39a9ca8b64572"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5145,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-08-setpoint.jsonl.gz",
+     "bytes_raw": 292178,
+     "sha256_raw": "d29a15925e1a87c57a120828dd6f138b0ee3738f0418f789e6b14451785dcab4"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 118,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-08-soc.jsonl.gz",
+     "bytes_raw": 6481,
+     "sha256_raw": "f07d9cd878763dcda6e8bf58653d260a5d897f4bc65efd446707e0af5a84c813"
+    }
+   }
+  },
+  {
+   "date": "2026-09-09",
+   "window": [
+    "2026-09-09T00:00:00+02:00",
+    "2026-09-10T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16017,
+     "non_numeric_states": 1,
+     "attempts": 1,
+     "file": "2026-09-09-grid.jsonl.gz",
+     "bytes_raw": 894526,
+     "sha256_raw": "50924035a087895b89b72f6acf5db24a3b9ed704362968854e1328493e0c7758"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4124,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-09-batt.jsonl.gz",
+     "bytes_raw": 235314,
+     "sha256_raw": "93e26b5f40b20d1478c457b7cae06f899c2b52f1ce2abba90fe08ca14ad4607e"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5855,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-09-setpoint.jsonl.gz",
+     "bytes_raw": 334751,
+     "sha256_raw": "d5286bc477b825343804e4fd8eb85e9a35c3a8e98e83abba9df5d2879637bab9"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 123,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-09-soc.jsonl.gz",
+     "bytes_raw": 6757,
+     "sha256_raw": "c4b6b1a3fc3de4e928db2f6ac7520a7556893e1b588d2f57711a4c7ded6646d4"
+    }
+   }
+  },
+  {
+   "date": "2026-09-10",
+   "window": [
+    "2026-09-10T00:00:00+02:00",
+    "2026-09-11T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16172,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-10-grid.jsonl.gz",
+     "bytes_raw": 902807,
+     "sha256_raw": "7a388548ce9b10374354afe17ba10567f7a592c38b7614b60e570d12a8c4cc87"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4322,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-10-batt.jsonl.gz",
+     "bytes_raw": 246291,
+     "sha256_raw": "e01417fb54e163f188feed3aab464cd7e125d1c8c6e2b5ed51066d86f84cc221"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5450,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-10-setpoint.jsonl.gz",
+     "bytes_raw": 310937,
+     "sha256_raw": "5fd7917fa89459a7f89eb838cc07d09f2dda85964f45df27a16d49a5608af797"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 142,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-10-soc.jsonl.gz",
+     "bytes_raw": 7802,
+     "sha256_raw": "ff94001915949d165377ad6b2ac8dd0f00c84a0cd1c8a83fbddf474543dc1871"
+    }
+   }
+  },
+  {
+   "date": "2026-09-11",
+   "window": [
+    "2026-09-11T00:00:00+02:00",
+    "2026-09-12T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15975,
+     "non_numeric_states": 1,
+     "attempts": 1,
+     "file": "2026-09-11-grid.jsonl.gz",
+     "bytes_raw": 889154,
+     "sha256_raw": "335847b7f757a1fa3682be000ef3e77dcf637ccb52b9ad3d739539d1a7fd1384"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4399,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-11-batt.jsonl.gz",
+     "bytes_raw": 250012,
+     "sha256_raw": "bd91e7a0e33cbec1737fb95019746c44bdf3ff71e71933ff99b45383b3bcef29"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5519,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-11-setpoint.jsonl.gz",
+     "bytes_raw": 315079,
+     "sha256_raw": "8f538f230ff2076a5a098d27a6d26390c9995e88a14b9b30e7b141bd216b211a"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 124,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-11-soc.jsonl.gz",
+     "bytes_raw": 6812,
+     "sha256_raw": "d090fe60687ce35498afa923089881d1eaec3b50be2604ffe4ac4261c6d7f8b5"
+    }
+   }
+  },
+  {
+   "date": "2026-09-12",
+   "window": [
+    "2026-09-12T00:00:00+02:00",
+    "2026-09-13T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16001,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-12-grid.jsonl.gz",
+     "bytes_raw": 893240,
+     "sha256_raw": "3ff17d8fa70133338cd4c54067b7c37d5f33fd971d8037e99b8f829703d42a2d"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3744,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-12-batt.jsonl.gz",
+     "bytes_raw": 213926,
+     "sha256_raw": "228b3498d915d6b96781dca039899816b4a9c45874af019095cede1128c2d2aa"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5012,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-12-setpoint.jsonl.gz",
+     "bytes_raw": 287190,
+     "sha256_raw": "bfb3389a021c2b01a005901c961c2c30bb6ca4a42e5e80c00855ea1144f3464a"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 126,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-12-soc.jsonl.gz",
+     "bytes_raw": 6922,
+     "sha256_raw": "ca17b220922550d9d00330f62742edf9b9cdf990cd3647a14a580f3427023092"
+    }
+   }
+  },
+  {
+   "date": "2026-09-13",
+   "window": [
+    "2026-09-13T00:00:00+02:00",
+    "2026-09-14T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15912,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-13-grid.jsonl.gz",
+     "bytes_raw": 888912,
+     "sha256_raw": "79a2f5462c396cc26c90c72e2b38390f1665bb41b77fc9120019595228133ca3"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3432,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-13-batt.jsonl.gz",
+     "bytes_raw": 193080,
+     "sha256_raw": "9410b9b80632c2ad68cd0632a5dd6513077eaecfc7a776986df867f847b19b39"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 3566,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-13-setpoint.jsonl.gz",
+     "bytes_raw": 201353,
+     "sha256_raw": "8173b590ed7a33d441cc0f2fb447ad88ce1c12aef6019155124132f44b11981c"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 80,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-13-soc.jsonl.gz",
+     "bytes_raw": 4391,
+     "sha256_raw": "15a8328cc07964216be4f3a6001fb640937e33f81b13c64e8da0872ab0da8a46"
+    }
+   }
+  },
+  {
+   "date": "2026-09-14",
+   "window": [
+    "2026-09-14T00:00:00+02:00",
+    "2026-09-15T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 16086,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-14-grid.jsonl.gz",
+     "bytes_raw": 904274,
+     "sha256_raw": "26c255b793432474a45dc6f0fff156f358f8468f2381e8161f4d0812d732e754"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 2679,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-14-batt.jsonl.gz",
+     "bytes_raw": 152706,
+     "sha256_raw": "d2bec4260c3649db865744a93f20c38c8f76b4f09f2e0b2308e61280b415321d"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 4007,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-14-setpoint.jsonl.gz",
+     "bytes_raw": 229164,
+     "sha256_raw": "4b3feb9cf7349bf8d6b3c4b6daa7d8b598f5589e52dfe48c98791d89e5678d79"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 75,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-14-soc.jsonl.gz",
+     "bytes_raw": 4116,
+     "sha256_raw": "31b3d54b0b4ea4e2e5ee5fc0131c05bea5f920996699888ac764b66d19763d89"
+    }
+   }
+  },
+  {
+   "date": "2026-09-15",
+   "window": [
+    "2026-09-15T00:00:00+02:00",
+    "2026-09-16T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15947,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-15-grid.jsonl.gz",
+     "bytes_raw": 890223,
+     "sha256_raw": "6a6d39306d47b08dc190d576b3b7a2e486a755ad846fa721262a53002305bb2c"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3651,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-15-batt.jsonl.gz",
+     "bytes_raw": 208309,
+     "sha256_raw": "4b60ab3ab24b9fc6dbde7262d36c74b0ef164429e382448c48ceea709921ddf4"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 4641,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-15-setpoint.jsonl.gz",
+     "bytes_raw": 265543,
+     "sha256_raw": "308ab0767d0dfd1c78daf313aef292e4383cd78d155656f2e829b88ad8539ece"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 116,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-15-soc.jsonl.gz",
+     "bytes_raw": 6372,
+     "sha256_raw": "5a8d8bdca4c6eccc275edcc13ee1b1ec24092f86d209b605f4405d95f23107d6"
+    }
+   }
+  },
+  {
+   "date": "2026-09-16",
+   "window": [
+    "2026-09-16T00:00:00+02:00",
+    "2026-09-17T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15888,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-16-grid.jsonl.gz",
+     "bytes_raw": 886214,
+     "sha256_raw": "cc3a1fc8f892fd22bb27b64f9928dcbbea9849a9c26ef8e7b2221483c82e5c15"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 4444,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-16-batt.jsonl.gz",
+     "bytes_raw": 252502,
+     "sha256_raw": "70189159b45c26f742dca92475d991f70210b5766a711e466b2fbd266968842b"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 5424,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-16-setpoint.jsonl.gz",
+     "bytes_raw": 309293,
+     "sha256_raw": "9f8c00b6bdea1de540f7ade4bc31870f61d972dfcd58d48a1653b1e114320d75"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 155,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-16-soc.jsonl.gz",
+     "bytes_raw": 8517,
+     "sha256_raw": "1bf7f07c5b60eea5cadb9758a40d2b34463ecaf33627b117ea2bed6afa45fb57"
+    }
+   }
+  },
+  {
+   "date": "2026-09-17",
+   "window": [
+    "2026-09-17T00:00:00+02:00",
+    "2026-09-18T00:00:00+02:00"
+   ],
+   "files": {
+    "grid": {
+     "read": "OK",
+     "entity": "sensor.p1_meter_active_power",
+     "samples": 15544,
+     "non_numeric_states": 0,
+     "attempts": 1,
+     "file": "2026-09-17-grid.jsonl.gz",
+     "bytes_raw": 867466,
+     "sha256_raw": "340bec5e35fed7a4f0964694bbca294fba21fce77ddd27af616720398c1cbbc4"
+    },
+    "batt": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+     "samples": 3868,
+     "non_numeric_states": 2,
+     "attempts": 1,
+     "file": "2026-09-17-batt.jsonl.gz",
+     "bytes_raw": 218642,
+     "sha256_raw": "4cb8e89baa89b4919d5e9b578585ab591eac4e94a636fa3aa88d293926f8401b"
+    },
+    "setpoint": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+     "samples": 4599,
+     "non_numeric_states": 2,
+     "attempts": 1,
+     "file": "2026-09-17-setpoint.jsonl.gz",
+     "bytes_raw": 261144,
+     "sha256_raw": "ddebbc60d2d8b0b8e06d2bef6bc3b61ea7c39becb22f25b7b2219455a7398519"
+    },
+    "soc": {
+     "read": "OK",
+     "entity": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+     "samples": 97,
+     "non_numeric_states": 2,
+     "attempts": 1,
+     "file": "2026-09-17-soc.jsonl.gz",
+     "bytes_raw": 5336,
+     "sha256_raw": "f1fade3d84a924447659fefa680f5b795266f3281bc2f5d5b6f86a1e434ddd4e"
+    }
+   }
+  }
+ ]
+}

goodwe_controller/test_arbitrage.py

@@ -94,6 +94,8 @@ from app.arbitrage import (
     CHARGE, DISCHARGE, ArbitrageDecision, claim, decide, enabled, soc_bounds,
     threshold_eur_kwh,
 )
+# SAFETY-47 section 3d. The shipped shadow-mode row, not a transcription of it.
+from app import shadow as _shadow
 from app.price import (
     PRICE_OPTION_DEFAULTS, Absence, PricePoint, PriceProduct, PriceRead,
     Uncertainty, WIDEN_FACTOR, brussels, required_spread, widen_factor,
@@ -890,18 +892,61 @@ check("a ZERO headroom does not cap a DISCHARGE. §9.1: 'discharge and export "
 # caller fills is a TypeError only on the one path a suite does not run. Same
 # pin, same reason, as `weights=` in test_packshare.py part 10.
 _S45_MAIN = open(os.path.join(HERE, "app", "main.py"), encoding="utf-8").read()
-_s45_calls = [n for n in ast.walk(ast.parse(_S45_MAIN))
+_S45_MAIN_TREE = ast.parse(_S45_MAIN)
+_s45_calls = [n for n in ast.walk(_S45_MAIN_TREE)
               if isinstance(n, ast.Call)
               and ast.unparse(n.func).endswith("arbitrage.decide")]
 _s45_arg = [ast.unparse(k.value) for c in _s45_calls for k in c.keywords
             if k.arg == "charge_headroom_w"]
+
+
+def _s45_assigned(name, clear=("None",)):
+    """Every expression main.py assigns to `self.<name>` that is not a CLEAR.
+
+    ⚠️ SAFETY-47 HOISTED THE HEADROOM OUT OF THE CALL, so pinning the call
+    argument alone stopped covering anything: the literal a mutation would put
+    there now goes one line up instead. Both ends are pinned.
+
+    ⚠️ `clear` NAMES THE CONSTANTS THAT MEAN "NOTHING HAS ANSWERED THIS YET" -
+    `__init__`'s value and the per-cycle reset - and they are not a second
+    source for the number. Excluding them does NOT soften the pin: a mutation
+    that replaces the real assignment with one of those constants leaves this
+    list EMPTY, which matches no expected value and is red.
+    """
+    return [ast.unparse(n.value) for n in ast.walk(_S45_MAIN_TREE)
+            if isinstance(n, ast.Assign)
+            and [ast.unparse(t) for t in n.targets] == [f"self.{name}"]
+            and ast.unparse(n.value) not in clear]
+
+
+_s45_head_src = _s45_assigned("arb_headroom_w")
 print(f"    main.py has {len(_s45_calls)} `arbitrage.decide(` call site(s); "
-      f"charge_headroom_w= is {_s45_arg}")
+      f"charge_headroom_w= is {_s45_arg}, and self.arb_headroom_w is assigned "
+      f"from {_s45_head_src}")
 check("main.py passes the guard's OWN measured headroom at its one "
       "arbitrage.decide() call site - the shipped expression, not a "
       "transcription of it, so a mutation back to a literal or to max_w is red "
       "rather than silent",
-      _s45_arg == ["peakguard.charge_headroom_w(self.peak_guard)"])
+      _s45_arg == ["self.arb_headroom_w"]
+      and _s45_head_src == ["peakguard.charge_headroom_w(self.peak_guard)"])
+# ⚠️ AND THE HOIST DID NOT MOVE IT OUT OF THE CYCLE. An `arb_headroom_w` set
+# once in `__init__` and never refreshed would satisfy the pin above and would
+# size every trade from the guard decision of whatever cycle happened to run
+# last - which is the defect the hoist's own comment warns about, one level up.
+_s45_cycle = next(n for n in ast.walk(_S45_MAIN_TREE)
+                  if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))
+                  and n.name == "cycle"
+                  and any(isinstance(c, ast.Call)
+                          and ast.unparse(c.func).endswith("arbitrage.decide")
+                          for c in ast.walk(n)))
+check("...and the assignment is INSIDE the same `cycle()` that makes the call, "
+      "so the headroom the trade is sized from is this cycle's guard decision "
+      "and not one carried from an arbitrary earlier one",
+      any(isinstance(n, ast.Assign)
+          and [ast.unparse(t) for t in n.targets] == ["self.arb_headroom_w"]
+          and ast.unparse(n.value)
+          == "peakguard.charge_headroom_w(self.peak_guard)"
+          for n in ast.walk(_s45_cycle)))
 
 
 # --------------------------------------------------------------------------- #
@@ -946,14 +991,26 @@ S45_T0 = D0 + timedelta(hours=CHEAP_H)
 
 
 def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
-             seconds=S45_RUN_S):
+             seconds=S45_RUN_S, shadow=False):
     """One closed hour. `sized=False` is the behaviour this card removes.
 
     ⚠️ THE COUNTERFACTUAL IS ONE ARGUMENT, NOT A SECOND CODE PATH. `sized=False`
     hands `decide()` a headroom nothing can bind - which is exactly what the
     tree did before this card, because nothing was passing one - so the two runs
     below differ in one value and share every line of shipped code. Habit 7.
+
+    ⚠️ SAFETY-47's `shadow=True` IS THE SAME DISCIPLINE, ONE ARGUMENT AGAIN. It
+    reproduces the THREE things `Controller._write_unit()` and
+    `_shadow_settle()` do and nothing else: the resolved command is RECORDED,
+    the plant is driven from `shadow.WIRE_W` instead of from it, and the
+    carried command is RE-SEEDED to `shadow.WIRE_W` after the record is taken.
+    Those three lines are a TRANSCRIPTION of main.py's placement and are marked
+    as one - `test_clamp.py` part 8 is the check on the shipped placement, and
+    it drives the real `Controller`. What is NOT transcribed is every number
+    that matters here: the averager, the projection, the guard, the headroom,
+    the strategy, the arbiter and the row's own words are all the shipped ones.
     """
+
     avg = QuarterAverager(phases=1, max_hold_s=900.0)
     tuning = Tuning(gain=0.6, max_w=MAX_W, slew_w=0.0)
     t0 = S45_T0
@@ -962,6 +1019,7 @@ def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
     loop_w = None
     batt_cmd = batt = 0.0           # + discharge, as main.py's site_batt_w
     onsets = blocks = 0
+    rec = []
     prev_action = "<start>"
     grid_lo, grid_hi = None, None
     billed = []
@@ -1008,7 +1066,32 @@ def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
             claims.append(Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W,
                                       "max_w"))
             claims.append(Claim.set("loop", P_LOOP, d.target_w, d.reason))
-            target = resolve(claims).target_w
+            res = resolve(claims)
+            target = res.target_w
+            head_w = _pg.charge_headroom_w(pk) if sized else HEADROOM_CLEAR
+            rec.append(dict(
+                t_s=t, action=arb.action, power_w=arb.power_w,
+                reason=arb.reason, price=arb.price_now_eur_kwh,
+                spread=arb.spread_eur_kwh, winner=res.winner,
+                target_w=float(res.target_w), headroom_w=head_w,
+                engaged=bool(pk.engaged),
+                sized_from_meter=_arb.sized_from_meter(
+                    arb, head_w, winner=res.winner)))
+            if shadow:
+                # --- TRANSCRIBED 1/3: `_shadow_settle()`'s record, taken
+                #     BEFORE the re-seed destroys its evidence.
+                rec[-1]["would_w"] = float(res.target_w)
+                rec[-1]["row"] = _shadow.words(
+                    {"shadow_mode": "on"}, control_started=False,
+                    would_w=float(res.target_w),
+                    sized_from_meter=rec[-1]["sized_from_meter"],
+                    reason=res.explain())
+                # --- TRANSCRIBED 2/3: `_write_unit()`'s substitution - the
+                #     plant below is driven from WIRE_W, not from the decision.
+                # --- TRANSCRIBED 3/3: `_shadow_settle()`'s re-seed of the
+                #     carried command, which is what `compute(prev_w=...)`,
+                #     `standing_w()` and SAFETY-42 read next cycle.
+                target = _shadow.WIRE_W
         # THE PLANT, MODELLED: an 800 W/s ramp into a 10 s first-order lag.
         step = min(1.0, acc)
         delta = target - batt_cmd
@@ -1020,7 +1103,9 @@ def s45_loop(*, sized: bool, cap_w=S45_CAP_W, load_w=S45_LOAD_W,
         grid_hi = grid if grid_hi is None else max(grid_hi, grid)
     return dict(onsets=onsets, grid_lo=round(grid_lo, 1),
                 grid_hi=round(grid_hi, 1), swing=round(grid_hi - grid_lo, 1),
-                billed=billed, blocks=blocks)
+                billed=billed, blocks=blocks, rec=rec,
+                engaged=sum(1 for r in rec if r["engaged"]),
+                cycles=len(rec))
 
 S45_BEFORE = derived(lambda: s45_loop(sized=False))
 S45_AFTER = derived(lambda: s45_loop(sized=True))
@@ -1076,11 +1161,440 @@ S45_WIDE_S = derived(lambda: s45_loop(sized=True, cap_w=5000.0, load_w=1200.0,
 print(f"    peak_cap_w 5000 W, 1200 W house (load + max_w = "
       f"{S45_LOAD_W + MAX_W:.0f} W, under the cap): unsized "
       f"{S45_WIDE['billed']} W, sized {S45_WIDE_S['billed']} W")
+
+
+
+def _s45_outcome(r):
+    """Everything the two runs put on the PLANT and the METER.
+
+    ⚠️ `rec` IS EXCLUDED AND THE EXCLUSION IS NAMED. SAFETY-47 added a
+    per-cycle record to this harness, and it carries `headroom_w` and
+    `sized_from_meter` - which are THE ONE ARGUMENT the two runs differ in, by
+    construction. Comparing them would make this check fail for the reason it
+    exists to rule out. The resolved command per cycle IS compared, below, and
+    that is a stronger statement than the six aggregates ever were.
+    """
+    return {k: v for k, v in r.items() if k != "rec"}
+
+
 check("on a site where the trade cannot reach the cap the two runs are "
       "IDENTICAL to the watt - so this card costs nothing on the installs it "
       "is not about, and the check above is not passing because the cap "
       "dominates everything",
-      S45_WIDE == S45_WIDE_S and S45_WIDE["onsets"] == 1)
+      _s45_outcome(S45_WIDE) == _s45_outcome(S45_WIDE_S)
+      and S45_WIDE["onsets"] == 1)
+check("...and identical CYCLE BY CYCLE, not merely in the six aggregates: "
+      "every resolved command and every traded size matches to the float",
+      [(r["target_w"], r["power_w"]) for r in S45_WIDE["rec"]]
+      == [(r["target_w"], r["power_w"]) for r in S45_WIDE_S["rec"]])
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("3d. SAFETY-47 - the SHADOW record against a LIVE run, at a BINDING cap")
+# ---------------------------------------------------------------------------
+# WHAT THIS PART EXISTS FOR, AND IT IS NOT A SECOND SAFETY-45 CHECK.
+#
+# SAFETY-10 shipped shadow mode saying, in three merged documents, that "the
+# strategies are unaffected - they ask for a fixed power from inputs that do
+# not depend on what the battery did - so a shadow run does show you the
+# trades, the peak-guard engagements and the SoC-limit behaviour". That was
+# true until 3c's own fix merged. SAFETY-45 makes the buy leg
+# `min(asked, headroom)`, and the headroom is
+#
+#     (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. The strategy
+# became closed-loop the day 3c landed, and shadow mode holds the battery at
+# 0 W, so in a shadow run that accumulator contains THE HOUSE AND NOTHING ELSE.
+#
+# ⚠️ AND SAFETY-10 §6's COMMITTED EVIDENCE COULD NEVER HAVE FAILED - TWO
+#    INDEPENDENT REASONS, AND CLOSING EITHER ONE ALONE CLOSES NOTHING.
+#   (1) its fixture is `peak_cap_w: 15000` against a 350 W house, so the guard
+#       never engages and the sizing is inert - MUTATION.md habit 4, inside a
+#       merged card's own proof;
+#   (2) every identity row reads THE FIRST CHARGING SAMPLE, and at `elapsed=0`
+#       the projection IS the held level, so the two runs agree to the float
+#       there even AT a binding cap. 3d-2 drives that and says so.
+#
+# So this part is the grader for the class: a shadow run and a live run, the
+# same hour, the same code, at a cap that BINDS. What is REAL and what is
+# TRANSCRIBED is in `s45_loop()`'s own docstring - the three lines that stand
+# in for `Controller._write_unit()` and `_shadow_settle()` are named there, and
+# `test_clamp.py` part 8 is the check on the shipped placement.
+# ---------------------------------------------------------------------------
+S47_LIVE = derived(lambda: s45_loop(sized=True))
+S47_SHAD = derived(lambda: s45_loop(sized=True, shadow=True))
+# The SAFETY-45 defect itself, watched from inside shadow mode - which is what
+# SAFETY-10's header claimed a shadow run would surface.
+S47_UNSIZED_SHAD = derived(lambda: s45_loop(sized=False, shadow=True))
+
+_s47_lc = derived(lambda: [r for r in S47_LIVE["rec"] if r["action"] == CHARGE])
+_s47_sc = derived(lambda: [r for r in S47_SHAD["rec"] if r["action"] == CHARGE])
+
+# ⚠️ THE SECTION CARRIES ITS OWN PRECONDITION INTO EVERY CHECK, AND THIS IS
+# FCST-06's SHAPE RATHER THAN TIDINESS. A mutation that stops either run
+# trading at all leaves these lists EMPTY; the first `min()` below then raises,
+# the file dies before part 4, and the run reports ZERO reds - which reads
+# exactly like a survivor. Measured: driving `wanted = batt_w - ex` through
+# this section did precisely that. So the lists are replaced by a sentinel that
+# cannot satisfy anything, and `s47check()` fails every check in the section
+# when the stimulus was not produced.
+_S47_DEAD = dict(action=None, power_w=0.0, reason="<no charging cycle>",
+                 price=None, spread=None, winner=None, target_w=0.0,
+                 headroom_w=0.0, engaged=False, sized_from_meter=False,
+                 would_w=0.0, row="", t_s=0.0)
+_S47_OK = bool(_s47_lc) and bool(_s47_sc)
+if not _S47_OK:
+    _s47_lc = _s47_sc = [dict(_S47_DEAD)]
+_s47_n = min(len(_s47_lc), len(_s47_sc))
+
+
+def s47check(name, cond):
+    """A 3d check, AND the section's own precondition, in one verdict."""
+    check(name, _S47_OK and bool(cond))
+
+
+check("PRECONDITION: both runs actually reached a charging decision - without "
+      "this the section raises on its first `min()`, the file dies before "
+      "part 4 and the run reports ZERO reds, which reads exactly like a "
+      "survivor (MUTATION.md, FCST-06's shape). Measured, not imagined",
+      _S47_OK)
+print(f"    live  : {len(_s47_lc)} charging cycles, traded "
+      f"{min(r['power_w'] for r in _s47_lc):+.1f} .. "
+      f"{max(r['power_w'] for r in _s47_lc):+.1f} W, "
+      f"headroom {min(r['headroom_w'] for r in _s47_lc):.1f} .. "
+      f"{max(r['headroom_w'] for r in _s47_lc):.1f} W, "
+      f"grid {S47_LIVE['grid_lo']:.0f} .. {S47_LIVE['grid_hi']:.0f} W")
+print(f"    shadow: {len(_s47_sc)} charging cycles, RECORDED "
+      f"{min(r['power_w'] for r in _s47_sc):+.1f} .. "
+      f"{max(r['power_w'] for r in _s47_sc):+.1f} W, "
+      f"headroom {min(r['headroom_w'] for r in _s47_sc):.1f} .. "
+      f"{max(r['headroom_w'] for r in _s47_sc):.1f} W, "
+      f"grid {S47_SHAD['grid_lo']:.0f} .. {S47_SHAD['grid_hi']:.0f} W")
+
+# --- 3d-1. THE PRECONDITION: the cap binds, and the meter proves it --------
+# ⚠️ WITHOUT THIS EVERY CHECK BELOW IS SAFETY-10 §6's DEFECT IN A NEW FILE. At
+# a cap the trade cannot reach, live and shadow agree exactly and nothing here
+# could ever go red - which is precisely what the committed evidence did.
+s47check("PRECONDITION: the cap BINDS - the live run's trade is sized by the "
+      f"guard on every charging cycle, never reaching the {MAX_W:.0f} W ask",
+      _s47_lc and all(abs(r["power_w"]) < MAX_W - 1.0 for r in _s47_lc))
+s47check("...and the live METER is what closed the gap: it is held up at the "
+      f"{S45_CAP_W:.0f} W ceiling rather than sitting at the "
+      f"{S45_LOAD_W:.0f} W house, which is the feedback a shadow run does not "
+      f"have",
+      S47_LIVE["grid_hi"] > S45_LOAD_W + 200.0)
+s47check("...and the SHADOW meter sees the house and nothing else for the whole "
+      "run, which is what makes its billed quarter a different quarter",
+      near(S47_SHAD["grid_lo"], S45_LOAD_W, 0.001)
+      and near(S47_SHAD["grid_hi"], S45_LOAD_W, 0.001))
+
+# --- 3d-2. WHY THE OLD SHAPE COULD NOT FAIL --------------------------------
+# Graded as an EXPECTATION rather than left as a footnote, so that nobody
+# rebuilds a check on `[0]` and believes it covers something.
+print(f"    first charging cycle: live {_s47_lc[0]['power_w']:+.4f} W, "
+      f"shadow {_s47_sc[0]['power_w']:+.4f} W")
+s47check("⚠️ THE FIRST CHARGING CYCLE IS IDENTICAL IN BOTH RUNS EVEN HERE, so "
+      "widening SAFETY-10 §6's fixture ALONE would not have made its table go "
+      "red: at elapsed=0 the projection IS the held level and neither plant "
+      "has moved yet. Both reasons had to be closed, and this is the one a "
+      "reviewer cannot see from a diff",
+      _s47_lc[0]["power_w"] == _s47_sc[0]["power_w"]
+      and _s47_lc[0]["reason"] == _s47_sc[0]["reason"])
+
+# --- 3d-3. AND ACROSS THE WHOLE RUN THEY DIVERGE ---------------------------
+_s47_mis = sum(1 for i in range(_s47_n)
+               if _s47_lc[i]["power_w"] != _s47_sc[i]["power_w"])
+_s47_worst = min(_s47_sc, key=lambda r: r["power_w"])
+_s47_live_worst = min(_s47_lc, key=lambda r: r["power_w"])
+# ⚠️ NaN AND NOT AN EXCEPTION when the sentinel above is in play: `nan > 2.0`
+# is False, so the check goes RED, while a ZeroDivisionError here would kill
+# the file and report zero reds. Same defect, one line further down - it was
+# driven, and it is why this is not a plain division.
+_s47_over = (abs(_s47_worst["power_w"]) / abs(_s47_live_worst["power_w"])
+             if _s47_live_worst["power_w"] else float("nan"))
+print(f"    size mismatches {_s47_mis}/{_s47_n} charging cycles; the shadow "
+      f"run records {_s47_worst['power_w']:+.0f} W where the live run's "
+      f"hardest trade is {_s47_live_worst['power_w']:+.1f} W - "
+      f"{_s47_over:.2f}x")
+s47check("ACROSS THE WHOLE RUN the recorded trade size diverges on all but the "
+      "first few cycles - the check SAFETY-10 §6 should have been",
+      _s47_mis > 0.9 * _s47_n)
+s47check(f"...and the shadow run RECORDS a trade the live run never commanded, "
+      f"over by {_s47_over:.2f}x. `900/remaining` amplifies a "
+      f"(ceiling - projected) gap the battery never closed, and the row "
+      f"carried that number to a commissioning engineer with no caveat",
+      _s47_over > 2.0)
+s47check("...and the amplification is IN THE HEADROOM, which is where the "
+      f"measurement enters: the shadow guard offers up to "
+      f"{max(r['headroom_w'] for r in _s47_sc):.0f} W of charging headroom "
+      f"against a {S45_CAP_W:.0f} W ceiling and a {S45_LOAD_W:.0f} W house, "
+      f"while the live guard never exceeds "
+      f"{max(r['headroom_w'] for r in _s47_lc):.0f} W",
+      max(r["headroom_w"] for r in _s47_sc) > MAX_W
+      and max(r["headroom_w"] for r in _s47_lc) < MAX_W)
+
+# --- 3d-3b. THE SENTENCE THE ROW PRINTS, GRADED AS ARITHMETIC --------------
+# ⚠️ THE ROW CLAIMS THE RECORDED NUMBER IS AN **UPPER BOUND**, and a claim on
+# an operator-facing surface is a claim this file has to be able to fail.
+# Charging only ADDS offtake, so a live `projected` is never below a shadow
+# one and the headroom is never above it. The earlier wording said "smaller",
+# which is FALSE on every cycle where the two are equal - the start of each
+# quarter, where `900/remaining` is 1.0 and neither plant has moved.
+_s47_below = [i for i in range(_s47_n)
+              if abs(_s47_sc[i]["power_w"]) < abs(_s47_lc[i]["power_w"]) - 1e-9]
+_s47_equal = sum(1 for i in range(_s47_n)
+                 if abs(_s47_sc[i]["power_w"]) == abs(_s47_lc[i]["power_w"]))
+print(f"    the shadow record is below the live command on "
+      f"{len(_s47_below)}/{_s47_n} cycles and exactly equal on {_s47_equal}")
+s47check("the recorded size is an UPPER BOUND on the live one, on every compared "
+      "cycle - which is the sentence `shadow.SIZED_FROM_METER` puts on the "
+      "status row, so the row is making a claim this file can fail",
+      not _s47_below)
+s47check("...and it is NOT strictly greater: the two are equal at the start of "
+      f"each quarter ({_s47_equal} cycles here), which is why the row says "
+      f"'upper bound' and not 'smaller' - the second would be a false "
+      f"sentence on exactly those cycles",
+      _s47_equal > 0)
+
+# ⚠️ AND THE MECHANISM BEHIND THE BOUND, AS TWO POINTS OF THE SHIPPED
+# ARITHMETIC RATHER THAN AS ONE PROPERTY OF A WHOLE RUN. Same ceiling, same
+# elapsed, same house: one quarter that carried the battery's charge at the
+# meter (LIVE) and one that did not (SHADOW). The closed-loop version above
+# cannot be driven red by any mutation that ALSO stops the fixture trading -
+# measured - so the relation it rests on is graded directly here.
+def _s47_headroom(*, meter_w, batt_w, elapsed_s=450.0):
+    """`charge_headroom_w()` for a quarter that banked `meter_w` for
+    `elapsed_s`, with `batt_w` measured at the pack. All shipped."""
+    avg = QuarterAverager(phases=1, max_hold_s=900.0)
+    t = 0.0
+    while t <= elapsed_s:
+        imp, exp = split_signed(meter_w)
+        avg.add(make_sample("ha_signed", imp, exp, phases=1,
+                            ingest_ts=S45_T0 + timedelta(seconds=t),
+                            ingest_mono=(S45_T0.timestamp() + t)))
+        t += 5.0
+    pk = _pg.decide(
+        PeakTracker.project(avg, S45_T0 + timedelta(seconds=elapsed_s)),
+        batt_w=batt_w, cap_w=S45_CAP_W, reading=None, achievable_w=MAX_W,
+        soc=50.0, soc_floor=20.0, max_hold_s=900.0, frozen=False)
+    return _pg.charge_headroom_w(pk)
+
+
+_S47_TRADE_W = 300.0
+_s47_h_shadow = derived(lambda: _s47_headroom(meter_w=S45_LOAD_W, batt_w=0.0))
+_s47_h_live = derived(lambda: _s47_headroom(
+    meter_w=S45_LOAD_W + _S47_TRADE_W, batt_w=-_S47_TRADE_W))
+print(f"    half-way through one quarter, {S45_LOAD_W:.0f} W house under a "
+      f"{S45_CAP_W:.0f} W ceiling: the SHADOW meter (battery at 0 W) offers "
+      f"{_s47_h_shadow:.0f} W of headroom, the LIVE meter (the same house "
+      f"plus a {_S47_TRADE_W:.0f} W charge) offers {_s47_h_live:.0f} W")
+s47check("the SHADOW meter offers STRICTLY MORE charging headroom than the "
+         "live one on the same house, same ceiling and same elapsed - which "
+         "is the whole mechanism, in two points of the shipped arithmetic "
+         "rather than as a property of a whole run",
+         _s47_h_shadow > _s47_h_live)
+s47check("...and the live answer is the one that lands the block ON the "
+         "ceiling, so the shadow answer is the one that is wrong about the "
+         "bill rather than the other way round",
+         near(_s47_h_live, S45_CAP_W - S45_LOAD_W, 1.0))
+
+# --- 3d-4. WHAT SURVIVES OF THE EXEMPTION, GRADED --------------------------
+# The narrowed claim the three documents now make, as a check rather than as a
+# sentence: WHICH hour and WHY are unaffected; HOW HARD is not.
+s47check("WHICH hour the strategy picked and at WHAT price are identical on "
+      f"every one of the {_s47_n} compared cycles - the clock and the price "
+      f"series are not functions of what the battery did, which is the half "
+      f"of the old exemption that is still true",
+      all(_s47_lc[i]["price"] == _s47_sc[i]["price"] for i in range(_s47_n)))
+s47check("...and so is the spread it had to clear",
+      all(_s47_lc[i]["spread"] == _s47_sc[i]["spread"]
+          for i in range(_s47_n)))
+
+# --- 3d-5. THE CLOSED-LOOP DEFECT THE DOCUMENTS SAID WAS VISIBLE -----------
+# ⚠️ SAFETY-10's HEADER NAMED SAFETY-45's LIMIT CYCLE AS EXAMPLE #1 OF WHAT A
+# SHADOW RUN SURFACES. 3c's own PRECONDITION establishes that the unsized loop
+# really does run away; the same stimulus watched from inside shadow mode is
+# a settled, uneventful hour.
+print(f"    SAFETY-45's own defect, unsized: live {S45_BEFORE['onsets']} "
+      f"onsets/swing {S45_BEFORE['swing']:.0f} W, guard engaged "
+      f"{S45_BEFORE['engaged']}/{S45_BEFORE['cycles']}  ->  in shadow mode "
+      f"{S47_UNSIZED_SHAD['onsets']} onsets/swing "
+      f"{S47_UNSIZED_SHAD['swing']:.0f} W, guard engaged "
+      f"{S47_UNSIZED_SHAD['engaged']}/{S47_UNSIZED_SHAD['cycles']}")
+s47check("⚠️ SAFETY-45's LIMIT CYCLE IS NOT VISIBLE FROM A SHADOW RUN, and three "
+      "merged documents said it was. The same hour, the same unsized code: "
+      f"{S45_BEFORE['onsets']} charge onsets and a "
+      f"{S45_BEFORE['swing']:.0f} W grid swing live, "
+      f"{S47_UNSIZED_SHAD['onsets']} onsets and "
+      f"{S47_UNSIZED_SHAD['swing']:.0f} W in shadow",
+      S45_BEFORE["onsets"] >= 10 and S45_BEFORE["swing"] > 2000.0
+      and S47_UNSIZED_SHAD["onsets"] <= 2
+      and S47_UNSIZED_SHAD["swing"] < 1.0)
+s47check("...and neither are the guard ENGAGEMENTS the same documents promised: "
+      f"{S45_BEFORE['engaged']} engaged cycles live against "
+      f"{S47_UNSIZED_SHAD['engaged']} in shadow. Every term of "
+      f"`wanted = batt_w + excess` is MEASURED, and in shadow mode the "
+      f"battery contributes nothing to either term",
+      S45_BEFORE["engaged"] > 100 and S47_UNSIZED_SHAD["engaged"] == 0)
+
+# --- 3d-6. THE THREE RUNGS OF `sized_from_meter()`, SEPARATED --------------
+# TEST-16's rule: three rungs answer one question, so each is reached with the
+# other two clear. Any two of them left standing would mask the third.
+_s47_chg = _s47_worst
+_s47_sell = derived(lambda: act(PLAN, DEAR_H, thresh=_shipped, unc=NO_WEATHER,
+                                headroom=0.0))
+s47check("the CHARGE rung: a metered headroom that sized a buy leg answers True, "
+      "which is the state the caveat exists for",
+      _arb.sized_from_meter(
+          ArbitrageDecision(action=CHARGE, power_w=-300.0, reason="x",
+                            spread_eur_kwh=1.0, required_eur_kwh=0.1,
+                            price_now_eur_kwh=0.05),
+          300.0, winner=_arb.SOURCE) is True)
+s47check("...the SELL rung: a DISCHARGE answers False however the headroom reads. "
+      "§9.1 - discharge and export are never capped by the peak guard - so a "
+      "caveat on a sell would be a FALSE sentence on the status row",
+      _s47_sell.action == DISCHARGE
+      and _arb.sized_from_meter(_s47_sell, 300.0, winner=_arb.SOURCE) is False)
+s47check("...the UNMEASURED rung: a None headroom answers False. Nothing sized "
+      "anything from a meter, so there is nothing to disclose - and `decide()` "
+      "refuses the trade there anyway",
+      _arb.sized_from_meter(
+          ArbitrageDecision(action=CHARGE, power_w=-300.0, reason="x",
+                            spread_eur_kwh=1.0, required_eur_kwh=0.1,
+                            price_now_eur_kwh=0.05),
+          None, winner=_arb.SOURCE) is False)
+s47check("...the WINNER rung: the same sized charge answers False once something "
+      "else owns the resolution. `Resolution.target_w` is then somebody "
+      "else's number and a caveat filed against it would be false",
+      _arb.sized_from_meter(
+          ArbitrageDecision(action=CHARGE, power_w=-300.0, reason="x",
+                            spread_eur_kwh=1.0, required_eur_kwh=0.1,
+                            price_now_eur_kwh=0.05),
+          300.0, winner="loop") is False)
+
+# --- 3d-7. THE ROW, AT THE WORST CYCLE -------------------------------------
+_s47_row = _s47_chg["row"]
+_s47_first_row = _s47_sc[0]["row"]
+print(f"    worst cycle row: {_s47_row[:230]}")
+s47check("the shipped row carries the caveat at the worst cycle: the operator is "
+      "told the number was sized from a meter with only the house in it",
+      _shadow.SIZED_FROM_METER in _s47_row)
+s47check("...and it still carries the watts, in their own slot, and the standing "
+      "0 W beside them - the caveat NARROWS the claim rather than deleting "
+      "the record a shadow run exists to produce",
+      "WOULD HAVE COMMANDED" in _s47_row and "inverter held at 0 W" in _s47_row
+      and f"{round(_s47_chg['would_w']):+d}".replace("+", "") != "")
+s47check("...and the watts are introduced as what it would have commanded ON "
+      "THIS CYCLE, in every shadow state and not only the caveated ones - no "
+      "number a shadow run records is a forecast of a live run",
+      "ON THIS CYCLE WOULD HAVE COMMANDED" in _s47_row
+      and "ON THIS CYCLE WOULD HAVE COMMANDED" in _s47_first_row)
+
+# --- 3d-7b. THE ACTION LOG, WHICH IS THE RECORD READ AFTERWARDS -----------
+# ⚠️ THE TWO SURFACES ARE GRADED SEPARATELY BECAUSE THEY FAILED SEPARATELY.
+# Driven as one mutation, deleting the caveat from the log line alone 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 is `shadow.log_line()` now, so it can be graded.
+_s47_log = derived(lambda: _shadow.log_line(
+    would_w=_s47_chg["would_w"], reason="arbitrage -> -2000 W",
+    sized_from_meter=_s47_chg["sized_from_meter"]))
+_s47_log_plain = derived(lambda: _shadow.log_line(
+    would_w=_s47_chg["would_w"], reason="loop -> -300 W",
+    sized_from_meter=False))
+print(f"    action log: {_s47_log[:190]}")
+s47check("the ACTION LOG line carries the same caveat the row does - a page that "
+      "discloses and a 40-row record that does not is the worse half of the "
+      "two, because the record is what is read after the run",
+      _shadow.SIZED_FROM_METER in _s47_log)
+s47check("...and it is the SAME constant, not a second wording of it, so the two "
+      "surfaces cannot start disagreeing about which cycles are caveated",
+      _shadow.SIZED_FROM_METER in _s47_row and _shadow.SIZED_FROM_METER
+      in _s47_log)
+s47check("...and an uncaveated cycle gets the plain sentence, so the caveat is "
+      "not simply printed on everything",
+      _shadow.SIZED_FROM_METER not in _s47_log_plain
+      and "would have commanded" in _s47_log_plain
+      and "ON THIS CYCLE" in _s47_log_plain)
+
+# --- 3d-8. ⚠️ AND IT IS NOT KEYED ON WHETHER THE TRADE WAS CAPPED ----------
+# THE TRAP THIS PART EXISTS TO SPRING. `arbitrage`'s own sentence says "SIZED
+# BY THE CAPACITY-TARIFF GUARD" only when the headroom came out BELOW the ask.
+# In a shadow run that 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 that sentence would
+# be quietest exactly where it is needed loudest.
+_S47_CAPPED = "SIZED BY THE CAPACITY-TARIFF GUARD"
+print(f"    at the worst cycle the shipped trade sentence says "
+      f"{'' if _S47_CAPPED in _s47_chg['reason'] else 'NOT '}capped; at the "
+      f"first it says "
+      f"{'' if _S47_CAPPED in _s47_sc[0]['reason'] else 'NOT '}capped")
+s47check("PRECONDITION: the shipped 'capped' sentence IS present at the first "
+      "charging cycle, where the shadow number is RIGHT - so the inverse "
+      "below is a real inversion and not an absence everywhere",
+      _S47_CAPPED in _s47_sc[0]["reason"])
+s47check("⚠️ ...and ABSENT at the worst cycle, where the shadow number is "
+      f"{_s47_over:.2f}x out. A caveat keyed on `capped` would fire only "
+      f"where the record is accurate and go silent where it is multiples "
+      f"wrong; `sized_from_meter()` is keyed on the headroom having been "
+      f"MEASURED, so it fires on both",
+      _S47_CAPPED not in _s47_chg["reason"]
+      and _s47_chg["sized_from_meter"] is True
+      and _s47_sc[0]["sized_from_meter"] is True)
+
+# --- 3d-9. main.py's CALL SITES, PINNED ------------------------------------
+# ⚠️ THE CALL SITE IS THE UNIT OF COVERAGE (habit 15), same as 3b's. Nothing
+# behavioural in this file can see main.py render the row with a hard-coded
+# False, because every check above calls `shadow.words()` itself.
+_s47_words = [n for n in ast.walk(_S45_MAIN_TREE)
+              if isinstance(n, ast.Call)
+              and ast.unparse(n.func).endswith("shadow.words")]
+_s47_flag = [ast.unparse(k.value) for c in _s47_words for k in c.keywords
+             if k.arg == "sized_from_meter"]
+_s47_flag_src = _s45_assigned("shadow_sized_from_meter",
+                              clear=("None", "False"))
+print(f"    main.py: shadow.words(sized_from_meter={_s47_flag}), and "
+      f"self.shadow_sized_from_meter is assigned from {_s47_flag_src}")
+s47check("main.py renders the row from the flag THE CYCLE RECORDED, at its one "
+      "shadow.words() call site - not from a literal and not re-derived on "
+      "the status task, where `self.peak_guard` is a different cycle's",
+      _s47_flag == ["self.shadow_sized_from_meter"])
+s47check("...and that flag comes from the SHIPPED predicate with all three of its "
+      "arguments - the decision, the headroom the trade was sized from, and "
+      "the arbiter's winner - so a mutation to `False`, to a literal or to a "
+      "two-argument transcription is red rather than silent",
+      _s47_flag_src == ["arbitrage.sized_from_meter("
+                        "self.arb, self.arb_headroom_w, "
+                        "winner=resolution.winner)"])
+_s47_logcalls = [n for n in ast.walk(_S45_MAIN_TREE)
+                 if isinstance(n, ast.Call)
+                 and ast.unparse(n.func).endswith("shadow.log_line")]
+_s47_logflag = [ast.unparse(k.value) for c in _s47_logcalls for k in c.keywords
+                if k.arg == "sized_from_meter"]
+print(f"    main.py: shadow.log_line(sized_from_meter={_s47_logflag})")
+s47check("...and the ACTION LOG line comes from the shipped sentence with the "
+      "same flag, at main.py's one call site - not re-assembled as an "
+      "f-string where no check can reach it, which is how it survived a whole "
+      "mutation battery once already",
+      _s47_logflag == ["self.shadow_sized_from_meter"])
+# ⚠️ AND THE PARAMETER HAS NO DEFAULT. TEST-14's rule, and this card is the
+# reason it matters here: a caller that FORGOT the caveat and a caller that
+# DECIDED it did not apply would render the identical row.
+_s47_sig = inspect.signature(_shadow.words)
+_s47_logsig = inspect.signature(_shadow.log_line)
+s47check("`shadow.words()` and `shadow.log_line()` BOTH require "
+      "`sized_from_meter` - no default on either, so a caller cannot omit the "
+      "caveat by accident and get the un-caveated surface",
+      "sized_from_meter" in _s47_sig.parameters
+      and _s47_sig.parameters["sized_from_meter"].default
+      is inspect.Parameter.empty
+      and "sized_from_meter" in _s47_logsig.parameters
+      and _s47_logsig.parameters["sized_from_meter"].default
+      is inspect.Parameter.empty)
 
 
 # --------------------------------------------------------------------------- #

goodwe_controller/test_control.py

@@ -522,7 +522,20 @@ for _ in range(20):
 pinned = [r for r in rows if r[3] == "saturated-freeze"]
 check(f"non-zero prev_w, another writer: pinned at {pinned[0][1]:.0f} W...",
       pinned and all(r[1] == -800.0 for r in pinned))
-check(f"...then released, settling at {prev:.0f} W", prev == -2390.0)
+# ⚠️ SAFETY-48 MOVED THIS NUMBER FROM -2390 W TO -1200 W, DELIBERATELY, AND
+# THE PROPERTY IT IS HERE FOR IS UNCHANGED. The release lets the command walk
+# to the FROZEN INTEGRATOR; SAFETY-48 bounds how far that integrator can have
+# wound ahead of the command before the freeze engaged, so the value it walks
+# to is smaller. What this run must still show is that the release happens and
+# that it stops at the integrator - both asserted, the second against `i_w`
+# rather than against a literal, because the literal is the half this card
+# moves. The cost is stated rather than smoothed: on a persistent second writer
+# this run buys back 1200 W of a 2000 W export where release/1.0 bought back
+# 2390 W. DECISIONS/SAFETY-48 §5 records it as the price of the bound and the
+# rejected alternative that avoids it.
+check(f"...then released, settling at {prev:.0f} W, at the frozen integrator "
+      f"({i_w:.0f} W) - release/1.0 settled at -2390 W, at its own unbounded "
+      f"one", prev == -1200.0 and prev == i_w)
 
 # --- 5. THE CARD'S OWN CASE, DRIVEN END TO END -----------------------------
 # The live install's shape (max_w 5000, slew_w 400, target_grid_w -10). The site
@@ -546,9 +559,14 @@ check(f"the card's case: the charge starts at cycle {started[0]}"
 # that divergence into windup. It cannot, because releasing the OUTPUT freeze
 # does not release the INTEGRATOR freeze - so the command can only walk, one
 # slew step per cycle, to a value the integrator stopped accumulating at.
+# ⚠️ SAFETY-48 MOVED THIS ONE TOO, -1190 W -> -800 W against an integrator that
+# stood at -1194 W and now stands at -800 W, for the reason above. AC 4's
+# property - the release stops at the integrator and not at the rail - is what
+# is asserted; the literal is the branch's own number and is printed.
 check(f"the card's case: it settles at {prev:.0f} W, at the frozen integrator "
-      f"({i_w:.0f} W) and not the {TL.max_w:.0f} W rail",
-      prev == -1190.0 and abs(prev) <= abs(i_w) and abs(prev) < TL.max_w)
+      f"({i_w:.0f} W) and not the {TL.max_w:.0f} W rail - release/1.0 settled "
+      f"at -1190 W against an integrator of -1194 W",
+      prev == -800.0 and abs(prev) <= abs(i_w) and abs(prev) < TL.max_w)
 steps = [abs(cmds[i] - cmds[i - 1]) for i in range(1, len(cmds))]
 check(f"the card's case: no cycle moves more than the slew limit "
       f"(worst {max(steps):.0f} W of {slew_limit_w(TL):.0f})",
@@ -1115,25 +1133,58 @@ check("⭐ FIXED, ON THE THING THE SLEW ACTUALLY OWNS: following the rail remove
       _R["live"]["big"] > 0 and _R["rail"]["big"] == 0
       and _R["interim"]["big"] == 0)
 
-# ⚠️ AND WHAT IT DOES NOT BUY, MEASURED, ASSERTED, AND SAID BEFORE ANYBODY CAN
-# READ MORE INTO THIS CARD THAN IT DELIVERED. `slew_w` bounds the OUTPUT; the
-# integrator accumulates `gain * error` per cycle and is bounded only by
-# `integrator_max_w`. At gain 0.6 into a 3.4 kW error the integrator moves
-# ~2000 W per tick and reaches a 5000 W rail in under three ticks WHATEVER
-# `slew_w` is. So the over-absorption is a GAIN term, and slowing the slew does
-# not reduce it - on this model it gets slightly WORSE, because the command
-# spends longer away from where it needs to be while the integrator keeps
-# winding. admin/goodwe's rig, a different plant model, agrees: over-absorption
-# 990 W at slew 1000 and 1086 W at slew 250, against 1010 W at gain 0.6 and
-# 863 W at gain 0.3 (tools/slew_sim.py).
+# --- SAFETY-48 RE-BASELINED THIS CHECK, AND THE INVERSION IS THE EVIDENCE ----
 #
-# `gain` is therefore the next constant to re-derive. SAFETY-39 measured it and
-# CHANGED NOTHING: it is a live control-law constant on a running house, and two
-# of them moving in one release makes the next measurement uninterpretable.
-check("⚠️ THE SLEW DOES NOT OWN THE OVER-ABSORPTION, AND THIS CHECK IS HERE SO "
-      "THAT NOBODY READS SAFETY-39 AS 'THE OVERSHOOT IS FIXED'. Quartering the "
-      "slew from 1000 to 250 does not reduce the over-absorption at all",
-      _R["slower"]["over"] >= _R["live"]["over"])
+# ⚠️ WHAT THIS LINE USED TO SAY, AND WHY IT IS NOT A SILENT EDIT. SAFETY-39
+# shipped:
+#
+#     "⚠️ THE SLEW DOES NOT OWN THE OVER-ABSORPTION ... Quartering the slew
+#      from 1000 to 250 does not reduce the over-absorption at all"
+#      asserted as  _R["slower"]["over"] >= _R["live"]["over"]
+#
+# and the reasoning under it was right about the mechanism and therefore wrong
+# about the conclusion: `slew_w` bounds the OUTPUT while the integrator
+# accumulates `gain * error` and is bounded only by `integrator_max_w`, so
+# slowing the slew leaves the integrator winding for LONGER and the
+# over-absorption got WORSE. Measured on this model at release/1.0
+# (`68c5ede`), worst case over the same 51-step family:
+#
+#     slew_w  1000   over-absorbed  1005 W
+#     slew_w     0   (rail, 556)    1109 W      <- SLOWER IS WORSE
+#     slew_w   400                  1285 W
+#     slew_w   250                  1330 W
+#
+# SAFETY-48 bounds the integrator's LEAD at one slew step, which is exactly the
+# quantity that sentence describes. The same six runs on this branch:
+#
+#     slew_w  1000   over-absorbed   729 W
+#     slew_w     0   (rail, 556)      550 W     <- AND NOW SLOWER IS BETTER
+#     slew_w   400                    424 W
+#     slew_w   250                    326 W
+#
+# So the claim is inverted rather than weakened, on a plant model this file
+# writes itself and SAFETY-48's 15.7-day replay of the live install's recorded
+# disturbances has never seen. The two agree on the sign, which is worth more
+# than either alone. ⚠️ The old direction is asserted as a NEGATIVE below so
+# that a revert of SAFETY-48 cannot quietly restore it and leave this section
+# green on the other law.
+#
+# `gain` is still the next constant to re-derive, and SAFETY-48 CHANGED NOTHING
+# ABOUT IT: it is a live control-law constant on a running house, and two of
+# them moving in one release makes the next measurement uninterpretable.
+check("⭐ SAFETY-48: WITH THE INTEGRATOR'S LEAD BOUNDED, A SLOWER SLEW REDUCES "
+      "THE OVER-ABSORPTION - 1000 -> rail -> 400 -> 250 falls monotonically, "
+      f"{_R['live']['over']:.0f} -> {_R['rail']['over']:.0f} -> "
+      f"{_R['interim']['over']:.0f} -> {_R['slower']['over']:.0f} W. On "
+      "release/1.0 the same four runs RISE: 1005 -> 1109 -> 1285 -> 1330 W",
+      _R["rail"]["over"] < _R["live"]["over"]
+      and _R["interim"]["over"] < _R["rail"]["over"]
+      and _R["slower"]["over"] < _R["interim"]["over"])
+check("...and every member of the family over-absorbs LESS than release/1.0's "
+      "own figure for that member - the recorded four are 1005, 1109, 1285 and "
+      "1330 W, taken on 68c5ede by running this file",
+      _R["live"]["over"] < 1005.0 and _R["rail"]["over"] < 1109.0
+      and _R["interim"]["over"] < 1285.0 and _R["slower"]["over"] < 1330.0)
 check("...while the GAIN does own it: 0.6 -> 0.3 -> 0.2 falls monotonically, at "
       "the same slew. That is the measurement behind 'gain is the next constant "
       "to re-derive', and it is a measurement rather than an opinion",

goodwe_controller/test_mqtt.py

@@ -151,6 +151,47 @@ BASELINE = [
     ('goodwe_ctl/availability', 'online', True),
 ]
 
+# --- TEL-10's three, and they are DELIBERATELY NOT IN `BASELINE` -------------
+#
+# ⚠️ `BASELINE` IS WHAT release/1.0 PUBLISHES AND NOTHING MAY BE ADDED TO IT.
+# Every strong claim in this file rests on that list being a record of another
+# tree; append a row this branch invented and "byte-identical to release/1.0"
+# quietly becomes "identical to itself", which is the defect MUTATION.md's
+# habit 4 is about - a check whose data cannot reach the failure it names.
+#
+# So TEL-10's arrival is TWO claims and gets two checks: the nine release/1.0
+# messages did not move, and EXACTLY these three arrived after them.
+#
+# ⚠️ AND THIS LIST IS A REGRESSION PIN, NOT EVIDENCE OF CORRECTNESS - the same
+# status as part 3's sha256 over the per-unit payloads, for the same reason:
+# there is no released version of these bytes to diff against, so all it can
+# say is "these three payloads have not changed since the PR was reviewed".
+_TEL10_NUM = ('"availability_topic": "goodwe_ctl/availability", "device": ' + _DEV
+              + ', "unit_of_measurement": "W", "device_class": "power", '
+                '"state_class": "measurement"}')
+TEL10 = [
+    ('homeassistant/sensor/goodwe_ctl_loop_i/config',
+     '{"name": "Loop integrator", "object_id": "goodwe_loop_integrator", '
+     '"unique_id": "goodwe_ctl_loop_i", "state_topic": "goodwe_ctl/loop_i", '
+     + _TEL10_NUM, True),
+    ('homeassistant/sensor/goodwe_ctl_loop_lead/config',
+     '{"name": "Loop integrator lead", "object_id": "goodwe_loop_integrator_lead", '
+     '"unique_id": "goodwe_ctl_loop_lead", "state_topic": "goodwe_ctl/loop_lead", '
+     + _TEL10_NUM, True),
+    ('homeassistant/sensor/goodwe_ctl_loop_reason/config',
+     '{"name": "Loop reason", "object_id": "goodwe_loop_reason", '
+     '"unique_id": "goodwe_ctl_loop_reason", "state_topic": "goodwe_ctl/loop_reason", '
+     '"availability_topic": "goodwe_ctl/availability", "device": ' + _DEV + ', '
+     '"icon": "mdi:sigma"}', True),
+]
+
+# What THIS branch announces at a roster of one: release/1.0's eight sensor
+# configs, then TEL-10's three, then the availability message - which stays
+# LAST, because `_announce()` publishes it after every config and a broker
+# replaying the retained set must see availability arrive after the entities it
+# is the availability OF.
+SITE_NOW = BASELINE[:-1] + TEL10 + BASELINE[-1:]
+
 
 class FakeClient:
     """Captures what `_announce()` actually hands paho."""
@@ -177,7 +218,7 @@ def announce(units=(), omit=(), module=mqtt):
     return pub.client.msgs
 
 
-def diff(got, want=BASELINE):
+def diff(got, want=SITE_NOW):
     """`(missing, changed, added)` between two announcement lists, by topic."""
     g, w = dict((t, (p, r)) for t, p, r in got), dict((t, (p, r)) for t, p, r in want)
     missing = [t for t in w if t not in g]
@@ -186,7 +227,7 @@ def diff(got, want=BASELINE):
     return sorted(missing), sorted(changed), sorted(added)
 
 
-def report(label, got, want=BASELINE):
+def report(label, got, want=SITE_NOW):
     m, c, a = diff(got, want)
     print(f"    {label}: {len(want)} topics, {len(m)} missing, {len(c)} changed, "
           f"{len(a)} added")
@@ -231,11 +272,33 @@ print("\n1. the recorded baseline, and a roster of one")
 # entity on a live install.
 m, c, a = report("roster of one (`inverters:` empty, i.e. every install today)",
                  announce(units=roster_names({})))
-check("⭐ AT THE SHIPPED ROSTER OF ONE THE ANNOUNCEMENT IS BYTE-IDENTICAL TO "
-      "release/1.0: same topics, same unique_ids, same payload bytes, same "
-      "retain flags, in the same order - no second device, no renamed entity, "
-      "no added topic",
-      (m, c, a) == ([], [], []) and announce(units=roster_names({})) == BASELINE)
+# ⚠️ THE HEADLINE SAYS EIGHT, NOT NINE, AND THE SLICE UNDER IT IS WHY.
+# release/1.0 announces NINE messages; the ninth is `goodwe_ctl/availability`,
+# which `_announce()` publishes LAST and which TEL-10 therefore MOVES - it is
+# byte-identical but no longer at index 8. So what is asserted here is the eight
+# entity CONFIGS, `[:len(BASELINE) - 1] == BASELINE[:-1]`, and the word "nine"
+# above it named an assertion this file does not make. The ninth is not
+# unguarded: the `== SITE_NOW` on the next check pins it byte-for-byte in its
+# new last position. Two sentences, two checks.
+check("⭐ AT THE SHIPPED ROSTER OF ONE EVERY ONE OF release/1.0's EIGHT ENTITY "
+      "CONFIGS IS STILL BYTE-IDENTICAL AND STILL FIRST: same topics, same "
+      "unique_ids, same payload bytes, same retain flags, in the same order - "
+      "no second device, no renamed entity, nothing re-ordered. TEL-10 adds "
+      "rows AFTER them; it may not move one of them. (release/1.0's NINTH "
+      "message, `availability`, is byte-identical too and deliberately moves "
+      "to LAST; the `== SITE_NOW` below is what pins it)",
+      announce(units=roster_names({}))[:len(BASELINE) - 1] == BASELINE[:-1])
+
+# ⚠️ AND THE ADDITION IS ITS OWN CLAIM, WITH A COUNT. "Nothing moved" and
+# "exactly three arrived" are different sentences and a single `== SITE_NOW`
+# would let a fourth row hide inside whichever of the two a reader had in mind.
+_m1, _c1, _a1 = diff(announce(units=roster_names({})), BASELINE)
+check("⭐ TEL-10 ADDS EXACTLY THREE TOPICS AND CHANGES NONE: the integrator, "
+      "the lead and the loop's own reason string, all NEW, all on the SITE "
+      "device - nothing of release/1.0's is missing and nothing of it changed",
+      (_m1, _c1) == ([], [])
+      and sorted(_a1) == sorted(t for t, _p, _r in TEL10)
+      and announce(units=roster_names({})) == SITE_NOW)
 
 check("...and the roster-of-one path is the one every install actually reads: "
       "an empty `inverters:` names exactly one unit",
@@ -244,11 +307,11 @@ check("...and the roster-of-one path is the one every install actually reads: "
 check("...and a publisher told NOTHING about the roster announces the same "
       "thing, so a caller that has not been taught about units cannot change "
       "what a live install sees",
-      announce(units=()) == BASELINE)
+      announce(units=()) == SITE_NOW)
 
 m, c, a = report("roster of one, P1 off (`omit=('p1_age',)`)",
                  announce(units=roster_names({}), omit=("p1_age",)),
-                 [row for row in BASELINE if "p1_age" not in row[0]])
+                 [row for row in SITE_NOW if "p1_age" not in row[0]])
 check("...and the `omit` path is unchanged too: with P1 ingestion off the "
       "watchdog input is still not announced, and nothing else moved",
       (m, c, a) == ([], [], []))
@@ -280,11 +343,18 @@ check("⭐ AC 1: AT A ROSTER OF TWO, EVERY ONE OF A's NINE MESSAGES IS STILL "
       (m, c) == ([], []))
 check("...and the eight additions are all B's and A's own per-unit rows, and "
       "all of them are NEW topics", len(a) == 8)
-check("...and A's nine messages are still the FIRST nine, in the same order, "
-      "so a broker replaying retained messages sees them unchanged",
+check("...and A's eight entity configs are still the FIRST eight, in the same "
+      "order, so a broker replaying retained messages sees them unchanged "
+      "(the ninth, `availability`, is byte-identical and last - the check "
+      "above is the one that covers it, as a diff rather than a prefix)",
       TWO[:len(BASELINE) - 1] == BASELINE[:-1])
 
-site_ids = {c_["unique_id"] for c_ in cfgs(BASELINE)}
+# ⚠️ THE SITE SET IS `SITE_NOW`, NOT `BASELINE`. Read from `BASELINE` it would
+# be short by TEL-10's three, and those three would then be counted as PER-UNIT
+# rows by every line below that says "not a site id" - which silently changes
+# what the sha256 pin, the uniqueness checks and part 7's fed/announced set are
+# taken over.
+site_ids = {c_["unique_id"] for c_ in cfgs(SITE_NOW)}
 unit_cfgs = [c_ for c_ in cfgs(TWO) if c_["unique_id"] not in site_ids]
 a_cfgs = [c_ for c_ in unit_cfgs if "inverter_a" in c_["unique_id"]]
 b_cfgs = [c_ for c_ in unit_cfgs if "inverter_b" in c_["unique_id"]]
@@ -330,7 +400,7 @@ def field(rows, key):
 
 for key in ("unique_id", "object_id", "state_topic"):
     av, bv = set(field(a_cfgs, key)), set(field(b_cfgs, key))
-    sv = set(field(cfgs(BASELINE), key))
+    sv = set(field(cfgs(SITE_NOW), key))
     check(f"⭐ AC 2: no `{key}` is shared between A's entities and B's, and "
           f"none of B's collides with a SITE entity that already exists",
           len(av) == 4 and len(bv) == 4 and not (av & bv) and not (bv & sv)
@@ -340,10 +410,10 @@ all_ids = field(cfgs(TWO), "unique_id")
 check("...and across the WHOLE announcement every unique_id is distinct - an "
       "HA discovery collision is not an error, it DROPS the second entity, so "
       "one inverter's telemetry would silently stop existing",
-      len(all_ids) == len(set(all_ids)) == 16)
+      len(all_ids) == len(set(all_ids)) == 19)
 
 all_topics = [t for t, _, _ in TWO]
-check("...and so is every topic", len(all_topics) == len(set(all_topics)) == 17)
+check("...and so is every topic", len(all_topics) == len(set(all_topics)) == 20)
 
 # ⚠️ THE SLUG COLLISION rule 9(c) DOES NOT REFUSE. `inverter-b` and `Inverter B`
 # are two different names by the validator's test and one string once slugged.
@@ -363,8 +433,14 @@ print("\n5. site-scoped sensors stay site-scoped")
 # firmware's ingest guard). A second copy of it is a second answer to "is the
 # meter fresh?", one of which is always the one nobody is looking at. `grid` is
 # the same argument without the safety edge: there is ONE grid connection.
+# ⚠️ TEL-10's THREE ARE IN HERE, AND THE ARGUMENT IS `grid`'s. There is ONE
+# integrator - §6.2's architecture is one integrator on the P1 meter whose
+# output is then SPLIT - so a per-inverter copy of it would invent N of a thing
+# there is one of, and two of them would disagree the moment the allocator gave
+# the units different shares.
 SITE_ONLY = ("goodwe_ctl_grid", "goodwe_ctl_p1_age", "goodwe_ctl_circulation",
-             "goodwe_ctl_phase", "goodwe_ctl_status")
+             "goodwe_ctl_phase", "goodwe_ctl_status",
+             "goodwe_ctl_loop_i", "goodwe_ctl_loop_lead", "goodwe_ctl_loop_reason")
 rows = []
 for n in range(1, 7):
     names = [f"inverter-{chr(ord('a') + i)}" for i in range(n)]
@@ -377,8 +453,8 @@ check("⭐ AC 3: `grid` and `p1_sample_age_s` are announced EXACTLY ONCE at ever
       "two of a thing there is one of, and would duplicate a safety signal",
       all(counts == [1] * len(SITE_ONLY) for _n, counts, _t in rows))
 check("...and the site set does not grow with the roster while the per-unit "
-      "set does: 8 site entities always, 4 more per unit past the first",
-      [t for _n, _c, t in rows] == [8, 16, 20, 24, 28, 32])
+      "set does: 11 site entities always, 4 more per unit past the first",
+      [t for _n, _c, t in rows] == [11, 19, 23, 27, 31, 35])
 
 site_devices = {json.dumps(c_["device"], sort_keys=True)
                 for c_ in cfgs(announce(units=NAMES2))
@@ -420,7 +496,7 @@ for c_, eid in zip(cfgs(TWO), composed):
           f"name {c_['name']!r}")
 check("⭐ every composed entity_id at a roster of two is DISTINCT: no per-unit "
       "entity can land on top of a site entity that already has history",
-      len(composed) == len(set(composed)) == 16)
+      len(composed) == len(set(composed)) == 19)
 
 base_composed = [compose(c_["device"]["name"], c_["name"]) for c_ in cfgs(BASELINE)]
 check("...and the eight ids that exist today are unchanged by adding B, which "
@@ -620,9 +696,9 @@ def properties(mod):
         bc = [c_ for c_ in uc if "inverter_b" in c_["unique_id"]]
         ac = [c_ for c_ in uc if "inverter_a" in c_["unique_id"]]
         comp = [compose(c_["device"]["name"], c_["name"]) for c_ in tc]
-        out["A byte-identical at N=1"] = base == BASELINE
+        out["A byte-identical at N=1"] = base == SITE_NOW
         out["A byte-identical at N=2"] = diff(two)[:2] == ([], [])
-        out["N=1 adds no topic"] = len(base) == len(none) == len(BASELINE)
+        out["N=1 adds no topic"] = len(base) == len(none) == len(SITE_NOW)
         out["unique_ids all distinct"] = (
             len(set(c_["unique_id"] for c_ in tc)) == len(tc))
         out["slug-alike names still distinct"] = (
@@ -703,6 +779,25 @@ MUTATIONS = [
        '    ("grid", "grid_power", "Grid power", "W", "power", "measurement", None),\n')]),
     ("B's device drops `via_device`",
      [('        "via_device": DEVICE["identifiers"][0],\n', "")]),
+    # --- TEL-10 ------------------------------------------------------------
+    ("TEL-10's integrator row is DROPPED (published to a topic nothing "
+     "announced, which AC 4 forbids in the other direction)",
+     [('    ("loop_i", "goodwe_loop_integrator", "Loop integrator", "W", "power", "measurement", None),\n', "")]),
+    ("TEL-10's integrator is announced PER INVERTER - two answers to a "
+     "question §6.2 says there is one integrator for",
+     [('    ("sign_latch", "sign_latch", "Sign latch", None, None, None, "mdi:flash-alert"),\n',
+       '    ("sign_latch", "sign_latch", "Sign latch", None, None, None, "mdi:flash-alert"),\n'
+       '    ("loop_i", "loop_integrator", "Loop integrator", "W", "power", "measurement", None),\n')]),
+    # ⚠️ THE ONE THAT CHANGES NO BYTE OF ANY PAYLOAD. Every id, name, unit and
+    # topic is identical; only the POSITION of the integrator row moves. A
+    # broker replaying the retained set then hands HA a different sequence, and
+    # part 1's claim is about order as much as about bytes - which is why it is
+    # asserted as a LIST and not as a set.
+    ("TEL-10's integrator row is announced BEFORE release/1.0's nine",
+     [('    ("loop_i", "goodwe_loop_integrator", "Loop integrator", "W", "power", "measurement", None),\n', ""),
+      ('    ("setpoint", "goodwe_setpoint", "Setpoint", "W", "power", "measurement", None),\n',
+       '    ("loop_i", "goodwe_loop_integrator", "Loop integrator", "W", "power", "measurement", None),\n'
+       '    ("setpoint", "goodwe_setpoint", "Setpoint", "W", "power", "measurement", None),\n')]),
 ]
 
 survivors = []
@@ -757,11 +852,13 @@ for line in [
     "resolve it, because it renames no device and no entity, and the byte-diff "
     "protects both spellings equally. SIZE: unresolved, 8 live entity ids; it "
     "wants one look at the live registry, which this branch must not take.",
-    "3. THE PER-UNIT PAYLOADS HAVE NO RELEASED BASELINE. A's are diffed against "
-    "release/1.0; B's can only be diffed against this branch (the sha256 pin in "
-    "part 3). A wrong `device_class` or unit on a per-unit sensor is therefore "
-    "caught as a CHANGE from review, not as an error. SIZE: 4 sensors x 4 "
-    "optional fields.",
+    "3. THE PER-UNIT PAYLOADS HAVE NO RELEASED BASELINE, AND NEITHER DO "
+    "TEL-10's THREE. A's are diffed against release/1.0; B's can only be "
+    "diffed against this branch (the sha256 pin in part 3), and `TEL10` above "
+    "is the same kind of pin for the three site rows this branch adds. A wrong "
+    "`device_class` or unit on any of them is therefore caught as a CHANGE "
+    "from review, not as an error. SIZE: 4 per-unit sensors x 4 optional "
+    "fields, plus 3 site sensors x 4.",
     "4. NO CHECK HERE RUNS A BROKER. `_announce()` is graded through a fake "
     "paho client, so QoS, retain semantics on a real broker, and what HA does "
     "with a retained config for a device it has never seen are all out of "

goodwe_controller/test_telemetry.py

@@ -0,0 +1,575 @@
+"""Runnable check for TEL-10 and SAFETY-48.  `python3 test_telemetry.py`
+
+TEL-10 publishes the loop's integrator. SAFETY-48 bounds it. They are graded in
+one file because they are one observable: the number SAFETY-48 bounds is the
+number TEL-10 added, and a check on either that could not see the other would
+be grading its own fixture.
+
+`self.i_w` is carried between cycles of `Controller.cycle()` and, before this
+card, left the process nowhere at all - no entity, no MQTT attribute, no log
+line. The last investigation into what it does had to RECONSTRUCT it from the
+grid trace; the reconstruction reproduced about a third of the engagements it
+was checked against and was discarded.
+
+⚠️ WHAT THIS FILE REFUSES TO DO, SAID FIRST. It does not assert that a row
+EXISTS. `publish()` handing a dict with `loop_i` in it is satisfied by
+`loop_i: 0.0` forever, by `loop_i: setpoint`, and by a row that reports the
+command under the integrator's name - which is exactly the confusion the card
+is about, because on a default install the two are within a quantisation step
+of each other for most of every day. Every check below therefore drives REAL
+CYCLES through the real `Controller.cycle()` until the two quantities are
+MEASURABLY DIFFERENT, and grades the published number at a tick where reading
+the wrong one gives the wrong answer. MUTATION.md habit 4.
+
+VERIFIED BY BREAKING IT. Every check below was driven by the mutation that
+defeats the claim it names, in the CI image, on a tree purged of `__pycache__`
+before each run, with the file's sha256 taken before, after, and again after
+the revert (MUTATION.md's reporting rules, and habit 18's unique backup path).
+
+  #   mutation                                        bytes  reds  file
+  --  ----------------------------------------------  -----  ----  -----------
+  M1  `self.loop_i_w = loop_prev` - publish the         -3 B    5   this file
+      COMMAND under the integrator's name
+  M2  `decision.i_w - self.target` for the lead         +2 B    0   SURVIVOR
+  M2b `decision.i_w - decision.target_w` for the lead   +8 B    1   this file
+  M3  `"loop_reason": self.reason` - the ARBITER's      -5 B    5   this file
+      sentence in the loop's row
+  M4  delete `self.loop_reason = "not-running"`        -45 B    1   this file
+  M5  delete the not-running branch's two zeroes       -67 B    1   this file
+  M6  `"loop_i": round(self.target, 1)`                 -2 B    4   this file
+  M7  the `loop_i` row deleted from `SENSORS`          -96 B 10+1   test_mqtt
+                                                                      + this file
+  M8  `loop_i` announced PER INVERTER                  +89 B    8   test_mqtt
+  M9  `loop_i` announced BEFORE release/1.0's nine      +0 B    7   test_mqtt
+
+⚠️ A RED COUNT IS A PROPERTY OF THE SUITE AS MUCH AS OF THE MUTATION, SO EVERY
+ONE ABOVE NAMES A TREE - this one, at this commit. A later card that adds a
+check, re-baselines one or deletes one moves the number with the mutation
+untouched. Re-measure rather than inherit: `tools/mutation_run.sh` on a `cp -a`
+of the tree, one file at a time, and say which tree. M7's count was written as
+8 and is 10 on a re-run, on both trees - the direction was right and the count
+was decoration, which is the half of MUTATION.md's reporting rule 3 that is
+easiest to let rot.
+
+⚠️ AND SAFETY-48 HAS ALREADY MOVED ONE OF THEM. M1 defeats FIVE checks on
+TEL-10's own tree and FOUR on this one: this card replaced the "...the gap is
+the slew limit and not an accident" check, because the gap it asserted is now
+bounded and the assertion is written against the bound instead. The mutation
+did not change; the suite did. Both counts are right, for different trees, and
+neither is right without one.
+
+⚠️ M9 IS ZERO BYTES AND CHANGES NO PAYLOAD. Every id, name, unit and topic is
+identical; only the ORDER of the retained messages moves. No fingerprint and no
+byte delta can see it, which is why part 1 asserts the announcement as an
+ordered LIST and not as a set.
+
+⚠️ M2 IS A REAL SURVIVOR AND IS REPORTED AS ONE. At the line it edits,
+`loop_prev` and `self.target` are the same value: `cycle()` does not reassign
+`self.target` until `self.target = resolution.target_w`, further down. The
+mutation therefore changes nothing that runs, on a purged tree, which is not
+the direction stale bytecode fabricates. `loop_prev` is kept anyway - it is the
+name the `compute()` call is made with, so the lead cannot be measured against
+a different cycle's command by anybody moving a line - and M2b is the mutation
+that DOES change the value, aimed at exactly that.
+
+⚠️ AND THE FIRST DRAFT OF THIS FILE HAD TWO CHECKS OF ITS OWN THAT COULD NOT
+REACH THE FAILURE THEY NAMED. Both are MUTATION.md habit 4:
+
+  * "the published integrator reaches its bound" was GREEN under M1, because
+    the command reaches the bound too - twelve cycles later. The check now
+    asserts the LEAD TIME, not the value.
+  * "a stopped controller publishes `not-running`" was GREEN under M4 and M5,
+    because the fixture STARTED stopped and `__init__` writes the same values.
+    It stops the controller part-way through a run that has already wound the
+    integrator to -5000 W, so a row left standing is a WRONG row.
+
+SAFETY-48's OWN BATTERY, same discipline, against `app/control.py`:
+
+  #   mutation                                        bytes  reds
+  --  ----------------------------------------------  -----  --------------------
+  L1  the whole SAFETY-48 block deleted              -195 B  5 here + 4 control
+  L2  `SLEW_LEAD_STEPS = 0` - the velocity form        +0 B  4 here + 3 control
+  L3  `SLEW_LEAD_STEPS = 12` - a cap above the rail    +1 B  4 here + 3 control
+  L4  the cap applied unconditionally, outside the   -92 B  1 here   ⚠️ SURVIVOR
+      slew branch                                             of all 30 files
+                                                              until part 4's
+                                                              `integrator_max_w`
+                                                              case existed
+  L5  `min`/`max` swapped - the cap on the wrong      +0 B  5 here + 5 control
+      side                                                  (or 5 + 4; see below)
+  L6  the lead measured against `prev_w` rather than  +0 B  6 here + 3 control
+      the command it emits
+
+⚠️ L4, L5 AND L6 ARE ALL ZERO- OR NEGATIVE-BYTE EDITS THAT CHANGE NO PAYLOAD
+AND NO OPTION, AND L4 WAS BIT-IDENTICAL ON THE SHIPPED CONFIGURATION - 0 of
+256 246 ticks over the 16-day recording. It is separable only where
+`integrator_max_w` is above `max_w`, which is the stimulus part 4 drives; the
+COUNT of separable states is a property of whatever grid was swept and three
+sweeps disagree about it, so DECISIONS/SAFETY-48 §4 carries all three rather
+than one.
+
+⚠️ AND L5 IS TWO MUTATIONS WEARING ONE NAME, WHICH IS WHY ITS COUNT NEEDS A
+SPELLING BESIDE IT. "min/max swapped" can mean the FUNCTION names exchanged
+(`max(i_w, slewed + cap)` / `min(i_w, slewed - cap)`) - 5 here + 5 in
+test_control.py, one of the five being SAFETY-13's own "frozen integrator never
+deadlocks" sweep over 13 041 states - or the whole BRANCH bodies exchanged
+(`max(i_w, slewed - cap)` / `min(i_w, slewed + cap)`), which is 5 + 4 and does
+NOT reach the deadlock sweep. Both are red, both are the cap on the wrong side,
+and a table that writes one number for the pair is reporting a mutation nobody
+can re-run. The first spelling is the one the row above quotes.
+
+⚠️ MUTATING THE MODULE THIS FILE GRADES? PURGE `__pycache__` FIRST - or run
+`tools/mutation_run.sh`, which does. `python3 -B` alone does NOT save you: it
+stops bytecode being WRITTEN, not a stale one being READ, and a size-preserving
+edit reverted inside one second is invisible to CPython's staleness test. That
+is TEST-15, and it has already turned one live mutation into a false survivor.
+Read MUTATION.md before you report a survivor.
+"""
+
+import asyncio
+import sys
+
+from app import mqtt
+from app.control import SLEW_LEAD_STEPS, Tuning, compute, slew_limit_w
+from app.main import Controller
+
+fails = []
+
+# The live install's shape, and every number in it is measured rather than
+# chosen: `max_w` and `slew_w` are read straight off the recorder (the setpoint
+# sensor's extremes are exactly +-5000 and 11 226 recorded steps are exactly
+# 400 W), `gain` and `target_grid_w` are what the options carry.
+LIVE = {"max_w": 5000.0, "gain": 0.6, "slew_w": 400.0, "target_grid_w": -10.0,
+        "deadband_w": 15, "step_w": 10}
+# The integrator's bound on a default install: `integrator_max_w` is None, which
+# control.py resolves to `max_w`. Written as a literal on purpose (habit 2) -
+# `== c.tuning.max_w` would compare the thing under test against itself.
+BOUND_W = 5000.0
+# `slew_w / gain`: the error above which the integrator moves further in one
+# cycle than the command is allowed to. 400 / 0.6.
+OUTRUN_W = 666.67
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+class _Store:
+    def __init__(self):
+        self.data = {}
+
+    def set(self, *a):
+        pass
+
+    def get_time(self, *a):
+        return None
+
+
+class _Pub:
+    """Captures what `Controller.publish()` hands the publisher, every cycle."""
+
+    enabled = False
+
+    def __init__(self):
+        self.frames = []
+
+    def publish(self, values):
+        self.frames.append(dict(values))
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    """A scripted meter and an inverter that follows what it is told.
+
+    ⚠️ THE PLANT FOLLOWS EXACTLY AND WITH NO LAG, WHICH IS DELIBERATE AND IS
+    THE HARDER CASE FOR EVERY CHECK HERE. A lagging inverter trips the
+    SATURATION freeze (`|prev_w - actual_w| > saturation_w`), and the
+    saturation freeze already holds the integrator - so a laggy fixture would
+    let SAFETY-13's mechanism pass for SAFETY-48's. Nothing below may be
+    explained by saturation, and part 4 asserts `frozen` is False throughout.
+    """
+
+    def __init__(self, grid, soc=50.0):
+        self.grid_seq = grid if callable(grid) else (lambda _n: grid)
+        self.soc = soc
+        self.batt = 0.0
+        self.n = 0
+        self.writes = []
+        self.calls = []
+
+    async def limits(self, entity):
+        return (-LIVE["max_w"], LIVE["max_w"], 1.0)
+
+    async def number(self, entity, invert=False):
+        return {"sensor.grid": self.grid_seq(self.n), "sensor.soc": self.soc,
+                "sensor.batt": self.batt}.get(entity)
+
+    async def set_number(self, entity, value):
+        self.writes.append(float(value))
+        self.batt = float(value)
+        return True
+
+    async def call(self, domain, service, data):
+        self.calls.append((domain, service, data))
+        return True
+
+
+def run(grid, cycles=30, auto=True, stop_after=None, **over):
+    """`cycles` real `Controller.cycle()`s, and every published frame.
+
+    `stop_after` presses stop part-way through - which is not the same run as
+    starting stopped, and is the only one that can tell a row that was WRITTEN
+    on the not-running branch from a row that was never written at all.
+    """
+    async def go():
+        hass = _Hass(grid)
+        pub = _Pub()
+        c = Controller(dict(
+            {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+             "meter_source": "off", "heartbeat_s": 10, "stale_input_s": 15},
+            **LIVE, **over),
+            hass, _Store(), pub, stop=asyncio.Event())
+        c.auto = auto
+        c.dev_min, c.dev_max = -LIVE["max_w"], LIVE["max_w"]
+        for k in range(cycles):
+            if stop_after is not None and k == stop_after:
+                c.auto = False
+            await c.read_inputs()
+            await c.cycle()
+            c.publish()
+            hass.n += 1
+        return c, hass, pub.frames
+    return asyncio.run(go())
+
+
+# ==============================================================================
+print("1. TEL-10: the integrator is published, and it is NOT the command")
+# ==============================================================================
+# A standing 6 kW export against a 5 kW rail and a 400 W slew step.
+#
+# ⚠️ THIS FIXTURE WAS BUILT AGAINST THE UNBOUNDED INTEGRATOR AND SAFETY-48 TOOK
+# ITS SEPARATION AWAY, WHICH IS WORTH SAYING RATHER THAN QUIETLY RE-TUNING. On
+# the law TEL-10 shipped against, the integrator reached its 5000 W bound on
+# cycle 1 and the command needed twelve more cycles to arrive, so the two rows
+# differed by KILOWATTS and any check at all could see it. SAFETY-48 bounds the
+# lead at one slew step, so the gap is now 800 W and the integrator arrives ONE
+# cycle early instead of twelve. Both surviving separations are graded: the
+# ARRIVAL ORDER, and the 800 W plateau that holds for the whole ramp.
+ctl, hass, frames = run(-6000.0, cycles=30)
+i_row = [f["loop_i"] for f in frames]
+sp_row = [f["setpoint"] for f in frames]
+lead_row = [f["loop_lead"] for f in frames]
+why_row = [f["loop_reason"] for f in frames]
+print("    cycle  loop_i   setpoint  loop_lead  loop_reason")
+for k in range(8):
+    print(f"      {k:<5d}{i_row[k]:8.0f} {sp_row[k]:9.0f} {lead_row[k]:10.0f}"
+          f"  {why_row[k]}")
+
+first_at_bound = next((k for k, v in enumerate(i_row) if abs(v) >= BOUND_W), None)
+first_cmd_at_bound = next((k for k, v in enumerate(sp_row) if abs(v) >= BOUND_W),
+                          len(sp_row))
+print(f"    the integrator reaches {-BOUND_W:.0f} W at cycle "
+      f"{first_at_bound}; the command reaches it at cycle "
+      f"{first_cmd_at_bound}")
+
+# ⚠️ THE ARRIVAL ORDER IS THE CLAIM, NOT THE VALUE. "The published number
+# reaches the bound" is satisfied by publishing the COMMAND too - it gets there
+# as well, a cycle later - so a check written on the value alone grades nothing
+# and the mutation that publishes `prev_w` walks straight through it. Measured:
+# with `self.loop_i_w = loop_prev` the value-only form was GREEN and this one is
+# red.
+check("⭐ THE PUBLISHED INTEGRATOR REACHES ITS BOUND, AND REACHES IT BEFORE THE "
+      f"COMMAND DOES. A 6 kW export winds it to exactly {BOUND_W:.0f} W - "
+      "`integrator_max_w` is None, which control.py resolves to `max_w` - while "
+      "the command is still a slew step short",
+      first_at_bound is not None and i_row[first_at_bound] == -BOUND_W
+      and first_cmd_at_bound > first_at_bound)
+
+# ⚠️ THE PRECONDITION, AS ITS OWN CHECK (habit 1). If the command happened to be
+# at the bound too, the line above would be satisfied by publishing EITHER
+# number and would be grading nothing.
+check("...and the command is NOT at the bound at that tick, so the two are "
+      f"separable: setpoint {sp_row[first_at_bound]:.0f} W against an "
+      f"integrator of {i_row[first_at_bound]:.0f} W",
+      abs(BOUND_W - abs(sp_row[first_at_bound])) >= 200.0)
+
+# ⚠️ AND THE PLATEAU, WHICH IS THE SEPARATION THAT LASTS. Through the whole
+# ramp the integrator stands exactly two slew steps ahead of the command the
+# previous cycle left standing - one step is `SLEW_LEAD_STEPS` against the
+# command this cycle EMITS, and the emitted command is itself one step ahead of
+# `prev_w`. It is graded as a RUN of identical values rather than as a maximum,
+# because a maximum is reached by one tick and a plateau is the shape.
+_plateau = [k for k in range(1, 13) if lead_row[k] == -800.0]
+print(f"    the lead plateau: {lead_row[1:13]}")
+check("⭐ AND THE TWO ROWS ARE SEPARATED FOR THE WHOLE RAMP, not at one tick: "
+      f"the lead sits at exactly -800 W (two slew steps) on "
+      f"{len(_plateau)} of cycles 1..12 while both numbers travel 400 W a "
+      "cycle", len(_plateau) >= 8)
+check("...and the command really is travelling a full slew step a cycle "
+      "through that plateau, so the plateau is not a stalled loop",
+      all(round(abs(sp_row[k] - sp_row[k - 1]), 6)
+          == slew_limit_w(Tuning(**LIVE)) for k in _plateau))
+
+# The lead is `i_w - prev_w`, and `prev_w` is the command the LAST cycle left
+# standing - which is the setpoint this file captured one frame earlier. Graded
+# as that identity rather than as a magnitude, because a magnitude cannot tell
+# a lead from the integrator itself.
+ident = [k for k in range(1, 12)
+         if round(lead_row[k], 1) != round(i_row[k] - sp_row[k - 1], 1)]
+check("⭐ AND `loop_lead` IS THE INTEGRATOR MINUS THE COMMAND IT WAS COMPUTED "
+      "AGAINST - the PREVIOUS cycle's setpoint, not this one's. Checked as an "
+      f"identity over cycles 1..11 ({len(ident)} disagreements)", not ident)
+check("...and it is never a permanent zero while the loop is working: worst "
+      f"lead {min(lead_row):.0f} W",
+      min(lead_row) <= -800.0)
+
+
+# ==============================================================================
+print()
+print("2. TEL-10: the reason row is compute()'s OWN word, not the arbiter's")
+# ==============================================================================
+# ⚠️ THE TWO SENTENCES EXIST SIDE BY SIDE AND ONE OF THEM ALREADY HAD A ROW.
+# `self.reason` is `Resolution.explain()` - "loop -> -800 W" - and it prints the
+# winning claim's NAME, never the claim's reason. So a publisher wired to
+# `self.reason` would produce a row that is never wrong-looking and never once
+# says `slew-limited`, which is the value SAFETY-48 is about.
+print(f"    the arbiter's sentence: {ctl.reason!r}")
+print(f"    the loop's own word   : {ctl.loop_reason!r}")
+check("⭐ THE LOOP'S REASON REACHES THE WIRE, and on a slew-limited cycle it is "
+      "the string `slew-limited` - a value the arbiter's sentence does not "
+      "contain at all",
+      "slew-limited" in why_row and "slew-limited" not in ctl.reason)
+check("...and the two rows are DIFFERENT STRINGS on the same cycle, so one "
+      "cannot have been published from the other",
+      frames[-1]["loop_reason"] != ctl.reason)
+check("...and every published reason is one `compute()` can actually produce",
+      set(why_row) <= {"tracking", "deadband", "i-clamped", "clamped",
+                       "slew-limited", "saturated-freeze", "freeze-released",
+                       "not-running"})
+
+# A converged site: the error is inside the deadband and the law says so.
+calm = run(-10.0, cycles=6)[2]
+check("...and a site resting inside the deadband publishes `deadband`, not the "
+      "last exciting word the loop said", calm[-1]["loop_reason"] == "deadband")
+
+# ⚠️ THE NOT-RUNNING PATH IS A DIFFERENT BRANCH OF `cycle()` AND IS GRADED AS
+# ONE (habit 9). That branch zeroes `self.i_w`, so a row that kept repeating the
+# last integrator there would say the loop was winding while nothing is being
+# controlled at all.
+#
+# ⚠️ AND `auto: False` IS NOT THAT BRANCH, WHICH IS WHY BOTH ARE HERE. The
+# shipped `shadow_mode: auto` means a STOPPED controller still runs the whole
+# decision path and records it - SAFETY-10 - so the loop is live, the
+# integrator is real, and a check that assumed otherwise would have been
+# asserting `not-running` about a loop that was running. It took `auto: False`
+# AND `shadow_mode: off` to reach the arm that zeroes it.
+shadowed = run(-6000.0, cycles=6, auto=False)[2]
+print(f"    stopped, shadow_mode auto: status {shadowed[-1]['status']!r}, "
+      f"loop_i {shadowed[-1]['loop_i']:+.0f} W, "
+      f"reason {shadowed[-1]['loop_reason']!r}")
+check("a STOPPED controller in shadow mode still publishes a live integrator - "
+      "the decision path runs, so the row must report it rather than a zero "
+      "that would read as 'nothing is winding'",
+      shadowed[-1]["status"] == "shadow"
+      and shadowed[-1]["loop_i"] < -100.0
+      and shadowed[-1]["loop_reason"] != "not-running")
+
+# ⚠️ AND IT IS STOPPED PART-WAY, NOT STARTED STOPPED, WHICH IS THE WHOLE
+# DIFFERENCE. A controller that never ran carries `__init__`'s values, so a run
+# that begins stopped is satisfied by a branch that writes NOTHING - measured:
+# deleting `self.loop_reason = "not-running"` from `cycle()` outright was a
+# -45 B SURVIVOR of the first draft of this check. The loop has to wind first,
+# so that a row left standing is a row that says the wrong thing.
+stopped = run(-6000.0, cycles=12, stop_after=6, shadow_mode="off")[2]
+print(f"    while running  : loop_i {stopped[5]['loop_i']:+.0f} W, "
+      f"reason {stopped[5]['loop_reason']!r}, status {stopped[5]['status']!r}")
+print(f"    after stopping : loop_i {stopped[-1]['loop_i']:+.0f} W, "
+      f"reason {stopped[-1]['loop_reason']!r}, status {stopped[-1]['status']!r}")
+check("...and the precondition: the loop really was winding before stop was "
+      "pressed, so a stale row afterwards would be a WRONG row and not merely "
+      "an unset one",
+      stopped[5]["loop_i"] <= -1000.0
+      and stopped[5]["loop_reason"] != "not-running")
+check("⭐ AND ONCE THE DECISION PATH IS GENUINELY OFF THE ROWS SAY SO: "
+      "`not-running` and a zero integrator - the same zero `cycle()` writes to "
+      "`self.i_w` on that branch, not the number it was carrying a cycle ago",
+      stopped[-1]["status"] == "stopped"
+      and stopped[-1]["loop_reason"] == "not-running"
+      and stopped[-1]["loop_i"] == 0.0 and stopped[-1]["loop_lead"] == 0.0)
+
+
+# ==============================================================================
+print()
+print("3. TEL-10: announced and published are the same three topics")
+# ==============================================================================
+# mqtt.py's `omit` note: an entity that exists and is never fed is a worse
+# signal than one that does not exist. This is that claim for TEL-10's rows,
+# taken off the SHIPPED announcement and the SHIPPED `publish()`.
+announced = {t.rsplit("/", 2)[-2].replace(f"{mqtt.BASE}_", "")
+             for t, _ in mqtt.discovery_payloads()}
+published = set(frames[-1])
+TEL10 = {"loop_i", "loop_lead", "loop_reason"}
+print(f"    announced keys: {sorted(announced & TEL10)}")
+print(f"    published keys: {sorted(published & TEL10)}")
+check("all three rows are announced AND published - no entity nothing feeds, "
+      "no topic nothing declared",
+      TEL10 <= announced and TEL10 <= published)
+check("...and they are on the SITE device, not per unit - there is one "
+      "integrator",
+      all(c["device"] == mqtt.DEVICE
+          for t, c in mqtt.discovery_payloads(["inverter-a", "inverter-b"])
+          if c["unique_id"].replace(f"{mqtt.BASE}_", "") in TEL10))
+# ==============================================================================
+print()
+print("4. SAFETY-48: the slew step ceiling stops the integrator outrunning it")
+# ==============================================================================
+# ⚠️ THE ARITHMETIC THE CARD IS ABOUT, RE-DERIVED RATHER THAN QUOTED. The
+# integrator moves `gain * error` a cycle and the command moves at most
+# `slew_w`, so the integrator outruns the command whenever
+# `|error| > slew_w / gain`. At the live shape that is 667 W, and the recorded
+# median error at the onset of an episode is 1114 W.
+T = Tuning(**LIVE)
+check(f"the outrun threshold is `slew_w / gain` = {OUTRUN_W:.0f} W, and it is "
+      "the shipped pair that produces it, not a constant written here",
+      abs(T.slew_w / T.gain - OUTRUN_W) < 0.5)
+
+# ⚠️ TWO LEADS, AND CONFUSING THEM IS HOW THIS CHECK WOULD BE WRITTEN WRONG.
+# The bound is on `i_w - target`, the command this cycle EMITS - that is what
+# makes the unwind one cycle, because the command can cover one slew step in
+# one cycle. `loop_lead`, and `Decision.i_w - prev_w`, are measured against the
+# command the PREVIOUS cycle left standing, and the emitted command is itself
+# one slew step further on - so the published figure is bounded by TWO steps,
+# not one. Both are asserted, against their own bound.
+_SLEW = slew_limit_w(T)
+d = compute(prev_w=0.0, grid_w=-6000.0, actual_w=0.0, tuning=T, i_w=-100.0)
+print(f"    one cycle at a 5990 W error: command {d.target_w:+.0f} W, "
+      f"integrator {d.i_w:+.0f} W, ahead of the EMITTED command by "
+      f"{d.i_w - d.target_w:+.0f} W and of `prev_w` by {d.i_w:+.0f} W, "
+      f"reason {d.reason!r}")
+check(f"⭐ THE INTEGRATOR MAY LEAD THE COMMAND IT EMITS BY AT MOST "
+      f"{SLEW_LEAD_STEPS} x slew_w = {SLEW_LEAD_STEPS * _SLEW:.0f} W - so the "
+      "worst-case unwind is ONE cycle, not `integrator_max_w / slew_w` (12.5 "
+      "at this shape)",
+      abs(d.i_w - d.target_w) <= SLEW_LEAD_STEPS * _SLEW + 1e-9)
+
+# ...and over a real run, which is where release/1.0 walks to the rail.
+leads = [abs(f["loop_lead"]) for f in frames]
+print(f"    over {len(frames)} driven cycles: worst published lead "
+      f"{max(leads):.0f} W, worst integrator {min(i_row):.0f} W")
+check(f"⭐ AND IT HOLDS ON EVERY DRIVEN CYCLE: the published lead - measured "
+      f"against the PREVIOUS command - never exceeds "
+      f"{(SLEW_LEAD_STEPS + 1) * _SLEW:.0f} W, one step for the bound and one "
+      "for the step the command took. On release/1.0 this same run reaches "
+      "4600 W",
+      max(leads) <= (SLEW_LEAD_STEPS + 1) * _SLEW + 1e-9)
+check("...and release/1.0's figure is not merely larger, it is over the bound: "
+      "the run that produced 4600 W here would be red on the line above",
+      4600.0 > (SLEW_LEAD_STEPS + 1) * _SLEW)
+check("...and nothing here is the SATURATION freeze doing SAFETY-48's work: "
+      "the inverter tracks exactly, so `frozen` is never true",
+      not any(f["loop_reason"] in ("saturated-freeze", "freeze-released")
+              for f in frames))
+
+# ⚠️ AND THE CAP IS NOT ZERO, WHICH IS ITS OWN CHECK BECAUSE NOTHING ELSE
+# NOTICES. `i_w = slewed` - a cap of zero - satisfies every bound above and is
+# what control.py's docstring calls "the exact velocity form it replaced":
+# the accumulator stops being a separate quantity at all. The claim is
+# therefore that the integrator is STRICTLY ahead of the command it emits, by
+# exactly one step, on a slew-limited cycle.
+check(f"⭐ AND IT IS NOT A BACK-CALCULATION: on a slew-limited cycle the "
+      f"integrator stands EXACTLY {SLEW_LEAD_STEPS} slew step(s) ahead of the "
+      f"command it emits ({d.i_w - d.target_w:+.0f} W), not on top of it - "
+      "a cap of zero would collapse this function to the velocity form it "
+      "replaced",
+      d.reason == "slew-limited"
+      and round(abs(d.i_w - d.target_w), 6) == SLEW_LEAD_STEPS * _SLEW)
+
+# ⚠️ AND IT BINDS IN BOTH DIRECTIONS OF TRAVEL, WHICH IS NOT OBVIOUS FROM THE
+# SPELLING. `if target > slewed ... elif target < slewed` reads like two cases
+# and is one: a command FALLING from +2400 W toward an integrator at +100 W has
+# an integrator 2300 W ahead of it in the direction of travel, and it is capped
+# exactly as a rising one is. A check written only on the rising case would be
+# green for a gate that had lost half of itself.
+_dn = compute(prev_w=2400.0, grid_w=-200.0, actual_w=2400.0, tuning=T,
+              sat_count=0, i_w=100.0)
+print(f"    descending: prev +2400 W, integrator +100 W -> command "
+      f"{_dn.target_w:+.0f} W, integrator {_dn.i_w:+.0f} W, "
+      f"reason {_dn.reason!r}")
+check("⭐ THE CAP BINDS ON A FALLING COMMAND TOO: descending from +2400 W the "
+      f"integrator is pulled to exactly one slew step beyond the command it "
+      f"emits ({_dn.i_w - _dn.target_w:+.0f} W), not left 2300 W below it",
+      _dn.reason == "slew-limited"
+      and round(abs(_dn.i_w - _dn.target_w), 6) == SLEW_LEAD_STEPS * _SLEW)
+
+# ⚠️ THE CAP IS INSIDE THE SLEW BRANCH, AND THIS IS THE ONLY STIMULUS THAT CAN
+# TELL THAT FROM AN UNCONDITIONAL ONE. Applying it to every cycle - `i_w =
+# max(target - cap, min(target + cap, i_w))` after `target = slewed` - is a
+# -92 B edit that is BIT-IDENTICAL on the shipped configuration, and it was a
+# SURVIVOR of all 30 files until this check existed. It is measured: 0 of
+# 256 246 ticks differ over the 16-day recording, and 2050 of 257 400 swept
+# states do - every one of them at `integrator_max_w` ABOVE `max_w`, the
+# configuration control.py says is the only way its `clamped` reason is
+# reachable. There the integrator is DELIBERATELY allowed above the rail, and a
+# cap that fired on every cycle would drag it back to the command and make the
+# option inert.
+_HI = Tuning(gain=0.6, max_w=2000.0, slew_w=400.0, target_grid_w=-10.0,
+             integrator_max_w=5000.0)
+_hi = compute(prev_w=-2400.0, grid_w=-8000.0, actual_w=-6000.0, tuning=_HI,
+              sat_count=0, i_w=-2400.0)
+print(f"    integrator_max_w 5000 above a max_w of 2000: command "
+      f"{_hi.target_w:+.0f} W, integrator {_hi.i_w:+.0f} W, "
+      f"reason {_hi.reason!r}")
+check("⭐ THE CAP DOES NOT FIRE WHERE THE SLEW DID NOT BIND: with "
+      "`integrator_max_w` deliberately above `max_w` the integrator keeps its "
+      "own bound (-5000 W) instead of being dragged to the command - an "
+      "unconditional cap would put it at -2400 W and make the option inert",
+      _hi.i_w == -5000.0 and _hi.reason == "clamped")
+
+# ⚠️ THE TWO RECORDED DEADLOCKS, AS TEST CASES. control.py names both at
+# length; a gate written on the integrator is exactly the edit that brings them
+# back, so each is driven rather than argued.
+#
+# (a) THE `i_w == 0.0` CASE. `main.py` resets the integrator to exactly 0.0 on
+#     every stop and every reseed, and "may not wind further in the direction it
+#     is already pushing" has no referent there. A gate that files zero under
+#     one sign blocks the first push toward the other one forever.
+z = compute(prev_w=0.0, grid_w=-6000.0, actual_w=0.0, tuning=T, sat_count=0,
+            i_w=0.0)
+check("at `i_w == 0.0` the first push toward charging is NOT blocked - the "
+      f"command leaves zero ({z.target_w:+.0f} W) and the integrator moves "
+      f"({z.i_w:+.0f} W)", z.target_w < 0.0 and z.i_w < 0.0)
+
+# (b) THE SHRINK-ONLY ENCODING. "Only corrections that shrink |i_w|" is
+#     unsatisfiable for both signs whenever the correction is larger than twice
+#     the integrator, and the loop then sits at its last value forever. Driven
+#     as the measured case: 0 W held into a 2 kW import.
+imp = run(2000.0, cycles=12)[2]
+print(f"    2 kW import from rest: setpoints "
+      f"{[f['setpoint'] for f in imp[:6]]}")
+check("a 2 kW import from rest recovers rather than sitting at its last value "
+      "- the shrink-only encoding held 0 W indefinitely here",
+      imp[-1]["setpoint"] >= 1000.0)
+
+# ⚠️ AND THE GATE MUST NOT BE A DELAY. A loop that is slew-limited for a long
+# ramp has to arrive, or the fix has bought export back with standing error.
+far = run(-6000.0, cycles=40)[2]
+print(f"    a 6 kW export, 40 cycles: setpoint reaches "
+      f"{far[-1]['setpoint']:.0f} W of the {-BOUND_W:.0f} W rail")
+check("⭐ THE COMMAND STILL ARRIVES: a railed export drives the command to the "
+      "rail, one slew step a cycle, with the integrator bounded the whole way "
+      "- the gate bounds the LEAD, it does not stop the loop",
+      far[-1]["setpoint"] == -BOUND_W)
+
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED:")
+    for f in fails:
+        print(f"  - {f}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_version_gate.py

@@ -272,6 +272,136 @@ check("REFUSED is exactly 1, not merely non-zero",
 print("\nthe shipped tree's own version is readable")
 check("shipped_version() finds a version", bool(shipped_version(HERE)))
 
+
+# --------------------------------------------------------------------------- #
+# PKG-14 - THE OTHER HALF OF THE NO-OP, AND NOTHING GRADED IT.
+#
+# PKG-09 refuses a deploy whose `version:` did not move. It cannot see the
+# mirror failure, which this repository has now produced twice: the version
+# DOES move and the changelog's `## Unreleased` block is never closed, so the
+# operator who opens the file to find out what they are about to install reads
+# "THIS HAS NO VERSION AND CANNOT REACH AN INSTALL UNTIL IT GETS ONE" about a
+# tree that is being installed. `## 0.8.0` records one such block that
+# accumulated across three releases; `## 0.9.0` was cut with a second one left
+# standing underneath it.
+#
+# ⚠️ THE TWO SIDES COME FROM DIFFERENT FILES ON PURPOSE (MUTATION.md habit 4).
+# config.yaml's `version:` and CHANGELOG.md's newest heading are written by
+# different hands at different times, and the whole defect is that they drift.
+# A check that read the number once and compared it with itself would be the
+# DEV-02 fixture again: a number against itself.
+#
+# ⚠️ AND IT IS NOT A SUBSTRING SCAN OVER THE WHOLE FILE. Every id this section
+# looks for occurs dozens of times lower down, so a scan of the file would pass
+# on any tree whatever the newest section said - CFG-04's defect, which asserted
+# against the TEXT of the thing under test. The section is SLICED first, and
+# part 11a grades the slicer against a sentinel that exists only below it.
+print("\n11. PKG-14 - the bump and the closed section are one act")
+
+_CHANGELOG = os.path.join(HERE, "CHANGELOG.md")
+with open(_CHANGELOG, encoding="utf-8") as fh:
+    _cl_lines = fh.read().splitlines()
+
+_heads = [(i, l[3:].strip()) for i, l in enumerate(_cl_lines)
+          if l.startswith("## ")]
+check(f"precondition: the file has {len(_heads)} `## ` headings, so the "
+      f"quantifiers below are not over an empty set", len(_heads) >= 8)
+
+# 11a. THE SLICE, AND TWO CONTROLS ON THE SLICER.
+# ARCH-02's fifteenth instance: a splitter that never closes attributes
+# everything to the last thing it opened, and every per-section check
+# downstream silently becomes a total over the whole file. Both controls below
+# exist because 11b/11c would go on passing for a tree in which nothing they
+# name is true.
+
+
+def slice_newest(lines):
+    """(heading text, the lines of the FIRST `## ` section) - closing at the
+    next `## `, which is the half that has to be graded rather than assumed."""
+    heads = [i for i, l in enumerate(lines) if l.startswith("## ")]
+    if not heads:
+        return None, []
+    start = heads[0]
+    end = heads[1] if len(heads) > 1 else len(lines)
+    return lines[start][3:].strip(), lines[start:end]
+
+
+# CONTROL ONE, run on every invocation rather than attested in a commit
+# message: a synthetic document whose token appears ONLY below the first
+# section. A slicer that runs to the end of the file finds it; this one must
+# not. test_defaults_pin.py part 5 plants a literal for the same reason.
+_SYNTH = ["# Changelog", "", "## 9.9.9", "", "the newest section.", "",
+          "## 9.9.8", "", "PLANTED-ONLY-BELOW", ""]
+_syn_name, _syn_body = slice_newest(_SYNTH)
+check("11a. the slicer CLOSES - on a synthetic document it excludes a token "
+      "that exists only in the section BELOW the newest one",
+      _syn_name == "9.9.9" and "PLANTED-ONLY-BELOW" in "\n".join(_SYNTH)
+      and "PLANTED-ONLY-BELOW" not in "\n".join(_syn_body))
+
+_top_name, _top_body = slice_newest(_cl_lines)
+_newest = "\n".join(_top_body)
+_SENTINEL = "## 0.8.0"
+check(f"...and on the shipped file too: it does not contain {_SENTINEL!r}, "
+      f"which the file does", _SENTINEL in "\n".join(_cl_lines)
+      and _SENTINEL not in _newest)
+check(f"...and it is not empty: {len(_top_body)} lines under {_top_name!r}",
+      len(_top_body) > 20)
+
+# CONTROL TWO - and this is the one that catches a LOST HEADING rather than a
+# loose slicer. Every version section in this file carries exactly one
+# "in merge order since" contents table. Delete a released section's `## `
+# heading and its table is swallowed by the section above, which is a released
+# record disappearing into an unreleased one - the shape `## 0.7.0` already
+# records for 0.6.0, and the one PKG-08 is left holding.
+_tables = [l for l in _top_body if "in merge order since" in l]
+check(f"...and it carries EXACTLY ONE contents table, not {len(_tables)} - a "
+      f"second one means a released section below lost its `## ` heading and "
+      f"was absorbed into this one", len(_tables) == 1)
+
+# 11b. THE BLOCK IS CLOSED, AND IT CARRIES THE SHIPPED NUMBER.
+check("11b. the newest `## ` heading is a VERSION and not `Unreleased` - the "
+      "block was closed by whoever bumped the version",
+      _top_name.lower() != "unreleased")
+_shipped = shipped_version(HERE)
+check(f"...and it is exactly config.yaml's `version:` ({_shipped!r} in "
+      f"config.yaml, {_top_name!r} in CHANGELOG.md) - two files, so a bump "
+      f"without a section, or a section without a bump, is red",
+      _top_name == _shipped)
+
+# 11c. A WITHDRAWN price_provider IS NAMED IN THE SECTION THAT WITHDRAWS IT.
+# ⚠️ READ OFF app/price.py BY AST, NOT TYPED HERE. A list transcribed into this
+# file would go on passing after a fourth id was retired and documented
+# nowhere, which is the exact failure TARIFF-07 exists to prevent: an id the
+# add-on refuses at startup and no release note mentions.
+import ast                                                    # noqa: E402
+_price_src = open(os.path.join(HERE, "app", "price.py"),
+                  encoding="utf-8").read()
+_retired = []
+for _node in ast.walk(ast.parse(_price_src)):
+    if isinstance(_node, ast.AnnAssign) and getattr(
+            _node.target, "id", None) == "RETIRED_PROVIDERS":
+        _retired = [k.value for k in _node.value.keys]
+    elif isinstance(_node, ast.Assign) and any(
+            getattr(t, "id", None) == "RETIRED_PROVIDERS" for t in _node.targets):
+        _retired = [k.value for k in _node.value.keys]
+check(f"11c. precondition: RETIRED_PROVIDERS was read off app/price.py and is "
+      f"not empty - {sorted(_retired)}", len(_retired) > 0)
+_unnamed = sorted(p for p in _retired if p not in _newest)
+check(f"...and every one of the {len(_retired)} withdrawn id(s) is named in "
+      f"`## {_top_name}` - an id the validator refuses at startup that no "
+      f"release note mentions is the TARIFF-07 defect with the sign flipped",
+      _unnamed == [])
+
+# 11d. THE LEDGER OF BLOCKS STILL MISFILED, FROZEN RATHER THAN FIXED.
+# PKG-08 owns splitting them; this file owns the promise that the number can
+# only go DOWN. A release that cuts its section and leaves a second
+# `## Unreleased` standing is red here on the commit that does it.
+_stale = [n for _, n in _heads[1:] if n.lower() == "unreleased"]
+check(f"11d. exactly {len(_stale)} `## Unreleased` block(s) remain BELOW the "
+      f"newest section, and the count is pinned EXACTLY so the ledger can "
+      f"only shrink - splitting them is PKG-08, not this file",
+      len(_stale) == 1)
+
 for d in tmpdirs:
     shutil.rmtree(d, ignore_errors=True)
 

goodwe_controller/test_watchdog.py

@@ -2938,10 +2938,19 @@ check("...and it is inert BY CONSTRUCTION, not by a special case: the value it "
 # controller command NOW, from a battery at 0 W" - ONE STEP - and not "what
 # trajectory would it have followed". The trajectory is a closed-loop property
 # and it did not happen; reporting it would be a simulation of a plant that
-# does not exist. The strategies are unaffected: arbitrage, the peak guard and
-# maintenance all file SET claims at a fixed power from level-triggered inputs,
-# which is why the three defects this card was written for are all visible from
-# a shadow run and this one is not.
+# does not exist.
+#
+# ⚠️ AMENDED BY SAFETY-47. The three lines that stood here said "the strategies
+# are unaffected ... which is why the three defects this card was written for
+# are all visible from a shadow run and this one is not." That was true until
+# SAFETY-45 merged, one commit earlier: the buy leg is now sized from the
+# BILLED-QUARTER METER, which is a function of what the battery did. So this is
+# NOT the loop leg's own limitation - it is the GENERAL case, and the loop leg
+# is merely where it had already been noticed. A shadow run cannot surface any
+# closed-loop defect, and of the three this card was written for exactly one -
+# TARIFF-14's wrong quarter-hour - is visible from one. `test_arbitrage.py`
+# part 3d grades that; this check keeps grading the loop leg, which is what it
+# has always been for.
 check("RECORDED LIMITATION: the loop leg's shadow decision is ONE slew step "
       "from the standing command and stays there, while the live run RAMPS. A "
       "shadow run answers 'what would it do now', not 'what trajectory would "

goodwe_controller/tools/rehearsal/announced-reference.txt

@@ -38,6 +38,14 @@
 #
 # Editing this file is how you say "the announcement changed on purpose". Do not
 # edit it to make a check pass.
+#
+# ⚠️ TEL-10 ADDED THE LAST THREE ROWS, AND THEY ARE ADDITIONS RATHER THAN A
+# RE-COMPOSITION. Nothing above them moved: same entity_ids, same unique_ids,
+# same device. They are recorded here - the BUILD's reference - and deliberately
+# NOT in `live-entities-recorded.txt`, because the install does not have them
+# yet and an id the build announces that the install lacks is a NEW entity, not
+# an orphan. `test_mqtt.py` part 1 grades the same two claims on the payload
+# bytes.
 sensor.goodwe_setpoint            goodwe_ctl_setpoint     goodwe_rs485_controller
 sensor.goodwe_grid_power          goodwe_ctl_grid         goodwe_rs485_controller
 sensor.goodwe_battery_power       goodwe_ctl_battery      goodwe_rs485_controller
@@ -46,3 +54,6 @@ sensor.goodwe_circulating_power   goodwe_ctl_circulation  goodwe_rs485_controlle
 sensor.goodwe_maintenance_phase   goodwe_ctl_phase        goodwe_rs485_controller
 sensor.goodwe_controller_status   goodwe_ctl_status       goodwe_rs485_controller
 sensor.goodwe_p1_sample_age       goodwe_ctl_p1_age       goodwe_rs485_controller
+sensor.goodwe_loop_integrator      goodwe_ctl_loop_i       goodwe_rs485_controller
+sensor.goodwe_loop_integrator_lead goodwe_ctl_loop_lead    goodwe_rs485_controller
+sensor.goodwe_loop_reason          goodwe_ctl_loop_reason  goodwe_rs485_controller

goodwe_controller/tools/replay_recorded_loop.py

@@ -0,0 +1,649 @@
+#!/usr/bin/env python3
+"""SAFETY-48's evidence: the live install's OWN recorded disturbances, replayed
+through the shipped control law with and without the card.
+
+    python3 tools/replay_recorded_loop.py                 # the A/B table
+    python3 tools/replay_recorded_loop.py --sensitivity   # ...and does it survive
+                                                          #    a different plant?
+    python3 tools/replay_recorded_loop.py --export --days 16 --token $HASS_TOKEN
+
+WHY A REPLAY AND NOT A STEP RESPONSE
+====================================
+`test_control.py`'s SAFETY-39 section drives a family of synthetic export steps
+through a first-order plant, and it is a good instrument for the question it
+asks. It cannot answer this one. The defect this card is about is a MISSING
+CASE - the integrator outrunning the command whenever `|error| > slew_w / gain`
+- and whether that case matters is a question about how often the house
+actually produces such an error, how long it stands, and what else is happening
+when it does. A step family answers "what would happen if"; only the recording
+answers "how much did this cost".
+
+WHAT IS REAL IN HERE
+====================
+  * THE DISTURBANCE. `D = grid + batt` at every recorded meter instant: the
+    house's own net demand with THIS loop's battery power taken back out. It is
+    exogenous - the house does not know what the battery did - which is what
+    makes it valid to drive a counterfactual with, for a run of any length.
+  * THE TICK. The replay steps on the METER's own recorded sample instants, not
+    on a constant. Median 5.0 s over the window. ⚠️ `control.LOOP_TICK_S` says
+    2.0 s; that was measured on 2026-09-05 and is NOT what this install has been
+    running since. The figure matters to `SLEW_RAIL_FRAC`, and it is wrong in
+    the SAFE direction (a slower meter makes validate.py rule 10 conservative).
+  * THE CONTROL LAW. `app/control.py`, imported out of this checkout. The
+    "before" law is THE SAME FILE with the SAFETY-48 block removed by a named
+    substitution and exec'd into a fresh namespace - so it is release/1.0's
+    behaviour derived from the shipped bytes, never a transcription. The
+    substitution anchor must occur exactly once or this refuses to run.
+
+MODELLED, AND THEREFORE NOT EVIDENCE ABOUT THE THING MODELLED
+=============================================================
+  * THE INVERTER. A pure delay + first-order lag + affine gain, FITTED on this
+    same recording at SoC above the floor. Its residual is printed on every run
+    and is large (~375 W RMS): the replay tracks the meter WORSE than the real
+    install does, so the absolute export figures below are pessimistic by about
+    a third against the recording. ⚠️ THE DELTA IS WHAT THIS TOOL IS FOR - both
+    laws run against the same plant, on the same ticks, from the same seed.
+  * THE PACK. SoC integrated from the simulated battery power off the recorded
+    SoC, discharge refused at or below the floor, charge refused at 100 %.
+  * EVERYTHING ELSE THE ARBITER DOES. The recorded setpoint is the ARBITER's
+    output - the loop's claim after the peak guard, the SoC clamps, maintenance
+    and arbitrage have had their say. This replay runs `compute()` ALONE. That
+    is the largest single reason the fidelity section below is not tighter, and
+    it is why no absolute figure here should be quoted as "what the install
+    did"; the recording itself is that.
+
+⚠️ WHAT THIS CANNOT SHOW, SAID BEFORE THE RESULTS RATHER THAN AFTER THEM
+=======================================================================
+  * IT CANNOT SHOW THAT THE FIX IS SAFE ON THE REAL PLANT. Nothing here drives
+    an inverter. The rig and a live run are what answer that, and SAFETY-47
+    records why a shadow run cannot.
+  * IT CANNOT SEPARATE THE FIX FROM THE PLANT MODEL ON ONE RUN. `--sensitivity`
+    re-runs the whole table on five other plants and tunings; the ranking is the
+    claim, not the watt figures.
+  * THE BILLED QUANTITY IS A MAXIMUM OVER ~1500 QUARTERS, so it is a tail
+    statistic and one quarter decides it. The per-quarter MEAN delta is printed
+    beside it for exactly that reason.
+"""
+import argparse
+import bisect
+import gzip
+import hashlib
+import json
+import math
+import os
+import pathlib
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timedelta
+
+HERE = pathlib.Path(__file__).resolve().parent
+ADDON = HERE.parent
+sys.path.insert(0, str(ADDON))
+
+SCENARIO = ADDON / "scenarios" / "loop-2026-09-02_2026-09-17"
+DEFAULT_URL = "http://192.168.2.158:8123"
+TZNAME = "Europe/Brussels"
+
+# The entities, and what each is for. ⚠️ `setpoint` is NOT an input to the
+# replay: it is the RECORDING the replay is graded against in §fidelity, and it
+# is what `slew_w` and `max_w` are read off rather than assumed.
+ENTITIES = {
+    "grid": "sensor.p1_meter_active_power",
+    "batt": "sensor.goodwe_rs485_controller_goodwe_battery_power",
+    "setpoint": "sensor.goodwe_rs485_controller_goodwe_setpoint",
+    "soc": "sensor.goodwe_rs485_controller_goodwe_battery_soc",
+}
+
+# The live install's shape. `max_w` and `slew_w` are READ OFF THE RECORDING by
+# `--export` and re-derived on every run below; `gain` and `target_grid_w` are
+# the options and are not observable in the trace.
+LIVE = dict(gain=0.6, max_w=5000.0, slew_w=400.0, target_grid_w=-10.0)
+SOC_FLOOR = 10.0
+CAP_WH = 17379.0        # measured: -dE/dSoC over 1604 segments of this record
+GRID_HOLD_S = 30.0      # `meter_max_age_s`: past this a held meter is no reading
+TICK_CAP_S = 60.0       # a longer gap is an outage, not a cycle
+
+
+# ---------------------------------------------------------------------------
+# the recording
+
+
+def _rows(key):
+    out = []
+    for fn in sorted(os.listdir(SCENARIO)):
+        if not fn.endswith(f"-{key}.jsonl.gz"):
+            continue
+        with gzip.open(SCENARIO / fn, "rb") as fh:
+            for line in fh:
+                r = json.loads(line)
+                out.append((datetime.fromisoformat(r["t"]).timestamp(), r["v"]))
+    out.sort(key=lambda r: r[0])
+    ded = []
+    for t, v in out:
+        if ded and abs(ded[-1][0] - t) < 1e-9:
+            ded[-1] = (t, v)          # the history endpoint's day-boundary repeat
+            continue
+        ded.append((t, v))
+    return ded
+
+
+def _steps(key):
+    """[(t, float|None)] - None OPENS A HOLE and nothing is held across it.
+
+    ⚠️ A LONG SILENCE IS NOT A HOLE. Home Assistant's recorder stores a row only
+    when a state CHANGES, so eleven hours of `setpoint` silence means the
+    command held that value for eleven hours - which is exactly what this site
+    does overnight at its SoC floor. What IS a hole is a row whose state is
+    `unavailable`/`unknown`, and `grid` additionally stops being believed after
+    GRID_HOLD_S because that is the age the shipped controller stops believing
+    it at.
+    """
+    out = []
+    for t, s in _rows(key):
+        try:
+            out.append((t, float(s)))
+        except (TypeError, ValueError):
+            out.append((t, None))
+    return out
+
+
+def stream():
+    """[(t, grid, batt, setpoint, soc)] at every recorded METER instant."""
+    g = [(t, v) for t, v in _steps("grid") if v is not None]
+    others = {}
+    for k in ("batt", "setpoint", "soc"):
+        s = _steps(k)
+        others[k] = ([r[0] for r in s], [r[1] for r in s])
+    prev_t = None
+    out = []
+    for t, v in g:
+        if prev_t is not None and t - prev_t > GRID_HOLD_S:
+            prev_t = t
+            continue
+        prev_t = t
+        row = [t, v]
+        for k in ("batt", "setpoint", "soc"):
+            tt, vv = others[k]
+            j = bisect.bisect_right(tt, t) - 1
+            row.append(None if j < 0 else vv[j])
+        if any(x is None for x in row):
+            continue
+        out.append(tuple(row))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# the plant, fitted on this same recording
+
+
+def _lsq(xs, ys):
+    n = len(xs)
+    mx, my = sum(xs) / n, sum(ys) / n
+    sxy = sum((a - mx) * (b - my) for a, b in zip(xs, ys))
+    sxx = sum((a - mx) ** 2 for a in xs)
+    syy = sum((b - my) ** 2 for b in ys)
+    return sxy / sxx, my - (sxy / sxx) * mx, sxy / math.sqrt(sxx * syy)
+
+
+def fit_plant(rows, stride=1):
+    """(lag_s, tau_s, gain, offset, rms_W), fitted where the pack can MOVE.
+
+    ⚠️ THE SoC FILTER IS THE WHOLE FIT. This install spends 36 % of its ticks at
+    or below a 10 % SoC with the command standing near 2 kW and the battery
+    delivering nothing, and a fit taken over all ticks reads
+    `batt = 0.50 x cmd - 396 W, r = 0.70` - a plant that follows half the
+    command, which no inverter does. Above the floor the same data says
+    `batt = 1.00 x cmd - 28 W, r = 0.977`. The floor is the PACK and is modelled
+    separately.
+    """
+    t = [r[0] for r in rows]
+    ba = [r[2] for r in rows]
+    sp = [r[3] for r in rows]
+    live = [r[4] > SOC_FLOOR + 2 for r in rows]
+    best = None
+    for lag in (0.0, 2.5, 5.0, 7.5, 10.0, 12.5):
+        j, u = 0, []
+        for i, ti in enumerate(t):
+            while j + 1 < len(t) and t[j + 1] <= ti - lag:
+                j += 1
+            u.append(sp[j])
+        idx = [i for i in range(0, len(t), stride)
+               if live[i] and abs(u[i]) > 50]
+        g, o, _ = _lsq([u[i] for i in idx], [ba[i] for i in idx])
+        for tau in (0.5, 1.0, 2.0, 4.0, 8.0, 16.0):
+            b, err, cnt = 0.0, 0.0, 0
+            for i in range(1, len(t)):
+                dt = min(t[i] - t[i - 1], TICK_CAP_S)
+                b += (1.0 - math.exp(-dt / tau)) * (g * u[i] + o - b)
+                if live[i]:
+                    err += (b - ba[i]) ** 2
+                    cnt += 1
+            rms = math.sqrt(err / cnt)
+            if best is None or rms < best[-1]:
+                best = (lag, tau, g, o, rms)
+    return best
+
+
+class Plant:
+    def __init__(self, lag_s, tau_s, g, o, soc0):
+        self.lag_s, self.tau_s, self.g, self.o = lag_s, tau_s, g, o
+        self.b, self.soc, self.q = 0.0, soc0, []
+
+    def seed(self, t, b, cmd):
+        self.b, self.q = b, [(t - self.lag_s - 1e-6, cmd)]
+
+    def step(self, t, dt, cmd):
+        self.q.append((t, cmd))
+        want = self.q[0][1]
+        while len(self.q) > 1 and self.q[1][0] <= t - self.lag_s:
+            self.q.pop(0)
+            want = self.q[0][1]
+        tgt = self.g * want + self.o
+        if self.soc <= SOC_FLOOR:
+            tgt = min(tgt, 0.0)          # an empty pack cannot discharge
+        if self.soc >= 100.0:
+            tgt = max(tgt, 0.0)          # a full one cannot charge
+        self.b += (1.0 - math.exp(-dt / self.tau_s)) * (tgt - self.b)
+        self.soc = max(0.0, min(100.0, self.soc - self.b * dt / 36.0 / CAP_WH))
+        return self.b
+
+
+# ---------------------------------------------------------------------------
+# the two laws
+
+
+SAFETY_48_BLOCK_ANCHOR = "        _lead_cap = SLEW_LEAD_STEPS * slew\n"
+
+
+def laws():
+    """(before, after) - the shipped module, and the same SOURCE without the card.
+
+    ⚠️ NOT A TRANSCRIPTION, AND NOT A FLAG. `test_mqtt.py` part 8's technique:
+    the shipped file's bytes with one named substitution, exec'd into a fresh
+    namespace. An anchor that does not occur exactly once is a refusal, because
+    a substitution that applied to nothing would be reported as "the card
+    changes nothing" - MUTATION.md's survivor, wearing an instrument's clothes.
+    """
+    import app.control as after
+    src = (ADDON / "app" / "control.py").read_text()
+    if src.count(SAFETY_48_BLOCK_ANCHOR) != 1:
+        raise SystemExit(
+            "replay_recorded_loop: app/control.py does not contain exactly one\n"
+            f"  {SAFETY_48_BLOCK_ANCHOR.strip()!r}\n"
+            "NOTHING HAS BEEN MEASURED. This is a REFUSAL, not a result: with no\n"
+            "anchor there is no `before` law to compare against, and a run that\n"
+            "quietly compared the shipped law with ITSELF would report the card\n"
+            "as changing nothing - which is the survivor MUTATION.md is about,\n"
+            "wearing an instrument's clothes.")
+    start = src.index(SAFETY_48_BLOCK_ANCHOR)
+    end = src.index("    target = slewed\n", start)
+    block = src[start:end]
+    stripped = src.replace(block, "")
+    if "SLEW_LEAD_STEPS * slew" in stripped:
+        raise SystemExit("replay_recorded_loop: the block was not removed - "
+                         "NOTHING HAS BEEN MEASURED")
+    before = type(sys)("control_before")
+    exec(compile(stripped, "<release/1.0 law>", "exec"), before.__dict__)
+    return before, after
+
+
+def replay(rows, law, fit, tuning):
+    """[(t, dt, grid, batt, cmd, i_w, lead, reason, soc)] over the whole record."""
+    t0, g0, b0, sp0, soc0 = rows[0]
+    pl = Plant(*fit[:4], soc0)
+    pl.seed(t0, b0, sp0)
+    prev, i_w, sat = sp0, sp0, 0
+    out = []
+    for i in range(1, len(rows)):
+        t, gr, ba, sp, soc = rows[i]
+        dt = t - rows[i - 1][0]
+        if dt > TICK_CAP_S:
+            # An outage. Re-seed from the recording rather than inventing a
+            # cycle: nothing this loop did across it is knowable.
+            pl = Plant(*fit[:4], soc)
+            pl.seed(t, ba, sp)
+            prev, i_w, sat = sp, sp, 0
+            continue
+        D = gr + ba                       # the exogenous half of the meter
+        b = pl.step(t, dt, prev)
+        grid = D - b
+        d = law.compute(prev, grid, b, tuning, sat, i_w)
+        out.append((t, dt, grid, b, d.target_w, d.i_w, d.i_w - prev, d.reason,
+                    pl.soc))
+        prev, i_w, sat = d.target_w, d.i_w, d.sat_count
+    return out
+
+
+# ---------------------------------------------------------------------------
+# the five reported quantities - ONE implementation, run on both traces
+
+
+def export_kwh(tr):
+    return sum(max(0.0, -r[2]) * r[1] for r in tr) / 3.6e6
+
+
+def import_kwh(tr):
+    return sum(max(0.0, r[2]) * r[1] for r in tr) / 3.6e6
+
+
+def reversals(tr, dead_w=50.0):
+    n, last = 0, 0
+    for r in tr:
+        s = 1 if r[3] > dead_w else (-1 if r[3] < -dead_w else 0)
+        if s and last and s != last:
+            n += 1
+        if s:
+            last = s
+    return n
+
+
+def wasted_kwh(tr, bin_s=60.0):
+    """Throughput that went round rather than anywhere, in FIXED clock bins.
+
+    Per bin, `sum |b|dt - |sum b dt|`. A bin spent charging, or discharging, or
+    idle contributes ZERO; only a bin that does both contributes. ⚠️ The bins
+    are wall-clock and identical for both laws on purpose: an episode-scoped
+    definition would MOVE with the fix and compare two different questions.
+    """
+    tot, cur, absE, net = 0.0, None, 0.0, 0.0
+    for r in tr:
+        k = math.floor(r[0] / bin_s)
+        if cur is None:
+            cur = k
+        if k != cur:
+            tot += abs(absE) - abs(net)
+            cur, absE, net = k, 0.0, 0.0
+        absE += abs(r[3]) * r[1]
+        net += r[3] * r[1]
+    return (tot + abs(absE) - abs(net)) / 3.6e6
+
+
+def quarters(tr):
+    """{quarter -> mean OFFTAKE in W}. The billed quantity.
+
+    Calendar quarter-hours, the average of NET power, floored at 0 - a quarter
+    that nets to export is not offtake and is not billed. A quarter with less
+    than 80 % coverage is not a quarter and is dropped.
+    """
+    acc = {}
+    for r in tr:
+        k = math.floor(r[0] / 900.0)
+        e, s = acc.get(k, (0.0, 0.0))
+        acc[k] = (e + r[2] * r[1], s + r[1])
+    return {k: max(0.0, e / s) for k, (e, s) in acc.items() if s > 720.0}
+
+
+def recoveries(tr, bias, onset_w, cap_s=900.0):
+    """Seconds from the error leaving `onset_w` to it back inside the deadband.
+
+    ⚠️ AN EXCURSION THE PACK CANNOT ANSWER IS NOT A RECOVERY TIME. This install
+    spends 36 % of its ticks at the SoC floor with the command standing near
+    2 kW and the battery delivering nothing; the error there is not the loop's
+    to clear and every law scores the same non-answer. Leaving those in gave a
+    p99 of eight hours. An excursion counts only if the pack had headroom in the
+    needed direction for its whole length, and one still standing after `cap_s`
+    is counted as UNRECOVERED rather than as a large number.
+    """
+    out, unrec, t_on, ok = [], 0, None, True
+    for r in tr:
+        err = r[2] - bias
+        head = (r[8] > SOC_FLOOR + 1) if err > 0 else (r[8] < 99.0)
+        if t_on is None:
+            if abs(err) > onset_w:
+                t_on, ok = r[0], head
+        else:
+            ok = ok and head
+            if abs(err) < 15.0:
+                if ok:
+                    out.append(r[0] - t_on)
+                t_on = None
+            elif r[0] - t_on > cap_s:
+                unrec += 1 if ok else 0
+                t_on = None
+    return sorted(out), unrec
+
+
+def pct(xs, p):
+    return xs[min(len(xs) - 1, int(round(p / 100.0 * (len(xs) - 1))))] if xs else float("nan")
+
+
+def table(tr, tuning):
+    rec, unrec = recoveries(tr, tuning.target_grid_w, tuning.slew_w / tuning.gain)
+    leads = sorted(abs(r[6]) for r in tr)
+    q = quarters(tr)
+    return dict(export_kwh=export_kwh(tr), import_kwh=import_kwh(tr),
+                reversals=reversals(tr), wasted_kwh=wasted_kwh(tr),
+                worst_quarter_w=max(q.values()), rec_n=len(rec),
+                rec_med=pct(rec, 50), rec_p99=pct(rec, 99),
+                rec_max=rec[-1] if rec else float("nan"),
+                rec_unrecovered=unrec, lead_p99=pct(leads, 99),
+                lead_max=leads[-1], slew_ticks=sum(1 for r in tr if r[7] == "slew-limited"),
+                ticks=len(tr), _q=q)
+
+
+ROWS = [("export_kwh", "export kWh", "the cost"),
+        ("import_kwh", "import kWh", ""),
+        ("reversals", "battery sign reversals", ""),
+        ("wasted_kwh", "wasted throughput kWh", ""),
+        ("worst_quarter_w", "worst 15-min offtake W", "⚠️ THE BILLED ONE"),
+        ("rec_n", "recovery events", ""),
+        ("rec_med", "recovery median s", ""),
+        ("rec_p99", "recovery p99 s", ""),
+        ("rec_max", "recovery max s", ""),
+        ("rec_unrecovered", "unrecovered (>900 s)", ""),
+        ("lead_p99", "|i_w - prev_w| p99 W", ""),
+        ("lead_max", "|i_w - prev_w| max W", ""),
+        ("slew_ticks", "slew-limited ticks", "")]
+
+
+def show(a, b, name_a="release/1.0", name_b="SAFETY-48"):
+    print(f"    {'':26} {name_a:>13} {name_b:>13} {'delta':>11}")
+    for k, lab, note in ROWS:
+        print(f"    {lab:<26} {a[k]:13.2f} {b[k]:13.2f} {b[k] - a[k]:+11.2f}"
+              + (f"   {note}" if note else ""))
+    d = [b["_q"][k] - a["_q"][k] for k in a["_q"] if k in b["_q"]]
+    print(f"    {'mean quarter delta W':<26} {'':13} {'':13} "
+          f"{sum(d) / len(d):+11.2f}   over {len(d)} quarters")
+    print(f"    {'worst quarter delta W':<26} {'':13} {'':13} {max(d):+11.2f}")
+
+
+def fidelity(tr, rows):
+    """What the BEFORE run gets wrong against the recording it came from.
+
+    ⚠️ PRINTED BEFORE THE A/B TABLE IS READ, NOT AFTER. This is the number that
+    says how far any ABSOLUTE figure above may be trusted, and it is large.
+    """
+    n = len(tr)
+    rec_g = [rows[i + 1][1] for i in range(n)]
+    rec_sp = [rows[i + 1][3] for i in range(n)]
+    sim_g = [r[2] for r in tr]
+    sim_c = [r[4] for r in tr]
+    dt = [r[1] for r in tr]
+    _, _, r_sp = _lsq(sim_c, rec_sp)
+    _, _, r_g = _lsq(sim_g, rec_g)
+    ex_sim = sum(max(0.0, -g) * d for g, d in zip(sim_g, dt)) / 3.6e6
+    ex_rec = sum(max(0.0, -g) * d for g, d in zip(rec_g, dt)) / 3.6e6
+    print(f"    setpoint  r={r_sp:.3f}  mean {sum(sim_c) / n:+8.0f} W simulated "
+          f"vs {sum(rec_sp) / n:+8.0f} W recorded")
+    print(f"    grid      r={r_g:.3f}  mean {sum(sim_g) / n:+8.0f} W simulated "
+          f"vs {sum(rec_g) / n:+8.0f} W recorded")
+    print(f"    export    {ex_sim:8.2f} kWh simulated vs {ex_rec:8.2f} kWh "
+          f"recorded  ->  the model is {100 * (ex_sim / ex_rec - 1):+.0f} % "
+          f"PESSIMISTIC about the loop's tracking")
+
+
+# ---------------------------------------------------------------------------
+# --export: the read-only capture
+
+
+def _get(url, token, timeout=180.0):
+    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {token}"})
+    last = None
+    for attempt in range(1, 5):
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                if resp.status != 200:
+                    raise RuntimeError(f"HTTP {resp.status}")
+                return json.loads(resp.read().decode()), attempt
+        except Exception as exc:
+            last = f"{type(exc).__name__}: {exc}"
+            if attempt < 4:
+                time.sleep(3 * attempt)
+    raise RuntimeError(last)
+
+
+def export(base, token, days, out_dir):
+    """One local day per request, per entity. Read-only: GET only, never a write.
+
+    ⚠️ URL-ENCODE THE TIMESTAMPS. The history endpoint answers `Invalid
+    end_time` otherwise, and it answers it with a 400 that reads like a bad
+    entity id.
+    """
+    from zoneinfo import ZoneInfo
+    tz = ZoneInfo(TZNAME)
+    out_dir = pathlib.Path(out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    today = datetime.now(tz).date()
+    man = {"generated": datetime.now(tz).isoformat(),
+           "generator": "tools/replay_recorded_loop.py --export",
+           "source": f"{base}/api/history/period", "timezone": TZNAME,
+           "entities": ENTITIES,
+           "format": '{"t": <ISO-8601 with offset>, "v": <state string>} per '
+                     'line, gzip, mtime 0',
+           "days": []}
+    rc = 0
+    for d in range(days, 0, -1):
+        day = today - timedelta(days=d)
+        s = datetime(day.year, day.month, day.day, tzinfo=tz)
+        e = s + timedelta(days=1)
+        rec = {"date": str(day), "window": [s.isoformat(), e.isoformat()],
+               "files": {}}
+        for key, ent in ENTITIES.items():
+            q = urllib.parse.urlencode({"filter_entity_id": ent,
+                                        "end_time": e.isoformat(),
+                                        "minimal_response": ""})
+            url = (f"{base}/api/history/period/"
+                   f"{urllib.parse.quote(s.isoformat())}?{q}")
+            try:
+                doc, attempts = _get(url, token)
+            except Exception as exc:
+                rec["files"][key] = {"read": "FAILED", "error": str(exc)}
+                print(f"  {day} {key:9s} FAILED {exc}", flush=True)
+                rc = 1
+                continue
+            series = doc[0] if doc else []
+            body = b""
+            n_bad = 0
+            for row in series:
+                t = row.get("last_changed") or row.get("last_updated")
+                v = row.get("state")
+                if t is None or v is None:
+                    continue
+                try:
+                    float(v)
+                except (TypeError, ValueError):
+                    n_bad += 1
+                body += (json.dumps({"t": t, "v": v}) + "\n").encode()
+            fn = f"{day}-{key}.jsonl.gz"
+            with gzip.GzipFile(out_dir / fn, "wb", mtime=0) as fh:
+                fh.write(body)
+            rec["files"][key] = {
+                "read": "OK", "entity": ent, "samples": len(series),
+                "non_numeric_states": n_bad, "attempts": attempts, "file": fn,
+                "bytes_raw": len(body),
+                "sha256_raw": hashlib.sha256(body).hexdigest()}
+            print(f"  {day} {key:9s} {len(series):7d} rows, {n_bad} non-numeric",
+                  flush=True)
+        man["days"].append(rec)
+    (out_dir / "manifest.json").write_text(json.dumps(man, indent=1) + "\n")
+    return rc
+
+
+# ---------------------------------------------------------------------------
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--export", action="store_true")
+    ap.add_argument("--days", type=int, default=16)
+    ap.add_argument("--url", default=DEFAULT_URL)
+    ap.add_argument("--token", default=os.environ.get("HASS_TOKEN"))
+    ap.add_argument("--out-dir", default=str(SCENARIO))
+    ap.add_argument("--sensitivity", action="store_true")
+    args = ap.parse_args()
+
+    if args.export:
+        if not args.token:
+            raise SystemExit("--export needs --token or $HASS_TOKEN")
+        return export(args.url, args.token, args.days, args.out_dir)
+
+    from app.control import Tuning
+    t0 = time.time()
+    rows = stream()
+    span = (rows[-1][0] - rows[0][0]) / 86400.0
+    dts = sorted(rows[i + 1][0] - rows[i][0] for i in range(len(rows) - 1))
+    print(f"\nTHE RECORDING: {len(rows)} meter instants over {span:.2f} days, "
+          f"{SCENARIO.name}")
+    print(f"    tick   p5 {pct(dts, 5):.2f} s   median {pct(dts, 50):.2f} s   "
+          f"p95 {pct(dts, 95):.2f} s   (control.LOOP_TICK_S says 2.0)")
+
+    # ⚠️ READ OFF THE RECORDING, NOT ASSUMED. `max_w` is the setpoint's own
+    # extreme and `slew_w` is the step the recorded command takes over and over.
+    sp = [r[3] for r in rows]
+    steps = {}
+    for i in range(1, len(rows)):
+        if rows[i][0] - rows[i - 1][0] < 8.0:
+            steps[round(abs(sp[i] - sp[i - 1]))] = \
+                steps.get(round(abs(sp[i] - sp[i - 1])), 0) + 1
+    top = max((c, w) for w, c in steps.items() if w > 100)
+    print(f"    the recorded command: extremes {min(sp):+.0f} / {max(sp):+.0f} W"
+          f"  ->  max_w {LIVE['max_w']:.0f};  most common step above 100 W is "
+          f"{top[1]:.0f} W, {top[0]} times  ->  slew_w {LIVE['slew_w']:.0f}")
+
+    fit = fit_plant(rows, stride=7)
+    print(f"    the fitted inverter: lag {fit[0]:.1f} s, tau {fit[1]:.1f} s, "
+          f"batt = {fit[2]:.4f} x cmd {fit[3]:+.1f} W, residual {fit[4]:.0f} W "
+          f"RMS above the SoC floor")
+
+    before, after = laws()
+    T = Tuning(**LIVE)
+    tr_b = replay(rows, before, fit, T)
+    tr_a = replay(rows, after, fit, T)
+    tab_b, tab_a = table(tr_b, T), table(tr_a, T)
+
+    print("\nFIDELITY - the BEFORE law replayed against the recording it came from")
+    fidelity(tr_b, rows)
+
+    print("\nTHE A/B, same ticks, same disturbance, same plant, same seed")
+    show(tab_b, tab_a)
+
+    if args.sensitivity:
+        print("\nSENSITIVITY - the ranking, not the watts")
+        variants = [
+            ("plant lag 5.0 s", (5.0, fit[1], fit[2], fit[3], 0.0), LIVE),
+            ("plant lag 10.0 s", (10.0, fit[1], fit[2], fit[3], 0.0), LIVE),
+            ("plant tau 8 s", (fit[0], 8.0, fit[2], fit[3], 0.0), LIVE),
+            ("gain 1.0135, offset -26", (fit[0], fit[1], 1.0135, -26.0, 0.0), LIVE),
+            ("slew_w 555.6 (the rail)", fit, dict(LIVE, slew_w=555.6)),
+            ("gain 0.3", fit, dict(LIVE, gain=0.3)),
+        ]
+        print(f"      {'variant':<26}{'export kWh':>22}{'worst quarter W':>26}"
+              f"{'mean quarter dW':>18}")
+        for name, f2, tune in variants:
+            T2 = Tuning(**tune)
+            b = table(replay(rows, before, f2, T2), T2)
+            a = table(replay(rows, after, f2, T2), T2)
+            d = [a["_q"][k] - b["_q"][k] for k in b["_q"] if k in a["_q"]]
+            print(f"      {name:<26}{b['export_kwh']:9.1f} ->{a['export_kwh']:9.1f}"
+                  f"{b['worst_quarter_w']:13.0f} ->{a['worst_quarter_w']:9.0f}"
+                  f"{sum(d) / len(d):+18.2f}")
+
+    print(f"\n    ({time.time() - t0:.0f} s)")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

goodwe_controller/tools/slew_sim.py

@@ -220,6 +220,7 @@ def slew_table(ps, ct, tick_s, rail):
           f"faster than the")
     print(f"  plant settles. {rail:.0f} W / ({ct.PLANT_SETTLE_S:.0f} s / "
           f"{tick_s:.0f} s per tick) = {frac * rail:.0f} W per tick.\n")
+    overs = []
     for slew in (1000, 800, 700, 600, int(frac * rail), 500, 400, 300, 250):
         w = family(ps, ct, gain=0.6, slew_w=float(slew), rail_w=rail,
                    tick_s=tick_s)
@@ -227,13 +228,52 @@ def slew_table(ps, ct, tick_s, rail):
               "   <- the 2026-09-05 live pair" if slew == 1000 else (
               "   <- the live interim" if slew == 400 else ""))
         row(f"slew_w {slew}{tag}", w)
+        overs.append(w["over"])
     print("\n  READ IT THIS WAY. The >= 900 W step - the live symptom, which")
     print("  escalated 2 -> 1 -> 13 -> 43 per 30 min that morning - is gone from")
     print("  every run below 900 W of slew, and that is what the slew owns.")
-    print("  The OVER-ABSORPTION does not move, and at the slowest slews it is")
-    print("  slightly WORSE. The rig cannot pick the derived value out of that")
-    print("  column, and it is not asked to: the CONSTRAINT picks it, and this")
-    print("  table is what says what the constraint does and does not buy.")
+
+    # ⚠️ THE NARRATION BELOW IS DERIVED FROM THE COLUMN JUST PRINTED, NOT
+    # WRITTEN ABOUT IT. SAFETY-39 wrote "the over-absorption does not move, and
+    # at the slowest slews it is slightly WORSE" - true of release/1.0's law,
+    # which is what it was measured against, and FALSE under SAFETY-48's lead
+    # cap, where the same script on the same plant prints a monotonically
+    # FALLING column. A transcript whose prose contradicts its own table is a
+    # failing check (MUTATION.md habit 8), and a sentence that is right under
+    # one law and wrong under another has to be computed rather than typed. So:
+    # which law is imported is read off `control.py` itself, and whether the
+    # column falls is read off the column.
+    cap = getattr(ct, "SLEW_LEAD_STEPS", None)
+    falling = all(b < a for a, b in zip(overs, overs[1:]))
+    law = ("release/1.0's law - the integrator's lead over the command is "
+           "UNBOUNDED" if cap is None else
+           f"SAFETY-48's law - the integrator may lead the command by "
+           f"{cap} slew step(s)")
+    print(f"\n  THE LAW THIS RAN AGAINST: {law}.")
+    if cap is None and not falling:
+        print("  The OVER-ABSORPTION does not move with the slew, and at the")
+        print("  slowest slews it is slightly WORSE - `slew_w` bounds the")
+        print("  OUTPUT while the integrator goes on winding, so a slower slew")
+        print("  leaves it winding for longer. SAFETY-48 bounds that lead and")
+        print("  INVERTS this column; see DECISIONS/SAFETY-48 §6.")
+    elif cap is not None and falling:
+        print("  The OVER-ABSORPTION FALLS MONOTONICALLY with the slew, which")
+        print("  is the OPPOSITE of what SAFETY-39 measured on release/1.0")
+        print("  (958/1107/1133/1058/987/1029/1150/1143/1081 W, flat and")
+        print("  non-monotone). Bounding the integrator's lead is what changed")
+        print("  it: the slew now owns a share of the over-absorption it did")
+        print("  not own before. DECISIONS/SAFETY-48 §6 has both tables and an")
+        print("  independent confirmation on test_control.py's own plant.")
+    else:
+        print("  ⚠️ NEITHER NARRATION FITS. The law above and the shape of the")
+        print(f"  column ({'falling' if falling else 'not falling'}) are the")
+        print("  combination this script has no sentence for - which means the")
+        print("  measurement has moved and DECISIONS/SAFETY-39 §3 and")
+        print("  DECISIONS/SAFETY-48 §6 both need re-reading before this table")
+        print("  is quoted anywhere.")
+    print("\n  EITHER WAY THE RIG DOES NOT PICK THE NUMBER, and it is not asked")
+    print("  to: the CONSTRAINT picks it, and this table is what says what the")
+    print("  constraint does and does not buy.")
 
 
 def gain_table(ps, ct, tick_s, rail):