TEST-26: a missing value in a check is a named FAIL, not a traceback

Checks and prints that indexed an empty list, exhausted next(), or formatted
None killed the rest of their file (FCST-06). Read them through the new
named_absence.py (nth/first/field/given/present) and conjoin a presence term.

- every site in the brief, plus the family the new scan and a sweep found
- test_named_absence.py: scans every test_*.py for unguarded filtered-list
  indexing, next() without a default and numeric formats on maybe-None
  names; proven to bite; prints what it cannot see, counted
- test_price.py 16a: the `_T17_CAPS is _T17_CAPS` tautology now grades the
  two assemble() calls' arguments
- test_control.py: coverage table re-measured on runs graded to the end

Co-Authored-By: Claude Opus 5.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,116 @@
 # 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.
+#
+# ⚠️ READ THE BLIND SPOTS ON THAT STEP BEFORE TRUSTING THE SENTENCE ABOVE.
+# "Mechanically" holds only for a reintroduced filter that still names the
+# PR's own base. For blind spots 1 and 3 the defence IS this comment, because
+# the guard lives inside the workflow that a filter makes Gitea skip. Blind
+# spot 3 is the one that matters: a filter naming a branch THIS pull request
+# does not target is itself skipped, lands green and untested, and then every
+# subsequent pull request the filter DOES NOT NAME is skipped too. That is the
+# gate off, silently.
+#
+# ⚠️ THAT DIRECTION IS THE WHOLE POINT AND IT IS EASY TO WRITE BACKWARDS. A
+# pull request that MATCHES the filter still runs; it is the one the filter
+# excludes that Gitea sits out, reports `skipped`, and the rollup launders
+# into `success`. An earlier draft of this very clause said "matching it is
+# skipped", which is the inverse of the measurement and contradicted the
+# paragraph directly below.
+#
+# ⚠️ AND THE DANGEROUS ONE IS NOT `branches: [main]`, WHICH AT LEAST LOOKS
+# WRONG. It is `branches: [release/1.0]`, which looks like tightening onto the
+# protected branch and is what a careful person would write. Every day-to-day
+# pull request still runs and still goes green, so nothing appears broken -
+# and the only thing switched off is the `release/1.0` -> `master` release
+# PR, i.e. the one whose content reaches an installed system. SEC-2 made that
+# PR the mandated release path (docs/RELEASE.md), so this is now a live route
+# rather than a hypothetical one.
+#
+# Closing it needs a SECOND permanently unfiltered workflow posting its own
+# context, with that context added to the `status_check_contexts` of BOTH
+# `release/1.0` AND `master` - both carry the rule since SEC-2, and adding it
+# to one alone leaves the hole open on the other. A forge change, with the
+# owner.
+#
+# 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 +354,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

README.md

@@ -33,6 +33,8 @@ estop/rs485_log.py           optional RS485 e-stop / bus witness
 docs/GoodWe-RS485-Field-Guide.pdf  the guide techs carry (10pp, A4)
 docs/build_guide.py          its single source - rebuilds the HTML and PDF
 FIELD-GUIDE.md             how to edit and rebuild the guide
+docs/RELEASE.md            how a change reaches the battery - `master` is
+                           protected, releases go via PR from `release/1.0`
 ```
 
 **Picking this up after a break? Read `HANDOVER.md` first** — current state,

docs/RELEASE.md

@@ -0,0 +1,116 @@
+# Releasing — how a change reaches the battery
+
+`master` is the **default branch**, and the default branch is what the Home
+Assistant Supervisor clones when it installs or updates this add-on. Whatever
+sits on `master` is what runs on a real 5 kW inverter. Treat a push to `master`
+as a deployment, because that is what it is.
+
+---
+
+## 1. `master` is protected — releases go through a pull request
+
+Until 2026-09-23 `master` had **no protection of any kind**. Every gate this
+repo built (CI-01, CI-9) sat on `release/1.0`, the branch that does *not* ship.
+On 2026-09-22 version 0.10.1 went straight onto `master` — no pull request, no
+CI run, no reviewer — and it succeeded (commit `0f14c2a`, the only commit on
+`master` that carries no `(#NN)` merge suffix). SEC-2 closed that.
+
+**The release path is now:**
+
+1. Merge the work into `release/1.0` as usual, via a pull request that goes
+   green. Bump `version:` in `goodwe_controller/config.yaml` on that branch —
+   the Supervisor keys the built image by `version:`, so without a bump nothing
+   is offered and nothing changes.
+2. Open a pull request **`release/1.0` → `master`**. Do not push to `master`;
+   it will be refused by the pre-receive hook:
+
+   ```
+   remote: error: Not allowed to push to protected branch master
+   ! [remote rejected] ... (pre-receive hook declined)
+   ```
+
+3. Wait for `checks / unit (pull_request)` to go **green** on that pull request.
+   The workflow in `.gitea/workflows/checks.yml` carries **no `branches:`
+   filter**, so a `master` base matches and a real run happens — verified on
+   throwaway PR #107 (base `master`), which queued a genuine run.
+
+   ⚠️ Green means green. A `skipped` status is laundered into a `success`
+   rollup by this Gitea and the merge gate accepts it — see the long note at
+   the top of `.gitea/workflows/checks.yml`. Never add an event filter there.
+
+4. Merge the pull request. `required_approvals` is **0**, so a green check is
+   the whole gate; there is no second pair of eyes unless someone asks for one.
+
+5. **Reload the store.** Merging to `master` does not, by itself, offer the
+   update. The Supervisor only sees the new version after:
+
+   ```bash
+   ssh root@192.168.2.158 "ha store reload && ha addons update local_goodwe_controller"
+   ```
+
+   Until `ha store reload` runs, the add-on page still shows the old version
+   and the release looks like it did nothing.
+
+Note that `release/1.0` is normally an *ancestor* of `master` between releases,
+so a `release/1.0 → master` pull request is empty until new commits land on
+`release/1.0`. That is expected; it means there is nothing to release yet.
+
+---
+
+## 2. Branch protection — before and after SEC-2
+
+Forge is Gitea at `192.168.2.147:3000`, repo `admin/goodwe-addon`. Read it back
+with `GET /api/v1/repos/admin/goodwe-addon/branch_protections`.
+
+**Before (2026-09-23):**
+
+| branch | protected | status check required | context | approvals |
+|---|---|---|---|---|
+| `master` (default) | **no rule at all** | — | — | — |
+| `release/1.0` | yes | yes | `checks / unit (pull_request)` | 0 |
+
+**After:**
+
+| branch | protected | status check required | context | approvals |
+|---|---|---|---|---|
+| `master` (default) | yes | yes | `checks / unit (pull_request)` | 0 |
+| `release/1.0` | yes (unchanged) | yes | `checks / unit (pull_request)` | 0 |
+
+Both rules are otherwise identical: `enable_push: false`,
+`enable_force_push: false`, `block_admin_merge_override: true`, no whitelists,
+no file patterns. `required_approvals` stays at **0** on purpose — raising it
+would block the review agent from merging, and nobody asked for it.
+
+The default branch was **not** changed. Changing it would change what the
+Supervisor clones, which is a different decision from this one.
+
+### How the gate was proven to actually bite
+
+A protection rule on this forge can *appear* satisfied while having checked
+nothing, so the rule was tested rather than trusted. The discriminator is a
+merge `POST` carrying a deliberately wrong `head_commit_id`: Gitea evaluates
+branch protection *before* it checks the head, so
+
+* `409 head out of date` → the request **cleared** protection;
+* `405 Not all required status checks successful` → protection **refused** it.
+
+Read the *message*, not just the code: `405` is also returned as
+`Please try again later` for a pull request with **no commits**, which has
+nothing to do with protection. An empty pull request on an unprotected base
+gives that same `405` (verified, throwaway PR #110), so an empty
+`release/1.0 → master` reports it too.
+
+Validated against a control on an unprotected base (PR #106), which answered
+`409` while its check was still pending — i.e. protection was no obstacle
+there. On `master` (PR #107) the same probe answered `405` while pending, and
+`409` once the check was genuinely green. A direct `git push` to `master` was
+rejected by the pre-receive hook with `master`'s SHA unmoved.
+
+---
+
+## 3. Rolling back
+
+There is no force-push escape hatch: `enable_force_push` is `false` on both
+branches. To undo a bad release, land a revert on `release/1.0`, bump the
+version again, and take it through §1. The `/addons/` rollback for the
+reference install is in `HANDOVER.md`.

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/SAFETY-56-what-the-gate-cannot-tell-apart.md

@@ -0,0 +1,181 @@
+# SAFETY-56 — what the gate cannot tell apart, said in the sentence
+
+**Text only. No behaviour changes in this card**, and §5 is the measurement that
+says so: the same stimuli through the tree before and after produce a
+**byte-identical** trace of every verdict, every `reading()`, every `inputs_ok`
+and every readiness row's `(ok, warn)`.
+
+---
+
+## 1. The defect
+
+0.10.1 is regulating a real GW5000S-BP. Two messages tell the operator that
+healthy hardware has failed.
+
+**The log line**, as emitted on the reference site on 2026-09-21:
+
+> SAFETY-37: inverter-a battery-power register **is not following its own
+> command** - STALE_READING: -3 unchanged for 36 s while the standing command
+> moved 800 W to +1600 W - **the reading is not following**, so it is reported
+> as MISSING rather than as a measurement … Treating it as MISSING, which
+> commands 0 W.
+
+**The readiness row**, at the same moment:
+
+> NOT READY — battery power: `sensor.kelder_goodwe_master_stage1_goodwe_inverter_ac_power`
+> **is missing or not numeric**
+
+That entity was present, numeric and updating.
+
+**SAFETY-37's conjunction is correct and is not touched by this card** —
+`unchanged > 35 s AND |command| > 250 W AND |travel| > 250 W`. A register
+genuinely stuck against a real command is exactly what it should catch, and a
+pack that cannot comply is a state the site must stop in too. What was wrong is
+what the sentences **concluded** from it.
+
+## 2. Two worlds satisfy the conjunction
+
+| | the register | the pack |
+|---|---|---|
+| **DEAD** | has stopped reporting reality | is doing what it was told |
+| **REFUSED** | is reporting reality correctly | cannot comply — the BMS is refusing at its floor |
+
+A refused pack holds still under any setpoint, so an honest register publishes
+the same unchanged number a dead one does. **Nothing `freshness.py` is handed
+separates them.** All three sentences asserted DEAD.
+
+## 3. The live episode was REFUSED, and it is measured, not argued
+
+Off the committed capture `scenarios/safety57-2026-09-21/bus-a-2026-09-21-1030-1110.log.gz`,
+whose bytes and decoder are already graded by `test_freshness.py` part 10a:
+
+| | |
+|---|---|
+| the register | answered **-3 W for 850 s**, 10:51:24 → 11:05:34 |
+| the commands during that hold | **+260, +660, +1060 W** — discharge only, never a charge |
+| pack SoC throughout | **11 %** |
+| first **charge** command after the restart | 11:05:31 at **-400 W** |
+| the register moves | **11:05:34** — **3 s**, inside one 17.0 s obligation window |
+
+**A register that answers a reversed command inside one obligation window had
+not stopped reporting.** What would not move was the pack. The sentence the
+operator read named the one thing in the loop that was telling the truth.
+
+⚠️ What this does **not** establish: that no register is ever intermittently
+wrong. It excludes a register that had simply stopped; it cannot exclude one
+that was wrong and then right. That is the point — the new sentence claims
+neither.
+
+## 4. The fix, and why it is three sentences and not one helper
+
+Each message states **what was observed** and names **both** explanations.
+
+| where | before | after |
+|---|---|---|
+| `app/freshness.py` `_grade()` | *"…+1600 W - the reading is not following, so it is reported as MISSING…"* | *"…+1600 W. **TWO THINGS LOOK LIKE THIS AND THIS GATE CANNOT TELL THEM APART**: the register may have stopped reporting reality, or the source may be unable to comply with the command - a pack the BMS is refusing holds still under any setpoint, and an honest register then reads exactly like a frozen one. Either way the number cannot be read as this command's effect, so it is reported as MISSING…"* |
+| `app/main.py` `_read_unit()` | *"SAFETY-37: %s battery-power **register is not following its own command** - %s."* | *"SAFETY-37: %s battery-power reading **did not move under a command that did, WHICH IS NOT BY ITSELF A VERDICT ON THE REGISTER** - %s."* |
+| `app/main.py` `checks()` | *"{label}: {entity} **is missing or not numeric**"* | *"{label}: **no usable value this cycle from** {entity} - **and this row cannot tell which of two things that is**: the entity is missing or not numeric, or it is publishing a number that this controller is withholding (a freshness gate does exactly that, and names itself in a row of its own). Confirm the entity in Developer Tools before replacing it"* |
+
+**Three sentences, three wordings, no shared helper.** The first two are a log
+line about a **behaviour**; the third is a banner about a named **entity**, and
+the two answer different questions ("what did the register do" against "can I
+trust this entity"). A helper serving both would have to drop whichever half
+the other caller does not need, and the half it dropped would be the
+operator's next step. The log line names the pair **once**, inside the `%s` it
+already interpolates, rather than in both of its own halves.
+
+**No new input, and SoC is not wired.** `BOUNDS["soc"]` stays *STATED, NOT
+WIRED*; telling the two worlds apart needs the pack floor (SAFETY-32's number)
+and SoC (TEL-08's wiring), and a message honest about its own ambiguity needs
+neither. Part 11b drives the two worlds at **50 %** and **11 %** SoC and
+asserts the sentence does not move one byte.
+
+**The readiness row does not branch.** `inv.batt_fresh.stale` is on the same
+object at the same moment, and the row deliberately does not ask it: the same
+loop renders the grid and SoC rows, which have no gate, and a branch per row
+would be a second place where "why is this None" is decided. The gate already
+has a surface — `stale_note()` rides `liveness_notes()` a few rows below with
+the whole STALE_READING sentence in it — so the operator's discriminator is
+*"is that row there?"*, and part 11d asserts that row is **present in REFUSED
+and absent in ABSENT**.
+
+## 5. Behaviour is byte-identical, measured
+
+`tools/safety56_behaviour_trace.py` prints two documents from one stimulus set.
+The `behaviour` half contains **no sentence**: only `stale`, `reading()`,
+`releases`, `held`, the window bookkeeping, `inputs_ok`, and every readiness
+row's `(ok, warn)`. Run in the CI image, purged, `:ro`, against
+`origin/release/1.0` **archived out of git** and against this branch:
+
+| | |
+|---|---|
+| the committed live capture | **2390 reads**, 7 verdict edges |
+| a swept grid of command × register schedules | **66 cells × 120 reads** — 1060 stale reads, 1309 `MISSING` readings, 6 releases |
+| six driven controller worlds through the shipped read path | DEAD, REFUSED, ABSENT, HEALTHY, RELEASE, RETRIP — every read's `(batt, inputs_ok, stale)` and every `checks()` row's `(ok, warn)` |
+| **result** | `6030175ed2ab9a4143e86e89a71d45c8ab041ac1c00121a3e3e023cd2b08996c` **on both trees** |
+
+⚠️ **AND THE CONTROL IS INSIDE THE TOOL, BECAUSE AN IDENTITY BETWEEN TWO TREES
+THAT ARE THE SAME TREE IS HABIT 4.** `--compare` refuses to report "behaviour
+unchanged" unless the `sentences` halves **differ**. This card's first
+invariance run was exactly that mistake — it archived a branch whose edits were
+not committed yet, so `before` and `after` were the same code and the identity
+was perfect and worthless.
+
+Both of the tool's refusals are **driven**, not asserted:
+
+| | |
+|---|---|
+| the same file compared with itself | `REFUSED: the sentences halves are IDENTICAL…`, exit **2** |
+| `MOVE_W` 250.0 → 240.0 in the after tree | `BEHAVIOUR MOVED at 'sweep_stale_reads' / 'sweep_missing_reads' / 'sweep_trace'`, exit **1** |
+| this card | `OK: sentences differ, behaviour is byte-identical.`, exit **0** |
+
+## 6. The mutation battery
+
+Each in its own `mktemp`'d copy (habit 18), purged on the host, mounted `:ro`,
+graded by `tools/mutation_run.sh` in the CI image.
+
+| | mutation | Δ bytes | named reds |
+|---|---|---|---|
+| M1 | `_grade()` reverted to *"the reading is not following"* | -402 | **3** |
+| M2 | the log line reverted to *"register is not following its own command"* | -80 | **2** |
+| M3 | the row reverted to *"{entity} is missing or not numeric"* | -619 | **2** |
+| M4 | *register* and *source* transposed between the two explanations | **0** | **1** |
+| M5 | the second explanation deleted, the first kept | -216 | **1** |
+| M6 | *"CANNOT TELL THEM APART"* replaced by *"IN ORDER OF LIKELIHOOD"* | -13 | **1** |
+| M7 | the REFUSED world's ground truth set to the DEAD world's | 0 | **2** |
+| M8 | the row's second cause deleted | -309 | **1** |
+| M9 | `label` and `entity` transposed in the row | **0** | **3** |
+| M10 | M1 + M2 + M3 together, i.e. exactly what 0.10.1 ships | -1101 | **5** |
+| M11 | the accusation literals replaced by one that matches nothing | 0 | **1** |
+
+⚠️ **M9's first run was a defect in this card's own check, and it is the one
+worth reading.** The row was fetched with `[...][0]`. Transposing `label` and
+`entity` makes the row unfindable, so the run died on an `IndexError` — a red
+with **no name attached**, with every check after that line **ungraded**. That
+is FCST-06's shape exactly. `_s56_row()` now returns a named absence instead of
+raising, and a precondition grades it: **0 named reds before, 3 after.**
+
+⚠️ **M11 is the other one aimed inward.** `not any(...)` over an empty list is
+True, and so is one over three mistyped literals. The positive control runs the
+same predicate against the three sentences **as 0.10.1 shipped them** and
+requires it to find an accusation in every one, and every literal to match at
+least one of them (habit 7: vary one thing from an accepted baseline).
+
+## 7. What part 11 does not grade
+
+* It does not show the live episode was a BMS refusal beyond doubt — see §3.
+* It does not grade English. A sentence that named both explanations and then
+  said something useless about them would pass.
+* The `no entity configured` branch beside the rewritten row is untouched and
+  ungraded: a blank entity really is the only thing it can be.
+* The **grid-power and battery-SoC rows** go through the same rewritten line and
+  have no freshness gate today, so for them the second cause is a hypothesis
+  about this controller rather than a live possibility. That is weaker than the
+  battery-power case and is the price of not branching per row. A gate on either
+  signal — TEL-08 would be one — makes it exact.
+* **SAFETY-58 is not touched** (the first read after a long rest trips before a
+  healthy register could answer), and neither is the 710/790 disagreement
+  between `test_freshness.py` and the changelog. Both are separate cards; the
+  second has a **fourth site** at
+  `DECISIONS/SAFETY-57-the-exit-from-a-stale-verdict.md:274` that a fix written
+  off the PR table alone would miss.

goodwe_controller/DECISIONS/SAFETY-57-the-exit-from-a-stale-verdict.md

@@ -0,0 +1,388 @@
+# SAFETY-57 — the stale-reading verdict gets an exit, because its own consequence is what stopped it being tested
+
+**Status:** decided and implemented on branch `SAFETY-57`, off `origin/master` @ `6f5e8e3`
+(content-identical to `release/1.0` @ `8a57361`).
+**Card:** SAFETY-57 — *"the freshness gate has no exit reachable from inside the state it creates"*.
+**Nothing here reached the inverter.** No contact was made with 192.168.2.158 or
+192.168.2.221. The one live system touched is `sniffer@192.168.2.167`, a
+**passive** RS-485 listener with no address on the bus, and it was read only.
+
+---
+
+## 0. The five things a reader should take away
+
+1. **The live episode is reproduced from the wire, not modelled.** The capture
+   is committed, the decoder is committed, and the box that produced it was
+   running the defect — so the `0 W` in the trace *is* the add-on's own
+   `inputs missing → command 0 W`. §2.
+2. **Option 2 from the card — "do not arm the gate when the command is 0 W" —
+   already holds, and it is not the bug.** `_grade()` has required
+   `|standing| >= MOVE_W` since SAFETY-37. The trip happened at **+1060 W** and
+   the stuck state is at **0 W**; they are different moments. §3.
+3. **The decision is not "how long", it is "when".** The verdict is withdrawn
+   when the **obligation that produced it is no longer standing** — SAFETY-13's
+   shape one module over. The 17.0 s is the obligation window that was already
+   derived in the file, taken at the **floor** of its band, and which half is
+   safe is the **opposite** of SAFETY-13's. §4.
+4. **It costs 52 % exposure on a permanently dead register, and that number is
+   in the suite so it cannot be forgotten.** It is payable only because one
+   re-grading window (35 s) is shorter than both consumer holds (75 s, 85 s).
+   **No detection SAFETY-37 had is given back.** §5.
+5. **The battery had been rescuing this code by accident.** 93 trips in the
+   committed 16-day capture; median wait for the BMS keep-alive pulse that
+   cleared them **143 s**, worst **5 h 57 m**. §6.
+
+---
+
+## 1. What was there, in the terms the code uses
+
+`freshness.py`, `Freshness.submit()` and `_grade()`:
+
+```python
+if self.changed_mono is None or value != self.held:
+    ...
+    self.stale = False          # the only place the latch is cleared
+def _grade(self, standing_w, now_mono):
+    if self.stale or self.changed_mono is None:
+        return                  # sets the latch; never clears it
+```
+
+and `main.py:1777`, `inv.batt = inv.batt_fresh.reading()`, where `reading()`
+answers `None` while `stale`. `inputs_ok` sees the `None`, the site holds for
+`stale_input_s`, then files `Claim.set("safety", P_SAFETY, 0.0, "inputs
+missing")` and keeps filing it.
+
+The reason the latch exists is written in the class docstring and it is a good
+one: without it the verdict oscillates at about 1 Hz, because declaring the
+reading stale drops the command below `MOVE_W`, which un-arms the conjunction,
+which hands the held number straight back.
+
+**The defect is that the only thing that ends it is an arrival carrying a
+different number — and the state's own output is what stops the register being
+asked for one.** The log line promised the opposite, in the same sentence that
+announced the 0 W:
+
+> *Treating it as MISSING, which commands 0 W. It clears itself the moment the
+> register reports a different value.*
+
+---
+
+## 2. Reproducing it, from the wire
+
+`scenarios/safety57-2026-09-21/bus-a-2026-09-21-1030-1110.log.gz` is 3840
+verbatim frames off the RS-485 pair, 10:30–11:10 Europe/Brussels, decoded by
+`tools/decode_bus_capture.py`. The decoder reports **0 unparsed, 0 bad CRC,
+0 unknown shapes**, and its mode→sign convention is **graded off the capture**
+rather than trusted: 298 commands at or under −1000 W are each answered one
+obligation window later by a negative register reading, and not one positive.
+
+| capture time | on the wire |
+|---|---|
+| 10:51:14 | `0x0518` = **−447 W**; the loop is charging |
+| 10:51:19 | the command reverses: EMS **mode 3**, 260 W of discharge |
+| 10:51:24.7 | `0x0518` = **−3 W**. The pack is at **11 %**, the BMS refuses the discharge, the inverter idles. **The register is healthy and truthful.** |
+| 10:51:29.7 | the command reaches **+1060 W**. 800 W of travel |
+| 10:52:21.7 | the setpoint is written **0 W** — this is the add-on's own §11.1 rule 1, recorded on the wire |
+| …850.0 s | `0x0518` does not change value |
+| …790.0 s | the setpoint does not change value |
+| ~11:04 | **a person restarts the add-on** — not visible in this file, and the only thing that ends the episode |
+| 11:05:31.7 | the restarted loop commands **−400 W of charge**, which the pack accepts at 11 % |
+| 11:05:34.7 | `0x0518` = **−137 W** |
+
+⚠️ **THE CAPTURE IS CLOSED-LOOP FOR THE WHOLE PARKED INTERVAL**, which is why
+this is a reproduction and not a simulation: the box was running 0.10.0, so
+every command in the trace is the shipped code's own. The only event inside the
+window the file cannot account for is the human restart.
+
+Replaying the shipped `_read_unit` loop at 1 Hz against those two series
+(`test_freshness.py` part 10b):
+
+| | stale at | clear at | parked |
+|---|---|---|---|
+| **before** (`release_s = inf`) | 10:52:00 | 11:05:35 | **815 s**, and `reading()` is `None` on all **812** reads from the trip to the first command a human put on the wire, with the register at −3.0 W in every one of them |
+| **after** | 10:52:00 | **10:52:39** | **39 s**, with `0x0518` still answering the same **−3 W** |
+
+⚠️ **THE COUNTERFACTUAL IS `release_s = inf`, AND IT IS GRADED RATHER THAN
+CLAIMED.** With an infinite bound `_release()` never fires, `_open_window()` is
+only ever called where the register moves, and the window pair is the
+change-stamp pair — byte-for-byte the pre-SAFETY-57 conjunction. Part 10b
+asserts that by driving part 1's own fresh/stale pair through both bounds and
+comparing the verdict streams.
+
+The replay also found a **one-read trip at 10:48:14** that clears one second
+later. That is a pre-existing false positive and it is now recorded as
+survivor 5 — §7.
+
+---
+
+## 3. What the card's option 2 actually buys, which is nothing here
+
+The card offered *"do not arm the gate when the command being graded is 0 W"*
+and warned that it might hold already. **It does, and it has since SAFETY-37**:
+`_grade()` returns at `abs(standing_w) < self.bound.move_w`, and
+`test_freshness.py` part 4 has a named check on that term, added because a
+mutation removing it survived.
+
+The warning in the card is the right one and it is worth writing down: **the
+trip and the stuck state are different moments.** The gate armed at **+1060 W**,
+where the conjunction is entirely correct — a command travelled 800 W and the
+register did not move for 35 s. The site then went to **0 W** *because of the
+verdict*. An entry-side rule cannot reach a state that is entered legitimately
+and then persists. **The defect is the exit, and nothing else in the conjunction
+is touched by this card.**
+
+Option 3 — probing with a small non-zero command — was not taken and does not
+need to be. It writes to a real actuator to test an assumption, and §4's rule
+does not need a probe: the site's *normal* control resuming is the test, and it
+is gated behind the same `inputs_ok` everything else is.
+
+---
+
+## 4. The decision: which verdicts get an exit, and what the bound is
+
+> The stale verdict holds as before, **unless** the obligation that produced it
+> is no longer standing — `|standing| < MOVE_W` — **and** it has been gone
+> longer than the register would have needed to answer it. On a release the
+> latch clears and a **new grading window** opens at that instant.
+
+This is [[SAFETY-13]]'s §4 in a different module, and deliberately so: that card
+established the house answer to "a latch with no exit" and its answer was *not*
+a plain time bound but a **predicate plus a time bound**, where the predicate
+says whether the state can end on its own. Here the predicate is that **the
+question is no longer being asked.** A register under a 0 W command is obliged
+to be nowhere, so a verdict about whether it is following cannot be tested, and
+a verdict that cannot be tested may not stand for ever.
+
+### 4.1 Why the window has to re-open, and what happens if it does not
+
+`_grade()` compares the register's unchanged time against `unchanged_s` and the
+command's travel against the command standing when the window opened. If a
+release cleared the latch **without** re-opening the window, the first read at
+which the resumed command travels 250 W would re-trip immediately — the
+register would never get the 17 s in which it could answer, and the live
+episode's recovery (a charge the pack **accepts**) would be killed inside two
+seconds. Mutating exactly that (`graded_from` re-anchored to `changed_mono`,
++82 B) takes four named checks red.
+
+The new window is `BATT_UNCHANGED_S` = **35 s**, the same bound as entry,
+because it is the same question — *does this register follow the commands issued
+from now on?* — and there is no principled shorter answer to it. It is also the
+number the exposure argument in §5 rests on, so it is not free to move.
+
+### 4.2 `RELEASE_S` = `BATT_OBLIGED_S` = 17.0 s, and which half is safe
+
+The quantity needed is *has the register had its chance to answer the command
+standing now?*, and `freshness.py` already derives it as the floor of
+`BATT_UNCHANGED_S`'s band:
+
+```
+6.0 s   plant          goodwe/NOTES.md §5.9, measured 2026-08-22
+10.0 s  publisher      firmware/goodwe-master.yaml:181, update_interval: 10s
+1.0 s   this add-on    run_control()'s await asyncio.sleep(1)
+```
+
+⚠️ **IT IS THE FLOOR OF ITS BAND, NOT A SENSITIVITY PREFERENCE** — the mirror of
+`MOVE_W` taking the **ceiling** of its own for the mirrored reason.
+
+| | the question | the safe half | why |
+|---|---|---|---|
+| SAFETY-13's `SETTLE_CYCLES` | may the plant still be the **explanation**? | the **longer** half | a shorter bound stops believing the plant too early, and then it accuses |
+| this one | may the verdict still be **tested**? | the **shorter** half | being wrong *long* is the failure being fixed; being wrong *short* costs one re-grading window, and §5 bounds that |
+
+Below 17.0 s the release pre-empts the **cheaper exit** — the register answering
+the new 0 W command by itself, which clears the latch on evidence rather than on
+a timer. That is graded behaviourally rather than asserted: a register that
+answers at +16 s clears by **movement** at `release_s = 17.0` with `releases`
+still 0, and by **timer** at `release_s = 5.0`.
+
+The family is computed and printed (habit 10): `5, 16, 17, 18, 35, inf` give
+six distinct release instants, so no check in the file can confuse two of them.
+
+### 4.3 Two clocks, and the operator reads the register's
+
+`changed_mono` / `unchanged_s()` remain facts about the **register**: after a
+release they go on reporting that it has not moved for 850 s, because it has
+not. `graded_from` / `graded_s()` are the **verdict's** window. They coincide
+until the first release. Collapsing them either lies to the operator or defeats
+the re-grading, and both directions are mutated red.
+
+The stale sentence's `unchanged for N s` slot carries the **register's** number;
+a re-trip appends a clause naming the window and the grade count, so the two
+durations cannot be read as one number that moved (habit 14).
+
+---
+
+## 5. What it costs, measured
+
+Driven against a register frozen for good, 1201 reads, shipped defaults
+(`test_freshness.py` part 10c):
+
+| | parked | the held number reaches a consumer | releases |
+|---|---|---|---|
+| before | 1166 s | **35 reads (2.9 %)** | 0 |
+| after | 571 s | **630 reads (52.5 %)** | 17 |
+
+⚠️ **52 % IS PAID EVERY CYCLE, NOT OCCASIONALLY.** The period is
+`stale_input_s` (15 s) + `RELEASE_S` (17 s) parked, then one 35 s window.
+
+It is payable because of one inequality, and it is the inequality
+`test_freshness.py` part 6 has graded against the shipped `config.yaml` since
+SAFETY-37:
+
+```
+35 s  (the re-grading window)  <  75 s  (circulation_hold_s)  <  85 s  (unit_sign_disagree_s)
+```
+
+Every unbroken run of exposure is **exactly one window**, so neither consumer
+can reach a verdict inside one, and the re-trip that ends each run hands them a
+`None`, which **clears** their windows rather than accumulating into them.
+
+**And nothing SAFETY-37 detects is given back**, which is the half that makes
+this a trade rather than a regression: a permanent `None` clears those same two
+windows for ever as well, so on the shipped-before module those detectors are
+*equally* unable to speak about the unit. What the held number does reach for
+35 s is `site_batt_w`, the anti-windup input of `control.compute()` — which
+answers a large unexplained divergence by **freezing the output**, the
+conservative direction and SAFETY-13's business — and the command itself is
+derived from the **P1 meter**, never from `batt`.
+
+### 5.1 The narrowing this does NOT take, named so the next card can
+
+The live episode's register refused a **discharge** into an 11 % pack and then
+followed a **charge** three seconds later. A refusal in one direction is not
+evidence about the other, and a gate that knew the pack's floor could re-grade
+on the first command that crosses it instead of on a timer — which would shrink
+the 52 % above. That needs SoC, which this module deliberately does not take
+(see the `soc` row and TEL-08), and the pack floor, which is SAFETY-32's number.
+It is **not needed to give the state an exit**, and folding it in here would
+make the exit depend on a second measurement being right.
+
+---
+
+## 6. The measurement that says the old exit was luck
+
+`scenarios/loop-2026-09-02_2026-09-17/` replayed at 1 Hz through the shipped
+conjunction (`test_freshness.py` part 8b): **93 trips in 16 days.** The only
+thing that could clear any of them was the register carrying a different number,
+and that took:
+
+| | |
+|---|---|
+| minimum | 0.6 s |
+| **median** | **143.4 s** |
+| maximum | **21440.1 s** (5 h 57 m) |
+| at or over the live episode's 710 s | **17 of 93** |
+
+The short waits are the BMS keep-alive pulse — SAFETY-50 measured its ceiling at
+508 W — twitching `0x0518` and satisfying the clearing rule **by accident**.
+Over a fifth of the trips are cleared in under 20 s by something nothing in this
+add-on asked for.
+
+⚠️ **WHAT THAT REPLAY IS AND IS NOT.** The capture runs 2026-09-02…17 and
+0.10.0 — the first version carrying this gate — was cut on 2026-09-16, so the
+setpoint column is an **ungated** controller's. That makes each trip an honest
+register-versus-command divergence off the real bus, and it makes the post-trip
+command column something a gated box would **not** have written. The figure
+taken from it is therefore the only one that does not depend on the command at
+all — how long this register goes without changing value — and it **under**-states
+the wait, because a site parked at 0 W gives the register even less reason to
+move than the one recorded here.
+
+---
+
+## 7. Survivors, and the two things the battery found
+
+The battery is 22 mutations over `app/freshness.py`, `app/main.py` and
+`tools/decode_bus_capture.py`, plus one over the committed capture itself. All
+run through `ci_run.sh`, a mirror of `checks.yml`'s own step: a purged copy of
+the tree, bind-mounted `:ro`, one file at a time, `PYTHONDONTWRITEBYTECODE=1`.
+Per MUTATION.md habit 18 the harness's scratch file is `mktemp`ed per
+invocation and the tree is fingerprinted **after the revert** as well as before;
+every revert restored the recorded sha256 and byte count.
+
+**21 red, 1 argued equivalent, 0 unexplained survivors.** The table is in the
+PR body. Two of them are worth keeping here.
+
+### 7.1 The equivalent mutant, argued rather than rounded off
+
+Swapping `_release()` and `_grade()` in `submit()` is a **zero-byte** edit and
+survived the whole battery. **It is not a missing fixture and no fixture can
+close it**: `_grade()` acts only when `|standing| >= move_w` and `_release()`
+only when `|standing| < move_w`, so at most one of them can do anything on any
+read, whichever runs first.
+
+⚠️ **THE FIRST VERSION OF THE CODE CLAIMED THE ORDER WAS LOAD-BEARING**, in a
+`⚠️` comment, with a reason that sounded right. It was false, and the battery is
+what said so — **MUTATION.md habit 22 exactly, one card later: an explanation in
+a comment is a claim, and this one had not been run.** The comment now states
+the disjointness, and part 10 pins **that** — at 0, 100, 249, 250, 251 and
+1300 W — instead of pinning an order that is not observable.
+
+### 7.2 The sibling that survived, which is habit 11 earning its place
+
+`_release()`'s obligation test is `abs(standing_w) >= self.bound.move_w`.
+Swapping `move_w` for `unchanged_s` — comparing **watts against 35** — survived
+the file at **+5 B**, because **every fixture rested at exactly 0 W**, and 0 is
+below both 35 and 250. They separate only in the band between them, and a site
+can sit there: a peak-guard floor, a shadow substitution, any claim that wins
+with a small non-zero number. Closed by a three-point fixture at 0 / 100 / 300 W
+that asserts the 100 W case releases and the 300 W case does not.
+
+### 7.3 ⚠️ And the instrument lied once, which is habit 16's second half
+
+The first form of the `graded_from` mutation was
+`float(self.changed_mono or now_mono)`. It reported a **survivor at +21 B**, and
+the tree fingerprint showed the edit really was on disk and really did run.
+`changed_mono` is **0.0** in the dead-register fixture, and `0.0 or x` is `x` —
+so the mutant was a *no-op on the fixture*, for a Python truthiness reason that
+has nothing to do with the property under test. Rewritten as an explicit
+`is None` test (+82 B) it is red on four named checks.
+
+**A mutation is subject to every habit in MUTATION.md, including habit 4.** A
+purge, a fingerprint and a byte delta all say the edit is present; none of them
+says the edit *changed the answer on this stimulus*. MUTATION.md gains habit 19
+for it.
+
+---
+
+## 8. What this does NOT fix, said plainly
+
+**It does not tell a BMS refusal apart from a dead register**, and it does not
+try to. Both are re-graded on the same timer. §5.1 names what telling them apart
+would need.
+
+**It does not make the diagnosis right.** The line the operator reads still says
+*"battery-power register is not following its own command"*, which is wrong in a
+different way when the pack is simply empty. That wording is **SAFETY-56's**,
+together with `main.py`'s NOT READY row, and it is deliberately untouched here —
+two cards editing one sentence is how one of them silently loses. Only the
+**escape clause** was rewritten, because this card is what made the old one
+false, and part 10h has a named check asserting the diagnosis half is still
+there so that rewrite has to be a deliberate act.
+
+> ⚠️ **SINCE SUPERSEDED, WHICH IS WHAT THAT CHECK WAS FOR.** [[SAFETY-56]] is
+> the deliberate act: all three sentences now name **both** explanations and
+> accuse neither, and part 10h's check is inverted — it requires the accusation
+> to be **gone**. Nothing else in this section moved; the escape clause above is
+> still this card's and is untouched by it. See
+> `DECISIONS/SAFETY-56-what-the-gate-cannot-tell-apart.md`, and
+> `test_freshness.py` part 11 for the graded pair of worlds.
+
+**Survivor 5 is older than this card and is not closed by it.** After a long
+rest the unchanged clock is already past 35 s, so the **first** read carrying a
+travelled command trips the gate — before the 17.0 s in which a healthy register
+could have answered it. The live capture contains one (10:48:14, cleared one
+second later). Its size is one `stale_input_s` hold, during which `cycle()`
+returns at `inputs missing {n}s` and commands nothing differently. Fixing it
+means measuring the unchanged clock from when the **obligation** appeared rather
+than from the register's last move, which re-derives the 35.0 s bound and is a
+different card.
+
+**Nothing was measured on two inverters.** Inverter B does not physically exist
+(`goodwe/NOTES.md` §1.1b). Every two-unit figure in `test_freshness.py` is two
+copies of A's behaviour with different numbers passed in.
+
+**No deploy is proposed.** 0.10.0 is on the reference install and this branch's
+CHANGELOG row is filed under it only because `test_version_gate.py` part 11b
+requires the newest heading to be a version. Moving it, and deciding whether a
+version is cut, is a PKG card's.

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/DECISIONS/TEL-11-pv-production.md

@@ -0,0 +1,351 @@
+# TEL-11 — the PV production channel
+
+*What was decided, what it was decided against, and what the evidence was.*
+
+## 0. The problem, in OPT-10's numbers
+
+Over sixteen days at the reference site the pack reached 90 % SoC on **two** of
+them, and **20.5 kWh of surplus left the site while the pack still had room** —
+**12.6 kWh** of it with the battery **not charging at all**. That single
+measurement is upstream of most of what else was found that week: the nightly
+floor, SAFETY-37's misdiagnosis, the SAFETY-57 deadlock, a 2 h 47 min saturation
+freeze.
+
+It cannot be **attributed**, because **PV production is recorded nowhere in this
+system**. Three causes need three different fixes:
+
+| cause | fix |
+|---|---|
+| there was no irradiance | none — the site behaved correctly |
+| production was there, charge power was limited | a limit, somewhere |
+| production was there, the pack had room, the optimiser declined | **the only software defect** |
+
+Guessing between them is how an optimiser gets tuned to solve a cloud problem.
+**This card adds the channel and does not do the attribution.** Ship it, let it
+record a week, OPT-10 picks it up with data.
+
+## 1. It is an HA entity, not a register — and that is a product decision
+
+The RS485 bus this add-on speaks carries the **battery** inverter it drives. On
+nearly every site the PV inverter is a different box from a different vendor,
+reporting into Home Assistant through its own integration; it is **not** on this
+bus and there is no reason it would be. So the signal comes from an entity:
+`pv_entity` takes whatever `sensor.*` the site's PV integration provides, any
+brand HA can read.
+
+Reading a register would have been cheaper on one house and wrong for a fleet —
+the trade [[product-not-one-house]] names.
+
+## 2. The sign convention: **positive is production**, and there is no `pv_invert`
+
+### The convention is derived, not assumed
+
+Two sign rules already ship, and both are recorded in `DOCS.md`'s *Sources*
+table rather than inferred here:
+
+* `meter_entity` — **positive must mean importing** (`meter_invert` flips it);
+* `batt_entity` — **`+` = discharging** (`batt_invert` flips it).
+
+Both are *"positive = power arriving at the house's AC bus"*. Production arrives
+there too, so **positive = producing** is the continuation of the shipped
+convention rather than a fresh choice.
+
+### Why an invert flag would be over-building
+
+The question is not "could a sensor be reversed" — it could. It is what a flag
+would **buy**, and the answer is nothing, for two reasons that do not apply to
+the two keys it would sit beside:
+
+1. **Those two quantities are read by the control path; this one is read by
+   nothing.** `inv.batt` feeds SAFETY-30's per-unit sign check and SAFETY-31's
+   circulating-power sensor (`_read_unit()`'s own docstring says so), so a
+   reversed battery sensor hands the site a plausible number it then **acts**
+   on — a latch that trips when it should not, or does not trip when it should.
+   `pv_w` reaches no decision at all (§4), so a reversed PV sensor cannot
+   mislead one.
+2. **Production is unipolar, so the error is self-announcing.** Battery power
+   and grid power are legitimately negative half the time, which is exactly why
+   a flipped sign is invisible in them. A PV array does not consume: a reversed
+   sensor reads **−4 kW at noon**, in the first day of the very history this card
+   exists to create. An invert flag would let an installer *hide* that by
+   flipping it to something that looks right, and a second place for the sign to
+   be wrong is a second thing to get wrong.
+
+So: the convention is documented in `config.yaml`, both translations, `DOCS.md`
+and `app/pv.py`, the value is published **exactly as the sensor reports it**,
+and there is no flag. `test_pv.py` part 1 pins `-8 W` through unchanged.
+
+### And no negative-value alarm either
+
+The tempting middle path — warn when the reading is negative — needs a
+threshold, because a PV inverter's own standby draw makes a small negative
+reading at night entirely ordinary. Any threshold here would be a number nobody
+measured, in a card whose whole subject is not fabricating numbers. The
+published row is the detector.
+
+## 3. Absence is never zero, and it is not "dropped" either
+
+This is the constraint that shaped the publication, and the obvious
+implementation fails it.
+
+`MqttPublisher.publish()` **skips** a `None` value. That is right for
+`circulation` — its note in `main.py` says a missing per-unit reading should
+leave the last figure standing rather than publish a zero that reads as health —
+and it is **exactly wrong here**: a skipped row leaves Home Assistant holding
+the last number it was told, *forever*, and the recorder then draws a **flat
+line at that value through the outage**. Read back a week later that is
+indistinguishable from a real measurement, and if the last value happened to be
+small it manufactures precisely the *"there was no surplus to store"* conclusion
+the card exists to **test**.
+
+So TEL-11 publishes the absence, using Home Assistant's own mechanism:
+
+> `homeassistant/components/mqtt/const.py`: `PAYLOAD_NONE = "None"`.
+> `homeassistant/components/mqtt/sensor.py`, in the state-message handler:
+> `if payload == PAYLOAD_NONE: self._attr_native_value = None; return` — and it
+> is tested **before** the numeric branch, so it holds for a row carrying
+> `device_class: power`.
+> (github.com/home-assistant/core, branch `dev`, retrieved 2026-09-24. The
+> shipped MQTT-sensor documentation says the same thing in its `state_topic`
+> entry: *"a 'None' value will set the sensor to an unknown state"*.)
+
+The entity therefore goes to **`unknown`** and the recorder stores a **gap**.
+`mqtt.ABSENT_AS_UNKNOWN` is a one-key set and `test_pv.py` part 3 asserts both
+that the pv row gets this treatment **and that `circulation` still does not** —
+widening the rule silently would be a behaviour change to another card's row.
+
+⚠️ **What was NOT built, and why.** A per-entity `availability` block
+(`availability_mode: all`, an extra retained topic) would also produce a
+distinguishable state — `unavailable` rather than `unknown` — but it needs a
+second topic, a second retained message, a change to `_payload()`'s
+byte-order-sensitive key construction, and it survives restarts only if the
+retention is right. The payload route is one branch in `publish()` and one
+constant, and it is graded as **bytes on the topic** rather than as a claim
+about HA's availability handling.
+
+### Three states, not two
+
+| state | frame | wire | page |
+|---|---|---|---|
+| no source (`pv_entity` unset) | no `pv` key | no topic, no entity | no row |
+| no reading | `pv: None` | `goodwe_ctl/pv` = `None` | `PV —` + a caution naming the reason |
+| zero watts | `pv: 0.0` | `goodwe_ctl/pv` = `0.0` | `PV 0 W` |
+
+A failed read also **clears** the last good value (`_read_pv()` assigns on every
+call), so a reading never outlives its own sensor. `test_pv.py` part 2 drives a
+good read followed by a dead one, because a fixture that answers the same thing
+forever cannot reach that failure — MUTATION.md habit 9's shape.
+
+## 4. It must not become a control input, and that is graded twice
+
+### In the suite
+
+`test_pv.py` part 6 drives twelve cycles of the real `Controller.cycle()`
+against a 6 kW export and asserts the commands written to the inverter are
+**bit-identical** across `unset` / `no reading` / `0 W` / `8 kW` of production,
+with a precondition check that the stimulus commands something at all (habit 1).
+`inputs_ok` is asserted not to move either: a broken PV integration is **not** a
+missing input, because nothing computes with it.
+
+A computed census (habit 12 — the scope is derived from the tree, not typed)
+then reports which of the 33 modules under `app/` mention the material in any
+spelling, comments included. It is **three**: `pv.py`, `main.py`, `mqtt.py`. The
+scanner's own red direction is exercised on every run.
+
+### Across trees, by hash
+
+`tools/safety56_behaviour_trace.py` is the pattern; `tools/tel11_pv_trace.py` is
+this card's version of it, and **its control clause had to be different**, which
+is worth stating because the difference is the interesting part.
+
+SAFETY-56 changed wording and had to show behaviour did not move, so its
+`--compare` **refuses** unless the `sentences` halves **differ** — otherwise the
+two runs might be one tree twice. TEL-11's headline claim is the opposite shape:
+with the option unset, **nothing** differs. "The documents are identical" is the
+*result*, so it cannot also be the control. The two things proved instead are:
+
+* the two runs came from **different trees** (`app/*.py` sha256 + byte count,
+  compared, and an identity is **refused**);
+* **exactly one** side reacts to `pv_entity` — that side is the HEAD, the other
+  is a tree that does not have the option. Neither, or both, is refused.
+
+It drives 41 stimulus cells (5 grid worlds × 8 PV schedules, plus a run stopped
+part-way) and prints two documents per setting: `control` — every command
+written, every `self.target`, `inputs_ok`, the loop's three fields, the
+arbiter's resolution, the maintenance phase, tick by tick, **with no TEL-11
+material in it** — and `telemetry`, which is everything the card is allowed to
+move.
+
+Measured, in the CI image, on purged trees:
+
+```
+  HEAD is B; baseline is A (it does not react to `pv_entity`).
+  tree      A 73296909170ec789237d6e704cce9ab0d9f83b3df1495a14d2497285c3041a12
+  tree      B d5011b6a18e2e3803dc09cac0214b0378fa4c7388fc0ad8ad89b832a5c92af48
+  control   A unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B set   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  telemetry A unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B set   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+OK  1/3  UNSET: control AND telemetry are byte-identical to the baseline tree.
+OK  2/3  SET: the control document is byte-identical with the channel switched on.
+OK  3/3  CONTROL OF THE CONTROL: the telemetry document DOES move when the
+         option is set (42 stimulus cells differ).
+```
+
+Note what clause 1 claims and clause 2 does not: **unset** is identical in
+`control` *and* `telemetry`, which is stronger than "the control path is
+untouched" — an install that does not set the option sees no change of any kind,
+including its announcement and its status rows. **Set** is identical in
+`control` only, which is the whole of "instrumentation, not an input".
+
+## 5. Genuinely optional — and not a second `price_now_entity`
+
+`price_now_entity` / `price_avg_entity` are legal **only** while
+`price_provider` is `off`, and the add-on **refuses to start** otherwise. That
+is the trap this card was told not to rebuild, and it is avoided structurally
+rather than by intention:
+
+* `validate.py` does not mention `pv_entity` at all. It cannot conflict with
+  anything, because nothing else reads it.
+* the MQTT row lives in `OPTIONAL_SENSORS`, not `SENSORS`, and
+  `discovery_payloads()`'s new `include` argument **defaults to empty**. So a
+  caller that has never heard of `pv_entity` — every fixture in `test_mqtt.py`,
+  `tools/rehearse_roster.py`, anything written next year — announces exactly
+  what it announced before. `p1_age` solves the same problem the other way
+  round, with `omit`, because it is announced by default and withdrawn when the
+  meter is off; getting that direction wrong here would have left most installs
+  with an entity nothing feeds, which is the hazard `omit`'s own note names.
+* the read is gated on the option, so an unset install makes **no state call at
+  all** — not a read that fails quietly.
+* there is **no status row** when it is unset. `peak_forecast_entity` nags when
+  it is unset because an unset forecast leaves a money guard without an input;
+  this is instrumentation, and a permanent caution on every install that never
+  asked for a PV channel is the warning spam the card forbids.
+* when it **is** set and the read fails, the row is `ok=False, warn=True` — a
+  **caution**. `status_payload()` builds `NOT READY` out of rows that are
+  neither `ok` nor `warn`, so a telemetry channel can never put a battery site
+  into `NOT READY`.
+
+## 6. The unit is read off the entity, and an unreadable one is refused
+
+`read_inputs()` guesses kW-or-W for `peak_forecast_entity` with
+`abs(raw) < 50`, and that is safe there: nobody's quarter-hour demand forecast
+is 50 W. It is **not** safe here — 30 W of real production at dusk is an
+ordinary reading, and that heuristic would publish it as 30 kW.
+
+So `pv.watts()` reads the entity's own `unit_of_measurement` and converts
+against Home Assistant's own `UnitOfPower` table (`mW`, `W`, `kW`, `MW`, `GW`,
+`TW`; every factor an exact power of ten). A sensor with **no** unit, or a unit
+outside that table, is **refused by name** and the status page says which. The
+refusal is loud; a guess would be silent, and a factor of 1000 in the one
+channel that exists to be believed a week later is the worse failure.
+
+⚠️ `BTU/h` is in HA's enum and is deliberately **not** in the table: its factor
+is a measured conversion rather than a decimal shift, no PV integration
+publishes in it, and a fabricated constant is what this repository's whole
+process exists to prevent. It lands in the refusal, by name, and `test_pv.py`
+part 1 pins that.
+
+## 7. The mutation battery
+
+Every check this card adds was driven by the mutation that defeats the claim it
+names. Method: `cp -a` of the tree per mutation into a **unique** directory,
+the edit applied there, `__pycache__` purged, the suites run in the CI image
+with the tree bind-mounted `:ro`, one file at a time. **The shipped tree is
+never edited**, so habit 18's revert hazard — SAFETY-37's harness killed between
+the edit and the `cp` that put the file back, and two harnesses sharing one
+backup path — is closed by construction rather than by a verified revert. Each
+row below records the byte delta, the file's sha256 before and after, and that
+the mutated line was **read back off disk** before the run started.
+
+| # | mutation | file | bytes | sha256 (first 16) before → after | red on |
+|---|---|---|---|---|---|
+| M1 | the `pv` row moved into `SENSORS`, i.e. announced on every install | `mqtt.py` | −79 B | `328d249b9d698ef6` → `532d3954c023bf3d` | 3 named in `test_mqtt.py`, 1 in `test_pv.py` |
+| M2 | `publish()` drops a `None` `pv` row again, so HA keeps the last number | `mqtt.py` | −98 B | `328d249b9d698ef6` → `dd54be458f446475` | 1 named (the acceptance criterion itself) |
+| M3 | `ABSENT_AS_UNKNOWN` widened past the one key it was written for | `mqtt.py` | +23 B | `328d249b9d698ef6` → `8fe571ebff3dacf4` | 1 named (`circulation` must still be dropped) |
+| M4 | a dead sensor reported as **0 W** instead of an absence | `pv.py` | −1 B | `55ba7471e9995436` → `9eecc34152b7ac12` | 4 named |
+| M5 | `_read_pv()` assigns only on a good read — a value outlives its sensor | `main.py` | +46 B | `c4d2cab34e50b5fd` → `189802aa69ce166d` | 2 named |
+| M6 | the unit is read and then ignored — a kW sensor published as watts | `pv.py` | −18 B | `55ba7471e9995436` → `ab19ef66c52f9379` | 2 named |
+| **M7** | **`self.grid = self.grid − self.pv_w` in `read_inputs()` — PV wired into the control path** | `main.py` | +106 B | `c4d2cab34e50b5fd` → `c38216edb7c5c8db` | **2 named, plus `tel11_pv_trace.py` clause 2/3 on 26 of the 41 stimulus cells** |
+| M8 | `optional_keys()` returns `("pv",)` unconditionally | `mqtt.py` | −52 B | `328d249b9d698ef6` → `86ff23efe3088ad8` | 3 named |
+| M9 | the PV caution made a `bad` row, i.e. a dead sensor is a `NOT READY` | `main.py` | +1 B | `c4d2cab34e50b5fd` → `45c74cab89943564` | 1 named |
+| M10 | the read gate removed — an unset option is read once a second forever | `main.py` | −10 B | `c4d2cab34e50b5fd` → `b67baa8aba3019e8` | 2 named, **plus two crashes** |
+
+`on_disk = True` for all ten: the mutated line was grepped back out of the file
+after the edit and before the run (MUTATION.md reporting rule 2), and no
+mutation is size-preserving, so rule 1's `+0 B` caveat does not arise.
+
+⚠️ **M10's two extra reds are CRASHES, not named checks, and that is recorded
+rather than tidied away.** Every `Hass` double in `test_inverter.py` and
+`test_telemetry.py` predates this read and has no `state()` method, so an
+unconditional PV read is an `AttributeError` rather than a failed assertion —
+habit 20's shape, a red with no name attached. Fixing those fixtures would be a
+change to what *their* checks report and belongs to whoever next touches them;
+this card's own fixture has `state()` and grades the property by name.
+
+⚠️ **M7's trace limb is where the two halves meet.** The mutant moves the
+control document on 26 of 41 cells — every cell whose PV schedule produces a
+READING. The five `none` cells and the five `zero` cells do **not** move, which
+is correct and is worth seeing: subtracting nothing, and subtracting zero,
+change nothing. A battery that only drove a dead sensor would have reported this
+mutation as a survivor for the third time.
+
+The clean tree those `before` hashes belong to: `app/main.py`
+`c4d2cab34e50b5fd`, `app/mqtt.py` `328d249b9d698ef6`, `app/pv.py`
+`55ba7471e9995436`.
+
+### ⚠️ M7 was a SURVIVOR on the first battery, and the fixture was the reason
+
+The card's **central** mutation — `self.grid = self.grid - self.pv_w` in
+`read_inputs()`, i.e. exactly the defect the whole card forbids — came back
+**green** on a six-file run at **+106 B**, on disk, purged, genuinely running.
+
+The property did not hold; the fixture could not reach it. `test_pv.py` part 6
+drove a **6 kW export over 12 cycles**, which puts the loop **against its
+rail**: the command moves `slew_w` every cycle and −6000 W and −14 000 W of
+apparent error produce the **same ramp, tick for tick**. MUTATION.md habit 23,
+with a saturated actuator in place of a coinciding value — and the habit's list
+of no-op-prone constructs is all *expressions*, so this is worth its own entry,
+which it now has.
+
+The fixture now drives a **600 W import the loop settles on**, with a
+responsive meter (`grid = base − batt`) so the error actually closes, asserts
+the resting target is well inside the rail, and asks habit 23's own question as
+its own check: **shift the meter by the same 8 kW and confirm the commands
+really would have moved.** On the first fixture that question answers *no*, in
+one line. Every number in the table above is from the battery re-run against
+the fixed tree.
+
+⚠️ **A red count is a property of the suite as much as of the mutation.** These
+name **this** tree at this commit; a later card that adds or re-bases a check
+moves the number with the mutation untouched. Re-measure rather than inherit.
+
+## 8. What none of this covers, with shapes
+
+* **Home Assistant itself.** That `None` renders as `unknown` and that the
+  recorder keeps a gap is read out of HA's source and quoted in §3; no HA runs
+  in this suite. What is graded here is the bytes this add-on publishes.
+* **Whether the operator's sensor tells the truth.** A sensor wired backwards,
+  or reporting DC where AC was meant, or a string instead of the array, is
+  published faithfully. §2 is the argument for why that is the right failure
+  mode; it is not a claim that it cannot happen.
+* **A roster of more than one.** The row is a **site** row — there is one PV
+  array as far as this add-on is concerned — so nothing per-unit exists to
+  separate, and every fixture is the shipped roster of one.
+* **The attribution.** This card records production. Whether the 20.5 kWh was
+  cloud, a limit or the optimiser is OPT-10's, and it needs a week of this
+  channel's history before it can be asked.
+* **`tools/`, the firmware and the ingress HTML** are outside part 6's census.
+* **The identity is only as wide as the stimulus.** `tel11_pv_trace.py` prints
+  its 41 cells with the documents for exactly that reason.
+
+## 9. No `CHANGELOG.md` entry
+
+`test_version_gate.py` 11b refuses a newest `## ` heading that is not
+`config.yaml`'s `version:`, and opening an `## Unreleased` section would mean
+taking a packaging decision this card does not get to take. The operator account
+is in `DOCS.md`; the release note belongs to the next PKG ticket, which should
+say that **0.10.1 → next** adds one optional key, announces no new entity on an
+install that does not set it, and changes no control behaviour.

goodwe_controller/DECISIONS/TEL-12-several-pv-inverters.md

@@ -0,0 +1,359 @@
+# TEL-12 — several PV inverters, and why a partial total is worse than none
+
+TEL-11 shipped `pv_entity` as a single `str?` in 0.11.0. The owner of the
+reference site reported **within minutes of it going live** that they have
+several PV inverters and could configure one.
+
+That is not a property of one house. A multi-string or multi-orientation roof
+routinely carries two or three inverters, each publishing its own power sensor
+into Home Assistant, and the add-on is sold to clients. So the channel had to
+become a roster.
+
+**OPT-10 is blocked on this and cannot start recording until it lands.** Which
+sets the bar: the number this channel publishes has to be one an attribution can
+believe, or the week of history OPT-10 is waiting for is worse than no history.
+
+---
+
+## 1. The surface: `pv_entities` beside `pv_entity`, and the measurement that
+decided it
+
+Two candidates, and they differ on exactly one question nobody in this
+repository could answer by reading: **does Supervisor accept a stored STRING for
+a key whose schema has become a LIST?** 0.11.0 shipped `pv_entity: str?`; the
+live install *has* a string persisted in it; and an upgrade that refuses that
+string leaves an add-on which will not start — CFG-04 §B's trap, in the other
+direction, with the schema needed to fix it pinned to the version that cannot be
+installed.
+
+It was measured, against the release image, by a new **§G** of
+`tools/supervisor_shape_probe.py` — the instrument CFG-04 built for exactly this
+kind of question:
+
+```
+docker run --rm -v "$PWD:/w:ro" -v "$PWD/tools:/probe:ro" --entrypoint python3 \
+  ghcr.io/home-assistant/amd64-hassio-supervisor:2026.08.0 \
+  /probe/supervisor_shape_probe.py
+```
+
+```
+== G. TEL-12: the SHAPE of a several-inverter PV option ==
+  PASS  the shipped defaults with a 0.11.0 `pv_entity` STRING on top are ACCEPTED - the baseline every refusal below is varied from
+        pv_entity='sensor.pv_power' pv_entities=[]
+  PASS  ⭐ THE MEASUREMENT THAT DECIDED THE SURFACE: with `pv_entity` declared as a LIST, the string an 0.11.0 install has persisted is REFUSED, and the refusal names the key - so that shape would leave the live add-on unable to start on upgrade
+        Invalid list for option 'pv_entity' in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...and a shipped `pv_entity: []` DEFAULT does not rescue it: deepmerge's list strategy is `override`, so the operator's string survives the merge and is refused anyway
+        Invalid list for option 'pv_entity' in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...(the list shape itself is fine - it is only the STORED STRING it refuses, which is what makes this a migration and not a schema question)
+        a list value validates
+  PASS  ⚠️ ONE SPELLING DOES ACCEPT BOTH - `match(.*)?` - AND IT IS REJECTED FOR A DIFFERENT REASON, MEASURED HERE: it validates NOTHING. A string passes, a list passes, and so does the integer 417; and the Configuration tab renders it as a plain text box rather than a repeatable field, so an operator cannot enter a second inverter in the UI at all
+        string=True list=True integer-417=True ui=[{"name": "pv_entity", "optional": true, "type": "string"}]
+  PASS  ⭐ THE SHIPPED SHAPE: an 0.11.0 blob - `pv_entity` a string, no `pv_entities` key at all, because it did not exist when that blob was written - validates against THIS manifest, with the new key defaulted to the empty list. The live install upgrades without touching its options
+  PASS  ...and a three-entity roster validates, per-entry, with both keys set - which the add-on resolves by REPLACEMENT and says so on its status page
+        ["sensor.pv_east", "sensor.pv_west", "sensor.pv_garage"]
+  PASS  ⭐ ...and the shipped `options:` block with ONLY `pv_entities` removed is REFUSED, BY NAME - `Missing option 'pv_entities' in root`. That is why the `pv_entities: []` default is load-bearing, exactly as `inverters: []` is: Supervisor treats a nested list as required unless its element is an OPTIONAL scalar, and `- str` is not one
+        Missing option 'pv_entities' in root in GoodWe RS485 Controller (local_goodwe_controller)
+  PASS  ...and the Configuration tab renders it as a REPEATABLE string field (`multiple: true`), so an operator adds their second and third inverter in the UI rather than in YAML
+        [{"name": "pv_entity", "optional": true, "type": "string"}, {"name": "pv_entities", "multiple": true, "required": true, "type": "string"}]
+  PASS  a DOWNGRADE to a schema without `pv_entities` drops the key with a warning rather than refusing, and leaves `pv_entity` standing - so rolling back to 0.11.0 returns the install to its single entity rather than bricking it
+
+== all cases passed ==
+```
+
+| Claim | Evidence |
+|---|---|
+| **Option 1 — `pv_entity` becomes a list — cannot ship** | §G: `Invalid list for option 'pv_entity'` on the string an 0.11.0 install has stored |
+| …and a `[]` default does not rescue it | §G: `_OPTIONS_MERGER`'s list strategy is `override`, so the operator's string survives the merge and is refused anyway |
+| …and it is not a *schema* problem | §G: a list **value** validates fine against a list schema. It is a **migration**, and a migration is a bigger ticket than this |
+| **One key CAN carry both shapes** — `match(.*)?` | §G, and reported even though it *passes*, because "no spelling accepts both" would have been a **false reason** to reject option 1 |
+| …and it loses anyway, for a measured reason | §G: it validates nothing at all — a string, a list, and the integer `417` all pass — and the Configuration tab renders it as a plain text box, so an operator cannot add a second inverter in the UI |
+| **Option 2 — `pv_entities` beside `pv_entity` — ships** | §G: the 0.11.0 blob validates untouched, the new key defaults to `[]`, three entities validate, the UI renders `multiple: true` |
+| `pv_entities: []` in `options:` is load-bearing | §G: the shipped defaults **minus only that key** are refused with `Missing option 'pv_entities' in root` — CFG-04 §B's isolated counterfactual, for this key |
+| A downgrade is not the trap in reverse | §G: a schema without the key **drops** it and leaves `pv_entity` standing |
+
+`p1_phase_import_entities` (`options: []` + `schema: - str`) is the shipped
+precedent for the pair; nothing new was invented.
+
+**So the surface is uglier than option 1 and that is the correct trade.** The
+cleanest surface that breaks the one install this card exists to fix is not the
+cleanest surface.
+
+### And `pv_entities` REPLACES `pv_entity` rather than extending it
+
+CFG-04's rule for `inverters:` ("declared, it REPLACES those six keys"), applied
+to the only upgrade path that matters. The install being upgraded **has**
+`pv_entity` set, to inverter A. Opening the Configuration tab, the natural action
+is to put *all* the inverters in the new repeatable field — and under a union
+rule that **double-counts A** unless the operator also remembers to clear the old
+key. A doubled total is the same defect as a partial one pointing the other way,
+in the one channel that exists to be believed a week later.
+
+Under replacement the effective roster is exactly what one key says, and no
+arithmetic depends on a de-duplication rule the operator has to know about. It
+de-duplicates *within* the list (a site cannot have two sensors with one
+entity_id, so a repeated id is a typo that would double that inverter), and
+`Controller.checks()` prints a **caution** whenever both keys are set saying
+which one won — a replacement nobody is told about is the "one of which silently
+wins" `config.yaml` refuses elsewhere.
+
+⚠️ It is a **caution and never a refusal to start**. `validate.py` still does not
+mention either key. A telemetry channel that could stop a battery site from
+starting would be observability with a foot in the control path.
+
+---
+
+## 2. ⚠️⚠️ The decision the card turns on: absence of ONE is absence of the TOTAL
+
+Three inverters configured, one `unavailable`. The sum of the other two is **a
+smaller number indistinguishable from a real one.** Fed into OPT-10's
+attribution it reads as *"there was less PV than there was"* — which is the "no
+irradiance" conclusion the channel exists to **test** rather than to manufacture.
+
+Two designs were genuinely available:
+
+**(a) publish the total as absent** — `pv.total()` answers `None`, the topic
+carries HA's own `None`, the entity goes to `unknown`, the recorder stores a gap.
+
+**(b) publish the partial sum alongside a count of how many contributed.**
+
+**(a) shipped.** It wins on the one question that matters, which is *who reads
+the number and when*:
+
+* The **MQTT row** is read back **cold**, a week later, by OPT-10 and by anything
+  that plots `sensor.goodwe_pv_power` over that week. A partial sum there is a
+  smaller number indistinguishable from a real one, and the count that would
+  have qualified it lives in a **second entity with its own history** — so
+  believing the total requires joining two recorder series by timestamp to find
+  out which samples to distrust. Nobody re-derives that. And it is worse than a
+  gap in exactly the direction that matters: **a gap makes the attribution say
+  "I do not know"; a partial makes it say something false.**
+* The **status page** is read **live**, by a human who wants the diagnostic. So
+  the partial information is *not* thrown away — the row names every entity that
+  did report, with its watts, and every one that did not, with its reason, and
+  states plainly that there is no site total. Different reader, different
+  instant, different rule.
+
+A count published beside the total would also carry **no information** in the
+state (a) admits: the total is published *only* when every entity contributed, so
+the count would be the constant `len(roster)`.
+
+And this **extends** TEL-11's rule rather than weakening it. `mqtt.py`'s
+`ABSENT_AS_UNKNOWN` is still exactly one key and `publish()`'s `None` handling is
+untouched: the line that turns an absence into HA's `unknown` did not have to
+change, because "absence is never zero" already covered this one layer up.
+
+### The mirror, which matters just as much
+
+A member honestly reporting **0 W** is **summed**, not treated as absent. The
+test is `watts is None`, never falsiness. Shading, a tripped string and
+nightfall are all real zeros, and a roster that blanked the site whenever one
+member read zero would report an absence **on every clear evening** and defeat
+the channel from the other end.
+
+### ⚠️ And the answer is NOT "document a template sensor that adds them up"
+
+An operator may legitimately prefer one, and `pv_entity` will happily point at
+it. Shipping it as *the* answer pushes the absence problem onto them unseen: a
+template sensor summing an `unavailable` source silently yields the partial
+total — the same defect one layer down, in a place this add-on cannot see or
+report. DOCS.md says so in those terms.
+
+### The three published states, side by side
+
+| what happened | frame | `goodwe_ctl/pv` | status page |
+|---|---|---|---|
+| no roster at all | no `pv` key | no topic, no entity | no row |
+| 1200 / 2100 / 450 W, all three | `pv: 3750.0` | `3750.0` | `PV  3 750 W` + one ok row naming all three |
+| all three answer, one of them `0 W` | `pv: 1650.0` | `1650.0` | `PV  1 650 W` |
+| one of the three `unavailable` | `pv: None` | `None` → `unknown`, recorder **gap** | `PV  —` + a caution naming the missing entity, its reason, and what the others reported |
+| all three gone | `pv: None` | as above | as above |
+
+---
+
+## 3. Still not a control input
+
+Unchanged, and re-proved at the new roster size.
+`tools/tel11_pv_trace.py` was **extended rather than replaced** — the file name
+still says TEL-11 because `DECISIONS/TEL-11-pv-production.md` §5 and
+`test_pv.py`'s mutation table quote it, and a renamed instrument makes both
+references dangle for no gain.
+
+It now produces **three** document sets per tree — `unset`, `one`, `multi` — and
+grades five claims. The roster cells live in their own document precisely so
+`unset` and `one` keep the `control` hashes TEL-11 recorded; appending cells to
+an existing document would have moved a hash whose stability is itself the
+evidence.
+
+```
+$ python3 tools/tel11_pv_trace.py --compare base.json head.json
+  HEAD is B; baseline is A - its roster cells ARE its unset cells, which is what a tree that has never heard of `pv_entities` does with them.
+  supports_roster   A False / B True   (self-reported; the verdict above is MEASURED)
+  tree      A fa92ba6a6fc6d49c0f87a494e03b530a8575212a0b2c3046629cb400ef2ae0d4
+  tree      B 0b39198015b6a5a3f7538d4157d77ecadc89311daef18fce883762d94d8351eb
+  control   A unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B unset 846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   A one   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   B one   846a10a5b89e321086d535825925721e2f791012e8405948d4fd38d3f9d0be5f
+  control   A multi 2aafbfedfb9cc939082b36eeb7493289808fb21cd41113322d4817de0e414a30
+  control   B multi 2aafbfedfb9cc939082b36eeb7493289808fb21cd41113322d4817de0e414a30
+  telemetry A unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry B unset a443a6ceaffe072b44bcd5f2ad946c1ed6c9e01b69e278eca631f7f4d7892164
+  telemetry A one   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+  telemetry B one   4e6d1cb289a957223ad0205f732a6fec6110ce1f2032c98ad60694e67625274f
+  telemetry A multi d269168ffece375027c2c18ea33631a961ff92775781884a0592d6a37d78845c
+  telemetry B multi 550a49a73f39267ba28b1e78cd12b8f5c71ef7269bbbd2e12112696be0fef1ff
+OK  1/5  UNSET: control AND telemetry are byte-identical to the baseline tree. …
+OK  2/5  ONE ENTITY: control AND telemetry are byte-identical to 0.11.0's single-entity path - the same commands, the same payloads, the same status rows, the same announcement.
+OK  3/5  CONTROL, ONE ENTITY: the control document is byte-identical with the channel switched on - PV reaches no decision.
+OK  4/5  CONTROL, THREE ENTITIES: every roster cell's control document equals its grid world's `unset` one - 30 cells over 5 grid worlds, covering three healthy entities, one dead at EVERY position, all three dead and one honestly reporting 0 W. Neither the total nor any PARTIAL total reaches a decision, and the document is byte-identical to the BASELINE tree's for the same cells.
+OK  5/5  CONTROL OF THE CONTROL: the telemetry document DOES move under a roster (30 stimulus cells differ from their grid world's unset telemetry), so 1/5-4/5 are identities this instrument could have broken. AND in no cell with a dead member does the PV row carry the partial sum of the survivors, while every cell whose members all ANSWER publishes its total - including the one where a member honestly reports 0 W.
+$ echo $?
+0
+```
+
+**The control hash is unmoved: `846a10a5b89e…` on `unset` and on `one`, on both
+trees.** The roster control document `2aafbfedfb9c…` is byte-identical between
+the two trees, which is the strongest available form of the claim — the baseline
+runs those cells with a key it has never heard of, so its control document for
+them *is* 0.11.0's.
+
+⚠️ **2/5 is a claim TEL-11 could not make.** TEL-11's baseline had no channel at
+all to be identical to; TEL-12's baseline is 0.11.0, so "one entity behaves
+exactly as 0.11.0 does" is a real cross-tree identity over **both** documents.
+`pv.total()` passes a single entity's `(watts, why)` through verbatim for exactly
+this reason, and `Controller.checks()` keeps 0.11.0's two f-strings in a
+`len(...) == 1` branch rather than generalising them.
+
+### ⚠️ TEL-11's `--compare` refusal had to change, and that is a finding
+
+TEL-11's rule was *"exactly ONE side's `set` document may differ from its own
+`unset` — that side is the HEAD"*. It was correct evidence when written, because
+`release/1.0` predated `pv_entity` entirely. `release/1.0` is 0.11.0 now, **both**
+sides react to `pv_entity`, and that refusal fires on **every honest run**. The
+discriminator is the roster instead: only the HEAD has heard of `pv_entities`, so
+only the HEAD's `multi` document fails to reduce to its own `unset` one.
+
+It is asserted from the **documents**, not from `tree.supports_roster` — a
+self-report is the tree describing itself, whereas "this side's behaviour did not
+move when `pv_entities` was set" is the tree being measured. `supports_roster` is
+printed beside the verdict so a disagreement between the two is visible.
+
+See MUTATION.md habit 24.
+
+---
+
+## 4. Mutation battery
+
+Twelve mutations, each on a **fresh `cp -a`** of the clean worktree (never
+reverted — habit 18 / TARIFF-09's method), `__pycache__` purged before the run
+and the tree checked for one afterwards, byte delta from `stat` and the edit
+confirmed on disk with `cmp`, suites run in the CI image with `checks.yml`'s own
+command one file at a time under a `:ro` mount.
+
+| mutation | bytes | reds |
+|---|---|---|
+| N1 `total()` returns the partial sum, not an absence | +42 B | 6 named in `test_pv.py` + 1 crash |
+| **N1b ⭐ THE REJECTED DESIGN: the partial sum with a contributor count** | −282 B | **10 named + the trace `REFUSED 5/5`** |
+| N2 absence tested by falsiness (`not w`) | −4 B | 2 named |
+| N3 `pv_entities` UNIONS with `pv_entity` | −27 B | 3 named |
+| N4 the de-duplication dropped | −15 B | 1 named |
+| N5 `sum` → `max` over the roster | **+0 B** | 6 named |
+| N6 the roster-of-one stops passing `why` through | +13 B | 8 named |
+| N7 `optional_keys()` back to reading `pv_entity` | −6 B | 1 named + 1 crash |
+| N8 `self.grid -= self.pv_w` in `read_inputs()` | +106 B | 3 named + the trace (52 cells on 2/5, 26 on 3/5, 10 on 4/5) |
+| N9 the roster caution made a `bad` row (NOT READY) | +1 B | 1 named |
+| N10 `entity_is_ignored()` always False | +10 B | 2 named |
+| N11 `pv_entities: []` deleted from `options:` | −18 B | 2 named in `test_translations.py` + `11 CASE(S) FAILED` in the probe |
+
+**No survivors.**
+
+⚠️ **N5 is `+0 B` — the risky delta.** `sum` and `max` are the same three
+characters, so neither the file size nor its mtime moved, and TEST-15's
+stale-bytecode defect is exactly what manufactures a survivor there. The run was
+on a fresh purged copy and `cmp` confirmed the edit on disk before it started.
+
+⚠️ **N1b is the row that matters, and it is not a defect.** It is the *other*
+defensible design, implemented and run. The point is that the checks and the
+instrument can **tell the two apart** — an unexamined partial sum is what the
+card forbids, so a check that could not see one would be decoration:
+
+```
+REFUSED 5/5: THE PARTIAL SUM IS ON THE WIRE at [('EXPORT-6K/EAST-DEAD', '2550.0'),
+('EXPORT-6K/GARAGE-DEAD', '3300.0'), ('EXPORT-6K/WEST-DEAD', '1650.0'),
+('IMPORT-3K/EAST-DEAD', '2550.0'), ('IMPORT-3K/GARAGE-DEAD', '3300.0'),
+('IMPORT-3K/WEST-DEAD', '1650.0')] … - a smaller number indistinguishable from a
+real one, which is the defect this card exists to prevent.
+```
+
+⚠️ **N8's 1/5 stays GREEN and that is correct rather than a miss.** With no PV
+entity configured `pv_w` is `None` and the leak cannot fire — which is what makes
+1/5 a claim about the **default** and 2/5–4/5 the claims about the channel.
+
+### The fixture values are the design (habit 10 and habit 23)
+
+`test_pv.py` carries **two** rosters over the same three entities, because the
+two claims need different magnitudes and one fixture cannot serve both.
+
+* **Parts 8–10: 1200 W + 2.1 kW + 450 W = 3750 W.** The sum is separable from
+  max (2100), min (450), first (1200), last (450), mean (1250), count (3) and
+  every partial of itself (2550 / 1650 / 3300) — the family is computed, printed
+  and asserted non-colliding as its own precondition. One member is in **kW** so
+  "correct against their own units" is exercised. **Not one member is zero**: a
+  member contributing 0 W could go absent without moving the sum of the rest, and
+  a fixture like that cannot tell "published the absence" from "published the
+  partial sum" — habit 23 with a coinciding value in the *fixture* rather than in
+  the plant, which is precisely the trap the brief named. Absence is driven at
+  **every position** of the roster, not at one (habit 10's fixture-as-a-SET), and
+  each position's partial is **derived from the fixture** rather than typed
+  beside it.
+* **Part 6: 1500 W + 4.5 kW + 2000 W = 8000 W.** Sized so every *partial*
+  (6500 / 3500 / 6000) would still **move** a loop settling on a 600 W import.
+  Habit 23's own question is asked twice — shift the meter by 8000 W, and again
+  by 3500 W, the smallest partial any single dead member could produce — because
+  a leak of the partial is a different mutation leaking a smaller number.
+
+### Two false results this card produced, and what they were
+
+Both were in the **instrument**, and both are recorded rather than tidied away.
+
+1. `partial_w`/`partial_wire` were first written **inside** each telemetry cell.
+   They are a fact about the *stimulus*, produced by the tool and identical on
+   both trees — so every roster cell differed from its unset reference for a
+   reason that was not behaviour, and the HEAD/baseline discriminator fired on
+   *both* sides. They live in a separate top-level `partials` map now.
+2. The `WEST-ZERO` cell (all three answer, one honestly reporting 0 W) had its
+   **true total** labelled as its "partial". 5/5 then refused the *shipped* tree
+   for publishing 1650 W, which it is required to publish. A cell with no dead
+   member has no partial to leak, and `never` is `None` there.
+
+---
+
+## 5. What none of this can see
+
+* **Home Assistant itself.** That `None` on the state topic renders as state
+  `unknown` and that the recorder keeps a gap is read out of HA's source and
+  quoted in `app/mqtt.py`; whether the long-term statistics table then
+  interpolates across the gap is HA's behaviour, and OPT-10 will be reading it.
+* **Whether the operator's sensors are telling the truth.** A sensor wired
+  backwards reads −4 kW at noon and is summed as −4 kW. There is deliberately no
+  `pv_invert` — §2 of the TEL-11 record is the argument, and it holds at a roster.
+* **A roster larger than three.** Three is the smallest size at which the sum
+  separates from the reduction family *and* absence can be driven at every
+  position. Nothing here says what twenty entities do to a cycle's latency — the
+  read is `asyncio.gather`ed across the roster for exactly that reason, so a slow
+  sensor costs what one costs, but that is an argument rather than a measurement.
+* **A PV roster combined with a two-inverter battery roster.** No fixture
+  crosses CFG-04's `inverters:` with `pv_entities`.
+* **The real MQTT transport, and wall-clock behaviour.** As TEL-11.
+
+---
+
+## 6. Not deployable as merged
+
+`config.yaml` stays at `0.11.0`, so `tools/predeploy_check.py` reports a NO-OP
+until PKG cuts a version. A CHANGELOG entry is **wanted** and was deliberately
+not written: `test_version_gate.py` 11b forbids an `## Unreleased` heading and
+the bump is PKG's call. The material an entry needs is this file.
+
+The option surface moves **76 keys → 77**, one new optional key, `pv_entities`,
+empty on every install that does not set it.

goodwe_controller/DOCS.md

@@ -139,6 +139,8 @@ either direction, and the check is mutation-tested both ways.
 | `batt_invert` | | Flip if needed |
 | `capacity_kwh` | | This pack's usable capacity. Read only to divide the site target between packs by **energy** headroom — see below |
 | `setpoint_entity` | yes | The ESPHome `number.*_goodwe_setpoint_w` |
+| `pv_entity` | | Optional. **One** solar inverter's power sensor, `+` = producing. Measurement only — it changes no control behaviour. See [PV production](#pv-production-pv_entity-tel-11) |
+| `pv_entities` | | Optional. **Several** solar inverters, one row each — use this instead of `pv_entity` when your roof has more than one. Setting it **ignores** `pv_entity`. See [Several PV inverters](#several-pv-inverters-pv_entities-tel-12) |
 
 Use the ESP32's readings rather than the inverter's cloud or dongle sensors:
 those serve cached values, and a stale reading here ends the maintenance charge
@@ -287,8 +289,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,13 +325,255 @@ 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
 add-on gives the second one a `_2` suffix so nothing collides, but the ids you
 get then depend on roster order. Give your inverters plainly different names.
 
+### PV production (`pv_entity`, TEL-11)
+
+> **More than one solar inverter?** Use `pv_entities` instead — see
+> [Several PV inverters](#several-pv-inverters-pv_entities-tel-12) below. The
+> rest of this section applies to both.
+
+
+**Optional, off by default, and it changes no control behaviour whatsoever.**
+Set it and the add-on records what your solar is producing beside what the
+meter and the battery are doing. Leave it empty and the add-on reads no entity,
+announces no entity, publishes no topic and shows no row — which is what every
+install that upgrades into this version does.
+
+#### Why it is a Home Assistant entity and not a register
+
+This add-on's RS485 bus carries the **battery** inverter it drives. On nearly
+every site the PV inverter is a different box from a different vendor, on its
+own connection, reporting into Home Assistant through its own integration. So
+`pv_entity` takes whatever `sensor.*` your PV integration already provides —
+any brand Home Assistant can read. It does not have to be on the bus, and there
+is no assumption anywhere that it is.
+
+#### What it is for
+
+OPT-10 measured this site over sixteen days: the battery reached 90 % on **two
+of them**, and **20.5 kWh of surplus left the site while the pack still had
+room** — 12.6 kWh of it with the battery not charging at all. Three different
+things produce that number and they need three different fixes:
+
+* there was no irradiance to store — nothing to fix;
+* production was there and something limited the charge power;
+* production was there, the battery could take it, and the optimiser declined.
+
+Only the third is a software defect, and **none of them can be told apart
+without a record of production.** This entity is that record. The attribution
+itself is OPT-10's, with a week of history behind it.
+
+#### The sign, and why there is no `pv_invert`
+
+**Positive must mean producing.** That is the same convention as the two sign
+rules the add-on already ships — `meter_entity` is positive when **importing**
+and `batt_entity` is positive when **discharging**, both of which are "power
+arriving at the house" — and production arrives there too.
+
+`meter_invert` and `batt_invert` exist because those two quantities are
+**bipolar and are read by the control path**: a reversed battery sensor is a
+perfectly plausible number that the per-inverter sign failsafe then acts on.
+Production is unipolar and is read by **nothing**, so a reversed sensor here
+cannot mislead a decision — and it announces itself immediately as −4 kW at
+noon in the very history this entity creates. A flag would only hide it, so
+there is not one. If your sensor really is inverted, fix it where it is
+produced.
+
+#### The unit is read off the entity
+
+The add-on reads your entity's own `unit_of_measurement` and converts: `mW`,
+`W`, `kW`, `MW`, `GW`, `TW` — Home Assistant's own power units. A sensor with
+**no** unit, or with a unit that is not one of those, is **refused**, and the
+status page says which entity and which unit. That is deliberate: there is no
+magnitude test that can separate 30 W of dusk from 30 kW of noon, so a guess
+here would be a silent factor of 1000 in the one channel that exists to be
+believed a week later.
+
+#### ⚠️ Absence is never zero
+
+| what happened | `sensor.goodwe_pv_power` | on the status page |
+|---|---|---|
+| neither `pv_entity` nor `pv_entities` set | the entity does not exist | no row at all |
+| set, sensor answered `4100 W` | `4100.0` | `PV  4 100 W` |
+| set, sensor answered `0 W` | `0.0` | `PV  0 W` |
+| set, sensor unavailable / missing / bad unit | `unknown` | `PV  —`, plus a caution naming the reason |
+
+The last two rows are the point. A dead sensor publishes Home Assistant's own
+"no value" payload, so the entity goes to **`unknown`** and the recorder stores
+a **gap** — not a flat line at the last number it saw. Reading a week of
+history back, *"no PV was reported"* and *"PV reported 0 W"* are different
+pictures, which is exactly the distinction the whole card exists to preserve.
+
+A failed read also **clears** the previous good one: the value never outlives
+its own sensor.
+
+### Several PV inverters (`pv_entities`, TEL-12)
+
+A multi-string or multi-orientation roof routinely carries **two or three PV
+inverters**, each publishing its own power sensor into Home Assistant. List them
+all and the add-on records the **site total**:
+
+```yaml
+pv_entities:
+  - sensor.pv_east_power
+  - sensor.pv_west_power
+  - sensor.pv_garage_power
+```
+
+In the Configuration tab this is a repeatable field: press the **+** and add a
+row per inverter. Each entity's **own** `unit_of_measurement` is read, so a
+kW inverter beside a W one adds up correctly.
+
+#### It replaces `pv_entity` — clear that one
+
+Setting `pv_entities` makes `pv_entity` **ignored**, and the status page says so
+until you clear it. That is deliberate rather than tidy: if the two were *added*
+together, an upgrade where you leave your first inverter in `pv_entity` and also
+list it here would count it **twice**, and a doubled total is as wrong as a
+missing one in the one channel that exists to be believed a week later.
+
+#### ⚠️⚠️ If ANY of them stops reporting, there is NO site total
+
+This is the whole reason the key is shaped this way, so it is worth being plain
+about:
+
+| what happened | `sensor.goodwe_pv_power` | on the status page |
+|---|---|---|
+| all three reporting 1200 / 2100 / 450 W | `3750.0` | `PV  3 750 W` |
+| all three reporting, one of them **0 W** | `1650.0` | `PV  1 650 W` |
+| one of the three `unavailable` | `unknown` | `PV  —`, plus a caution naming which entity, why, and what the others reported |
+| all three gone | `unknown` | as above |
+
+**It does not publish the sum of the ones that answered.** Two inverters out of
+three add up to a smaller number that is *indistinguishable from a real one* —
+and read back a week later that says *"there was less sun than there was"*,
+which is precisely the conclusion this recording exists to **test** rather than
+to manufacture. A gap makes the analysis say *"I do not know"*; a partial makes
+it say something false. So the total goes to `unknown` and the recorder stores a
+gap, exactly as it does for a single dead sensor.
+
+The diagnostic is not thrown away — it is put where a person will see it. The
+status page names the entity that is missing, the reason, **and** what the
+others reported. That page is read live by a human who wants to fix something;
+the recorded number is read cold by an analysis that would believe it.
+
+Note the **third row against the second**: a member honestly reporting `0 W` is
+**summed**, not treated as missing. Shading, a tripped string and nightfall are
+all real zeros, and blanking the site whenever one member read zero would report
+an absence on every clear evening.
+
+#### ⚠️ Not "just use a template sensor that adds them up"
+
+You may legitimately prefer a template sensor, and `pv_entity` will happily
+point at one. But it is **not** the answer to this problem: a template sensor
+summing an `unavailable` source yields the partial total *silently*, which is
+the same defect one layer down — in a place this add-on cannot see and cannot
+report to you.
+
+#### ⚠️ What it does NOT do
+
+It is **instrumentation**. It is not an input to the control law, the
+allocator, the arbiter, the peak guard, the maintenance cycle or any watchdog;
+it is not part of `inputs_ok`, so a PV integration that breaks cannot stop the
+battery being regulated; and its status row is a **caution**, never a
+`NOT READY`. Wiring production into the control law would be a behaviour change
+on a system driving a real battery — and it would destroy the measurement,
+because the loop would then be reacting to the thing being measured.
+
+`tools/tel11_pv_trace.py` is what says so rather than claims it: it drives 41
+stimulus worlds through the shipped controller and hashes a document of control
+decisions containing none of this material, on this tree and on `release/1.0`,
+with the option set and unset.
+
 ### P1 meter ingestion
 
 `meter_entity` above expects one signed sensor, which usually means a template
@@ -441,6 +687,35 @@ next 10 s publish. There is **no option to configure**: the 35 s is derived from
 the ESPHome publish interval and the two watchdog windows it has to stay inside,
 and the add-on's own checks refuse a value that does not.
 
+⚠️ **AND IF THE REGISTER DOES NOT REPORT A DIFFERENT VALUE, THE ADD-ON STOPS
+WAITING AFTER 17 s (SAFETY-57).** This paragraph used to end at the sentence
+above, and on 2026-09-21 that turned out to be a promise the state could not
+keep: at 0 W **nothing is asking the register to be anywhere**, so "report a
+different value" is evidence a parked site cannot ask for. The live site sat at
+0 W for **790 s** while the house exported 2.4 kW, on a register that was
+working perfectly — the pack was simply at its floor and the BMS was refusing
+the discharge — and it was freed by a person restarting the add-on.
+
+So: once the standing command has been **under 250 W for 17 s**, the verdict is
+**withdrawn** and the register is graded again from scratch over a fresh 35 s.
+The whole parked interval is now `stale_input_s` + 17 s — **32 s at the
+defaults** — and it does not depend on what the battery decides to do.
+
+| in the action log | what it means | what to do |
+|---|---|---|
+| `STALE <unit>` alone, then nothing | the register stopped following and has not come back | look at the unit — comms, the ESP32, the inverter |
+| `STALE <unit>` then `STALE WITHDRAWN <unit>`, **once** | the pack was probably empty or full and the BMS refused the command. The site has resumed | nothing |
+| the pair repeating every ~70 s | the register really is not following, and the add-on is re-testing it | look at the unit; the site is regulating on the meter in between |
+
+⚠️ **`STALE WITHDRAWN` IS NOT "RECOVERED", AND THE LOG LINE SAYS SO ITSELF.**
+Nothing has been learned about the register when it is printed; the verdict is
+withdrawn because it can no longer be *tested*, and the next 35 s are the test.
+During those 35 s the held number reaches the site's telemetry again. That is
+deliberate and it is bounded: 35 s is shorter than both the circulating-power
+hold (75 s) and the per-unit sign hold (85 s), so neither of those alarms can be
+made to say anything by a held number, and the command itself is derived from
+the **meter**, never from this register.
+
 ⚠️ **What this does NOT catch: a register whose value is WRONG rather than
 STOPPED**, including a dead publisher whose last two samples happen to
 alternate. Detecting that needs an arrival stamp inside the ESP32 firmware
@@ -650,8 +925,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 +939,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 +959,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,177 @@ 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.
+
+23. ⚠️ **THE MUTATION IS SUBJECT TO EVERY HABIT ABOVE, HABIT 4 INCLUDED - AND
+    THE PURGE, THE FINGERPRINT AND THE BYTE DELTA ALL SAY IT TOOK.** SAFETY-57's
+    battery reported a **survivor at +21 B** for a mutation of
+    `Freshness._open_window()`: `self.graded_from = float(now_mono)` rewritten
+    as `float(self.changed_mono or now_mono)`, which is meant to re-anchor the
+    verdict's window to the register's own history and so delete the card's
+    whole exit. The harness purged, the tree fingerprint showed the edit on
+    disk, the delta was non-zero, and the mutant really did run. It was still a
+    survivor for a reason that has nothing to do with the property: in the
+    fixture the register never moves after `t = 0`, so `changed_mono` is
+    **`0.0`** - and `0.0 or x` is `x`. **The mutant was a no-op on that
+    stimulus.** Rewritten with an explicit `is None` test (+82 B) it is red on
+    four named checks.
+
+    Stale bytecode is a mutation that never *ran*. This is a mutation that ran
+    and could not *change the answer* on the data it was given, which is habit 4
+    exactly, one level up - and none of the three things a mutation report is
+    required to state (MUTATION.md's own list) can see it, because all three are
+    about the file rather than about the stimulus. Two rules:
+    * **Ask of every survivor what it would have had to change, and check that
+      the fixture reaches that value.** Here: "does any fixture have a non-zero
+      `changed_mono` at the moment `_open_window()` is called?" The answer was
+      no, and it is one line to ask.
+    * **Prefer a mutation that CANNOT be a no-op.** `or`, `and`, truthiness on
+      a numeric, a default argument and a `getattr` fallback all have a value at
+      which the mutant and the shipped tree coincide. An explicit comparison,
+      a constant swap or a deleted statement does not.
+
+    ⚠️ Note where this one was found: in the battery of a card whose whole
+    subject is a check that cannot reach the failure it names. **Second
+    instance in an instrument rather than in a check since habit 16, and the
+    third overall.**
+
+    ⚠️ **AND THE SAME CARD'S BATTERY CAUGHT A HABIT-22 COMMENT IN THE FIX
+    ITSELF, WHICH IS WHY THESE TWO BELONG NEXT TO EACH OTHER.**
+    `freshness.py` shipped `⚠️ RELEASE BEFORE GRADE, AND THE ORDER IS
+    LOAD-BEARING` with a worked reason. Swapping the two calls is **zero bytes**
+    and survived the battery: `_grade()` acts only when `|standing| >= move_w`
+    and `_release()` only when `|standing| < move_w`, so at most one can act on
+    any read and the order is **not observable**. Habit 22 says build X and
+    measure it; the battery is what builds X. The comment now states the
+    disjointness and the suite pins **that** - at 0, 100, 249, 250, 251 and
+    1300 W - rather than an order nothing depends on.
+
+    ⚠️ **SECOND INSTANCE, TEL-11, AND THE NO-OP WAS A SATURATED RAIL RATHER
+    THAN A VALUE.** The card's whole subject is that a PV reading must never
+    reach the control law, so its central mutation is
+    `self.grid = self.grid - self.pv_w` in `read_inputs()` - **+106 B**, on
+    disk, purged, genuinely running - and it came back a **SURVIVOR** of a
+    six-file battery. The property held in no sense: the fixture drove a 6 kW
+    export over 12 cycles, which puts the loop **against its rail**, and a
+    command moving `slew_w` every cycle produces the SAME ramp for -6000 W and
+    for -14000 W of apparent error. The mutant ran and could not change the
+    answer.
+    Two things generalise past PV:
+    * **A SATURATED ACTUATOR IS A VALUE AT WHICH EVERY INPUT COINCIDES.** The
+      habit-23 list above names `or`, `and`, truthiness, default arguments and
+      `getattr` fallbacks - all *expressions* with a coinciding value. A rail,
+      a clamp, a slew limit, a deadband and a latched alarm are the same hazard
+      in the **plant**: they are where a controller's output stops being a
+      function of its input. A fixture that parks there cannot separate any two
+      inputs, and this repository's control fixtures park there by default,
+      because the dramatic stimulus is the saturating one.
+    * **SO THE PRECONDITION IS NOT "DOES IT COMMAND SOMETHING", IT IS "DOES IT
+      REST SOMEWHERE THE MUTATION COULD MOVE IT FROM".** `test_pv.py` part 6
+      now drives a 600 W import the loop SETTLES on, asserts the resting target
+      is well inside the rail, and asks habit 23's own question as a check:
+      shift the METER by the same 8 kW and confirm the commands really would
+      have moved. On the first fixture that question answers NO, in one line,
+      and it is the line that turns the identity into evidence.
+
+24. **A REFUSAL DEFINED RELATIVE TO "THE BASELINE LACKS THIS FEATURE" DIES ON
+    THE RELEASE THAT SHIPS THE FEATURE — AND IT DIES AS A FALSE REFUSAL, WHICH
+    IS THE LOUD DIRECTION.** TEL-11 built `tools/tel11_pv_trace.py` to grade a
+    cross-tree identity, and because "the documents are identical" was its
+    *result* rather than its warning sign, it had to prove instead that the two
+    runs came from different trees and that **exactly one side reacts to
+    `pv_entity`**. That was correct evidence: `release/1.0` predated the option
+    entirely, so a side that reacted to it was the HEAD by construction.
+
+    TEL-11 then **merged**, `release/1.0` became 0.11.0, and the baseline for
+    the next card reacts to `pv_entity` too. `--compare` now answers
+    `REFUSED: set differs from unset on ['A', 'B']` on every honest run — the
+    instrument refuses its own shipped tree. TEL-12 found it on the first
+    comparison it ran.
+
+    * **A discriminator is a fact about a MOMENT, not about a card.** "The
+      baseline does not have X" is true until X ships and then false forever.
+      Write the discriminator against something the NEXT baseline still will not
+      have — TEL-12's is the roster key, not the channel — and say in the tool
+      which fact it rests on, so the next card can see what it has to replace.
+    * **Prefer a discriminator that is MEASURED over one the tree REPORTS.**
+      `tree.supports_roster` is the tree describing itself and would have been
+      one line; the shipped test is "this side's roster cells ARE its unset
+      cells", which is the tree being measured. Both are printed, side by side,
+      so a disagreement between the self-report and the measurement is visible
+      rather than silently trusted.
+    * ⚠️ **And this is the SAFE direction of the same defect, which is why it
+      was found in ten minutes rather than in a review.** A stale refusal is a
+      developer chasing a failure they cannot explain (the false-red case at the
+      top of this file). A stale *identity* — an instrument that goes on printing
+      OK because its reference drifted into agreement — is the survivor-
+      manufacturing direction, and nothing announces it. Ask of every cross-tree
+      instrument: *what does this print when the feature it is about has been in
+      the baseline for a year?*
+
+    TEL-12's own battery produced two more instrument defects of the ordinary
+    kind, both recorded in `DECISIONS/TEL-12-several-pv-inverters.md` §4: a
+    stimulus annotation written into the document being compared (so every cell
+    differed for a reason that was not behaviour, and the discriminator fired on
+    both sides), and a fixture cell whose TRUE total was labelled as its
+    "partial" (so the check refused the shipped tree for publishing a number it
+    is required to publish). ⚠️ **Both were caught by running the instrument
+    against the shipped tree BEFORE running it against a mutant** — which is the
+    one ordering rule that separates "the instrument is wrong" from "the tree is
+    wrong", and `test_mqtt.py` part 8's first line ("the shipped module satisfies
+    every property this instrument grades") is the same rule as a check.
+
+    ⚠️ **AND TEL-12's SUBJECT WAS HABIT 23 IN THE FIXTURE ITSELF.** The card adds
+    a SUM over a roster, and the defect it exists to prevent is publishing the
+    partial sum when a member is absent. A fixture whose absent member
+    contributes **0 W** cannot see that defect at all: the partial and the full
+    total are **the same number**, so "published the absence" and "published the
+    partial" produce identical output. That is a rail in the *arithmetic* rather
+    than in the plant — the same hazard as TEL-11's saturated actuator, one
+    domain over. `test_pv.py`'s roster is three distinct non-zero contributions
+    in two different units, absence is driven at **every position** rather than
+    at one (habit 10), and each position's partial is **computed from the
+    fixture** and asserted to differ from the true total as its own precondition.
+
 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/freshness.py

@@ -175,6 +175,124 @@ only one of them is WIRED - see `BOUNDS` below and the note on SoC.
   integrator, and K. It does NOT owe a second freshness mechanism - `Freshness`
   below takes its obligation term from the caller precisely so that an energy
   integral can be handed in where command travel is handed in here.
+
+
+THE EXIT, AND WHY THE FIRST VERSION OF THIS MODULE DID NOT HAVE ONE (SAFETY-57)
+==============================================================================
+⚠️ THE VERDICT ABOVE IS ABOUT AN OBLIGATION, AND ITS OWN CONSEQUENCE REMOVES
+THE OBLIGATION. Declaring the reading stale makes `Controller.inputs_ok` False,
+which commands 0 W (§11.1 rule 1). At 0 W nothing is asking the register to be
+anywhere - `|standing| >= MOVE_W` is false, so the conjunction cannot arm - and
+the class docstring's clearing rule, "an arrival carrying a DIFFERENT number",
+asks the register for evidence that only a command could have produced. A pack
+sitting at its BMS floor answers the same integer watt for hours. **The state
+had no exit reachable from inside it**, and the operator-facing line said the
+opposite: *"It clears itself the moment the register reports a different
+value."*
+
+MEASURED ON THE LIVE SITE, 2026-09-21, and committed as
+`scenarios/safety57-2026-09-21/` - a passive RS-485 capture, decoded by
+`tools/decode_bus_capture.py`:
+
+    10:51:24.7   0x0518 reaches -3 W. The pack is at 11 % and the loop has just
+                 reversed from -447 W of charge into discharge; the BMS refuses
+                 and the inverter idles. The register is HEALTHY and TRUTHFUL.
+    10:51:29.7   the standing command reaches +1060 W. 800 W of travel, and the
+                 register is obliged to follow it.
+    10:52:00     the conjunction arms. `Inverter.batt` becomes None.
+    10:52:21.7   the site commands 0 W - on the wire, in the capture.
+    ...          0x0518 does not change value for 850.0 s. The setpoint does not
+                 change value for 790.0 s. Nothing in this add-on can end it.
+    11:04        a human restarts the add-on.
+    11:05:31.7   the restarted loop commands -400 W of charge, which the pack
+                 ACCEPTS at 11 %, and the register moves 3 s later.
+
+⚠️ AND IT HAD BEEN ESCAPING BY LUCK. This BMS emits a keep-alive pulse of a few
+hundred watts, which twitches 0x0518 and satisfies the clearing rule by
+accident. Replaying the committed 16-day loop capture
+(`scenarios/loop-2026-09-02_2026-09-17/`) through the shipped conjunction at
+1 Hz gives **93 trips**, and the time from each trip to the register's next
+change - which was the ONLY exit - has a median of 143 s, 17 episodes at or
+over the live one's 710 s, and a worst case of 21440 s. That distribution is a
+property of this battery's firmware. It is not a property of this code, and the
+add-on must not depend on it.
+
+THE RULE, and it is SAFETY-13's shape one module over - "which latches get an
+exit, not how long the block lasts":
+
+    RELEASE  <=>  the verdict is standing
+                  AND |standing command| < MOVE_W has held continuously for
+                      >= RELEASE_S
+
+On a release the latch clears and a NEW grading window opens at that instant:
+the register is re-graded, from scratch, against the commands issued AFTER it.
+Nothing about the register's own history is rewritten - `changed_mono`,
+`held` and `unchanged_s()` go on reporting that the register has not moved for
+850 s, because it has not.
+
+⚠️ `RELEASE_S` IS `BATT_OBLIGED_S`, 17.0 s, AND IT IS THE FLOOR OF ITS BAND
+RATHER THAN A PREFERENCE - the mirror of `MOVE_W` taking the ceiling of its
+own. The question the bound answers is *has the register had its chance to
+answer the command that is now standing?*, and that is exactly the 17.0 s
+already derived above: 6.0 s of plant, one 10 s publish, one 1 s read. Below it
+the release happens before the cheaper exit - the register moving by itself -
+could have occurred. Which half is safe is the opposite of SAFETY-13's, and for
+the reason that card states in its §4.2 table: being wrong LONG here is the
+failure being fixed (a site parked while it exports), and being wrong SHORT
+costs one re-grading window, which is bounded below.
+
+WHAT A RELEASE COSTS, MEASURED AND NOT ABSORBED - AND IT IS NOT SMALL. For the
+duration of the new window the consumers get the held number again, which is
+the exposure this module was written to close. Driven at the live install's
+shape against a register frozen for good (`test_freshness.py` part 10c), over
+1200 s:
+
+    shipped     parked 1166 s, the held number reaches a consumer  35 s   2.9 %
+    SAFETY-57   parked  571 s, the held number reaches a consumer 630 s  52.5 %
+
+⚠️ **52 % IS THE PRICE OF THE EXIT AND IT IS PAID EVERY CYCLE**, not an
+occasional slip. The period is the whole of `stale_input_s` (15 s) + `RELEASE_S`
+(17 s) parked, then one `BATT_UNCHANGED_S` (35 s) window of re-grading. It is
+bounded by construction, and that bound is the one thing that makes it payable:
+
+    the new window is AT MOST BATT_UNCHANGED_S = 35 s, and 35 < 75 < 85 - the
+    circulation hold and the per-unit sign hold. NEITHER CONSUMER CAN REACH A
+    VERDICT INSIDE ONE WINDOW, and a re-trip returns them a None, which CLEARS
+    both windows rather than accumulating into them.
+
+That inequality is the same one part 6 already grades, and it is why the window
+is `BATT_UNCHANGED_S` rather than a number chosen to make the table above look
+better. Neither detector can be made to say anything by a held number under
+this scheme - which is exactly the state the shipped code leaves them in as
+well, since a permanent None clears both windows for ever. **So nothing that
+SAFETY-37 detects is given back.** What the held number does reach for those
+35 s is `site_batt_w`, the anti-windup input of `control.compute()`, which
+responds to a large unexplained divergence by FREEZING the output - the
+conservative direction, and SAFETY-13's business. And the command itself is
+derived from the P1 meter, never from `batt`, so a site regulating through a
+re-grading window is regulating on the signal it always regulates on.
+
+**A register frozen under a command that never travels 250 W is still not
+detected at all** (survivor 2, unchanged), and a dead publisher whose value
+alternates is still invisible (survivor 3).
+
+⚠️ AND THE NARROWING THIS DOES NOT TAKE, named so the next card can. The live
+episode's register refused a DISCHARGE into an 11 % pack and then followed a
+CHARGE immediately; a refusal in one direction is not evidence about the other,
+and a gate that knew the pack's floor could re-grade on the first command that
+crosses it instead of on a timer. That needs SoC, which this module deliberately
+does not take (see the `soc` row), and the pack floor, which is SAFETY-32's
+number. It would shrink the 52 % above; it is not needed to give the state an
+exit, and mixing it in here would make the exit depend on a second measurement
+being right.
+
+⚠️ WHAT THIS DOES NOT DO, because the temptation is to call it a fix for the
+whole episode: it does not tell a BMS refusal apart from a dead register. The
+site above was parked for 790 s by a register that was working perfectly, and
+after this change it is parked for `stale_input_s + RELEASE_S` instead - about
+32 s on the shipped default - and then regrades. Telling the two apart needs
+the pack's own floor, which is SAFETY-32's number and not this module's input;
+the wording the operator reads about it is SAFETY-56's.
 """
 
 import time
@@ -211,6 +329,19 @@ BATT_UNCHANGED_S = 35.0
 # and goes red if the two drift.
 MOVE_W = 250.0
 
+# SAFETY-57. How long the obligation must have been ABSENT before a standing
+# verdict is withdrawn and the register re-graded. See the module docstring's
+# last section for the live episode this exists for and for which half of the
+# band is the safe one.
+#
+# ⚠️ IT IS `BATT_OBLIGED_S` AND NOT A NEW NUMBER, and that identity is the
+# derivation rather than a convenience. The question is "has the register had
+# its chance to answer the command standing NOW?", which is the same physical
+# quantity the floor of `BATT_UNCHANGED_S`'s band is: 6.0 s of plant, one 10 s
+# ESPHome publish, one 1 s add-on read. Releasing sooner would throw away the
+# cheaper exit - the register moving by itself - before it could have happened.
+RELEASE_S = BATT_OBLIGED_S   # 17.0
+
 
 @dataclass(frozen=True)
 class Bound:
@@ -219,6 +350,7 @@ class Bound:
     signal: str
     unchanged_s: float
     move_w: float
+    release_s: float
     wired: bool
     derivation: str
 
@@ -233,13 +365,19 @@ BOUNDS = {
         signal="batt (0x0518, AC power, S16, 1 W, 10 s publish)",
         unchanged_s=BATT_UNCHANGED_S,
         move_w=MOVE_W,
+        release_s=RELEASE_S,
         wired=True,
         derivation="settle 6.0 + publish 10.0 + read 1.0 = 17.0 s floor; "
-                   "circulation_hold_s 75 s ceiling; band [34.0, 37.5]"),
+                   "circulation_hold_s 75 s ceiling; band [34.0, 37.5]. "
+                   "SAFETY-57: the verdict is withdrawn after 17.0 s of the "
+                   "standing command below 250 W, because at 0 W the register "
+                   "is obliged to nothing and the verdict cannot be tested "
+                   "again from inside the state it creates"),
     "soc": Bound(
         signal="soc (0x050E, pack SoC, U16, 1 %, 10 s publish)",
         unchanged_s=float("inf"),
         move_w=float("inf"),
+        release_s=float("inf"),
         wired=False,
         derivation="TEL-08. Command travel is the WRONG obligation term for "
                    "SoC - a rested pack holds a percent for hours under a 0 W "
@@ -263,10 +401,33 @@ class Freshness:
     Declaring the reading stale makes `Controller.inputs_ok` False, which
     commands 0 W (§11.1 rule 1), which drops the standing command below
     `MOVE_W`, which un-arms the conjunction, which would return the held number
-    to the consumers - and round again every read. So the ONLY thing that clears
-    the latch is an arrival carrying a DIFFERENT number, which is exactly the
-    evidence the verdict was about. A register that is working clears it on its
-    next 10 s publish; a register that is not, does not.
+    to the consumers - and round again every read. So an arrival carrying a
+    DIFFERENT number clears the latch, which is exactly the evidence the verdict
+    was about. A register that is working clears it on its next 10 s publish; a
+    register that is not, does not.
+
+    ⚠️ AND IT IS NOT THE ONLY THING THAT CLEARS IT ANY MORE (SAFETY-57), BECAUSE
+    THAT MADE THE STATE INESCAPABLE FROM INSIDE. The command the verdict itself
+    produces is 0 W, and at 0 W the register is obliged to be nowhere - so
+    "report a different value" is evidence a parked site cannot ask for. The
+    live site sat at 0 W for 790 s on 2026-09-21 with a register that was
+    working correctly, and was freed by a human. `_release()` below withdraws a
+    verdict whose obligation has been gone for `bound.release_s`, and opens a
+    new grading window at that instant. The 1 Hz oscillation the latch exists to
+    prevent is still prevented: the new window is `bound.unchanged_s` wide, so
+    no re-trip can land sooner than 35 s after a release, rather than on the
+    next read. ⚠️ MEASURED FROM THE RELEASE, NOT FROM THE COMMAND RESUMING - if
+    the site rests for longer than the window before it asks for anything, the
+    window is already old and the re-trip lands on the first read at which the
+    command travels 250 W again. That is survivor 5's shape, it predates this
+    card, and its cost is one `stale_input_s` hold.
+
+    ⚠️ TWO CLOCKS, AND THE DISTINCTION IS THE WHOLE OF SAFETY-57'S HONESTY.
+    `changed_mono` / `held` are facts about the REGISTER: when it last carried a
+    different number. `graded_from` / `standing_at_grade` are the window the
+    VERDICT is computed over, which a release re-opens. They are the same thing
+    until the first release and diverge afterwards, and `unchanged_s()` - the
+    number an operator reads - is always the register's.
     """
 
     def __init__(self, bound: Bound):
@@ -281,10 +442,20 @@ class Freshness:
         # ability to fetch it.
         self.held = None
         self.changed_mono = None
-        # The standing command at that same instant. The conjunction compares
-        # against THIS, not against the previous cycle's command: what matters
-        # is whether the register has followed anything since it last moved.
-        self.standing_at_change = None
+        # SAFETY-57. The window the VERDICT is graded over, as opposed to the
+        # register's own history above, and the standing command at the instant
+        # it opened. The conjunction compares against THIS, not against the
+        # previous cycle's command: what matters is whether the register has
+        # followed anything since the current question was put to it. A register
+        # that moves opens a window, so until the first release these two are
+        # the change-stamps; `_release()` is where they diverge.
+        self.graded_from = None
+        self.standing_at_grade = None
+        # The instant the standing command last FELL below `move_w`, or None
+        # while an obligation is standing. The release timer runs off this.
+        self.rested_since = None
+        self.released_at = None
+        self.releases = 0
         self.stale = False
         self.reason = ""
         self.arrivals = 0
@@ -311,20 +482,67 @@ class Freshness:
         if self.changed_mono is None or value != self.held:
             self.held = value
             self.changed_mono = float(now_mono)
-            self.standing_at_change = (None if standing_w is None
-                                       else float(standing_w))
-            # Movement is the ONLY thing that clears the latch. See the class
-            # docstring on the 1 Hz oscillation this prevents.
+            self._open_window(standing_w, now_mono)
+            # Movement clears the latch, because it is exactly the evidence the
+            # verdict was about. See the class docstring on the 1 Hz oscillation
+            # the latch prevents, and `_release()` for the other way out.
             self.stale = False
             self.reason = ""
         self.last = value
+        # ⚠️ THE ORDER OF THESE TWO IS NOT OBSERVABLE, AND THIS COMMENT SAYS SO
+        # BECAUSE THE FIRST VERSION OF IT CLAIMED THE OPPOSITE. Swapping them is
+        # a ZERO-BYTE edit and it SURVIVED the battery; the reason is structural
+        # rather than a missing fixture, so no fixture could have closed it:
+        # `_grade()` acts only when `|standing| >= move_w` and `_release()` only
+        # when `|standing| < move_w`, so at most one of them can do anything on
+        # any given read, whichever runs first. Release is written first because
+        # it reads in the order the state machine moves - withdraw, then
+        # re-grade - not because the code depends on it.
+        self._release(standing_w, now_mono)
         self._grade(standing_w, now_mono)
 
+    def _open_window(self, standing_w, now_mono) -> None:
+        """Start grading the register again, from this instant (SAFETY-57).
+
+        Called when the register moves - the window and the register's history
+        coincide there - and when a verdict is withdrawn, where they do not.
+        """
+        self.graded_from = float(now_mono)
+        self.standing_at_grade = (None if standing_w is None
+                                  else float(standing_w))
+
+    def _release(self, standing_w, now_mono) -> None:
+        """SAFETY-57. Withdraw a verdict whose obligation is no longer standing.
+
+        ⚠️ THE TIMER RUNS ON THE COMMAND, NOT ON THE VERDICT. `rested_since` is
+        maintained on every arrival, latched or not, so the elapsed rest is the
+        real one and not "time since we last looked". An obligation reappearing
+        resets it to None, which is the whole point: a site that goes back to
+        asking the register for 250 W of movement has put the question back, and
+        the verdict stands until the question is withdrawn again.
+        """
+        obliged = (standing_w is not None
+                   and abs(float(standing_w)) >= self.bound.move_w)
+        if obliged:
+            self.rested_since = None
+            return
+        if self.rested_since is None:
+            self.rested_since = float(now_mono)
+        if not self.stale:
+            return
+        if float(now_mono) - self.rested_since < self.bound.release_s:
+            return
+        self.released_at = float(now_mono)
+        self.releases += 1
+        self.stale = False
+        self.reason = ""
+        self._open_window(standing_w, now_mono)
+
     def _grade(self, standing_w, now_mono) -> None:
         """The conjunction. Sets the latch; never clears it."""
-        if self.stale or self.changed_mono is None:
+        if self.stale or self.graded_from is None:
             return
-        held_s = self.unchanged_s(now_mono)
+        held_s = self.graded_s(now_mono)
         if held_s < self.bound.unchanged_s:
             return
         # ⚠️ BOTH None GUARDS ARE FOR A CALLER THAT DOES NOT KNOW ITS OWN
@@ -333,30 +551,98 @@ class Freshness:
         # consumer today. They are here for TEL-08, whose obligation term is an
         # energy integral that has nothing to say until it has a window - and
         # "nothing to say" must withhold the verdict, not manufacture one.
-        if standing_w is None or self.standing_at_change is None:
+        if standing_w is None or self.standing_at_grade is None:
             return
         standing_w = float(standing_w)
         if abs(standing_w) < self.bound.move_w:
             return
-        moved_w = abs(standing_w - self.standing_at_change)
+        moved_w = abs(standing_w - self.standing_at_grade)
         if moved_w < self.bound.move_w:
             return
         self.stale = True
+        # ⚠️ THE SENTENCE SAYS "unchanged", SO IT GETS THE REGISTER'S OWN
+        # NUMBER, NOT THE WINDOW'S. They are the same until the first release
+        # and different afterwards, and an operator comparing this line against
+        # a history graph is reading the register.
+        shown_s = self.unchanged_s(now_mono)
+        # ⚠️ SAFETY-56. THE OBSERVATION IS A FACT, THE DIAGNOSIS WAS NOT, AND
+        # THE SENTENCE NOW STOPS WHERE THE EVIDENCE DOES. The conjunction above
+        # is satisfied by TWO disjoint worlds, and nothing this object is handed
+        # separates them:
+        #   (1) the register has stopped reporting reality - what the gate was
+        #       built for - or
+        #   (2) reality is not moving, because the SOURCE cannot comply with
+        #       the command. A pack the BMS is refusing at its floor holds
+        #       still under any setpoint, and a register reporting that
+        #       truthfully publishes the same unchanged number a dead one does.
+        # The live 2026-09-21 episode was (2) - the pack read 11 % for the
+        # whole 850 s hold, the commands were discharge-only, and the register
+        # answered the first CHARGE command within one obligation window
+        # (test_freshness.py 11a measures all three off the committed capture)
+        # - and this sentence asserted (1), which sent the operator to look at
+        # healthy hardware.
+        # Naming both is what the module can honestly say. Naming WHICH would
+        # need SoC and the pack floor - deliberately not this module's inputs
+        # (see the `soc` row in BOUNDS and the docstring's last section), and
+        # TEL-08's and SAFETY-32's numbers rather than this sentence's.
+        #
+        # ⚠️ AND IT IS NOT SHARED WITH `main.py`'s NOT READY ROW, WHICH SAYS
+        # THE SAME AMBIGUITY IN DIFFERENT WORDS ON PURPOSE. This sentence is a
+        # LOG LINE about a behaviour, quoted verbatim by `note()` onto the
+        # status page and by `_read_unit()` into the action log; that one is a
+        # BANNER about a named ENTITY, and the two answer different questions
+        # ("what did the register do" against "can I trust this entity"). One
+        # helper serving both would have to drop whichever half the other does
+        # not need, and the half it dropped would be the operator's next step.
         self.reason = (
-            f"STALE_READING: {self.held:+.0f} unchanged for {held_s:.0f} s "
+            f"STALE_READING: {self.held:+.0f} unchanged for {shown_s:.0f} s "
             f"while the standing command moved {moved_w:.0f} W to "
-            f"{standing_w:+.0f} W - the reading is not following, so it is "
+            f"{standing_w:+.0f} W. TWO THINGS LOOK LIKE THIS AND THIS GATE "
+            f"CANNOT TELL THEM APART: the register may have stopped reporting "
+            f"reality, or the source may be unable to comply with the command "
+            f"- a pack the BMS is refusing holds still under any setpoint, and "
+            f"an honest register then reads exactly like a frozen one. Either "
+            f"way the number cannot be read as this command's effect, so it is "
             f"reported as MISSING rather than as a measurement (limits: "
             f"unchanged over {self.bound.unchanged_s:.0f} s, command over "
             f"{self.bound.move_w:.0f} W and moved by over "
             f"{self.bound.move_w:.0f} W)")
+        # ⚠️ SAFETY-57, AND THE THREE DURATIONS ARE THREE DIFFERENT FACTS, each
+        # in its own slot: the register's unchanged time is in the sentence
+        # above, the WINDOW this verdict actually rests on is here, and so is
+        # how many times this unit has been round the loop. Without the second
+        # one the sentence reads as though 92 s of unchanged register were what
+        # was compared against the 35 s limit, and it was not.
+        if self.releases:
+            self.reason += (
+                f" [re-graded: the {held_s:.0f} s window this verdict rests on "
+                f"opened when the previous one was withdrawn, not when the "
+                f"register last moved - this unit has now been graded "
+                f"{self.releases + 1} times]")
 
     def unchanged_s(self, now_mono) -> float | None:
-        """Seconds since an arrival carried a different number. Status page."""
+        """Seconds since an arrival carried a different number. Status page.
+
+        ⚠️ THE REGISTER'S CLOCK, NEVER THE VERDICT'S (SAFETY-57). A release
+        re-opens the grading window; it does not make the register younger, and
+        an operator reading "unchanged for 12 s" off a register that has held
+        one value for 850 s would be reading this module's bookkeeping back as a
+        measurement. `graded_s()` is the other one and is named differently for
+        that reason.
+        """
         if self.changed_mono is None:
             return None
         return max(0.0, float(now_mono) - self.changed_mono)
 
+    def graded_s(self, now_mono) -> float | None:
+        """Seconds the CURRENT verdict window has been open (SAFETY-57).
+
+        Equal to `unchanged_s()` until the first release, and shorter after one.
+        """
+        if self.graded_from is None:
+            return None
+        return max(0.0, float(now_mono) - self.graded_from)
+
     def reading(self):
         """What the consumers get: the value, or None when it cannot be trusted.
 
@@ -366,6 +652,13 @@ class Freshness:
         rather than accumulating it, and `circulation.circulating_w` returns None
         for a roster with a missing term, which clears the circulation window
         too. This module is the thing that was missing between them.
+
+        ⚠️ AND IT CAN GO BACK TO BEING A NUMBER WITHOUT THE REGISTER MOVING
+        (SAFETY-57). That is the exit, and it is bounded rather than free: the
+        window a release opens is `bound.unchanged_s` = 35 s, shorter than both
+        consumer holds (75 s and 85 s), so neither can reach a verdict inside
+        one - and a re-trip hands them a None, which CLEARS their windows. See
+        the module docstring's last section.
         """
         return None if self.stale else self.last
 
@@ -373,6 +666,26 @@ class Freshness:
         """One line for the status page. Empty when there is nothing to say."""
         return f"{unit_name}: {self.reason}" if self.stale else ""
 
+    def release_note(self, unit_name: str) -> str:
+        """SAFETY-57's release, for the log. Empty when nothing was withdrawn.
+
+        ⚠️ IT NAMES WHAT IS AND IS NOT BEING CLAIMED, because a line reading
+        "recovered" would be a lie: nothing has been learned about the register.
+        The verdict was withdrawn because it can no longer be tested, and the
+        next 35 s are the test.
+        """
+        if self.released_at is None:
+            return ""
+        return (f"{unit_name}: STALE_WITHDRAWN after the standing command sat "
+                f"below {self.bound.move_w:.0f} W for "
+                f"{self.bound.release_s:.0f} s. NOTHING HAS BEEN LEARNED ABOUT "
+                f"THE REGISTER - it is still holding {self.held:+.0f} - but a "
+                f"verdict about a command that is no longer standing cannot be "
+                f"tested, and the 0 W this one produces is what stopped it "
+                f"being tested. The register is now re-graded over a fresh "
+                f"{self.bound.unchanged_s:.0f} s window; if it still does not "
+                f"follow, this returns")
+
 
 def monotonic() -> float:
     """The clock this module's callers use, in one place so tests can find it.

goodwe_controller/app/main.py

@@ -62,10 +62,11 @@ from .inverter import (LINK_STALE_S, UNIT_A, build_roster,
 from .maintenance import (
     IDLE, POWER_MOVING, MaintConfig, Maintenance, arbitrate as maint_arbitrate,
 )
-from .mqtt import (MqttPublisher, announced_units, unit_slugs,
+from .mqtt import (MqttPublisher, announced_units, optional_keys, unit_slugs,
                    unit_state_key)
 from . import peakguard
 from . import packshare
+from . import pv as pv_read
 from . import shadow
 from .p1 import P1Ingest, build_source, is_enabled
 from .price import Uncertainty, price_option, provider_configured
@@ -842,6 +843,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,7 +865,35 @@ 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
+        # --- TEL-11: the site's PV production, and NOTHING READS IT ----------
+        # ⚠️ INSTRUMENTATION. It is published, it is shown on the status page,
+        # and it reaches no decision: not `inputs_ok`, not the allocator, not
+        # the arbiter, not a claim, not a watchdog. Wiring it into the control
+        # law would be an unrequested behaviour change on a system driving a
+        # real battery AND would destroy the measurement, because the loop would
+        # then react to the quantity being measured. `tools/tel11_pv_trace.py`
+        # is the instrument that says so, on both trees and both settings.
+        #
+        # ⚠️ `None` IS A READING THAT DOES NOT EXIST, AND IT IS SEEDED AS ONE.
+        # Nothing here ever becomes 0.0 by default; see `app/pv.py`.
+        self.pv_w = None
+        # Why there is no reading, in words the page prints - or, on a good
+        # read, the UNIT the value came in. Never empty.
+        self.pv_why = ("not configured" if not self.pv_roster
+                       else "not read yet")
+        # TEL-12. EVERY configured entity's own answer, `(entity, watts, why)`,
+        # in roster order - kept because `checks()` has to be able to name the
+        # sensor that is missing, and `self.pv_w` alone cannot. Empty before the
+        # first read, which is what "no entity has answered yet" is.
+        self.pv_parts = []
         # 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
         # wire right now, so it is recorded when the arbitration happens rather
@@ -923,6 +964,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
@@ -1626,6 +1673,57 @@ class Controller:
                    for inv in self.inverters)
 
     # -- io ------------------------------------------------------------------
+    @property
+    def pv_roster(self) -> tuple:
+        """Every configured PV production entity, or `()`. TEL-11/TEL-12.
+
+        ⚠️ ONE READING OF THE OPTIONS, and it is `pv.entities()` - the SAME call
+        `mqtt.optional_keys()` makes. The thing that decides whether the row is
+        ANNOUNCED, the thing that decides whether it is READ and the thing that
+        decides WHAT IS SUMMED have to be one predicate, or the add-on ends up
+        with an entity nothing feeds, a topic nothing declared, or a total taken
+        over a different list from the announced one. `announced_units()` in
+        mqtt.py is the same argument for the inverter roster, in its own words.
+
+        ⚠️ IT REPLACED A `pv_entity` PROPERTY RATHER THAN JOINING ONE. Two
+        properties where one is a subset of the other is the second spelling
+        arriving by the back door; every gate in this file reads this one.
+        """
+        return pv_read.entities(self.o)
+
+    async def _read_pv(self) -> None:
+        """This cycle's SITE PV production, or an ABSENCE with a reason.
+
+        TEL-11 for one entity, TEL-12 for a roster of them. `pv.total()` is where
+        "one of three is absent" becomes an absence of the SITE figure rather
+        than the sum of the two that answered, and its docstring is the argument.
+
+        ⚠️ IT ASSIGNS ON EVERY CALL, INCLUDING THE FAILING ONES. Leaving the
+        last good number standing through an outage is what `circulation` does
+        on purpose - there, a stale figure beats a zero that reads as health -
+        and it is exactly wrong here: this row is read back as HISTORY, and a
+        value that persists through an outage is indistinguishable from a real
+        one at the moment somebody is trying to work out whether the sun was
+        shining.
+
+        ⚠️ `hass.state()` RATHER THAN `hass.number()`, because the UNIT is half
+        the reading. See `pv.watts()`: a PV integration may publish kW, and
+        there is no magnitude heuristic that can separate 30 W of dusk from
+        30 kW of noon.
+        """
+        # ⚠️ TEL-12: EVERY ENTITY IN ONE GATHER, for the reason the outer
+        # gather exists (see `read_inputs()`). Read serially, a three-inverter
+        # roster with one slow sensor would add up to three of `hass.state()`'s
+        # 10 s timeouts to a cycle that feeds the ESP32 heartbeat - i.e. the
+        # telemetry channel would be able to push a healthy battery towards
+        # layer 1's veto, which is exactly the foot in the control path this
+        # card is not allowed to have. Gathered, N entities cost what one does.
+        roster = self.pv_roster
+        states = await asyncio.gather(
+            *(self.hass.state(entity) for entity in roster))
+        self.pv_w, self.pv_why, self.pv_parts = pv_read.total(
+            list(zip(roster, states)))
+
     async def read_inputs(self, now_mono: float | None = None) -> None:
         """Every input this cycle needs, and SAFETY-37's freshness verdict.
 
@@ -1657,8 +1755,26 @@ class Controller:
         # names for the WRITE path, one function up. Within a unit the order is
         # unchanged (SoC, then battery power), so at the shipped roster of one
         # this is the same two calls in the same order.
-        await asyncio.gather(*(self._read_unit(inv, now_mono)
-                               for inv in self.inverters))
+        #
+        # --- TEL-11: AND THE PV READ RIDES IN THIS SAME GATHER ---------------
+        # ⚠️ IN THE GATHER RATHER THAN ON A LINE OF ITS OWN, AND THAT IS THE
+        # WHOLE "OBSERVABILITY MUST NOT BE ABLE TO DELAY CONTROL" DECISION.
+        # This coroutine feeds the ESP32 heartbeat; a sequential read would add
+        # its own worst case - `hass.state()`'s 10 s timeout - to every cycle,
+        # so a hung PV sensor at a client site would push a healthy battery
+        # towards layer 1's ~30 s veto for the sake of a telemetry row.
+        # Gathered, its latency OVERLAPS reads that already happen and the
+        # added worst case is zero. `peak_forecast_entity` below is read
+        # serially and stays that way because it is a CONTROL input (the
+        # capacity guard sizes off it), so the site is entitled to wait for it.
+        #
+        # ⚠️ AND AN EMPTY PV ROSTER APPENDS NOTHING. Not a coroutine, not an
+        # HTTP call, not a log line: at the shipped default this gather is the
+        # same list of the same coroutines it has always been.
+        _reads = [self._read_unit(inv, now_mono) for inv in self.inverters]
+        if self.pv_roster:
+            _reads.append(self._read_pv())
+        await asyncio.gather(*_reads)
         if o.get("peak_forecast_entity"):
             raw = await self.hass.number(o["peak_forecast_entity"])
             # Accept kW or W - nobody's quarter-hour forecast is 50 W.
@@ -1744,6 +1860,7 @@ class Controller:
         inv.soc = await self.hass.number(inv.soc_entity)
         raw = await self.hass.number(inv.batt_entity, inv.batt_invert)
         was_stale = inv.batt_fresh.stale
+        was_releases = inv.batt_fresh.releases
         inv.batt_fresh.submit(raw, inv.standing_w(), now_mono)
         # ⚠️ `inv.batt` IS THE GATED VALUE. A stale register is a MISSING input,
         # not a measurement - `inputs_ok` sees the None, the site holds for
@@ -1752,11 +1869,52 @@ class Controller:
         inv.batt = inv.batt_fresh.reading()
         if inv.batt_fresh.stale and not was_stale:
             self.log_event(f"STALE {inv.name}: " + inv.batt_fresh.reason)
-            _LOG.error("SAFETY-37: %s battery-power register is not following "
-                       "its own command - %s. Treating it as MISSING, which "
+            # ⚠️ SAFETY-57 REWROTE THE LAST SENTENCE OF THIS LINE AND NOTHING
+            # ELSE IN IT. The escape clause used to read "It clears itself the
+            # moment the register reports a different value", full stop - and
+            # that was FALSE for the state this same line announces, because the
+            # 0 W it announces in the sentence before is exactly what stops the
+            # register ever being asked to report anything different. The live
+            # site sat in it for 790 s on 2026-09-21 and was freed by a human.
+            # ⚠️ SAFETY-56 REWROTE THE DIAGNOSIS HALF, WHICH SAFETY-57 LEFT
+            # STANDING ON PURPOSE. It used to open "battery-power register is
+            # not following its own command" - an accusation against a named
+            # piece of hardware, and FALSE on the very episode above. The
+            # pack read 11 % for the whole hold, every command in it was a
+            # DISCHARGE, and the register answered the first CHARGE command
+            # three seconds later - so the BMS was refusing, the register was
+            # publishing that refusal correctly, and the operator was sent to
+            # look at a working sensor. All three numbers are measured off the
+            # committed capture by test_freshness.py part 11a. The gate's
+            # conjunction is right and is NOT touched; only its conclusion was.
+            #
+            # ⚠️ AND THE TWO EXPLANATIONS ARE NAMED ONCE, IN `%s`, NOT TWICE.
+            # This line's own words are the OBSERVATION plus the one thing a
+            # log reader has to be told before acting - that the observation is
+            # not yet a verdict - and `freshness._grade()`'s sentence, which
+            # this line already interpolates, is where the pair is spelled out.
+            # Saying it in both halves of one sentence is how an operator
+            # learns to skim it.
+            _LOG.error("SAFETY-37: %s battery-power reading did not move under "
+                       "a command that did, WHICH IS NOT BY ITSELF A VERDICT "
+                       "ON THE REGISTER - %s. Treating it as MISSING, which "
                        "commands 0 W. It clears itself the moment the register "
-                       "reports a different value.",
-                       inv.name, inv.batt_fresh.reason)
+                       "reports a different value, and failing that %.0f s "
+                       "after the standing command falls below %.0f W "
+                       "(SAFETY-57: a verdict whose own consequence is a 0 W "
+                       "command cannot be tested again from inside it).",
+                       inv.name, inv.batt_fresh.reason,
+                       inv.batt_fresh.bound.release_s,
+                       inv.batt_fresh.bound.move_w)
+        elif inv.batt_fresh.releases > was_releases:
+            # ⚠️ SAFETY-57. REPORTED, NEVER SILENT. A latch that lets go on a
+            # timer and says nothing is a latch no operator can audit - and this
+            # one is withdrawing a SITE STOP. `release_note()` is written to say
+            # that nothing has been learned about the register, because nothing
+            # has.
+            self.log_event(f"STALE WITHDRAWN {inv.name}")
+            _LOG.warning("SAFETY-57: %s",
+                         inv.batt_fresh.release_note(inv.name))
 
     @property
     def shadow(self) -> bool:
@@ -2818,9 +2976,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 +3004,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 +3194,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 +3215,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 +3274,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 +3640,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,7 +4479,39 @@ 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,
         }
+        # --- TEL-11 ----------------------------------------------------------
+        # ⚠️ THE KEY IS PRESENT WITH THE VALUE `None` WHEN THERE IS NO READING,
+        # AND ABSENT ENTIRELY WHEN THERE IS NO SOURCE. Those are two different
+        # states and the publisher treats them as two: `mqtt.ABSENT_AS_UNKNOWN`
+        # turns the first into HA's own `None` payload, so the entity's state
+        # goes to `unknown` and the recorder records a GAP - which is how a
+        # reader of a week of history tells "no PV reported" from "PV reported
+        # 0 W". The second never reaches the broker at all, because an install
+        # that never set `pv_entity` or `pv_entities` has no such entity
+        # announced. ⚠️ TEL-12: AND THE ROW IS STILL ONE NUMBER. At a roster of
+        # three it is the SITE total, `None` unless EVERY entity answered - see
+        # `pv.total()`, whose note is where the decision not to publish a
+        # partial sum is argued. This line did not have to change for that, and
+        # that is the point: TEL-11's `None`-is-an-absence rule already covered
+        # it, one layer up.
+        #
+        # ⚠️ AND THE GATE IS `optional_keys()`, THE SAME EXPRESSION THE
+        # ANNOUNCEMENT USES. Written as a second predicate here the two could
+        # disagree, and both directions are bad - an announced entity nothing
+        # feeds, or a topic nothing declared. `announced_units()` two blocks
+        # down is the same discipline for the roster.
+        if "pv" in optional_keys(self.o):
+            values["pv"] = (None if self.pv_w is None
+                            else round(self.pv_w, 1))
         # ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input
         # watchdog subscribes to sensor.goodwe_p1_sample_age - see the entity-id
         # note in mqtt.py; the composed name is not the object_id - and forces layer-1
@@ -4528,8 +4793,38 @@ class Controller:
             if not entity:
                 out.append({"ok": False, "warn": False, "text": f"{label}: no entity configured"})
             elif value is None:
+                # ⚠️ SAFETY-56. THIS ROW ASSERTED A FALSE FACT ABOUT A NAMED
+                # ENTITY, WHICH IS THE WORST THING A DIAGNOSTIC CAN DO. It read
+                # "<entity> is missing or not numeric" for ANY None, and one of
+                # the ways this value becomes None is SAFETY-37's freshness gate
+                # withholding a reading that is present, numeric and updating -
+                # `Freshness.reading()` returns None BY DESIGN there. On the
+                # live site on 2026-09-21 the operator opened Developer Tools on
+                # the entity this row named, found it working, and had every
+                # reason to conclude the diagnostics were broken.
+                #
+                # ⚠️ AND IT IS FIXED BY SAYING LESS, NOT BY LOOKING HARDER. The
+                # row could ask `inv.batt_fresh.stale` - it is on the same
+                # object at the same moment - but this loop also renders the
+                # grid and SoC rows, which have no gate, and a branch per row
+                # would be a second place where "why is this None" is decided.
+                # The gate already has a surface of its own: `stale_note()`
+                # rides `liveness_notes()` a few rows below with the whole
+                # STALE_READING sentence in it, so the operator's discriminator
+                # is "is that row there?" and this row's job is only to stop
+                # pre-empting the answer. Same reason the wording is not shared
+                # with `freshness._grade()`: that one is a log line about a
+                # BEHAVIOUR, this one is a banner about an ENTITY.
                 out.append({"ok": False, "warn": False,
-                            "text": f"{label}: {entity} is missing or not numeric"})
+                            "text": f"{label}: no usable value this cycle from "
+                                    f"{entity} - and this row cannot tell which "
+                                    f"of two things that is: the entity is "
+                                    f"missing or not numeric, or it is "
+                                    f"publishing a number that this controller "
+                                    f"is withholding (a freshness gate does "
+                                    f"exactly that, and names itself in a row "
+                                    f"of its own). Confirm the entity in "
+                                    f"Developer Tools before replacing it"})
             else:
                 out.append({"ok": True, "warn": False, "text": f"{label}: {entity} = {value:g}"})
 
@@ -4734,6 +5029,92 @@ class Controller:
             # is both is a check nobody reads.
             out.append({"ok": False, "warn": True,
                         "text": "no peak forecast: maintenance charging is not capacity-capped"})
+        # --- TEL-11 ----------------------------------------------------------
+        # ⚠️ NO ROW AT ALL WHEN THE ROSTER IS EMPTY, AND THAT IS A DELIBERATE
+        # DIFFERENCE FROM THE PEAK-FORECAST CAUTION DIRECTLY ABOVE. That one
+        # nags because an unset forecast entity leaves a MONEY GUARD without an
+        # input; this one is pure instrumentation, and a permanent caution on
+        # every install that never asked for a PV channel is exactly the
+        # "no warning spam, no degraded status row" the card forbids.
+        #
+        # ⚠️ AND WHEN IT IS SET, A FAILED READ IS `ok=False, warn=True` - a
+        # CAUTION, never `bad`. `status_payload()` builds "NOT READY" from rows
+        # that are neither ok nor warn, and a telemetry channel that could put a
+        # battery site into NOT READY would be observability with a foot in the
+        # control path. The reason comes from `pv.watts()` rather than being
+        # re-derived here, so the page cannot disagree with the reading.
+        #
+        # --- TEL-12: AND AT A ROSTER OF ONE THESE TWO SENTENCES ARE 0.11.0's --
+        # ⚠️ THE `len(...) == 1` BRANCH IS 0.11.0's CODE UNCHANGED, DOWN TO THE
+        # f-string, so an install that set `pv_entity` reads the row it already
+        # reads. That is an ACCEPTANCE CRITERION rather than a courtesy, and it
+        # is graded across trees by `tools/tel11_pv_trace.py` rather than argued
+        # here: `pv.total()` passes a single entity's `why` through verbatim for
+        # exactly this reason. Multi-entity sentences are separate BECAUSE they
+        # have to say something the single-entity ones never could.
+        roster = self.pv_roster
+        if roster:
+            if len(roster) == 1:
+                if self.pv_w is None:
+                    out.append({"ok": False, "warn": True,
+                                "text": f"PV production: no reading from "
+                                        f"{roster[0]} - {self.pv_why}"})
+                else:
+                    # habit 14: the value sits inside its own literal text, in
+                    # its own slot, beside the entity it was read from and the
+                    # unit it was read in - so a transposition of any two of the
+                    # three is visible in the sentence rather than merely
+                    # present in it.
+                    out.append({"ok": True, "warn": False,
+                                "text": f"PV production: {self.pv_w:.0f} W "
+                                        f"from {roster[0]} (reported "
+                                        f"in {self.pv_why})"})
+            elif self.pv_w is None:
+                # ⚠️ THE ROW THAT SAYS THERE IS NO TOTAL, AND IT SAYS IT IN
+                # THOSE WORDS. `pv.total()`'s note is the argument; this is
+                # where the operator meets it. The partial information is NOT
+                # thrown away - every entity that reported is named with its
+                # watts and every one that did not is named with its reason -
+                # because this surface is read LIVE by a human who wants the
+                # diagnostic, whereas the MQTT row is read back COLD a week
+                # later by an attribution that would believe a smaller number.
+                # Different reader, different instant, different rule.
+                out.append({"ok": False, "warn": True,
+                            "text": "PV production: NO SITE TOTAL - "
+                                    + self.pv_why + ". Reporting: "
+                                    + (", ".join(
+                                        f"{ent} {watt:.0f} W"
+                                        for ent, watt, _y in self.pv_parts
+                                        if watt is not None) or "nothing")})
+            else:
+                # habit 14 at a roster: the total in its own slot, then EVERY
+                # contributor in its own slot with its own watts and its own
+                # unit. A sum that disagrees with the addends it is printed
+                # beside is visible in the sentence.
+                out.append({"ok": True, "warn": False,
+                            "text": f"PV production: {self.pv_w:.0f} W from "
+                                    f"{len(self.pv_parts)} entities ("
+                                    + ", ".join(
+                                        f"{ent} {watt:.0f} W in {why}"
+                                        for ent, watt, why in self.pv_parts)
+                                    + ")"})
+            # ⚠️ AND WHEN BOTH KEYS ARE SET, WHICH ONE WON IS STATED. `pv.py`'s
+            # `entities()` makes `pv_entities` REPLACE `pv_entity`, which is the
+            # right rule (its docstring says why) and is also the rule an
+            # operator upgrading from 0.11.0 is most likely to trip over: they
+            # add all their inverters to the new field and the old key is left
+            # standing, doing nothing. A replacement nobody is told about is the
+            # "one of which silently wins" `config.yaml` refuses elsewhere - and
+            # refusing to START over a telemetry key would be observability with
+            # a foot in the control path, so this is a CAUTION and never a `bad`
+            # row.
+            if pv_read.entity_is_ignored(self.o):
+                out.append({"ok": False, "warn": True,
+                            "text": "PV production: `pv_entities` is set, so "
+                                    "`pv_entity` is IGNORED - the "
+                                    f"{len(roster)} entities in the "
+                                    "list are what is summed. Clear "
+                                    "`pv_entity` to remove this caution"})
         return out
 
     def status_payload(self) -> dict:
@@ -4853,6 +5234,13 @@ class Controller:
             # identically zero and a permanent "0 W" row would be noise.
             *(() if len(self.inverters) <= 1
               else ((("Circulating", w(self.site_circulating_w)),))),
+            # TEL-11, and ONLY when a source is configured - see `checks()`.
+            # `w(None)` renders "—", which is how this row says "no reading"
+            # rather than "0 W". It sits beside Grid and Battery because the
+            # question it answers is the one those two cannot: at "Grid 0 W,
+            # Battery 0 W" the site is either becalmed or throwing away every
+            # watt it makes, and only this row separates them.
+            *(() if not self.pv_roster else ((("PV", w(self.pv_w)),))),
             ("State of charge", "—" if self.pack_floor_soc is None
              else f"{self.pack_floor_soc:g} %"),
             ("Commanded", w(self.target)),
@@ -4865,7 +5253,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})"),
@@ -5121,6 +5514,11 @@ async def amain() -> None:
                 broker.get("username") if broker else None,
                 broker.get("password") if broker else None,
                 omit=() if is_enabled(opts) else ("p1_age",),
+                # TEL-11. ⚠️ THE SHIPPED PREDICATE, NOT A SECOND READING OF THE
+                # OPTION - `Controller.publish()` gates the row on this same
+                # call. An install with no PV roster announces exactly
+                # what it announced before: no topic, no entity, no row.
+                include=optional_keys(opts),
                 # TEL-07. ⚠️ THE NAMES, NOT A ROSTER. `build_roster()` here
                 # would construct a SECOND set of `Inverter`s off the same
                 # Store, minutes before `Controller.__init__` constructs the

goodwe_controller/app/mqtt.py

@@ -85,8 +85,114 @@ 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"),
 ]
 
+# --- TEL-11: rows that exist ONLY when the operator configured a source ------
+#
+# ⚠️ A SECOND LIST RATHER THAN A TENTH ENTRY IN `SENSORS`, AND THE DEFAULT IS
+# WHAT MAKES IT ONE. `SENSORS` is announced by every caller of
+# `discovery_payloads()`; `OPTIONAL_SENSORS` is announced only by a caller that
+# ASKS, so a caller that has not been taught about `pv_entity` - `test_mqtt.py`'s
+# fixtures, `tools/rehearse_roster.py`, anything written next year - announces
+# exactly what it announced before. `p1_age` solves the same problem the other
+# way round, with `omit`, because `p1_age` is announced by DEFAULT and withdrawn
+# when the meter is off; this one does not exist by default and appears when a
+# source for it does. Getting that direction wrong is the hazard `omit`'s own
+# note names: an entity that exists and is never fed is a worse signal than one
+# that does not exist at all, and MOST installs will never set `pv_entity`.
+#
+# ⚠️ `state_class: measurement` IS THE WHOLE POINT OF THE ROW. It is what puts
+# the number into the recorder's long-term statistics, and a week of statistics
+# is what OPT-10 needs to say whether the surplus that left this site was cloud,
+# a charge-power limit, or the optimiser declining to charge.
+OPTIONAL_SENSORS = [
+    ("pv", "goodwe_pv_power", "PV power", "W", "power", "measurement", None),
+]
+
+# ⚠️ HA's OWN "this sensor has no value" PAYLOAD, and the one place this add-on
+# spells it. `homeassistant/components/mqtt/const.py` declares
+# `PAYLOAD_NONE = "None"` and `mqtt/sensor.py` tests it BEFORE the numeric
+# branch - `if payload == PAYLOAD_NONE: self._attr_native_value = None` - so the
+# entity's state becomes `unknown` rather than a number. (Read out of
+# github.com/home-assistant/core `dev` on 2026-09-24; the shipped MQTT-sensor
+# documentation says the same thing in its `state_topic` entry: "a 'None' value
+# will set the sensor to an unknown state".)
+PAYLOAD_NONE = "None"
+
+# The keys whose ABSENCE MUST BE PUBLISHED rather than skipped. ⚠️ THIS IS THE
+# DIFFERENCE BETWEEN "no PV reported" AND "PV reported 0 W" IN A WEEK OF
+# HISTORY, AND WITHOUT IT THE CHANNEL LIES IN THE WORSE DIRECTION. `publish()`
+# below drops a `None` - which is right for `circulation`, where the last figure
+# standing is better than a zero that reads as health - but a DROPPED pv row
+# leaves Home Assistant holding the last number it was told, forever, and the
+# recorder then draws a flat line at that value through an outage. Someone
+# reading it back would conclude the sun was not shining, which is precisely the
+# conclusion this card exists to TEST rather than to manufacture.
+ABSENT_AS_UNKNOWN = frozenset({"pv"})
+
+
+def optional_keys(opts: dict) -> tuple:
+    """Which `OPTIONAL_SENSORS` rows this configuration has a source for.
+
+    ⚠️ ONE ANSWER TO "IS THE PV ROW LIVE", read by the ANNOUNCEMENT (through
+    `MqttPublisher`) and by `Controller.publish()`. `announced_units()` above
+    exists for exactly this reason and says it in full: two spellings of one
+    predicate is how an entity gets announced that nothing feeds, or fed on a
+    topic nothing announced.
+
+    ⚠️ AND SINCE TEL-12 IT IS `pv.entities()` RATHER THAN A SECOND READING OF
+    THE OPTION - `Controller.pv_roster` is the SAME call. TEL-11 got away with
+    two spellings because both were `bool()` of one string; with `pv_entities`
+    beside `pv_entity`, and `pv_entities` REPLACING it, a second spelling is how
+    the row gets announced off one key and summed off the other. ⚠️ THE ROW IS
+    ONE SITE TOTAL AT EVERY ROSTER SIZE: there is deliberately no per-entity
+    topic, because the recorder statistic OPT-10 reads back is the site figure
+    and a per-inverter breakdown is a dashboard question the operator's own PV
+    integration already answers.
+    """
+    # ⚠️ THE IMPORT IS FUNCTION-LOCAL AND THAT IS NOT A STYLE CHOICE. This
+    # module is EXEC'D STANDALONE, outside its package, by `test_mqtt.py`
+    # part 8's mutation harness - which says so in its own comment, and whose
+    # honesty depends on it ("`app/mqtt.py` imports nothing from this package,
+    # which is what makes exec'ing it standalone honest rather than a stub").
+    # A module-scope `from . import pv` turns that whole instrument into an
+    # `ImportError` before it grades anything. `tools/tel11_pv_trace.py`'s
+    # `_load()` is the same decision for the same kind of reason. Measured, not
+    # assumed: move this line to module scope and test_mqtt.py part 8 dies.
+    from . import pv as _pv
+    return ("pv",) if _pv.entities(opts) else ()
+
+
 BASE = "goodwe_ctl"
 AVAILABILITY = f"{BASE}/availability"
 
@@ -269,15 +375,23 @@ def _payload(name, object_id, unique_id, state_topic, device,
     return cfg
 
 
-def discovery_payloads(units=(), omit=()) -> list:
+def discovery_payloads(units=(), omit=(), include=()) -> list:
     """Every `(topic, payload)` this add-on announces, in announcement order.
 
     Split out of `_announce()` so that the acceptance criterion can be graded as
     a DIFF OF THE ANNOUNCED PAYLOADS against `release/1.0`, rather than as a
     reading of the code. `_announce()` publishes exactly this list and nothing
     else, which is itself checked.
+
+    `include` names `OPTIONAL_SENSORS` keys to announce. ⚠️ IT DEFAULTS TO
+    NOTHING AND THE ROWS GO LAST, so no existing row's POSITION moves under any
+    configuration - not the site rows, not the per-unit ones. Order is part of
+    the output here (`_payload()`'s note, and test_mqtt.py part 1 asserts an
+    ordered LIST precisely because a re-order is a zero-byte edit that
+    re-announces every entity on a live install).
     """
     omit = set(omit)
+    include = [k for k in include if k not in omit]
     out = []
     for key, object_id, name, unit, dev_class, state_class, icon in SENSORS:
         if key in omit:
@@ -306,12 +420,19 @@ def discovery_payloads(units=(), omit=()) -> list:
                          unique_id,
                          f"{BASE}/{unit_state_key(slug, key)}",
                          device, unit, dev_class, state_class, icon)))
+    for key, object_id, name, unit, dev_class, state_class, icon in OPTIONAL_SENSORS:
+        if key not in include:
+            continue
+        out.append((
+            f"homeassistant/sensor/{BASE}_{key}/config",
+            _payload(name, object_id, f"{BASE}_{key}", f"{BASE}/{key}",
+                     DEVICE, unit, dev_class, state_class, icon)))
     return out
 
 
 class MqttPublisher:
     def __init__(self, host, port, username=None, password=None, omit=(),
-                 units=()):
+                 units=(), include=()):
         # `omit` drops sensor keys from discovery entirely. ⚠️ Announcing a
         # sensor that nothing will ever publish to is not harmless here:
         # p1_sample_age_s is a watchdog input, and an entity that exists but is
@@ -323,6 +444,10 @@ class MqttPublisher:
         # per-unit is announced, so every caller that has not been taught about
         # the roster keeps publishing what it published before.
         self.units = [str(u) for u in units]
+        # TEL-11. `mqtt.optional_keys(opts)` - the shipped predicate, not a
+        # second reading of the option. Defaults to empty, so a caller that has
+        # not been taught about it announces exactly what it announced before.
+        self.include = [str(k) for k in include]
         self.enabled = mqtt is not None and bool(host)
         self.client = None
         if not self.enabled:
@@ -359,7 +484,8 @@ class MqttPublisher:
         # announcement, so the check that diffs it against `release/1.0` is
         # diffing what actually goes on the wire - and a payload built here
         # instead would be one this add-on publishes and no check has ever seen.
-        for topic, cfg in discovery_payloads(self.units, self.omit):
+        for topic, cfg in discovery_payloads(self.units, self.omit,
+                                             self.include):
             self.client.publish(topic, json.dumps(cfg), retain=True)
         self.client.publish(AVAILABILITY, "online", retain=True)
 
@@ -369,7 +495,16 @@ class MqttPublisher:
         try:
             for key, value in values.items():
                 if value is None:
-                    continue
+                    # ⚠️ TEL-11. A DROPPED ROW IS NOT AN ABSENT ROW. Skipping
+                    # leaves Home Assistant holding the last value it was told,
+                    # which is what `circulation` wants (its note in main.py
+                    # says why) and is exactly wrong for a measurement somebody
+                    # will read back as history: a flat line at the last number
+                    # is indistinguishable from a real one. See
+                    # `ABSENT_AS_UNKNOWN`.
+                    if key not in ABSENT_AS_UNKNOWN:
+                        continue
+                    value = PAYLOAD_NONE
                 self.client.publish(f"{BASE}/{key}", str(value))
         except OSError as err:  # pragma: no cover
             _LOG.debug("MQTT publish failed: %s", err)

goodwe_controller/app/pv.py

@@ -0,0 +1,259 @@
+"""TEL-11/TEL-12 - the site's PV production, read from Home Assistant entities.
+
+WHY THIS IS AN ENTITY AND NOT A REGISTER. This add-on's RS485 bus carries the
+BATTERY inverter it drives. A household's PV inverter is, on nearly every site,
+a different box from a different vendor that reports into Home Assistant
+through its own integration - so the only place a product can read production
+for an arbitrary install is an HA entity. `pv_entities` therefore takes whatever
+`sensor.*` the site's own PV integration provides.
+
+⚠️ AND THERE IS USUALLY MORE THAN ONE OF THEM, WHICH IS TEL-12. TEL-11 shipped
+`pv_entity` as a single string and the owner of the reference site reported
+within minutes of 0.11.0 going live that they have SEVERAL PV inverters and
+could configure one. That is not a property of one house: a multi-string or
+multi-orientation roof routinely carries two or three inverters, each
+publishing its own power sensor. `entities()` below is the roster and `total()`
+is the site figure over it.
+
+⚠️ AND A PARTIAL TOTAL IS WORSE THAN NO TOTAL, WHICH IS THE WHOLE OF TEL-12.
+Three inverters configured, one `unavailable`, and the sum of the other two is A
+SMALLER NUMBER INDISTINGUISHABLE FROM A REAL ONE. Fed into OPT-10's attribution
+that reads as "there was less PV than there was" - which is the "no irradiance"
+conclusion the card exists to TEST rather than to manufacture. So `total()`
+answers `None` the moment ANY configured entity is absent. See the note on
+`total()` for the alternative that was weighed and why it lost.
+
+WHY THE CHANNEL EXISTS AT ALL. OPT-10 measured that 20.5 kWh of surplus left the
+site in 16 days while the pack had room, 12.6 kWh of it with the battery not
+charging at all - and could not say WHY, because PV production is recorded
+NOWHERE. Three causes need three different fixes (no irradiance: nothing to fix;
+a charge-power limit; the optimiser declining to charge - the only software
+defect), and guessing between them is how an optimiser gets tuned to solve a
+cloud problem. This module is the missing measurement and NOTHING ELSE.
+
+⚠️ NOTHING HERE MAY EVER REACH A CONTROL DECISION, AND THAT IS THE CARD'S FIRST
+CONSTRAINT RATHER THAN A STYLE NOTE. The add-on regulates a real battery; adding
+production as a term of the control law would be an unrequested behaviour change
+AND it would destroy the measurement, because the loop would then be reacting to
+the quantity being measured. `tools/tel11_pv_trace.py` is what says the path is
+untouched: it grades a control document that contains none of this material on
+both trees and with `pv_entity` set and unset.
+
+⚠️ ABSENCE IS NEVER ZERO, AND THAT IS THE SECOND CONSTRAINT. Every refusal below
+returns `None` with a REASON, never `0.0`. A PV channel that reported 0 W for a
+dead sensor would manufacture exactly the "there was no surplus to store"
+conclusion the card exists to TEST - and it would do it silently, in a week of
+recorder history nobody would re-derive. `app/hass.py`'s own note on `state()`
+is the same rule one layer down. ⚠️ TEL-12 EXTENDS THAT RULE RATHER THAN
+WEAKENING IT: at a roster of three, "one of them is absent" is an absence of the
+SITE figure, and it publishes as an absence. A partial sum is a second way of
+reporting 0-where-there-was-production, one layer up, and it is refused for the
+same reason.
+
+THE SIGN CONVENTION: POSITIVE IS PRODUCTION. Derived from the two conventions
+this add-on already ships rather than assumed:
+
+    `meter_entity`   positive = IMPORTING from the grid   (DOCS.md, Sources)
+    `batt_entity`    positive = DISCHARGING the pack      (DOCS.md, Sources)
+
+Both are "positive = power arriving at the house's AC bus", and production
+arrives there too. There is deliberately NO `pv_invert` to go with
+`meter_invert` and `batt_invert`: those two quantities are BIPOLAR and are READ
+BY THE CONTROL PATH - a reversed `batt_entity` feeds SAFETY-30's per-unit sign
+check and SAFETY-31's circulating-power sensor with a plausible number the site
+then acts on - whereas production is unipolar and is read by nothing. A reversed
+PV sensor announces itself as -4 kW at noon in the very history this card
+creates, and flipping it here would only hide it. See
+`DECISIONS/TEL-11-pv-production.md` §2.
+"""
+
+from .hass import BAD_STATES
+
+# Home Assistant's OWN power units, each as the number of watts one of it is.
+# ⚠️ READ OUT OF HA, NOT LISTED FROM MEMORY: `UnitOfPower` in
+# `homeassistant/const.py` (github.com/home-assistant/core, `dev`, retrieved
+# 2026-09-24) declares mW, W, kW, MW, GW, TW and BTU/h. Every factor here is an
+# exact power of ten, so none of them is a number anybody chose.
+#
+# ⚠️ BTU/h IS IN HA's ENUM AND DELIBERATELY NOT HERE. Its factor (0.293071…)
+# is a measured conversion rather than a decimal shift, no PV integration
+# publishes in it, and a wrong constant in the one channel that exists to
+# attribute a 20.5 kWh shortfall is worse than a refusal an operator can read.
+# It lands in the "not a power unit" refusal below, BY NAME.
+WATTS_PER = {
+    "mW": 0.001,
+    "W": 1.0,
+    "kW": 1000.0,
+    "MW": 1000000.0,
+    "GW": 1000000000.0,
+    "TW": 1000000000000.0,
+}
+
+# What `watts()` answers when there is nothing to report. ⚠️ THE REASON IS PART
+# OF THE RETURN VALUE, not a log line: it is what the status page prints, and an
+# absence whose cause is invisible sends an operator to look at the wrong box.
+UNIT_KEY = "unit_of_measurement"
+
+
+def watts(state: dict | None) -> tuple:
+    """`(watts, why)` from a Home Assistant state object.
+
+    `watts` is `None` whenever there is no reading - and `why` then says which
+    of the five refusals it was, in words an operator can act on. On a good read
+    `why` is the unit the value was read in, because "1234 W" and "1234, unit
+    unknown" are different claims and the page has to be able to make the first.
+
+    ⚠️ THE UNIT IS READ OFF THE ENTITY AND NOT ASSUMED, AND THERE IS NO
+    MAGNITUDE HEURISTIC. `read_inputs()` guesses kW-or-W for
+    `peak_forecast_entity` with `abs(raw) < 50`, which is safe there because
+    nobody's quarter-hour demand forecast is 50 W. It is NOT safe here: 30 W of
+    real production at dusk is an ordinary reading, and that heuristic would
+    publish it as 30 kW - a fabricated number, in the channel whose entire
+    purpose is to be believed a week later. A sensor whose unit this cannot read
+    is REFUSED rather than guessed at.
+    """
+    if state is None:
+        # `hass.state()` answers None for a non-existent entity, a 404 and a
+        # transport failure alike. All three are "no reading", and HA does not
+        # consider a non-existent entity an error - see `hass.state()`.
+        return None, "no state (entity missing, or the read failed)"
+    raw = str(state.get("state", "")).strip()
+    if raw.lower() in BAD_STATES:
+        # ⚠️ THE SAME LIST `hass.number()` REFUSES ON, IMPORTED RATHER THAN
+        # RESPELLED. A second copy of it is how one path starts treating
+        # `unavailable` as a number the other one rejects.
+        return None, f"entity is {raw or 'empty'}"
+    try:
+        value = float(raw)
+    except ValueError:
+        return None, f"state {raw!r} is not numeric"
+    unit = str((state.get("attributes") or {}).get(UNIT_KEY) or "").strip()
+    if not unit:
+        return None, ("no unit_of_measurement on the entity - it cannot be "
+                      "read in watts")
+    if unit not in WATTS_PER:
+        return None, (f"unit {unit!r} is not one of "
+                      f"{', '.join(WATTS_PER)} - it cannot be read in watts")
+    return value * WATTS_PER[unit], unit
+
+
+# --- TEL-12: the ROSTER, and the SITE figure over it --------------------------
+
+def entities(opts: dict) -> tuple:
+    """Every PV entity this configuration names, in configured order. TEL-12.
+
+    ⚠️ ONE ANSWER TO "WHICH ENTITIES ARE THE PV CHANNEL", and it is the answer
+    BOTH sides read. `Controller.pv_roster` is this call and
+    `mqtt.optional_keys()` is `bool()` of this call, so the thing that decides
+    whether the row is ANNOUNCED, the thing that decides whether it is READ and
+    the thing that decides HOW MANY entities are summed cannot disagree. TEL-11
+    already had that discipline for one entity and spelled the predicate TWICE
+    - `str(opts.get("pv_entity") or "").strip()` in `main.py` and again in
+    `mqtt.py`. Two spellings of one predicate is how an entity gets announced
+    that nothing feeds; a roster makes it how a SUM gets taken over a different
+    list from the one that was announced. It is one function now.
+
+    ⚠️ `pv_entities` REPLACES `pv_entity` RATHER THAN EXTENDING IT, and that is
+    CFG-04's shipped precedent (`inverters:` replaces the six flat keys) applied
+    to the only upgrade path that matters. The install this card exists for HAS
+    `pv_entity` set, to inverter A. Opening the Configuration tab, the natural
+    action is to put ALL the inverters in the new repeatable field - and under a
+    UNION rule that double-counts A unless the operator also remembers to clear
+    the old key. A doubled total is the same defect as a partial one in the
+    other direction, in the one channel that exists to be believed a week later.
+    Under REPLACE the effective roster is exactly what one key says, and no
+    arithmetic depends on a de-duplication rule the operator has to know about.
+    ⚠️ `Controller.checks()` says WHICH key is in use whenever both are set, so
+    the replacement is stated on the page rather than being silent.
+
+    ⚠️ AND IT DE-DUPLICATES WITHIN THE LIST, ORDER PRESERVED. A site cannot have
+    two sensors with one entity_id, so a repeated id in the list is never a
+    second inverter - it is a typo that would DOUBLE that inverter's production
+    in the total. `dict.fromkeys` is the order-preserving spelling.
+    """
+    listed = [e for e in (str(x or "").strip()
+                          for x in (opts.get("pv_entities") or [])) if e]
+    if listed:
+        return tuple(dict.fromkeys(listed))
+    one = str(opts.get("pv_entity") or "").strip()
+    return (one,) if one else ()
+
+
+def entity_is_ignored(opts: dict) -> bool:
+    """Is a set `pv_entity` being REPLACED by a set `pv_entities`? TEL-12.
+
+    ⚠️ HERE RATHER THAN IN `Controller.checks()`, for the reason `entities()`
+    exists: the rule and the sentence that reports the rule must not be two
+    readings of the options. This is the negative half of `entities()`' first
+    branch and it is spelled once, beside it, where an edit to one is in front
+    of whoever is editing the other.
+    """
+    return bool(str(opts.get("pv_entity") or "").strip()
+                and [x for x in (opts.get("pv_entities") or [])
+                     if str(x or "").strip()])
+
+
+def total(readings) -> tuple:
+    """`(watts, why, parts)` - the SITE's production, or an ABSENCE. TEL-12.
+
+    `readings` is `[(entity_id, state), ...]` in `entities()` order, one entry
+    per configured entity, each `state` shaped as `hass.state()` returns.
+
+    `parts` is `[(entity_id, watts, why), ...]` - EVERY entity's own answer from
+    `watts()`, kept because the operator surfaces have to be able to name which
+    sensor is missing. `watts` is the sum when every entity answered, and `None`
+    otherwise; `why` always says which of those it was, in words a status page
+    can print.
+
+    ⚠️ ONE OR MORE ABSENT -> THE TOTAL IS ABSENT. NOT THE PARTIAL SUM. This is
+    the decision the card turns on and it was taken deliberately against the
+    alternative, which was to publish the partial sum ALONGSIDE a count of how
+    many entities contributed. Both are defensible; this one wins on the ONE
+    question that matters, which is who reads the number and when:
+
+      * the MQTT row is read back COLD, a week later, by OPT-10's attribution
+        and by whatever plots `sensor.goodwe_pv_power` over that week. A partial
+        sum there is a smaller number indistinguishable from a real one, and the
+        count that would have qualified it lives in a SECOND entity with its own
+        history - so believing the total requires joining two recorder series by
+        timestamp to find out which samples to distrust. Nobody re-derives that,
+        which is the same "nobody will re-derive it" TEL-11's note names. And it
+        is worse than a gap in exactly the direction that matters: a gap makes
+        the attribution say "I do not know", a partial sum makes it say "there
+        was less sun than there was".
+      * the STATUS PAGE is read LIVE, by a human, who wants the diagnostic. So
+        the partial information is not thrown away - `Controller.checks()` names
+        every entity that DID report, with its watts, and every one that did
+        not, with its reason, in a row that states plainly that there is no site
+        total. Different reader, different instant, different rule.
+
+    A count published beside the total would also carry no information in the
+    state this function actually admits: the total is published ONLY when every
+    entity contributed, so the count would be the constant `len(parts)`.
+
+    ⚠️ AND `0 W` IS STILL A READING AT EVERY ROSTER SIZE - the test is
+    `watts is None`, never falsiness. An inverter honestly reporting 0 W at dusk
+    beside two that are producing must give the SUM of the three, not blank the
+    site: shading, a tripped string and nightfall are all real 0s, and a roster
+    that went to `unknown` whenever one member read zero would report an absence
+    on every clear evening and defeat the channel from the other end.
+    """
+    parts = [(ent, *watts(st)) for ent, st in readings]
+    if not parts:
+        # No roster. `Controller` does not call this in that state - the gate is
+        # `pv_roster` - but a reader of `parts` should never have to wonder.
+        return None, "not configured", parts
+    if len(parts) == 1:
+        # ⚠️ AT ONE ENTITY THIS IS `watts()` AND NOTHING ELSE: the same value
+        # and the SAME `why` string, passed through rather than re-composed, so
+        # 0.11.0's single-entity surfaces are byte-identical rather than
+        # similar. `tools/tel11_pv_trace.py` grades that identity across trees.
+        return parts[0][1], parts[0][2], parts
+    missing = [(ent, why) for ent, w, why in parts if w is None]
+    if missing:
+        return None, (
+            f"only {len(parts) - len(missing)} of {len(parts)} entities are "
+            f"reporting and a partial sum would understate production: "
+            + "; ".join(f"{ent} - {why}" for ent, why in missing)), parts
+    return (sum(w for _e, w, _y in parts),
+            f"{len(parts)} entities", parts)

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.12.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -147,6 +147,74 @@ options:
   inverters: []
   estop_fitted: false
 
+  # TEL-11 - THE SITE'S PV PRODUCTION, IN WATTS, AND IT IS READ BY NOTHING THAT
+  # DECIDES ANYTHING. Optional, empty on every install that does not set it, and
+  # when it is empty the add-on reads no entity, announces no entity, publishes
+  # no topic and shows no status row.
+  #
+  # ⚠️ AN HA ENTITY AND NOT A REGISTER, BECAUSE MOST SOLAR INVERTERS ARE NOT ON
+  # THIS BUS. The RS485 bus this add-on speaks carries the BATTERY inverter it
+  # drives; a household's PV inverter is normally a different box from a
+  # different vendor, reporting into Home Assistant through its own integration.
+  # So this takes whatever `sensor.*` the site's PV integration provides, any
+  # brand Home Assistant can read.
+  #
+  # ⚠️ POSITIVE IS PRODUCTION, and there is deliberately no `pv_invert` beside
+  # `meter_invert` and `batt_invert`. Those two quantities are bipolar AND are
+  # read by the control path, so a reversed sensor there is a plausible number
+  # the site acts on; production is unipolar and is read by nothing, so a
+  # reversed sensor announces itself as -4 kW at noon in the history this key
+  # exists to create. See DECISIONS/TEL-11-pv-production.md.
+  #
+  # ⚠️ THE ENTITY'S OWN `unit_of_measurement` IS WHAT IS BELIEVED - W, kW, MW
+  # and the rest of Home Assistant's power units. A sensor with no unit, or with
+  # a unit that is not power, is REFUSED and the status page says which: there
+  # is no magnitude heuristic that can tell 30 W of dusk from 30 kW of noon, and
+  # a factor of 1000 in the one channel that exists to be believed a week later
+  # is worse than a refusal an operator can read.
+  pv_entity: ""
+
+  # TEL-12 - THE SAME CHANNEL WHEN THE ROOF HAS SEVERAL INVERTERS, WHICH IS THE
+  # ORDINARY CASE AND NOT AN EDGE ONE. A multi-string or multi-orientation roof
+  # routinely carries two or three PV inverters, each publishing its own power
+  # sensor; 0.11.0 shipped `pv_entity` as a single string and the reference
+  # site's owner reported within minutes that they could configure one of
+  # theirs. List them all here and the row carries the SITE total.
+  #
+  # ⚠️ DECLARED, THIS REPLACES `pv_entity` - it does not extend it. Set both and
+  # ONLY this list is read, and the status page says so. That is CFG-04's rule
+  # for `inverters:` applied to the upgrade path this key exists for: the
+  # install being upgraded HAS `pv_entity` set, and an operator who adds all
+  # their inverters to this list while the old key still names one of them would
+  # DOUBLE that inverter under a union rule. Clear `pv_entity` when you fill
+  # this in.
+  #
+  # ⚠️ AND IF ANY ONE OF THEM IS NOT REPORTING, THERE IS NO SITE TOTAL - the row
+  # publishes `unknown` and the recorder records a GAP. It does NOT publish the
+  # sum of the ones that answered: two of three inverters add up to a smaller
+  # number that is indistinguishable from a real one, and a week later that
+  # reads as "there was less sun than there was" - the exact conclusion this
+  # channel exists to TEST rather than to manufacture. The status page names
+  # which entity is missing and why, and lists what the others reported, because
+  # a human reading it live wants the diagnostic; the recorded number does not,
+  # because nobody re-derives a week of history. See
+  # DECISIONS/TEL-12-several-pv-inverters.md.
+  #
+  # ⚠️ THE FIX IS NOT A TEMPLATE SENSOR THAT SUMS THEM. You may legitimately
+  # prefer one, but a template sensor summing an `unavailable` source yields the
+  # partial total silently - the same defect one layer down, in a place this
+  # add-on cannot see or report.
+  #
+  #   pv_entities:
+  #     - sensor.pv_east_power
+  #     - sensor.pv_west_power
+  #     - sensor.pv_garage_power
+  #
+  # Each entity's OWN `unit_of_measurement` is read, so a kW inverter beside a W
+  # one sums correctly. Empty is the shipped default and means "use `pv_entity`,
+  # which is also empty" - i.e. no PV channel at all, which is every install.
+  pv_entities: []
+
   # ==========================================================================
   # METER - where the grid reading comes from
   # ==========================================================================
@@ -872,6 +940,37 @@ schema:
       capacity_kwh: float(0.1,200)?
 
   estop_fitted: bool
+  # TEL-11. Optional, and OPTIONAL WITHOUT A COMPANION RULE - unlike
+  # `price_now_entity`/`price_avg_entity`, which are legal only while
+  # `price_provider` is `off` and make the add-on REFUSE TO START otherwise.
+  # Nothing in validate.py mentions this key: it cannot conflict with anything,
+  # because nothing else reads it.
+  pv_entity: str?
+
+  # TEL-12. ⚠️ A SECOND KEY RATHER THAN A LIST SHAPE ON `pv_entity`, AND THAT IS
+  # A MEASUREMENT AND NOT A PREFERENCE. `pv_entity` shipped in 0.11.0 as `str?`
+  # and the reference site has a string persisted in it. Declared as a list,
+  # Supervisor 2026.08.0 answers that stored string with
+  #
+  #   Invalid list for option 'pv_entity' in GoodWe RS485 Controller
+  #
+  # and `deepmerge`'s list strategy is `override`, so a shipped `[]` default does
+  # NOT rescue it - the operator's string stands and is refused. That is CFG-04
+  # §B's trap in the other direction: an add-on that will not start, and the
+  # schema needed to fix it pinned to the version that cannot be installed. The
+  # only single-key spelling Supervisor accepts for BOTH shapes is `match(.*)?`,
+  # which validates nothing at all (it admits a number, a dict, any list of
+  # anything) and renders as a plain text box. Measured, both of them, by
+  # `tools/supervisor_shape_probe.py` §G - the transcript is in
+  # DECISIONS/TEL-12-several-pv-inverters.md §1.
+  #
+  # ⚠️ AND `pv_entities: []` IN THE `options:` BLOCK IS LOAD-BEARING, exactly as
+  # `inverters: []` is. §G measures the same isolated counterfactual: the
+  # shipped defaults MINUS only this key are refused with `Missing option
+  # 'pv_entities' in root`, which is every options blob written before 0.12.
+  # `p1_phase_import_entities` is the shipped precedent for the pair.
+  pv_entities:
+    - str
 
   # ==========================================================================
   # METER - where the grid reading comes from

goodwe_controller/named_absence.py

@@ -0,0 +1,99 @@
+"""Read a value a check prints or grades without raising (TEST-26).
+
+Each test file is one script, so an IndexError in a print or a check name
+kills every check after it (MUTATION.md, FCST-06). Read through these instead,
+and conjoin `present(x)` in the check so the absence grades as a named FAIL.
+
+`ABSENT` values never raise: they format as `<ABSENT ...>` under any spec,
+index and attribute to themselves, compare unequal AND not-unequal, and are
+falsy. `not x`, `"a" not in x` and `all(... for _ in x)` are therefore TRUE of
+one, which is why the check needs the `present()` term. `int()`, `range()` and
+use as a list index still raise: guard those with `present()`.
+"""
+
+_NAN = float("nan")
+
+
+class Absent:
+    __slots__ = ("what",)
+
+    def __init__(self, what):
+        object.__setattr__(self, "what", what)
+
+    def __repr__(self):
+        return f"<ABSENT {self.what}>"
+
+    __str__ = __repr__
+
+    def __format__(self, spec):
+        return repr(self)
+
+    def __bool__(self):
+        return False
+
+    def __eq__(self, other):
+        return False
+
+    __ne__ = __lt__ = __le__ = __gt__ = __ge__ = __eq__
+
+    def __hash__(self):
+        return id(self)
+
+    def __getitem__(self, _):
+        return self
+
+    def __getattr__(self, _):
+        return self
+
+    def __call__(self, *_a, **_k):
+        return self
+
+    def __len__(self):
+        return 0
+
+    def __iter__(self):
+        return iter(())
+
+    def __contains__(self, _):
+        return False
+
+    def __float__(self):
+        return _NAN
+
+    def _same(self, *_):
+        return self
+
+    __add__ = __radd__ = __sub__ = __rsub__ = __mul__ = __rmul__ = _same
+    __truediv__ = __rtruediv__ = __floordiv__ = __rfloordiv__ = _same
+    __mod__ = __rmod__ = __neg__ = __pos__ = __abs__ = __round__ = _same
+
+
+def present(*xs):
+    """True when none of `xs` is an ABSENT stand-in."""
+    return not any(isinstance(x, Absent) for x in xs)
+
+
+def nth(seq, i=0, what=None):
+    """`seq[i]`, or an ABSENT saying how many items there were."""
+    n = 0 if seq is None else len(seq)
+    if -n <= i < n:
+        return seq[i]
+    return Absent(what or f"[{i}] of {n} item(s)")
+
+
+def first(it, what="no match"):
+    """`next(it)`, or ABSENT when it is exhausted."""
+    return next(iter(it), Absent(what))
+
+
+def field(mapping, key, what=None):
+    """`mapping[key]`, or ABSENT when the key (or the mapping) is missing."""
+    try:
+        return mapping[key]
+    except (KeyError, IndexError, TypeError):
+        return Absent(what or f"key {key!r}")
+
+
+def given(x, what="None"):
+    """`x`, or ABSENT when it is None - so `:.2f` and arithmetic cannot raise."""
+    return Absent(what) if x is None else x

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/scenarios/safety57-2026-09-21/manifest.json

@@ -0,0 +1,70 @@
+{
+ "generated": "2026-09-21T11:30:00+02:00",
+ "card": "SAFETY-57",
+ "what": "The 2026-09-21 episode: a healthy 0x0518 declared stale, the site parked at 0 W, and no exit reachable from inside the state.",
+ "source": {
+  "host": "sniffer@192.168.2.167 (goodwe-sniff)",
+  "nature": "PASSIVE listener on the RS-485 pair between the ESP32 master and the GW5000S-BP. It has no address on the bus and writes nothing.",
+  "file": "~/bus-a.log",
+  "window_local": [
+   "2026-09-21T10:30:00+02:00",
+   "2026-09-21T11:10:00+02:00"
+  ],
+  "timezone": "Europe/Brussels (the capture stamps a time of day and no date; the date is asserted here, not derivable from the file)",
+  "extraction": "lines whose time-of-day field lies in the window, verbatim, in capture order"
+ },
+ "file": {
+  "name": "bus-a-2026-09-21-1030-1110.log.gz",
+  "sha256_gz": "876fdaaf6d087125b184bfb4dd7ef4c3d1dd71ccad0fc271f8d268e8b489d134",
+  "sha256_plain": "fa07e13b60e230626a8c0964b9539783a71b5627a522fc5930fd9fda54438a48",
+  "bytes_gz": 17181,
+  "bytes_plain": 182400,
+  "lines": 3840
+ },
+ "decoder": "tools/decode_bus_capture.py - and it is the ONLY interpretation of these bytes this repository carries. Re-run it to re-derive every number below.",
+ "frame_census": {
+  "lines": 3840,
+  "unparsed": 0,
+  "bad_crc": 0,
+  "requests": 720,
+  "responses": 720,
+  "writes": 1200,
+  "write_echoes": 1200,
+  "unknown": 0
+ },
+ "series": {
+  "setpoint_w": {
+   "frames": 1200,
+   "changes": 224,
+   "first_s": 37801.687,
+   "last_s": 40199.693
+  },
+  "batt_w": {
+   "frames": 240,
+   "changes": 133,
+   "first_s": 37804.716,
+   "last_s": 40194.724
+  },
+  "soc_pct": {
+   "frames": 240,
+   "changes": 4,
+   "first_s": 37806.725,
+   "last_s": 40196.732
+  }
+ },
+ "the_episode_in_the_capture": {
+  "10:51:24.736": "0x0518 reaches -3 W. The pack is at 11 %, the loop has just reversed out of -447 W of charge, and the BMS refuses the discharge.",
+  "10:51:29.695": "the setpoint reaches +1060 W of discharge - 800 W of travel from the command standing when the register last moved.",
+  "10:52:21.695": "the setpoint is written as 0 W and stays there. This is the add-on's own `inputs missing -> command 0 W`, on the wire.",
+  "10:51:24.736..11:05:34.734": "0x0518 does not change value. 850.0 s.",
+  "10:52:21.695..11:05:31.698": "the setpoint does not change value. 790.0 s.",
+  "~11:04": "a human restarts the add-on. NOT VISIBLE IN THIS FILE - it is an action on 192.168.2.158 - and it is the only reason the episode ends.",
+  "11:05:31.698": "the restarted loop commands -400 W of CHARGE, which the pack accepts at 11 %.",
+  "11:05:34.734": "0x0518 answers -137 W. The register was healthy throughout."
+ },
+ "not_in_this_file": [
+  "the grid meter - a P1 telegram on a different wire. The 2.4 kW of export during the episode is from Home Assistant history and is NOT re-derivable here.",
+  "anything the add-on believed: Inverter.batt, inputs_ok, log lines. Those are INFERRED by replaying the shipped modules against these series (test_freshness.py part 10).",
+  "the restart at ~11:04."
+ ]
+}

goodwe_controller/test_arbitrage.py

@@ -79,6 +79,7 @@ import sys
 from datetime import datetime, timedelta, timezone
 
 from app import arbitrage as _arb
+from named_absence import first
 from app import main as _main
 from app import peakguard as _pg
 from app.arbiter import (
@@ -94,6 +95,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 +893,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 = first((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))), "no cycle() calling arbitrage.decide")
+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 +992,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 +1020,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 +1067,33 @@ 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
+            row = 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))
+            rec.append(row)
+            if shadow:
+                # --- TRANSCRIBED 1/3: `_shadow_settle()`'s record, taken
+                #     BEFORE the re-seed destroys its evidence.
+                row["would_w"] = float(res.target_w)
+                row["row"] = _shadow.words(
+                    {"shadow_mode": "on"}, control_started=False,
+                    would_w=float(res.target_w),
+                    sized_from_meter=row["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 +1105,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 +1163,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_clamp.py

@@ -78,6 +78,8 @@ import re
 import sys
 from datetime import datetime, timedelta, timezone
 
+from named_absence import given, nth, present
+
 from app.clamp import (
     CLEAR_CYCLES, REASON_CODE, REASSERT_S, SUSTAINED_CYCLES, ClampWatchdog,
     clamp_to_rating,
@@ -322,15 +324,15 @@ _esc_fires = [5.0 * (CLEAR_CYCLES + 2 + _j)
                            T0 + timedelta(seconds=5.0 * (CLEAR_CYCLES + 2 + _j)))]
 _esc_delay = _esc_fires[0] - _RUNAWAY_AT if _esc_fires else None
 print(f"    budget spent by a benign episode, then a continuous runaway from "
-      f"t={_RUNAWAY_AT:.0f}s: first alarm at t={_esc_fires[0]:.0f}s "
-      f"(delay {_esc_delay:.0f}s)")
+      f"t={_RUNAWAY_AT:.0f}s: first alarm at t={nth(_esc_fires, 0):.0f}s "
+      f"(delay {given(_esc_delay):.0f}s)")
 check(f"⚠️ a SUSTAINED runaway speaks even when an earlier, unrelated episode "
-      f"spent the budget - it is not held for REASSERT_S ({_esc_delay:.0f}s "
+      f"spent the budget - it is not held for REASSERT_S ({given(_esc_delay):.0f}s "
       f"delay, escalation is {SUSTAINED_CYCLES} cycles)",
       _esc_delay is not None and _esc_delay < REASSERT_S / 2)
 check("...and it speaks at the escalation boundary rather than immediately, "
       "which is what keeps the scattered flood suppressed",
-      _esc_delay >= 5.0 * (SUSTAINED_CYCLES - 1))
+      _esc_delay is not None and _esc_delay >= 5.0 * (SUSTAINED_CYCLES - 1))
 
 # ⚠️ `last_alarm` SURVIVING THE DE-ASSERT IS NOW LOAD-BEARING, AND NOTHING
 # PINNED IT. Review built the mutation: if the de-assert path ALSO refreshed
@@ -523,7 +525,7 @@ check(f"a long winding episode does NOT flood the 40-row event log "
       f"({len(rows_l)} rows for {ctl_l.clamp_wd.engagements} engagements)",
       ctl_l.clamp_wd.engagements > 40 and len(rows_l) <= ctl_l.clamp_wd.episodes)
 check("...and the count in the row is the counter's, so nothing is lost",
-      f"{ctl_l.clamp_wd.engagements} engagement(s)" in rows_l[-1])
+      f"{ctl_l.clamp_wd.engagements} engagement(s)" in nth(rows_l, -1))
 # The RED row exists only while engaged, and the episode above is short, so it
 # is captured mid-run rather than asserted after the hysteresis has cleared it.
 check("the status page goes red WHILE it is engaged",
@@ -1093,7 +1095,8 @@ check("...and the TRANSPOSED sentence appears on NEITHER surface, so the two "
       not any(f"the computed setpoint {_sent_x:+.0f} W was clamped to "
               f"{_asked_x:+.0f} W" in e for e in _rows_x)
       and f"the computed setpoint {_sent_x:+.0f} W was clamped to "
-          f"{_asked_x:+.0f} W" not in notes_x[0]["message"])
+          f"{_asked_x:+.0f} W" not in nth(notes_x, 0)["message"]
+      and present(nth(notes_x, 0)))
 # The DEVICE bound, off part 6c's controller: same sentence, other stage. The
 # unit of coverage is the call site, and `bound` is the only thing that differs
 # between the two rows an operator can receive.
@@ -1105,7 +1108,7 @@ check("...and the same ordered pair holds on the DEVICE-bound row, where the "
       and any(f"the computed setpoint {_asked_w:+.0f} W was clamped to "
               f"{_sent_w:+.0f} W" in e for e in ctl_w.events)
       and f"the computed setpoint {_asked_w:+.0f} W was clamped to "
-          f"{_sent_w:+.0f} W" in notes_w[0]["message"])
+          f"{_sent_w:+.0f} W" in nth(notes_w, 0)["message"])
 
 
 # ==============================================================================

goodwe_controller/test_control.py

@@ -17,6 +17,7 @@ Read MUTATION.md before you report a survivor.
 
 import sys
 
+from named_absence import nth
 from app.control import (LOOP_TICK_S, PLANT_SETTLE_DOWN_S, PLANT_SETTLE_S,
                          SETTLE_CYCLES, SLEW_RAIL_FRAC, Tuning, compute,
                          slew_limit_w, unasked_power,
@@ -59,68 +60,34 @@ def check(name, cond):
 # stopped testing anything is precisely the failure this ticket exists to fix.
 # A comment cannot go stale-green, because it never claims to be running.
 #
-# Measured at 389d9ec. Numbers are the lead's independent reproduction.
-# ⚠️ THE SAFETY-13 ROWS WERE RE-MEASURED IN ROUND 2 AND THREE OF THEM WERE
-# WRONG AS FIRST WRITTEN. Every figure below marked (S13) was taken by deleting
-# the mechanism, purging __pycache__, running this file in the CI image and
-# counting `FAIL` lines, on THIS tree; the release/1.0 comparison figures were
-# taken the same way on a pristine c8dcb38 worktree.
+# Measured at TEST-26 on a purged tree in the CI image, each run graded to the
+# end of the file (98/99 where the `if _bad:` check is skipped). Before TEST-26
+# the rows marked * killed the file with an IndexError or ZeroDivisionError in
+# a check, so their earlier figures were short; those checks now fail by name.
 #
-#   - `output freeze` was written as 11. The mutation form its own note
-#     describes - the whole `target = min(...)/max(...)` line removed, `reason`
-#     left alone - gives 6 on this tree AND 6 on the first SAFETY-13 commit,
-#     against 2 on release/1.0. 11 is not reproducible by that form, or by
-#     removing the line and its `reason` (4), or by swapping min/max (12). The
-#     row is 6.
-#   - `saturation detector, saturated_now = False` was left at 11 while the
-#     SAFETY-13 section added checks that grade it. It is 15.
-#   - the footnote's `frozen = False` figure was left at 10 for the same
-#     reason. It is 13.
-#
-# The rows below `output freeze` are this ticket's own mechanisms: removing the
-# EXIT restores release/1.0's unbounded freeze; making `unasked_power()` return
-# True gives an exit to the limit case as well, which is the half of the
-# decision that has to stay unbounded; deriving SETTLE_CYCLES from
-# PLANT_SETTLE_S (18 s, the UP ramp) instead of PLANT_SETTLE_DOWN_S (23 s) is
-# the round-1 defect itself; and pinning `_SAT_COUNT_CAP` back at release/1.0's
-# literal 10 caps the counter below the bound and deletes the exit silently.
-#
-# ⚠️ ONLY THE ROWS THIS BRANCH MOVES WERE RE-MEASURED. Everything not marked
-# (S13) still carries 389d9ec's figures and was not re-run here.
-#
-# ⚠️ THE SLEW ROWS WERE RE-MEASURED AT SAFETY-39 AND ONE OF THEM MOVED: the
-# slew limit was 4 and is now 5, because the SAFETY-39 section grades it too.
-# The new row is the RAIL DEFAULT specifically - `slew_limit_w()` reduced to
-# `return abs(float(tuning.slew_w))`, which leaves the limit intact and only
-# removes the 0-means-the-rail resolution. Three checks notice, which is over
-# the invariant's floor of two. Both figures were reproduced by deleting the
-# mechanism, running this file and counting, on a tree with __pycache__ purged.
-#
-#   mechanism in compute()                     checks that fail when deleted
-#   ------------------------------------------ -----------------------------
-#   integrator freeze (AC 3)                                               2
-#   integrator clamp (AC 1)                                                6
-#   integrator bound follows max_w                                         4
-#   output clamp                                                           3
-#   slew limit                                                             5
-#   slew follows the rail (SAFETY-39), `slew_w` read raw                   3
-#   output freeze                                        (S13)             6
-#   the output freeze's EXIT (S13), freeze made unconditional again        4
-#   `unasked_power()` discriminates, replaced by `return True`  (S13)      6
-#   SETTLE_CYCLES from PLANT_SETTLE_S, not _DOWN_S        (S13)            9
-#   `_SAT_COUNT_CAP` pinned back at release/1.0's 10      (S13)            6
-#   deadband                                                               5
-#   quantisation                                                           2
-#   saturation detector, `saturated_now = False`         (S13)            15
-#   saturation duration (AC 2), fires instantly                            2
-#   sat counter reset on a good cycle                                      6
-#   target_grid_w bias                                                     3
-#   i_w=None seeding from prev_w                                           6
-#
-# The detector figure is for the `saturated_now = False` form specifically;
-# disabling it further down as `frozen = False` is a weaker mutation and gives
-# 13 on this tree (10 on release/1.0). Reproduce the same form or the number
-# will not match.
+#   mechanism in compute(), and the exact form deleted        checks that fail
+#   --------------------------------------------------------- ----------------
+#   integrator freeze: `if not frozen or i_w == 0.0` -> `if True`            6
+#   integrator clamp: `bounded = i_w`                                       6
+#   integrator bound follows max_w: default `limit = 5000.0`                3
+#   output clamp: `target = want`                                           3
+#   slew limit: `slewed = target`                                          17
+#   slew follows the rail (SAFETY-39): `slew_limit_w()` returns
+#     `abs(float(tuning.slew_w))` *                                          9
+#   output freeze: the `target = min(...)/max(...)` line removed            7
+#   output freeze: `if frozen:` -> `if False:` *                            14
+#   the output freeze's EXIT (S13): its `if` -> `if False` *                11
+#   `unasked_power()` returns True (S13)                                    6
+#   SETTLE_CYCLES from PLANT_SETTLE_S, not _DOWN_S (S13)                    9
+#   `_SAT_COUNT_CAP = 10`, release/1.0's literal (S13) *                   11
+#   deadband: its `if` -> `if False`                                        7
+#   quantisation: `target = target`                                         4
+#   saturation detector: `saturated_now = False` *                         27
+#   saturation detector: `frozen = False` *                                25
+#   saturation duration fires instantly: `sat_count >= 1`                   5
+#   sat counter not reset on a good cycle: `else sat_count`                 5
+#   target_grid_w bias: `error = grid_w`                                    5
+#   i_w=None seeding from prev_w: `i_w = 0.0`                              11
 #
 # ⚠️ IT HAS FOUND A DEAD MECHANISM TWICE, BOTH THE SAME WAY: a clamp standing in
 # for the mechanism under test. Deleting the integrator freeze once failed
@@ -142,10 +109,9 @@ def check(name, cond):
 # mutation run always has one, because the previous run wrote it. -B is still
 # worth passing, for the NEXT edit rather than this one.
 #
-# The error is one-directional - stale bytecode can only under-report - so
-# every figure above is a lower bound at worst, and the two zeros ever recorded
-# were both confirmed by fixing them and watching the count rise, which a
-# caching artefact cannot do.
+# Two things under-report a figure here, both in the same direction: stale
+# bytecode, and a check that raises and stops the file before the rest are
+# graded (MUTATION.md, FCST-06). The second is what the * rows above had.
 # ---------------------------------------------------------------------------
 
 print("control law")
@@ -520,9 +486,22 @@ for _ in range(20):
     rows.append((prev, d.target_w, d.i_w, d.reason))
     prev, i_w, sat = d.target_w, d.i_w, d.sat_count
 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...",
+check(f"non-zero prev_w, another writer: pinned at {nth(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
@@ -537,18 +516,23 @@ for c in range(24):
     cmds.append(d.target_w)
     prev, i_w, sat = d.target_w, d.i_w, d.sat_count
 check("the card's case: the block does hold at first, at 0 W",
-      cmds[6] == 0.0 and cmds[7] == 0.0)
+      nth(cmds, 6) == 0.0 and nth(cmds, 7) == 0.0)
 started = [i for i, c in enumerate(cmds) if c != 0.0]
-check(f"the card's case: the charge starts at cycle {started[0]}"
+check(f"the card's case: the charge starts at cycle {nth(started, 0)}"
       f" instead of never", bool(started))
 # ⚠️ AND IT STOPS AT THE FROZEN INTEGRATOR, NOT AT THE RAIL. This is AC 4: the
 # integrator moved while the output was blocked, and the release must not turn
 # 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})",
@@ -973,7 +957,8 @@ check("the shipped Tuning default is 0, i.e. the rail, so the law carries no "
 # serial, per goodwe/NOTES.md §1.1b. It is here because the ARITHMETIC is what
 # is being graded, and the arithmetic does not care.
 _rails = [100.0, 500.0, 1500.0, 2000.0, 5000.0, 9600.0, 10000.0]
-_ticks = {r: r / slew_limit_w(Tuning(max_w=r)) for r in _rails}
+# A zero limit grades as nan ticks (a named FAIL), not a ZeroDivisionError.
+_ticks = {r: r / (slew_limit_w(Tuning(max_w=r)) or float("nan")) for r in _rails}
 print("    ticks to cross the rail at the default, by rail: "
       + ", ".join(f"{r:.0f}W={t:.1f}" for r, t in _ticks.items()))
 check("⭐ AT EVERY RAIL THE DEFAULT TAKES THE SAME NUMBER OF TICKS TO CROSS IT - "
@@ -992,7 +977,7 @@ check("...and that is the same as saying the crossing takes the plant's own "
 # refuses on, and it is asserted HERE too so that the law and the gate cannot
 # drift apart - the rule can only ever refuse what this ratio says is too fast.
 _broken = Tuning(max_w=5000.0, slew_w=1000.0)
-_broken_s = 5000.0 / slew_limit_w(_broken) * LOOP_TICK_S
+_broken_s = 5000.0 / (slew_limit_w(_broken) or float("nan")) * LOOP_TICK_S
 print(f"    the 2026-09-05 configuration (max_w 5000, slew_w 1000) crosses its "
       f"rail in {_broken_s:.0f} s against a plant measured at {PLANT_SETTLE_S:.0f} s")
 check("⭐ RESTORING slew_w 1000 AT max_w 5000 IS FASTER THAN THE PLANT, and by "
@@ -1115,25 +1100,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_delivery.py

@@ -31,6 +31,8 @@ import re
 import sys
 from datetime import datetime, timedelta, timezone
 
+from named_absence import given, present
+
 from app.control import Tuning
 from app.delivery import (
     DELIVERY_OPTION_DEFAULTS, DELIVERY_SHARE_FRACTION, REASON_CODE,
@@ -738,8 +740,8 @@ async def _at_saturation_w(sat, b_frac=_SAT_B_FRAC):
 _c_ship, _r_ship = asyncio.run(_at_saturation_w(_SAT_SHIPPED))
 _c_up, _r_up = asyncio.run(_at_saturation_w(_SAT_RAISED))
 _b_ship, _b_up = _c_ship.inverters[1], _c_up.inverters[1]
-_gap_ship = short_by(_b_ship.standing_w(), _b_ship.batt)
-_gap_up = short_by(_b_up.standing_w(), _b_up.batt)
+_gap_ship = given(short_by(_b_ship.standing_w(), _b_ship.batt), "B not short")
+_gap_up = given(short_by(_b_up.standing_w(), _b_up.batt), "B not short")
 
 check(f"the raised threshold is a config an operator can actually enter: "
       f"{_SAT_RAISED} W is inside the shipped schema "
@@ -762,7 +764,7 @@ check("the raised arm REACHED the comparison: B was asked for a discharge "
       "share, is short of it, is live, is not parked, and NOTHING accounts for "
       "it - the only thing standing between this unit and an alarm is the "
       "configured watts",
-      float(_b_up.standing_w()) > 0 and _gap_up is not None
+      float(_b_up.standing_w()) > 0 and present(_gap_up)
       and not _b_up.sign_wd.tripped
       and account(live=True, parked=False, soc=_b_up.soc,
                   bms_floor=_b_up.bms_soc_floor) is None)
@@ -780,7 +782,7 @@ check("...and SAFETY-43's RELATIVE arm is silent on both arms of this fixture, "
 check("...and its shortfall lands STRICTLY BETWEEN the two configured "
       "thresholds, which is the one place the two answers can differ. Part 4's "
       "fixtures are all above both, which is exactly why they cannot see this",
-      _gap_up is not None and float(_SAT_SHIPPED) < _gap_up < float(_SAT_RAISED))
+      present(_gap_up) and float(_SAT_SHIPPED) < _gap_up < float(_SAT_RAISED))
 
 check("AT THE SHIPPED THRESHOLD THE UNIT IS NAMED",
       _r_ship[-1]["named"] == ("inverter-b",))

goodwe_controller/test_freeze.py

@@ -821,9 +821,9 @@ all_notes = all_notes_of(hass_f)              # the whole surface
 # install has. Flipped here rather than plumbing a whole P1 transport in - the
 # row's own content is what is under test.
 ctl_f.p1_enabled = True
-rows = [c for c in ctl_f.checks() if "METER MAY BE FROZEN" in c["text"]]
+frozen_rows = [c for c in ctl_f.checks() if "METER MAY BE FROZEN" in c["text"]]
 print(f"    frozen at +4000 W: command ran to {ctl_f.target:.0f} W, "
-      f"{len(notes)} notification(s), {len(rows)} red status row(s)")
+      f"{len(notes)} notification(s), {len(frozen_rows)} red status row(s)")
 # SURFACE-WIDE, deliberately, and the second guard has now landed. SAFETY-03
 # ships `goodwe_output_clamp`, and this scenario - a runaway loop winding into
 # the rail - raises it legitimately: the loop asks for more than the rating and
@@ -849,7 +849,7 @@ check("...with a fixed notification_id so repeats replace, not stack",
 check("...and it says the controller is still running",
       bool(notes) and "STILL RUNNING" in notes[0]["message"])
 check("the status page carries a failed row saying so",
-      len(rows) == 1 and not rows[0]["ok"] and not rows[0]["warn"])
+      len(frozen_rows) == 1 and not frozen_rows[0]["ok"] and not frozen_rows[0]["warn"])
 check("the event log names it", any("METER FROZEN" in e for e in ctl_f.events))
 # ⚠️ NOTIFY, NOT TRIP. If a later cut turns this into a trip it must come here
 # and change this expectation deliberately, not discover it in the field.

goodwe_controller/test_inverter.py

@@ -73,6 +73,8 @@ import time
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 
+from named_absence import first, given, nth, present
+
 from app import main as app_main
 from app.inverter import LINK_STALE_S, UNIT_A, Inverter, build_roster
 from app.main import WRITE_BUDGET_S, Controller
@@ -993,8 +995,9 @@ _compute_calls = [n for n in ast.walk(MAIN_AST)
                   and n.func.id == "compute"]
 check("main.py has exactly ONE `compute(` call site, so the argument graded "
       "below is unambiguously the shipped one", len(_compute_calls) == 1)
-_actual_src = ast.unparse(
-    next(k.value for k in _compute_calls[0].keywords if k.arg == "actual_w"))
+_actual_kw = first((k.value for k in nth(_compute_calls, 0).keywords if k.arg == "actual_w"),
+                   "no actual_w= keyword")
+_actual_src = ast.unparse(_actual_kw) if present(_actual_kw) else repr(_actual_kw)
 _site_batt_assign = [ast.unparse(n.value) for n in ast.walk(CTRL)
                      if isinstance(n, ast.Assign) and len(n.targets) == 1
                      and isinstance(n.targets[0], ast.Name)
@@ -1073,7 +1076,7 @@ print("6. AC 6: independent heartbeats, with the hang INJECTED")
 #
 # Two things fix it and both are graded: the writes go out CONCURRENTLY, and
 # each one is bounded by `WRITE_BUDGET_S`.
-_HB_MAX = read_schema_max("heartbeat_s")
+_HB_MAX = given(read_schema_max("heartbeat_s"), "heartbeat_s bound")
 print(f"    WRITE_BUDGET_S {WRITE_BUDGET_S:.0f} s + the schema's largest "
       f"heartbeat_s {_HB_MAX:.0f} s = {WRITE_BUDGET_S + _HB_MAX:.0f} s, against "
       f"layer 1's {FIRMWARE_INGEST_VETO_S:.0f} s veto")

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."""
@@ -162,22 +203,28 @@ class FakeClient:
         self.msgs.append((topic, payload, retain))
 
 
-def announce(units=(), omit=(), module=mqtt):
+def announce(units=(), omit=(), module=mqtt, include=()):
     """The messages `_announce()` publishes, through the SHIPPED method.
 
     ⚠️ Not `discovery_payloads()` directly. Part 2 proves the two agree; every
     other part goes through this one, so what is diffed is what paho is told.
+
+    `include` is TEL-11's optional-row set and DEFAULTS TO EMPTY here for the
+    same reason it does in the shipped constructor: every check in this file
+    written before that key existed must go on grading the announcement an
+    install that never set `pv_entity` receives, which is all of them.
     """
     pub = module.MqttPublisher.__new__(module.MqttPublisher)
     pub.omit = set(omit)
     pub.units = [str(u) for u in units]
+    pub.include = [str(k) for k in include]
     pub.enabled = True
     pub.client = FakeClient()
     pub._announce()
     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 +233,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 +278,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,15 +313,61 @@ 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) == ([], [], []))
 
+# --- TEL-11 ------------------------------------------------------------------
+# ⚠️ THE OPTIONAL ROW'S DEFAULT IS THE CLAIM, AND IT IS THE OPPOSITE DEFAULT
+# FROM `omit`'s. `p1_age` is announced unless withdrawn; `pv` does not exist
+# unless asked for. Every check above this line passes `include` nothing, so
+# they are all grading the announcement an install that never set `pv_entity`
+# receives - which is MOST installs, and is the acceptance criterion "unset
+# behaves exactly as today".
+check("⭐ TEL-11 ADDS NOTHING AT THE SHIPPED DEFAULT: a publisher that is told "
+      "nothing about `pv_entity` announces the same list, in the same order, "
+      "with the same bytes - so an install that never sets the option sees no "
+      "new entity, no new topic and no re-announcement of an old one",
+      announce(units=roster_names({})) == SITE_NOW)
+_PV_TOPIC = "homeassistant/sensor/goodwe_ctl_pv/config"
+_PV_PAYLOAD = ('{"name": "PV power", "object_id": "goodwe_pv_power", '
+               '"unique_id": "goodwe_ctl_pv", "state_topic": "goodwe_ctl/pv", '
+               '"availability_topic": "goodwe_ctl/availability", "device": '
+               + _DEV + ', "unit_of_measurement": "W", "device_class": '
+               '"power", "state_class": "measurement"}')
+_pv_one = announce(units=roster_names({}), include=("pv",))
+_m2, _c2, _a2 = diff(_pv_one, SITE_NOW)
+check("⭐ AND WITH `pv_entity` SET IT IS EXACTLY ONE NEW TOPIC AND NOTHING "
+      "ELSE MOVES: same eleven configs first, same bytes, same order - the "
+      "additions this card makes are additions, not a re-composition",
+      (_m2, _c2) == ([], []) and _a2 == [_PV_TOPIC]
+      and _pv_one[:len(SITE_NOW) - 1] == SITE_NOW[:-1])
+check("...and the payload is the site device, in watts, with "
+      "`state_class: measurement` - which is what puts it in the recorder's "
+      "statistics, and a week of statistics is the entire point of the card",
+      (_PV_TOPIC, _PV_PAYLOAD, True) in _pv_one)
+# ⚠️ AND IT GOES LAST, WHICH IS WHY A ROSTER OF TWO IS ASKED THE SAME QUESTION.
+# Placed among the site rows it would shift every per-unit entity's position in
+# the retained announcement - a zero-byte edit that re-announces inverter B.
+_pv_two = announce(units=NAMES2, include=("pv",))
+check("...and at a roster of two it is STILL the last config, after every "
+      "per-unit row, so no existing entity's position in the retained "
+      "announcement moves when the option is turned on",
+      [t for t, _p, _r in _pv_two if t.startswith("homeassistant/")][-1]
+      == _PV_TOPIC
+      and _pv_two == announce(units=NAMES2)[:-1] + [
+          (_PV_TOPIC, _PV_PAYLOAD, True)] + announce(units=NAMES2)[-1:])
+check("...and `omit` still wins over `include`, so the two arguments cannot "
+      "disagree about one key",
+      [t for t, _p, _r in announce(units=roster_names({}), include=("pv",),
+                                   omit=("pv",))
+       if t == _PV_TOPIC] == [])
+
 # ---------------------------------------------------------------------------
 print("\n2. what is diffed is what goes on the wire")
 # ---------------------------------------------------------------------------
@@ -280,11 +395,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 +452,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 +462,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 +485,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 +505,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 +548,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 "
@@ -588,8 +716,13 @@ print("\n8. verified by breaking it")
 # ---------------------------------------------------------------------------
 # ⚠️ MUTATED SOURCE, EXEC'D INTO A FRESH NAMESPACE. No file is edited and no
 # `.pyc` is consulted, so TEST-15's stale-bytecode failure cannot produce a
-# false survivor here. `app/mqtt.py` imports nothing from this package, which is
-# what makes exec'ing it standalone honest rather than a stub.
+# false survivor here. `app/mqtt.py` imports nothing from this package AT MODULE
+# SCOPE, which is what makes exec'ing it standalone honest rather than a stub.
+# ⚠️ TEL-12 IS WHY THAT NOW SAYS "AT MODULE SCOPE". `optional_keys()` reads
+# `pv.entities()` - one spelling of the roster predicate for the announcement and
+# for the SUM alike - and imports it INSIDE the function precisely so this
+# harness keeps working; its own comment says so. Nothing graded below calls
+# `optional_keys()`, so no mutant here is stubbed by that.
 def load(pairs):
     """`app/mqtt.py` with `pairs` applied, executed into a fresh module.
 
@@ -620,9 +753,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 +836,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 +909,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_named_absence.py

@@ -0,0 +1,426 @@
+"""Runnable check for TEST-26 - a missing value must be a NAMED red. `python3 test_named_absence.py`
+
+Every test file here is one script. A check or print that RAISES on a missing
+value (an empty list indexed, `next()` exhausted, `:.0f` on None) kills every
+check after it: the mutation it should name shows up as one unnamed traceback,
+and the checks below it are never graded (MUTATION.md, FCST-06).
+
+1. `named_absence.py`, the shared non-raising accessors.
+2. A scan of every `test_*.py` for the shapes that raise, which must find none.
+3. What the scan cannot see, counted on every run.
+"""
+import ast
+import sys
+from collections import Counter
+from pathlib import Path
+
+from named_absence import field, first, given, nth, present
+
+HERE = Path(__file__).resolve().parent
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+# ==============================================================================
+print("1. the accessors never raise, and an absence is never a pass")
+# ==============================================================================
+_a = nth([], 0)
+_b = first(x for x in (1, 2) if x > 5)
+_c = field({"a": 1}, "pv")
+_d = given(None)
+print(f"    {_a!r} {_b!r} {_c!r} {_d!r}")
+check("each accessor hands back the value when it is there",
+      nth([7, 8], -1) == 8 and first(iter([3])) == 3
+      and field({"pv": 0.0}, "pv") == 0.0 and given(0.0) == 0.0
+      and present(0.0, None, "", []))
+check("...and a stand-in that says what was missing when it is not",
+      repr(_a) == "<ABSENT [0] of 0 item(s)>" and repr(_c) == "<ABSENT key 'pv'>"
+      and not present(_a) and not present(1, _b) and not present(_c, _d))
+check("formatting, indexing, attributes and arithmetic do not raise",
+      f"{_a:.2f}|{_a[2]['x']:+.0f}|{_d.attr.get('k'):,}|{_d / 2 - 1:.1f}"
+      == "|".join(["<ABSENT [0] of 0 item(s)>"] * 2 + ["<ABSENT None>"] * 2))
+check("an absence is never equal, unequal, ordered or truthy - so `==`, `!=` "
+      "and `<` grade it FAIL",
+      not (_a == 0) and not (_a != 0) and not (_a < 1) and not (_a >= 1)
+      and not bool(_a) and not (_a == _a))
+
+
+# ==============================================================================
+print()
+print("2. no test file reads a possibly-missing value in a way that raises")
+# ==============================================================================
+# The scan flags, anywhere in a file:
+#   index   `name[k]` (constant k) where `name` holds a FILTERED list - a
+#           comprehension with an `if`, `filter()`, or an accumulator started
+#           as `[]` - directly or as returned by a function in the same file;
+#   next    `next(it)` without a default;
+#   format  a numeric format spec on a name that may be None - assigned None,
+#           an `... else None`, a one-argument `.get()`, or tested `is None`.
+# A site is guarded when an earlier operand of the same `and`/`or`, or the
+# test of an enclosing `if`/`while`/conditional expression, names the value,
+# or it sits in a `try`. A check's NAME is evaluated before its condition, so
+# a guard in the condition does not guard the name.
+_NUMFMT = set("fdeEgGn%xXbo")
+_FUNCS = (ast.FunctionDef, ast.AsyncFunctionDef, ast.Lambda)
+_COMPS = (ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp)
+
+
+def _filtered(rhs, returns):
+    if isinstance(rhs, (ast.ListComp, ast.GeneratorExp)):
+        return any(g.ifs for g in rhs.generators)
+    if isinstance(rhs, ast.List):
+        return not rhs.elts
+    if isinstance(rhs, ast.Call) and isinstance(rhs.func, ast.Name):
+        f = rhs.func.id
+        if f == "filter":
+            return True
+        if f in ("list", "sorted", "tuple") and rhs.args:
+            return _filtered(rhs.args[0], returns)
+        return "listy" in returns.get((f, None), ())
+    return False
+
+
+def _maybe_none(rhs, returns):
+    if isinstance(rhs, ast.Constant):
+        return rhs.value is None
+    if isinstance(rhs, ast.IfExp):
+        return _maybe_none(rhs.body, returns) or _maybe_none(rhs.orelse, returns)
+    if isinstance(rhs, ast.Call):
+        if isinstance(rhs.func, ast.Attribute) and rhs.func.attr == "get":
+            return len(rhs.args) == 1 or (len(rhs.args) == 2 and _maybe_none(rhs.args[1], returns))
+        if isinstance(rhs.func, ast.Name):
+            return "noney" in returns.get((rhs.func.id, None), ())
+    return False
+
+
+class _Scope:
+    def __init__(self, node, parent):
+        self.node, self.parent = node, parent
+        self.bound, self.listy, self.noney = set(), set(), set()
+
+
+def _dump(n):
+    return ast.dump(n)
+
+
+def _mentions(expr, base):
+    """`base` appears in `expr` other than as the thing being indexed, so
+    `x[0] == 1 and x[1]` does not count as guarding `x[1]`."""
+    b = _dump(base)
+    inner = {id(n.value) for n in ast.walk(expr) if isinstance(n, ast.Subscript)}
+    return any(_dump(x) == b and id(x) not in inner for x in ast.walk(expr))
+
+
+def _exits_on(st, base):
+    """`if not x: return` (or continue/break/raise) - x is guarded below it."""
+    return (isinstance(st, ast.If) and _mentions(st.test, base) and st.body
+            and isinstance(st.body[-1], (ast.Return, ast.Continue, ast.Break, ast.Raise)))
+
+
+def scan(src, census=None):
+    """[(line, kind, text)] for every unguarded raising read in `src`."""
+    tree = ast.parse(src)
+    parent = {c: p for p in ast.walk(tree) for c in ast.iter_child_nodes(p)}
+
+    def scope_node(n):
+        p = parent.get(n)
+        while p is not None and not isinstance(p, _FUNCS + _COMPS + (ast.Module,)):
+            p = parent.get(p)
+        return p
+
+    scopes = {tree: _Scope(tree, None)}
+    for n in ast.walk(tree):
+        if isinstance(n, _FUNCS + _COMPS):
+            scopes[n] = None
+    for n in list(scopes):
+        if n is not tree:
+            scopes[n] = _Scope(n, None)
+    for n, s in scopes.items():
+        if n is not tree:
+            s.parent = scopes[scope_node(n)]
+
+    def targets(t):
+        if isinstance(t, ast.Name):
+            yield t
+        elif isinstance(t, (ast.Tuple, ast.List)):
+            for e in t.elts:
+                yield from targets(e)
+        elif isinstance(t, ast.Starred):
+            yield from targets(t.value)
+
+    for n in ast.walk(tree):
+        if isinstance(n, _FUNCS):
+            a = n.args
+            for arg in a.posonlyargs + a.args + a.kwonlyargs + [a.vararg, a.kwarg]:
+                if arg is not None:
+                    scopes[n].bound.add(arg.arg)
+        elif isinstance(n, ast.comprehension):
+            for t in targets(n.target):
+                scopes[scope_node(n)].bound.add(t.id)
+        elif isinstance(n, (ast.For, ast.AsyncFor, ast.With, ast.AugAssign, ast.NamedExpr)):
+            ts = ([n.target] if not isinstance(n, ast.With)
+                  else [i.optional_vars for i in n.items if i.optional_vars])
+            for t0 in ts:
+                for t in targets(t0):
+                    scopes[scope_node(n)].bound.add(t.id)
+
+    # `x = <default> if x is None else x` makes x not-None: a scope that
+    # normalises x this way does not get x marked by its `is None` tests.
+    normalised = set()
+    for n in ast.walk(tree):
+        if (isinstance(n, ast.Assign) and isinstance(n.value, ast.IfExp)
+                and isinstance(n.value.test, ast.Compare)):
+            for t in n.targets:
+                if isinstance(t, ast.Name) and any(isinstance(x, ast.Name) and x.id == t.id
+                                                  for x in ast.walk(n.value.test)):
+                    normalised.add((scope_node(n), t.id))
+
+    # Two passes, so a function's return shape is known before its callers.
+    returns = {}
+    for _ in range(2):
+        for n in ast.walk(tree):
+            if isinstance(n, (ast.Assign, ast.AnnAssign)) and n.value is not None:
+                s = scopes[scope_node(n)]
+                for t0 in (n.targets if isinstance(n, ast.Assign) else [n.target]):
+                    if isinstance(t0, ast.Name):
+                        s.bound.add(t0.id)
+                        if _filtered(n.value, returns):
+                            s.listy.add(t0.id)
+                        if _maybe_none(n.value, returns):
+                            s.noney.add(t0.id)
+                    elif (isinstance(t0, ast.Tuple) and isinstance(n.value, ast.Tuple)
+                          and len(t0.elts) == len(n.value.elts)):
+                        for e, v in zip(t0.elts, n.value.elts):
+                            for t in targets(e):
+                                s.bound.add(t.id)
+                                if _filtered(v, returns):
+                                    s.listy.add(t.id)
+                                if _maybe_none(v, returns):
+                                    s.noney.add(t.id)
+                    elif (isinstance(t0, ast.Tuple) and isinstance(n.value, ast.Call)
+                          and isinstance(n.value.func, ast.Name)):
+                        for i, e in enumerate(t0.elts):
+                            for t in targets(e):
+                                s.bound.add(t.id)
+                                got = returns.get((n.value.func.id, i), ())
+                                if "listy" in got:
+                                    s.listy.add(t.id)
+                                if "noney" in got:
+                                    s.noney.add(t.id)
+                    else:
+                        for t in targets(t0):
+                            s.bound.add(t.id)
+            elif (isinstance(n, ast.Compare)
+                  and any(isinstance(o, (ast.Is, ast.IsNot)) for o in n.ops)
+                  and any(isinstance(c, ast.Constant) and c.value is None
+                          for c in [n.left] + n.comparators)):
+                for x in [n.left] + n.comparators:
+                    if isinstance(x, ast.Name) and (scope_node(n), x.id) not in normalised:
+                        s = scopes[scope_node(n)]
+                        while s.parent is not None and x.id not in s.bound:
+                            s = s.parent
+                        s.noney.add(x.id)
+        for fn in tree.body:
+            if not isinstance(fn, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                continue
+            s = scopes[fn]
+            for r in ast.walk(fn):
+                if not isinstance(r, ast.Return) or r.value is None or scope_node(r) is not fn:
+                    continue
+                vals = r.value.elts if isinstance(r.value, ast.Tuple) else [r.value]
+                for i, v in enumerate(vals):
+                    key = (fn.name, i if isinstance(r.value, ast.Tuple) else None)
+                    tags = returns.setdefault(key, set())
+                    if isinstance(v, ast.Name) and v.id in s.listy or _filtered(v, returns):
+                        tags.add("listy")
+                    if isinstance(v, ast.Name) and v.id in s.noney or _maybe_none(v, returns):
+                        tags.add("noney")
+
+    def resolve(name_node, attr):
+        s = scopes[scope_node(name_node)]
+        while s is not None:
+            if name_node.id in s.bound or name_node.id in getattr(s, attr):
+                return name_node.id in getattr(s, attr)
+            s = s.parent
+        return False
+
+    def guarded(node, base):
+        ch, p = node, parent.get(node)
+        while p is not None:
+            if isinstance(p, ast.BoolOp) and ch in p.values:
+                if any(_mentions(v, base) for v in p.values[:p.values.index(ch)]):
+                    return True
+            elif isinstance(p, (ast.IfExp, ast.If, ast.While)):
+                if ch is not p.test and _mentions(p.test, base):
+                    return True
+            elif isinstance(p, (ast.ListComp, ast.GeneratorExp, ast.SetComp)):
+                if ch is p.elt and any(_mentions(i, base) for g in p.generators for i in g.ifs):
+                    return True
+            elif isinstance(p, ast.Try) and ch in p.body:
+                return True
+            for field_ in ("body", "orelse"):
+                block = getattr(p, field_, None)
+                if (isinstance(block, list) and ch in block
+                        and any(_exits_on(st, base) for st in block[:block.index(ch)])):
+                    return True
+            if isinstance(p, _FUNCS):
+                return False
+            ch, p = p, parent.get(p)
+        return False
+
+    out = []
+    for n in ast.walk(tree):
+        if (isinstance(n, ast.Subscript) and isinstance(n.ctx, ast.Load)
+                and isinstance(n.value, ast.Name)):
+            k = n.slice
+            if isinstance(k, ast.UnaryOp) and isinstance(k.op, ast.USub):
+                k = k.operand
+            if (isinstance(k, ast.Constant) and type(k.value) is int
+                    and resolve(n.value, "listy") and not guarded(n, n.value)):
+                out.append((n.lineno, "index", ast.unparse(n)))
+        elif (isinstance(n, ast.Call) and isinstance(n.func, ast.Name)
+              and n.func.id == "next" and len(n.args) == 1 and not n.keywords):
+            if not guarded(n, n.args[0]):
+                out.append((n.lineno, "next", ast.unparse(n)[:60]))
+        elif (isinstance(n, ast.FormattedValue) and n.format_spec is not None
+              and isinstance(n.value, ast.Name)):
+            spec = "".join(v.value for v in n.format_spec.values
+                           if isinstance(v, ast.Constant))
+            if (spec and (spec[-1] in _NUMFMT or "," in spec)
+                    and resolve(n.value, "noney") and not guarded(n, n.value)):
+                out.append((n.lineno, "format", f"{{{n.value.id}:{spec}}}"))
+    if census is not None:
+        _count_blind(tree, resolve, census)
+    return sorted(set(out))
+
+
+def _count_blind(tree, resolve, census):
+    """Count, inside check() and print() arguments, the forms part 2 skips."""
+    for call in ast.walk(tree):
+        if not (isinstance(call, ast.Call) and isinstance(call.func, ast.Name)
+                and call.func.id in ("check", "print")):
+            continue
+        for n in (x for a in call.args for x in ast.walk(a)):
+            if isinstance(n, ast.Subscript) and isinstance(n.ctx, ast.Load):
+                k = n.slice.operand if isinstance(n.slice, ast.UnaryOp) else n.slice
+                if not isinstance(k, ast.Constant):
+                    continue
+                if isinstance(k.value, str):
+                    census["key"] += 1
+                elif isinstance(n.value, ast.Name):
+                    if not resolve(n.value, "listy"):
+                        census["name-list"] += 1
+                elif isinstance(n.value, ast.Attribute):
+                    census["attr-list"] += 1
+                else:
+                    census["other-index"] += 1
+            elif isinstance(n, ast.FormattedValue) and n.format_spec is not None:
+                if not isinstance(n.value, ast.Name):
+                    census["format-expr"] += 1
+                elif not resolve(n.value, "noney"):
+                    census["format-name"] += 1
+            elif isinstance(n, ast.BinOp) and isinstance(n.op, (ast.Div, ast.FloorDiv)):
+                census["division"] += 1
+
+
+# The scan must bite before its silence means anything: one planted site of
+# each kind, and the guarded spelling of each, which must NOT be flagged.
+_PLANTED = '''
+def run():
+    seen = []
+    t_gate = None
+    return seen, t_gate
+rows = [r for r in range(3) if r > 9]
+seen, t_gate = run()
+waits, n = [], 0
+check(f"first {rows[0]}", bool(rows))
+print(waits[0])
+check("pair", rows[0] == 1 and rows[1] == 2)
+print(seen[-1])
+print(f"{t_gate:.2f}")
+print(next(r for r in rows))
+'''
+_GUARDED = '''
+def run():
+    seen = []
+    t_gate = None
+    return seen, t_gate
+rows = [r for r in range(3) if r > 9]
+seen, t_gate = run()
+check("first", bool(rows) and rows[0] == 1)
+print(seen[-1] if seen else "-")
+check("pair", len(rows) == 2 and rows[0] < rows[1])
+print(f"{t_gate:.2f}" if t_gate is not None else "-")
+print(next((r for r in rows), None))
+def show(rows):
+    print(rows[0])
+def head():
+    if not rows:
+        return None
+    return rows[0]
+'''
+_hit = scan(_PLANTED)
+print(f"    planted: {_hit}")
+check("the scan flags a planted site of each kind - a filtered list indexed in "
+      "a check NAME whose condition guards it, an accumulator bound in a tuple "
+      "and one returned from a function, a maybe-None formatted, and next() "
+      "without a default",
+      [(k, t) for _l, k, t in _hit] == [
+          ("index", "rows[0]"), ("index", "waits[0]"), ("index", "rows[0]"),
+          ("index", "rows[1]"), ("index", "seen[-1]"),
+          ("format", "{t_gate:.2f}"),
+          ("next", "next((r for r in rows))")])
+check("...and flags none of the guarded spellings - `and`, a conditional, "
+      "an early return, a default - nor a parameter that shadows a filtered "
+      "name", scan(_GUARDED) == [])
+
+_SUITES = sorted(HERE.glob("test_*.py"))
+_found = {p.name: scan(p.read_text(encoding="utf-8")) for p in _SUITES}
+_all = [(f, *h) for f, hs in _found.items() for h in hs]
+for f, line, kind, text in _all:
+    print(f"    {f}:{line}  {kind:6}  {text}")
+check(f"no unguarded raising read in any of the {len(_SUITES)} test files "
+      f"({len(_all)} found) - read it through named_absence.py and conjoin "
+      f"present() in the check", _all == [] and len(_SUITES) >= 30)
+
+
+# ==============================================================================
+print()
+print("3. what part 2 cannot see, counted - these can still raise")
+# ==============================================================================
+# The scan knows a list is filtered, or a name may be None, only from its own
+# file's syntax. Each form below can still raise and is NOT graded; the counts
+# are of every such site in check() and print() arguments, largest first.
+_BLIND = {
+    "key": "`x['k']` - a dict key the code under test may omit",
+    "name-list": "`x[k]` on a list the scan cannot see is filtered - returned "
+                 "by another module or a method, or of a fixed length",
+    "format-name": "a numeric format on a name the scan has no reason to think "
+                   "is None - e.g. set from another module's function",
+    "format-expr": "a numeric format on an attribute, subscript or call",
+    "attr-list": "`obj.items[k]` - an attribute list",
+    "other-index": "`x[k]` on a call, a slice or a nested subscript",
+    "division": "`/` or `//` by a value that can be 0",
+}
+_census = Counter()
+for p in _SUITES:
+    scan(p.read_text(encoding="utf-8"), _census)
+for k, why in sorted(_BLIND.items(), key=lambda kv: -_census[kv[0]]):
+    print(f"    {_census[k]:5d}  {why}")
+print("    never counted: these forms outside check()/print() arguments; "
+      "attribute access, iteration, int() or range() on a None or an ABSENT; "
+      "a raise inside a fixture function or inside app/.")
+check("every counted form is in the printed table", set(_census) <= set(_BLIND))
+
+
+print()
+if fails:
+    print(f"{len(fails)} CHECK(S) FAILED")
+    sys.exit(1)
+print("all checks passed")