OPT-17 review: title the forecast row on Home; test the hint and blank rows

The new status row's id `solar_forecast` had no Home title, so Home showed it under the fallback "Inverter connection". Add "Solar forecast" / "Zonneprognose" to ui_text, and checks for the title, the tomorrow-gap hint and blank list rows (review mutations R7, R9, R14 now killed). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bdqr7PiaHcBnzPituu2yTC
OPT-17: the solar forecast can come from several entities, summed
2026-10-11 05:12:35 +02:00 · 2026-10-11 02:55:58 +02:00 · 2026-10-11 00:58:29 +02:00 · 2026-10-11 00:21:39 +02:00 · 2026-10-10 23:29:13 +02:00 · 2026-10-10 01:38:29 +02:00
316 changed files with 73945 additions and 3182 deletions
@@ -0,0 +1,2 @@
+# The admin/goodwe commit CI tests against. Bump: set to the full SHA of admin/goodwe release/1.0 HEAD (README.md, "CI and the infra pin").
+3b4ff84757f9c2c5b63a4b4a53e593ccaeafb847
@@ -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
@@ -156,8 +286,9 @@ jobs:
        run: |
          set -eu
          rm -rf "$WS" && mkdir -p "$WS/goodwe-addon" && cd "$WS/goodwe-addon"
-          git init -q .
-          git remote add origin "$(echo "$URL" | sed "s#://#://x-access-token:${TOKEN}@#")"
+          git init -q . && git remote add origin "$URL"
+          # Token as an env-set header: not in argv or .git/config (TOOL-9).
+          export GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN"
          if [ -n "$PRNUM" ]; then
            # Two fetches, not one, so that a failure to reach either ref fails
            # HERE with the ref in the message, rather than inside the merge
@@ -224,6 +355,165 @@ 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."
+
+      # CI-12: the infra repo at the ONE pinned commit in .gitea/infra-pin (read
+      # from the merged tree), as the sibling test_freeze.py looks for. Any
+      # failure here fails the job; the tests step below refuses the stub.
+      - name: check out admin/goodwe at the pin in .gitea/infra-pin
+        env:
+          URL: ${{ github.server_url }}/admin/goodwe.git
+          # Read access to admin/goodwe only; this job's own token cannot see it.
+          TOKEN: ${{ secrets.INFRA_READ_TOKEN }}
+        run: |
+          set -eu
+          # `|| true`: under pipefail a missing or comment-only pin would skip the FAIL line (TOOL-9).
+          PIN=$(grep -v '^#' "$WS/goodwe-addon/.gitea/infra-pin" | tr -d '[:space:]') || true
+          echo "$PIN" | grep -Eq '^[0-9a-f]{40}$' || { echo "FAIL: .gitea/infra-pin holds '$PIN', not a full 40-hex SHA."; exit 1; }
+          test -n "$TOKEN" || { echo "FAIL: secret INFRA_READ_TOKEN is not available to this run (a fork PR?)."; exit 1; }
+          rm -rf "$WS/goodwe" && mkdir -p "$WS/goodwe" && cd "$WS/goodwe"
+          git init -q .
+          # The token goes in a header via env: not in argv, and not in .git/config,
+          # which is mounted into the tests' container and outlives a failed job.
+          GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN" \
+            git fetch -q "$URL" "$PIN" || { echo "FAIL: could not fetch admin/goodwe at $PIN."; exit 1; }
+          git -c advice.detachedHead=false checkout -qf FETCH_HEAD
+          test "$(git rev-parse HEAD)" = "$PIN"
+          test -f sim/hwsim.py || { echo "FAIL: admin/goodwe@$PIN has no sim/hwsim.py."; exit 1; }
+          echo "infra: admin/goodwe @ $(git log --oneline -1)"
+
      - name: build the test image (shipped deps, from apk - see .gitea/ci/Dockerfile)
        run: |
          set -eu
@@ -244,16 +534,9 @@ jobs:
      # shorter timeout - a 60 s limit was tried during CI-01 and reported
      # exactly the false hang the docstring predicts.
      #
-      # ⚠️ WHAT THIS RUN DOES NOT COVER, stated because a pass here would
-      # otherwise over-claim. test_freeze.py's third section wants the infra
-      # repo's `sim/hwsim.py` to drive a real HTTP meter through the real
-      # transport. admin/goodwe is PRIVATE (checked via the API) and this
-      # workflow's GITHUB_TOKEN is minted for THIS repository only, so hwsim is
-      # absent here and `find_hwsim()` returns None. The rest of the file runs
-      # and passes. It does so SILENTLY - the file prints nothing to say the
-      # hwsim section was skipped - so "test_freeze.py: PASS" below is a weaker
-      # claim than it looks. That belongs to whoever owns test_freeze.py next;
-      # naming it here is the least this gate can do about it.
+      # test_freeze.py part 3 runs against the real `sim/hwsim.py` from the
+      # checkout above; GOODWE_REQUIRE_HWSIM=1 makes it fail rather than use its
+      # stub (CI-12). Lines a test prints with a `CI: ` prefix are echoed on PASS.
      # ⚠️ PYTHONDONTWRITEBYTECODE=1 IS BELT AND BRACES, NOT A FIX FOR A LIVE
      # HOLE. TEST-15 measured this runner's actual exposure and found none: the
      # checkout below is bind mounted `:ro`, so the interpreter physically
@@ -269,7 +552,7 @@ jobs:
      - name: the add-on's own tests
        run: |
          set -eu
-          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
+          docker run --rm -e PYTHONDONTWRITEBYTECODE=1 -e GOODWE_REQUIRE_HWSIM=1 -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
            cd /w/goodwe-addon/goodwe_controller
            set -- test_*.py
            if [ "$1" = "test_*.py" ]; then
@@ -282,6 +565,7 @@ jobs:
              start=$(date +%s)
              if python3 "$f" > /tmp/out 2>&1; then
                echo "PASS  $f  ($(( $(date +%s) - start ))s)"
+                grep "^CI: " /tmp/out || true
              else
                echo "FAIL  $f  ($(( $(date +%s) - start ))s)"
                tail -40 /tmp/out
@@ -0,0 +1,46 @@
+# CI-12: goes red when admin/goodwe release/1.0 has moved past .gitea/infra-pin.
+# It runs on add-on activity only; admin/goodwe's own `addon-pin` workflow
+# covers a move of release/1.0 there. Deliberately NOT a required check: it
+# reports; `checks / unit` stays the only gate. How to bump: README.md,
+# "CI and the infra pin".
+name: infra-pin
+
+on:
+  pull_request:
+  push:
+    branches: [release/1.0]
+
+jobs:
+  fresh:
+    runs-on: [self-hosted, goodwe-rig]
+    timeout-minutes: 30   # seconds of work; the rest is queueing for the shared slot
+    steps:
+      - name: compare .gitea/infra-pin with admin/goodwe release/1.0
+        env:
+          SELF: ${{ github.server_url }}/${{ github.repository }}.git
+          INFRA: ${{ github.server_url }}/admin/goodwe.git
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          INFRA_TOKEN: ${{ secrets.INFRA_READ_TOKEN }}   # admin/goodwe is private
+        run: |
+          set -eu
+          D=$(mktemp -d) && trap 'cd / && rm -rf "$D"' EXIT && cd "$D"
+          git init -q .
+          # The pin of the commit this event is about (the PR head, or the push).
+          # Token as an env-set header: not in argv or .git/config (TOOL-9).
+          GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $TOKEN" \
+            git fetch -q --depth 1 "$SELF" "$GITHUB_SHA" || { echo "FAIL: could not fetch $GITHUB_SHA here."; exit 1; }
+          # `|| true`: under the runner's pipefail a missing or comment-only pin
+          # would stop here on git's error instead of the FAIL line below (TOOL-9).
+          PIN=$(git show FETCH_HEAD:.gitea/infra-pin | grep -v '^#' | tr -d '[:space:]') || true
+          test -n "$PIN" || { echo "FAIL: .gitea/infra-pin is missing at $GITHUB_SHA, or holds only comments."; exit 1; }
+          test -n "$INFRA_TOKEN" || { echo "FAIL: secret INFRA_READ_TOKEN is not available to this run (a fork PR?)."; exit 1; }
+          # Header via env, as in checks.yml: the token stays out of argv.
+          HEAD=$(GIT_CONFIG_COUNT=1 GIT_CONFIG_KEY_0=http.extraHeader GIT_CONFIG_VALUE_0="Authorization: token $INFRA_TOKEN" \
+            git ls-remote "$INFRA" refs/heads/release/1.0 | cut -f1) || true
+          test -n "$HEAD" || { echo "FAIL: could not read admin/goodwe release/1.0."; exit 1; }
+          if [ "$PIN" != "$HEAD" ]; then
+            echo "STALE: .gitea/infra-pin is $PIN but admin/goodwe release/1.0 is $HEAD."
+            echo "       Test against $HEAD and bump the pin (README.md, \"CI and the infra pin\")."
+            exit 1
+          fi
+          echo "OK: .gitea/infra-pin $PIN is admin/goodwe release/1.0 HEAD."
@@ -4,6 +4,10 @@ The guide technicians carry is the PDF:

 **`docs/GoodWe-RS485-Field-Guide.pdf`** — 10 pages, A4, print it double-sided.

+⚠️ **Outdated: it is v0.1.0.** Its `slew_w` row is corrected in `build_guide.py`
+and `field-guide.html`, but the PDF has not been rebuilt (see below). Where the
+guide disagrees with `goodwe_controller/DOCS.md`, DOCS.md wins.
+
 It covers, in the order the work is done: pre-visit checks, hardware, firmware,
 add-on install and configuration, how to read the Web UI, the six commissioning
 gates, the e-stop (and the statement a site without one must sign), proving a
@@ -18,7 +22,8 @@ copy cannot drift from the PDF someone is holding in a cellar.
 python3 docs/build_guide.py     # regenerates field-guide.html and the PDF
 ```

-Requires Chrome or Chromium (used headless for print-to-PDF). Screenshots live
+Requires Chrome or Chromium (used headless for print-to-PDF); `CHROME` in the
+script is a Windows path, so edit it on any other machine. Screenshots live
 in `docs/img/` and are base64-embedded, so `field-guide.html` is standalone.

 ⚠️ **Every section must stay under the A4 printable height** (1039 px at 96 dpi
@@ -30,9 +30,11 @@ goodwe_controller/         the add-on
                           returns, run against its own release image
 firmware/goodwe-master.yaml  ESPHome config for the T-CAN485
 estop/rs485_log.py           optional RS485 e-stop / bus witness
-docs/GoodWe-RS485-Field-Guide.pdf  the guide techs carry (10pp, A4)
+docs/GoodWe-RS485-Field-Guide.pdf  the guide techs carry (10pp, A4; outdated)
 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,
@@ -48,6 +50,9 @@ https://gittea.kammenstraatha.duckdns.org/admin/goodwe-addon

 then install **GoodWe RS485 Controller**.

+Then turn on **Watchdog** on the add-on's Info tab — see
+[Before you start](goodwe_controller/DOCS.md#before-you-start).
+
 ⚠️ **The repository must be PUBLIC for this to work.** Home Assistant clones it
 anonymously; against a private repo the store shows nothing and gives no useful
 error. If it must stay private, install locally instead: copy
@@ -77,8 +82,8 @@ machine itself dying:
 2. **Wind-down before firmware updates** — 0 W written before the update starts.
 3. **RS485 e-stop (optional)** — writes 0 W after 30 s of total bus silence.

-Sites sold without the e-stop must have the acknowledgement in `FIELD-GUIDE.md`
-§10 signed.
+Sites sold without the e-stop must have the client acknowledgement in the field
+guide (Step 7b) signed.

 ## Development

@@ -100,6 +105,12 @@ has the mechanism, the measurement, and what the flags do not do. They are not u
 each assertion corresponds to a rule whose absence produced an observed failure
 on real hardware, and the comments in `control.py` say which.

+### CI and the infra pin
+
+CI (`.gitea/workflows/checks.yml`) runs every `test_*.py`, with `admin/goodwe` checked out next to this repo at the commit in `.gitea/infra-pin`, so `test_freeze.py` grades against the real `sim/hwsim.py`. If that checkout fails, the job fails. The local stub is used only in local runs, and it prints `STUB USED` when it is.
+The pin tracks `admin/goodwe` **release/1.0**, not master. Two non-required checks go red when release/1.0 has moved past the pin: `infra-pin / fresh` here, on any add-on PR or push to release/1.0, and `addon-pin / fresh` in `admin/goodwe`, on every push to its release/1.0. Nothing re-runs `addon-pin` after a bump, so it stays red on that admin/goodwe commit; `infra-pin / fresh` green on the bump is the all-clear.
+**Bump the pin** whenever either is red. Set `.gitea/infra-pin` to the new release/1.0 SHA (`git ls-remote <gitea>/admin/goodwe.git refs/heads/release/1.0`) in a PR, and let `checks / unit` grade the tests against it. CI reads `admin/goodwe` with the Actions secret `INFRA_READ_TOKEN`.
+
 ## Compatibility

 **Check the serial number, not the model name.** Characters 6-8 of the serial are
@@ -0,0 +1,64 @@
+# STYLE.md - how user-facing text is written (UX-08)
+
+This applies to everything a home owner or installer reads: notifications, phone pushes, the add-on page, refusals, add-on log lines at WARNING and above, and the names and descriptions of options. It is enforced by `goodwe_controller/test_messages.py`. Its allowlist is empty since phase 2d and its cap is 0: a new string that breaks the rule fails the test.
+
+## 1. Shape
+- **Title**: at most 5 everyday words. It says what is wrong ("Meter reading may be stuck"). No "GoodWe:" prefix, no full stop.
+- **Body**: **one sentence** of at most 25 words, saying what happened and what to do. A **red alarm** may use up to **3 sentences** (70 words, each sentence at most 30 words), so that no action a person must take is lost.
+- **Details**: the last line links to the add-on documentation and names the section with the rest: `Details: add-on documentation, section "<title>" under Notifications.` Background, figures, reason codes and history go there or into the log, never into the body.
+- **Status row**: one sentence of at most 15 words. A **red** row may use up to 3 sentences (30 words), like a red alarm. It shows the live numbers the reader acts on and never an HA entity id. **Banner**: at most 12 words. **Refusal**: at most 30 words, naming the setting by its label and then its key, as `messages.setting()` writes it: “Inverter rating” (max_w), or “Inverter rating” for inverter-b (inverters.max_w) for one inverter in the list. **Option name**: at most 6 words, not counting the group prefix. **Option description**: at most 30 words. Where a value comes from belongs in DOCS.md.
+- **Plan line** (UX-13 Home screen: the plan, tooltips, a battery's "now" line): at most 2 sentences, each at most 12 words. Words in `app/ui_text/<lang>.json` under `home_words`, built by `app/homeview.py`, checked by `test_messages.py` part 8. The page's own words, English and Dutch, are checked by `test_ui_text.py`.
+- **Log line** (WARNING/ERROR): one line of at most 25 words **as logged**, with any built text filled in. Log lines stay in English and are not translated. A line that reports a safety reason gives one plain sentence and the reason's code (`STALE_READING`, `OUTPUT_CLAMP`), the evidence an installer searches for. The reason itself, with its figures and limits, goes on a DEBUG line right after it and into the action log, never onto the WARNING/ERROR line. It keeps the shape of a red alarm: at most 3 sentences of at most 30 words. The line as logged has no semicolon, banned word, capitals, "1 times" or "(s)". `test_messages.py` part 6 builds every such text with the real code and checks it, and lists the few non-safety families still over 25 words. A line that repeats every cycle is DEBUG. INFO lines carry no section numbers, ISO timestamps or capitals.
+- **Refusal length is counted as shown**: a setting placeholder counts as its label and key, and the long cases are driven through the validator (`test_messages.py` part 3).
+- **Event line** under the buttons: the plain words of `messages.hint()`, like a green row. The add-on's own action log stays technical and is not shown on the page. Installers read it as `events` in the `status` JSON.
+- **Sentences**: one idea each, active voice, present tense, with nothing nested in brackets and no semicolons (a semicolon is a second sentence in disguise). These translate well into Dutch and French.
+
+## 2. Numbers
+Use a number only if it helps the reader act, for example the peak limit, or what was asked and what was sent in a fault report. Write it the way `app/messages.py` does: `5 000 W`, `20 %`, `10 minutes`, `14:05`.
+
+## 3. Severity
+Severity is shown by the title and the colour, never by CAPITALS or by words like "BUG SIGNAL".
+
+| Level | Colour | When |
+|---|---|---|
+| alarm | red | Control stopped, money or energy lost now, a fault, or a person must act now. Up to 3 sentences. |
+| warning | orange | Control is still running, but something needs a look. 1 sentence. |
+| info | grey | No action needed. 1 sentence. |
+| resolved | green | An earlier alarm or warning has cleared. 1 sentence. |
+
+A rewrite never changes an alarm's severity, `notification_id` or cadence.
+
+## 4. Words - the same word for the same thing everywhere
+A setting is named by its label in `translations/en.yaml`, in quotes when it sits mid-sentence (“Inverter rating”). The words below match those labels. If a label changes, change it here and in `app/messages.py` in the same change.
+
+| Say | Not |
+|---|---|
+| the add-on (who decides), control (what it does: "start control", "Control: last ran …") | controller, loop, planner |
+| battery | pack, BMS pack |
+| inverter, or its name | unit, device, actuator |
+| meter | P1 feed, telegram |
+| peak limit / this month's peak | ceiling, capaciteitstarief, billed quarter |
+| 15-minute period | quarter |
+| battery level (setting: “Battery level entity”) | SoC, state of charge, charge level |
+| battery cut-out level, or cut-out level next to "battery" (setting: “Battery cut-out level”) | BMS floor, `bms_soc_floor` |
+| peak reserve (setting: “Peak reserve”) | `peak_soc_floor`, EMS floor, "peak guard will not discharge below" |
+| “Inverter rating” (the setting) | `max_w`, rail, inverter rating as a fact about the hardware |
+| solar production, solar entity (settings: “Solar production entity”, “Solar production entities, per inverter”, “Reversed-sign solar entities”) | PV, reversed-sign list, single sensor setting |
+| “Where the meter reading comes from” | meter source |
+| “Grid power entity”; entity for any Home Assistant sensor a setting points at | grid power sensor, sensor setting |
+| draw the battery down, give power | discharge, discharging |
+| control is stopped / every inverter is set to 0 W | failsafe, trip, latch, parked |
+| safety stop (a stop that only starting control clears) | failsafe latch |
+| software fault | BUG SIGNAL |
+| control board | master, ESP32 |
+| power request, what the add-on asks | command, setpoint (on the page) |
+| the power went the wrong way | sign disagreement, command and meter point opposite ways |
+| check for inverters working against each other | circulating power check |
+| month peak, 15-minute periods measured | billed quarter, banked, soft limit, open block |
+| shadow mode | a mode that makes every decision but commands 0 W. The name is kept. In shadow mode a text says what the add-on **would** send, never that it sent it. |
+
+**Banned in titles and bodies** (the test fails on them): SAFETY-/TARIFF-/TEL-/CFG-/FW-/HW-nn and other card ids, integrator, anti-windup, windup, clamp, clamped, saturated, BUG SIGNAL, latch, latched, arbiter, allocator, register, `0x…`, layer 1/2/3, heartbeat, watchdog, telegram, ACK, CRC, OTA, Modbus, planner, `§n`, file names, IP addresses, option keys in snake_case, **HA entity ids**, and runs of 2 or more CAPITALISED words.
+
+HA entity ids are allowed only in refusals and validator messages, where the installer has to find that entity. They are never allowed in alarms or status rows.
+
+**Glossary.** DOCS.md "Words used on this page" explains, once, the words a home owner meets without context: control board, isolator, Developer Tools, shadow mode, safety stop, peak limit, peak guard, peak reserve and cut-out level. A home-owner text may use them without explaining them again. Card ids stay out of DOCS.md headings: they go on a *For installers* line under the heading.
@@ -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`.
@@ -95,7 +95,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <div class="page" id="p1">
  <div class="hdr">
    <div><h1>GoodWe RS485 Controller</h1>
-         <div class="sub">Field installation &amp; commissioning guide — v0.1.0</div></div>
+         <div class="sub">Field installation &amp; commissioning guide — v0.1.0, <b>outdated</b>: where it disagrees with DOCS.md, DOCS.md wins</div></div>
    <small>Installer copy</small>
  </div>

@@ -503,7 +503,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  <table>
    <tr><th style="width:30mm">Setting</th><th style="width:16mm">Value</th><th>Reason</th></tr>
    <tr><td><code>gain</code></td><td>0.6</td><td>Inverter needs 3–6 s to settle (1.4 s dead time, 94 % by 3.3 s) against a ~5 s cycle. <b>At the limit — do not raise</b></td></tr>
-    <tr><td><code>slew_w</code></td><td>1000</td><td>Most of a correction in the first cycle without running far ahead of the hardware</td></tr>
+    <tr><td><code>slew_w</code></td><td>0</td><td>0 follows the rail (<code>max_w</code>&nbsp;/&nbsp;9). A faster fixed value is <b>refused at startup</b> (SAFETY-39) — see DOCS.md</td></tr>
    <tr><td><code>deadband_w</code></td><td>15</td><td>Measured residual: mean 15.4 W, max 27 W. At 10 W the command never rests</td></tr>
    <tr><td><code>saturation_w</code> / <code>cycles</code></td><td>500 / 3</td><td>Divergence = inverter at a limit → magnitude may fall, never rise. <b>The 3-cycle term is essential</b>: tested instantly it fires on every large correction</td></tr>
    <tr><td><code>step_w</code></td><td>10</td><td>Register is 1 W but response lands on a ~17.6 W ladder. Finer is meaningless</td></tr>
@@ -60,7 +60,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
 <div class="page" id="p1">
  <div class="hdr">
    <div><h1>GoodWe RS485 Controller</h1>
-         <div class="sub">Field installation &amp; commissioning guide — v0.1.0</div></div>
+         <div class="sub">Field installation &amp; commissioning guide — v0.1.0, <b>outdated</b>: where it disagrees with DOCS.md, DOCS.md wins</div></div>
    <small>Installer copy</small>
  </div>

@@ -468,7 +468,7 @@ figcaption { font-size:9pt; color:#5b6169; margin-top:1.2mm; }
  <table>
    <tr><th style="width:30mm">Setting</th><th style="width:16mm">Value</th><th>Reason</th></tr>
    <tr><td><code>gain</code></td><td>0.6</td><td>Inverter needs 3–6 s to settle (1.4 s dead time, 94 % by 3.3 s) against a ~5 s cycle. <b>At the limit — do not raise</b></td></tr>
-    <tr><td><code>slew_w</code></td><td>1000</td><td>Most of a correction in the first cycle without running far ahead of the hardware</td></tr>
+    <tr><td><code>slew_w</code></td><td>0</td><td>0 follows the rail (<code>max_w</code>&nbsp;/&nbsp;9). A faster fixed value is <b>refused at startup</b> (SAFETY-39) — see DOCS.md</td></tr>
    <tr><td><code>deadband_w</code></td><td>15</td><td>Measured residual: mean 15.4 W, max 27 W. At 10 W the command never rests</td></tr>
    <tr><td><code>saturation_w</code> / <code>cycles</code></td><td>500 / 3</td><td>Divergence = inverter at a limit → magnitude may fall, never rise. <b>The 3-cycle term is essential</b>: tested instantly it fires on every large correction</td></tr>
    <tr><td><code>step_w</code></td><td>10</td><td>Register is 1 W but response lands on a ~17.6 W ladder. Finer is meaningless</td></tr>
@@ -0,0 +1,9 @@
+# UX-13 screenshots
+
+Made from the real page by `goodwe_controller/tools/ux13_screenshots.sh`. Do not
+edit them by hand: run the script again.
+
+- `home-*.png`: Home, running, in Dutch, in shadow mode, at phone width, and in setup.
+- `settings-*.png`: Settings, Simple and Installer, and the time-window editor with an overlap.
+- `batteries*.png`: the Batteries screen with modes on, in Dutch, an Off battery helping the peak limit, a refusal at phone width, and modes off.
+- `setup-step-1*.png`: Setup, step 1.
@@ -75,8 +75,9 @@ Every point still carries `provisional=True`, so the **flag never lies** — wha
 decays is the number, behind a flag that is telling the truth.

 ⚠️ **No value-level check can catch that**, and claiming one would be worse than
-claiming none. A carried point and a published-provisional point (`eneco_eddy`'s
-current quarter, §9.2) are the same three fields carrying the same flag. The
+claiming none. A carried point and a published-provisional point (a real-time
+product's current interval, §9.2) are the same three fields carrying the same
+flag. The
 difference is provenance, and provenance is not in the value.

 The defence is therefore an **ordering**, not a validation:
@@ -139,8 +140,16 @@ file constructs and still holds a reference to.

 ## 4. A sub-hourly feed passes through whole; the fill only decides which hours are missing.

-`eneco_eddy` is the Belgian imbalance product and settles **per quarter**, and
-`price.py`'s `_validate_raw()` accepts any strictly-increasing spacing — so a
+⚠️ **This section originally said `eneco_eddy` is "the Belgian imbalance
+product". That was false and [[TARIFF-07]] withdrew the plugin: Eneco's dynamic
+product is "Zon & Wind Dynamisch" and is indexed to Belpex/EPEX **day-ahead**,
+not to imbalance, and `api.eneco.be/eddy/prices` never existed. The mechanism
+below is unaffected, because the real quarter-hourly feed is the one still
+shipped.**
+
+Belgian **day-ahead** settles per **quarter** — the 15-minute MTU took effect
+on 2025-10-01, so `generic_dayahead` reads 96 points a day rather than 24 — and
+`price.py`'s `_validate_raw()` accepts any strictly-increasing spacing, so a
 published hour may legitimately hold four points.

 FCST-04's first caller keyed the published set as `{_utc_hour(p.start): p for p
@@ -285,32 +285,11 @@ cross-inverter `lo > hi` contradiction at `arbiter.py:114`. The only line this
 card changed there is **which** roster entry the claim is filed on: the one whose
 state machine produced the result, rather than `inverters[0]`.

-## 6. FOUND AND NOT FIXED: the site loop still contradicts a drain at N>=2
+## 6. FIXED BY SAFETY-78: the site loop contradicted a drain at N>=2

-Measured while wiring this card, and **pre-existing on `release/1.0` at
-`2d025ee`** — the same drain filed on `inverters[0]` produces the identical
-refusal with the two unit names swapped.
-
-The maintenance SET **pins** its pack. The loop's target is a **site** claim.
-When the site target is *below* the pin — a 2000 W drain while the house imports
-less than that, which is most of a night — the only split that sums to the site
-target asks the sibling to **charge** while the maintained pack **discharges**,
-and `allocator.plan()` refuses it by name as circulating power. The refusal is
-correct and fails safe: the whole site goes to 0 W with an `ARBITER: REFUSED`
-line in the action log.
-
-**The consequence an operator would see is a misdiagnosis.** The pack is held at
-0 W while its state machine believes it is draining, so after 12 h the DRAIN
-timeout fires and reports *"drain stuck"* — §12's words for a battery that is not
-following commands. The battery is fine; the site refused to allocate.
-
-**Why it is not fixed here.** The fix is to change what the site loop's target
-*means* while a unit is pinned — regulate the meter using only the unpinned
-packs — which is loop and allocator territory and changes the integrator's
-subject. MAINT-05 moves which pack is pinned and nothing else about it. It is
-pinned as a running check (`test_maintenance.py` part 12) rather than left as a
-comment, so it cannot be forgotten or quietly tuned away, and it wants a card of
-its own.
+Found here and pre-existing: below the pin the other pack had to charge, the
+allocator refused it and the site sat at 0 W. Fixed by a site `drain` floor;
+see [[SAFETY-78]] (`DECISIONS/SAFETY-78-drain-at-two.md`).

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

@@ -0,0 +1,67 @@
+# MAINT-10 — the maintenance start hour is local time, default 19:00
+
+Owner decision 2026-09-29 (option A). `maintenance_start_hour` was compared
+with the UTC hour, so the shipped 10 started at 12:00 in a Belgian summer and
+11:00 in winter. It is now read on the site's local clock, and the default moves
+to 19 so the drain runs into the evening and night rather than the solar day.
+
+Evening drains meet higher house loads; SAFETY-83 (merged first) lets the
+peak guard outrank the drain.
+
+## 1. Which zone
+
+Home Assistant's `time_zone` (`GET /core/api/config`, 3 s budget) at startup,
+else the container's `TZ`, else UTC. One log line says which (WARNING only for
+UTC). Resolved once per start: a zone change in HA takes effect on the next
+add-on restart. HA can still be starting when the add-on starts (502 from the
+proxy, 2026-10-05); then `TZ` holds. HA pushes its zone to the Supervisor
+(hassio `push_config`), which stores it and sets it as the add-on's `TZ`
+(`docker/app.py`, Supervisor 2026.08.0), so the hour stays right. Only a `TZ` of
+UTC there logs a WARNING asking for a restart. No later re-resolve: the fallback
+already is HA's zone, so the rare UTC case gets a warning rather than more code.
+The add-on image has tzdata (checked in `amd64-base:3.20`); the CI image does
+not, so the tests grade DST on `tariff._EUTimezone` too.
+
+## 2. DST
+
+`maintenance.in_start_slot()` works from UTC instants only, so it does not
+depend on how a tzinfo resolves a missing or doubled wall time:
+
+- normally the slot is the local hour `start_hour`;
+- clocks forward and the hour does not exist: the first hour after the jump;
+- clocks back and the hour happens twice: the first pass only. Without this an
+  aborted start (90 min cooldown) would start again in the 120 min repeated hour.
+
+Every day has exactly one 60 min slot for every hour 0-23: checked against
+zoneinfo for Europe/Brussels, America/New_York, America/Santiago (midnight
+transitions), Asia/Kathmandu (+05:45) and Australia/Lord_Howe (30 min DST)
+over all of 2026.
+
+## 3. Existing installs
+
+The Supervisor merges the shipped defaults under the STORED options, and saving
+the settings stores every key (the reference install's blob has all 76). So
+almost every existing install keeps its stored 10, which now means 10:00 local
+instead of 12:00 (summer) or 11:00 (winter). Only a blob without the key gets 19.
+The add-on does not rewrite a stored option: a silent migration would override
+an operator's choice with no way to tell it apart from the old default. A site
+that set an earlier hour to make up for UTC (17 for 19:00 summer) must set it
+back to 19 after the upgrade, or it starts two hours early. DOCS and the release
+note (drafted on the PR, for the version bump) say this.
+`tools/supervisor_shape_probe.py` §I measures this on Supervisor 2026.08.0.
+
+## 4. Two inverters
+
+`Controller` hands the same zone to every pack's `Maintenance`, so every pack's
+`wants_start()` reads the local hour. `arbitrate()` is unchanged: one pack
+cycles at a time, and the one that lost the slot starts in the first start
+slot after the other is done (a later day: a cycle outlasts its start hour). On the day the clocks go back, a pack freed during the second pass of
+a repeated hour does not start there. `test_maint10.py` part 10.
+
+## 5. What does not change
+
+Only the start decision (`Maintenance.wants_start`) and the Home screen's shown
+start time read the zone. `test_maint10.py` parts 9 and 10 run the real
+Controller at N=1 and N=2 with start hour 11 UTC against 13 Europe/Brussels (the
+same instant): every command, claim, reason and log line is identical. A
+`Maintenance` built without a zone reads UTC, as before.
@@ -0,0 +1,109 @@
+# MAINT-13 - a full pack that stops at 98-99 % is not a failed charge
+
+**Status: for review.** Tests: `test_maint13.py`. No option added; every number
+is a constant in `app/maintenance.py`.
+
+**What happened (live, B).** The drain ended 2026-10-04 18:24 UTC and the charge
+began. It ran in pieces behind the price gate, reached 99 % at 2026-10-06 04:00,
+fell back to 98 % at 04:15 while the loop still asked about -1370 W, and never
+reached `maintenance_soc_target` 100. At 06:24 (2160 min = 36 h of wall clock
+after the charge began) it aborted "charge stuck at 98 %". `last_completed` was
+not set, so B was still due and would have drained again from 98 % to 11 % at the
+next start hour, with no notice. Three faults: a pack may never report 100 %
+while the BMS balances; a failed cycle came back the next day; and the 36 h
+counted hours the price gate kept the pack waiting.
+
+## 1. The charge is complete when
+
+1. SoC >= target (as before), or
+2. SoC >= target - 3 (`CHARGE_NEAR_FULL_PCT`) and the SoC has not beaten its
+   best for 60 min (`CHARGE_STALL_MIN`) of allowed charging, or
+3. the charging time (`CHARGE_TIMEOUT_MIN`, 2160 min) runs out at SoC >= target - 3.
+
+Then the usual HOLD follows and `last_completed` is set after it. Each of 2 and
+3 logs one plain line ("the battery takes no more charge at 98 %, so the charge
+counts as done", "charge time is up at 98 %, close enough to full ...").
+
+**Why "SoC has not beaten its best", and not asked/delivered watts.** SoC is the
+one signal the live record gives us (99 at 04:00, 98 at 04:15); the asked power
+was -1370 W but no delivered figure was kept, so a watt threshold (X, Y) would be
+invented. SoC also covers the case where power flows but nothing is stored.
+**Why 3 points.** The card's band; at target 100 it is 97, and the live pack sat
+at 98-99. **Why 60 min.** A judgement, not a measurement: we have no per-minute record of
+the pack taking charge near full. The one live fact is 2 h 24 min (04:00 to
+06:24) without a new high, so 60 min is well inside it and long enough that a
+pack still creeping up (one new high within the hour) keeps resetting the wait.
+On the live run the rule fires after 60 gate-open minutes past the 99 %: 05:00
+UTC at the earliest, before 06:24 if the gate was open. If the pack turns out to
+step up more slowly than that, raise the constant. Falling back by one point
+does not reset the wait; only a new best does.
+
+## 2. A failed cycle backs off 7 days
+
+A drain stuck 12 h or a charge that times out below target - 3 is a failure
+(`FAIL_BACKOFF_DAYS` = 7). The machine goes IDLE as before, `last_failed` is
+stored, and `wants_start()` is false until 7 days later. The operator's forced
+start ignores it; a cycle that completes after the failure ends it. An operator
+abort, an interlock stop and a switched-off pack are not failures.
+
+**Why 7 days, not the 28 day interval.** A judgement: a failure may have a
+short cause (several dull days with no cheap hours, a pack switched off), and
+waiting the full interval leaves the coulomb counter uncalibrated for a month
+more. A week is long enough that a bad pack costs one drain a week, with one
+notice a week, not one a day. **Cost.** A truly faulty pack still drains once a week until someone looks;
+the notice says so each time.
+
+**Notice, once.** The tick that fails carries `failed`; the Controller sends one
+persistent notification "Battery cycle did not finish" (EN, with the Dutch
+below it; per pack at N=2). It is not repeated, and Home Assistant restarts
+wipe it, so the status page shows a "Maintenance paused" row with the date for
+as long as the wait lasts. The operator may also see the log lines.
+
+## 3. The timeout counts only allowed time
+
+`Controller._charge_gate_open()` says whether the pack may charge now. It is
+true when no price gate is set up (no price entities, no fixed tariff: nothing
+holds the charge back, and `cheap` is always false there), in a cheap window, or
+while the pack is really taking charge (battery power at or below -50 W, which is
+sun outside cheap hours). It is false only when a gate exists, is shut, and the
+pack is not charging; a pack asked for charge that delivers nothing then does not
+count, which is the case the clock cannot judge. A site with a price provider
+(TARIFF-11) and no fixed tariff counts as having no gate: the provider's plan
+reaches only the Tariff row, never `cheap`, so no cheap window ever opens a grid
+top-up there and only the sun charges the pack, as on a site with no tariff. Its
+time counts in full. When a provider plan starts to drive `cheap`,
+`_price_gated` must become true for it. Whether a fixed tariff is set up is
+worked out once an hour, not on every tick. Only open ticks add to `open_min`; one tick
+adds at most 5 min, so a gap (add-on down) adds nothing. The stall wait pauses
+while the gate is closed. The accounting is written to the state file at most
+every 5 min (`charge_track`); a restart loses at most that. A state file from
+before this change, or with no record for the current charge, starts from the
+wall-clock minutes so far, which is the old behaviour.
+
+**Backstop.** A gated site whose gate never opens (no cheap hours, no sun) would never time
+out, so a charge also ends after 7 days of wall clock (`CHARGE_WALL_TIMEOUT_MIN`):
+complete at >= target - 3, a failure below.
+
+**MAINT-12.** This is the smallest change that makes the timeout honest: one
+boolean in, one counter. MAINT-12's block plan can replace the boolean (the
+minutes it plans are the allowed ones) without touching the rest. Two things it
+must keep: the back-off is in `wants_start()`, so any new entry point (such as
+`price_forecast.begin_phase`, which is not wired today) must go through it or
+check `backoff_until()`; and `gate_open` must stay "the pack is allowed to
+charge now". The peak guard pausing the charge shaping is not seen as a closed
+gate: that time still counts.
+
+## 4. What does not change, and what this does not cover
+
+- The drain, the HOLD, the held-battery rules and `arbitrate()` are unchanged. A
+  backed-off pack does not want a start, so at N=2 the other pack may take the
+  slot. One pack at a time at N=1 and N=2.
+- `last_failed` is a maintenance key and moves with the others when a second
+  inverter is added (`MAINT_UNIT_KEYS`). The charge record is not moved; it
+  restarts from the wall-clock minutes.
+- It does not find out why a pack stopped. A pack that stops at 96 % and never
+  gets near is still a failure.
+- The Dutch text is only in the notification. The status row and the log lines
+  are English, like the rest of the status page.
+- It does not change the target: a site that wants a different stop point sets
+  `maintenance_soc_target`.
@@ -0,0 +1,68 @@
+# MAINT-14 - no SoC reading in a maintenance cycle
+
+**Status: for review.** Tests: `test_maint14.py`. No option added; the one new
+number is a constant in `app/maintenance.py`.
+
+**The fault.** `Maintenance.tick()` returned early when the SoC was `None`,
+before any timeout check. (1) A charge on a pack whose SoC reading was lost
+never ended: no timeout, no back-off, no notice, and the 7-day backstop of
+MAINT-13 sat behind the same return. (2) A drain kept commanding `discharge_w`
+with an unknown level, which breaks the TEL-08 rule that an unknown level never
+allows discharge.
+
+## Rules
+
+1. **Charge, no SoC.** The charge timeout (`CHARGE_TIMEOUT_MIN`, gate-open
+   minutes) and the 7-day wall backstop still run. When one fires: if the last
+   SoC seen was >= target - 3 the charge counts as done (the MAINT-13 "close
+   enough to full" rule, HOLD follows); otherwise it fails: MAINT-13 back-off
+   and its one notification. If no SoC was ever seen, it fails.
+2. **Drain, no SoC.** DRAIN holds at 0 W and owns the setpoint, exactly as HOLD
+   does. The 12 h drain timeout still runs and fails as before.
+3. **SoC comes back.** Nothing is recorded; the drain continues at the drain
+   rate, the charge carries on, and the stall wait of MAINT-13 restarts from
+   what it was: it paused while the reading was missing, so a gap never counts
+   as "no more charge".
+4. **HOLD** is unchanged (0 W).
+5. **Log.** One line when a drain starts holding for this reason ("the battery
+   level is unknown, so the drain holds at 0 W until it is back"), and one line
+   when the level has been missing for `NOSOC_NOTE_MIN` = 15 min. Both are said
+   once per episode; the old line that repeated every tick is gone.
+
+## Why
+
+- **"Last seen", not "best seen".** A pack that was at 99 and then dropped to 50
+  before the reading went is not close to full. Only the last reading counts.
+  It is saved with the charge record (`charge_track.last`), and saved at once
+  when the reading first goes missing, so a restart mid-gap still knows it
+  (within the usual 5 min save interval otherwise).
+- **Failure when nothing was seen.** With no level we cannot call a pack full.
+  The failure costs a 7-day wait and one notice; calling it done costs a
+  missed balance and a month-long false "complete". The first is the honest one.
+- **Timeouts count the same minutes as with a reading.** Gate-open charging
+  minutes only; the wall backstop for a gate that never opens.
+- **15 min.** A judgement. A poll glitch of a few minutes should not write a
+  line; a reading lost for a quarter of an hour is worth one. Raise it if the
+  action log shows noise.
+- **0 W, not "stop the phase".** Aborting a drain on a short gap would throw
+  away the part already drained. Holding at 0 W loses nothing and the 12 h
+  timeout is the limit.
+
+## Cost
+
+- A drain that loses its reading stops draining, and the 12 h clock keeps
+  running. A gap of many hours can therefore fail a drain that was working. The
+  back-off then applies (7 days).
+- A charge whose reading is lost early (last SoC below target - 3) fails at the
+  timeout, even if the pack was in fact filling. The same 7-day wait applies.
+
+## What this does not cover
+
+- **HOLD with no SoC**: closed by MAINT-15 (`MAINT-15-hold-ends-without-soc.md`).
+- It does not tell the operator why the reading is missing (sensor, register,
+  link). It does not reuse the stale-input gate; it is the cycle's own rule.
+- The charge itself is still driven by the control loop, which has its own
+  handling of a missing SoC (TEL-08 for the loop is a separate card).
+- A restart loses at most 5 min of accounting, as in MAINT-13. The "unknown for
+  long" line may be said again after a restart: the episode start is in memory.
+- Text added is two log lines, English only, like the other log lines.
@@ -0,0 +1,47 @@
+# MAINT-15 - the balancing hold ends on time with no SoC reading
+
+**Status: for review.** Tests: `test_maint15.py`. No option added.
+
+**The fault.** `step()` sent every tick with no SoC to `_no_soc()`, and for
+HOLD that returned 0 W without the time check. A hold that lost its reading
+never ended: `last_completed` was never written and the next due date never
+moved. Harmless for power (0 W), but the cycle was stuck. This was left open
+in MAINT-14.
+
+## Rule
+
+1. **HOLD ends at `hold_min` whether or not there is a reading.** One helper,
+   `Maintenance._hold()`, holds the time check and is used by both paths. When
+   the time is up it writes `last_completed`, goes IDLE and logs the same
+   "cycle COMPLETE" line. Before the time is up it commands 0 W as before.
+2. **Text.** The 15-min "no battery level" line in HOLD now reads "The hold
+   still ends at its normal time." Still once per episode.
+
+## Why
+
+HOLD is reached only after the charge counted as done. Every entry into HOLD
+is in `step()` or `_no_soc()` and follows a charge that reached the target,
+stalled near full (MAINT-13) or timed out near full (MAINT-13/14). Nothing else
+sets the phase to HOLD (`_enter(HOLD` has four call sites, all after a done
+charge). The hold is a wait for the BMS to balance; it never needed the level.
+So a hold that ends with no reading is a completed cycle. The "cycle COMPLETE"
+line is true without a reading: it names minutes of hold, not a level.
+
+## Cost
+
+- If the level was lost during the hold, the cycle is recorded as complete
+  without anyone seeing the final level. The charge had counted as done, so this
+  is the same trust MAINT-14 already gives a charge that ends with no reading.
+
+## What this does not cover
+
+- It does not check that the pack is still full at the end of the hold.
+- It does not say why the reading was lost.
+- With a reading, nothing changes. `test_maint15.py` section 7 compares the new
+  HOLD tick by tick with a frozen copy of the release/1.0 HOLD branch (phase,
+  setpoint, owner, events, `last_completed`) at four `hold_min` values. A wider
+  trace of the whole cycle (800 seeded runs against db9e231) was run outside the
+  repo; its script and log are kept under `scratch/MAINT-15/` of the dev
+  workspace, not in this repository.
+- A state file written by an older version with `phase: hold` loads and ends on
+  time; the file is not changed in format.
@@ -0,0 +1,129 @@
+# OPT-11 - battery modes, per battery
+
+A battery's mode (on/off, Solar first, Leftover solar) is a soft unit limit at
+`P_MODE` = 35 that always holds 0 W. A SET above 35 (a safety stop) overrides
+it; a limit above 35 (the peak guard) makes it give way only as far as that
+limit needs, and a battery its mode holds back then carries only what the
+others cannot (`arbiter._unit_modes()`, `_site_mode()`). Design and owner answers: `goodwe-session/OPT-11-design.md` (2026-09-27);
+P1 is its section 6 P1, and the pull request lists what was measured.
+
+- Off by default (`battery_modes_enabled`); off, commands are byte-identical to
+  a5dddad (`test_modes.py` part 1).
+- Off is a mode range, so the peak guard can still use an Off battery when the
+  others cannot cover the floor (design sections 2-3). Whether Off should be
+  absolute is an open owner question.
+- Review (PR #149): releasing only when the peak floor bound S let a trade won
+  above the floor keep the modes and place less than the floor, and let a
+  capped grid charge release an Off battery. Both are graded in
+  `test_arbiter.py` part 11. The loop bound leaves a side that reaches the
+  rail to the rail, so SAFETY-03 still flags a loop winding into it.
+- P2 (HA entities): a select and a switch per battery, only while modes are
+  on; commands go through `handle_action()`, the page's path. A retained
+  command is dropped, not applied: the store already holds the last choice,
+  and a replay after a restart could otherwise undo a newer one. The config
+  topics announced are kept in the store (`mqtt_mode_configs`), so turning
+  modes off removes exactly those, and an install that never turned them on
+  publishes what ed739d4 did (`test_mqtt.py` part 10). A removed topic stays
+  in that list and its empty config is re-sent on each start, so a start with
+  no broker cannot lose it; re-sending is harmless. The HA options are the
+  page's English names, pinned by a test, and are not renamed with the page:
+  automations send them.
+- In P1 only Off closes a direction; Leftover solar differs by charging last.
+- P3 (price runs, `priceruns.py`, `modetrade.py`): each battery's range is
+  narrowed by its role this tick (hold, give, charge, rest, sell); main.py
+  files the intersection with the switch, so it still holds 0 W. With modes on
+  the site trade is filed by the modes, sized from the loop bound (so no
+  battery a mode or a refusal holds is asked for watts, P1's unmet share) and
+  the guard's headroom; `arbitrage.decide()` runs only with modes off, which
+  stays byte-identical to 7a00f12 (`test_modes_p3.py` part 1).
+- SAFETY-46 item 2 is decided as the owner answered (2026-09-25): a trade is
+  a run of consecutive firm slots. It applies with battery modes on; the
+  modes-off trade keeps its one-period shape, because that path must not move.
+- Choices that were measured, not assumed (tools/opt11p3_replay.py):
+  - a sale needs the guard to have measured the quarter, not to be clear: a
+    5 kW discharge alone reads "engaged" on export and flipped the sale every
+    5 s;
+  - a grid charge makes the others rest, so it starts only at 500 W and, once
+    the guard or the headroom stops it, stays off for that 15-minute period
+    (without: 13 flips in 4 minutes under a 3.5 kW house);
+  - stored energy is valued at the last cheap run for 12 h, and a charge
+    needs its own run to clear the spread (without: a night charge was spent
+    on flat morning prices, then charging went on at them);
+  - a run edge reseeds the loop at the house's level (a 3 kW import spike
+    removed; about 0.1 x rating still overshoots as export).
+- Replay (tools/opt11p3_replay.py, 16 recorded days, EPEX hourly prices a
+  year earlier, modelled batteries), net EUR, lower is better: P2 19.33, P3
+  Solar first + Leftover solar 19.57, with a sale 19.60, the old one-period
+  trade 18.14. Review of #153 (same model, with a per-action split):
+  - the cheapest hours were at midday on 15 of 16 days, so Leftover solar (acting
+    as Cheap hours until P4) bought 12.2 kWh there that the sun would have
+    given: 7 kWh more exported, 12 kWh less solar stored. Holding for the
+    expensive hours saved 4 kWh of import, not enough. With no grid charge on
+    Leftover solar: 19.44;
+  - the old trade charged one hour, so the afternoon sun still fit;
+  - a sale earned the wholesale price (2.27 EUR for 11.4 kWh) and the house
+    then bought the same energy back (2.29 EUR): a wash before wear. It pays
+    only when the sale hour's wholesale price beats the later import price,
+    levies included (about 0.13 EUR/kWh above that hour's wholesale here);
+  - valuing the charge left at the end, wear and real Flemish levies make
+    selling worse and do not change the order.
+- Owner decision 2026-09-29 (option A): selling is off until it can be judged
+  on the price the grid pays (`packmode.SELLING_ENABLED`, code kept), and
+  Leftover solar takes solar only until P4's forecast
+  (`packmode.GRID_CHARGE_MODES`); Cheap hours only still charges from the grid. Replayed
+  (16 days, as above): Solar first + Leftover solar 19.44 EUR net against
+  P2's 19.33; Solar first + Cheap hours only 19.57.
+- Not done in P3: the forecast (P4), and a headroom too short for the run
+  moving the rest to the next cheap periods.
+
+## P4: the solar forecast and the day plan (2026-09-29)
+- Input: a Home Assistant forecast sensor (`pv_forecast_entity`, kWh left
+  today; `pv_forecast_tomorrow_entity` optional), read by `app/solarfc.py`.
+  Supported shapes: Forecast.Solar (state only), Solcast (`detailedForecast`)
+  and Open-Meteo Solar Forecast (`wh_period`). The unit is read, not guessed;
+  older than 3 h is stale (one missed hourly poll must not flag it).
+- Trust: `solar_trust_pct`, default 70 (owner answer 5).
+- House use: nothing the add-on recorded fitted. `tariff.db` holds grid
+  import per quarter, which the batteries shape. So `dayplan.HouseProfile`
+  keeps grid + battery per local hour for 7 days in the store
+  (`house_profile`), median per hour. It is net of the solar the house used,
+  so the solar sum never takes it below the night median. Solar readings are
+  not used (TEL-11). The first plan needs one day of it.
+- Verdict (`dayplan.plan()`): trust x sum max(0, forecast - house) x 0.95
+  until the expensive run the cheap run is for. Solar first takes it first.
+  - Leftover solar may then charge from the grid up to min(ceiling, floor +
+    the house's use in the expensive runs / 0.95), less its sun share: only
+    the shortfall.
+  - Cheap hours only ignores the plan and fills to the ceiling (design
+    section 1; review of #156, see the replay below).
+  - Solar first never charges from the grid (owner, 2026-09-29).
+- The level is kept unless it moves by min(1 kWh, 10 %). With no plan
+  (no, stale or failed forecast, no house profile, no capacity) every mode
+  is P3 option A exactly: `test_modes_p4.py` part 1 pins 12 digests from
+  5a4cdc2 (modes on, with and without an unavailable forecast).
+- The plan is made with the runs (every 15 min, or at once when the forecast
+  comes or goes). A lost forecast drops the levels at the next cycle.
+- Not done: the design's scaling by measured solar from 10:00 (it needs the
+  solar readings TEL-11 keeps out), the HA `goodwe_<inv>_plan` sensor, and
+  FCST-01.
+- Replay (`tools/opt11p4_replay.py`, 16 recorded days, Solar first + Leftover
+  solar, net EUR, lower is better; site solar rebuilt from the recording,
+  forecast errors from Elia's day-ahead Belgian solar forecast):
+  - year-earlier hourly prices: P2 19.33, P3 option A 19.44, old one-period
+    trade 18.14, P4 19.15 (perfect forecast 19.14, 1.5 x too high 19.16,
+    missing 19.44);
+  - the days' real 2026 quarter-hourly prices (held out): P2 32.26, option A
+    32.01, old trade 31.40, P4 29.19 (perfect 29.21, too high 29.28, missing
+    32.01).
+  - Solar first + Cheap hours only, skipping its sun share (the first
+    build): 19.57 (same as P3) and 29.72 against P3's 29.41. The shorter,
+    moved runs left B lower, so later midday top-ups rested A while the sun
+    shone. Cheap hours now ignores the plan, which is P3 exactly.
+  - A forecast of no sun at all gives 19.14 and 29.33. So nearly all of the
+    gain is Leftover solar buying the evening's shortfall in the cheap run;
+    the forecast itself was worth 0.14 EUR in 16 September days.
+  - Bias: the site's solar is rebuilt from the same net use the replay
+    plays, and "recorded" keeps its hourly shape and adds only the national
+    daily error. Both favour P4; "national" (no house leakage) gives 29.25.
+  No threshold was tuned to these days. The 2026-09-24 PV recording could not
+  be replayed: it is only in the live Home Assistant.
@@ -0,0 +1,79 @@
+# OPT-17 - the solar forecast from several entities, summed
+
+**Status: for review.** Tests: `test_opt17.py`. Two options added.
+
+A site whose forecast comes as several Home Assistant sensors (one per
+inverter or roof side) had to build a template sensor to sum them. Now each
+day can list them.
+
+## Options
+
+- `pv_forecast_entities` and `pv_forecast_tomorrow_entities`: lists of
+  sensors, default `[]`, the same shape as `pv_entities`.
+- `pv_forecast_entity` and `pv_forecast_tomorrow_entity` are unchanged. An
+  install that uses them needs no edit.
+- **Why new keys, not "string or list" in the old ones.** Measured on
+  Supervisor 2026.08.0 by `tools/supervisor_shape_probe.py` §J, as TEL-12's
+  §G did for `pv_entity`. Declared as a list, each forecast key refuses the
+  string an install already stores (`Invalid list for option
+  'pv_forecast_entity'`), and a `[]` default does not rescue it. The one
+  spelling that takes both, `match(.*)?`, also takes the integer 417 and
+  shows a plain text box, so a second sensor cannot be added in the UI.
+- §J also shows: a 0.17.0 blob validates unchanged with the lists at `[]`;
+  the lists render as repeatable fields; a downgrade drops them and keeps
+  the single keys.
+- `[]` in `options:` is load-bearing, as for `pv_entities`.
+
+## Rules
+
+1. **One key per day.** Setting the single key and the list for the same day
+   is refused at start, with one message: keep the list, clear the single one.
+   The list can hold that entity too. (TEL-12 lets `pv_entities` replace
+   `pv_entity` with a caution row. Here the brief asked for a refusal: a
+   doubled or dropped forecast changes what a battery buys, and no install
+   has both keys yet, so the refusal breaks nothing.)
+2. **Each member in its own unit.** Every member is read as one forecast
+   sensor is today (`solarfc._day()`): Wh, kWh or MWh, never guessed. Then the
+   day's kWh are added up. A repeated id counts once.
+3. **One member not usable means the day is not usable.** Missing,
+   unavailable, unknown, stale, not an energy unit, or a bad number: that
+   day's sum is not used, exactly as when the single sensor reads that way.
+   No today means no forecast (P3 option A). No tomorrow means today only.
+4. **Hourly split.** If every member has a split, the splits are joined
+   (overlapping periods add up). If any member has none, the sum is spread
+   over the bell, as for a state-only sensor.
+5. **Time.** The forecast is as old as its oldest member.
+6. **One read.** All members of both days are read in one gather, inside the
+   gather that reads the inverters, so a slow sensor does not delay control.
+7. **Shown and logged once.** With two or more members, each one not usable
+   is named on the status page by its place in the list (STYLE.md: no entity
+   ids on the page), as a caution row titled "Solar forecast" on Home. The
+   action log names the entity id, once when the set of failing members
+   changes.
+8. **One member is the single key.** A one-member list reads, plans, shows
+   and logs exactly as the single key with that entity.
+
+## Why
+
+- A partial sum is a smaller number that looks real. Two of three inverters'
+  forecasts read as a duller day, and Leftover solar would then buy grid
+  energy the sun was going to give. TEL-12 took the same rule for the same
+  reason. No forecast is a known state with a tested fallback.
+- The bell for a mixed list: joining one member's hours with another's total
+  has no honest shape, and the bell is the existing state-only rule.
+
+## Cost
+
+- One flaky member costs the whole day's forecast. A site with three
+  sensors loses the plan more often than one with a template sum that hides
+  gaps.
+- Two more options (85).
+
+## What this does not cover
+
+- No weighting or calibration per member; FCST-01 is still the own forecast.
+- Members on different integrations with different refresh times: each must
+  be fresh (3 h) on its own; there is no wait for a lagging one.
+- The day plan itself, the trust and the house profile are unchanged.
+- The Batteries screen still says only "no solar forecast now". The member
+  is named on the status page.
@@ -0,0 +1,406 @@
+# 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
+the CI image and on TEST-23 stage 3's closed-loop rig.
+
+---
+
+## 0. The four things a reader should take away
+
+1. **"Default-on" is delivered as `auto`, not as `true`, and the difference is
+   an install that is regulating a real battery today.** The Supervisor
+   composes an add-on's options as *its defaults, overlaid with the stored user
+   options*, so a new key with a new default reaches **every existing install**
+   on the next update. A boolean `shadow_mode: true` would silently stop the
+   reference site. §1.
+2. **Shadow mode WRITES. It writes 0 W, on the ordinary heartbeat, through the
+   ordinary single writer.** "Commands nothing" implemented as "stops writing"
+   would leave the inverter latched on whatever was standing — it has no meter
+   timeout — and would put the ESP32 into a tripped stale-input watchdog for
+   the whole run. §2.
+3. **The sign watchdogs are inert, and that was the decision that had to be got
+   right.** Fed the shadow decision they would trip within `sign_disagree_s`
+   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.
+
+---
+
+## 1. The default
+
+### The literal reading, and what it costs
+
+`config.yaml`'s `options:` block **is** the default. There is exactly one of it,
+and HA's Supervisor resolves an add-on's effective options as
+
+```
+{**config.yaml options, **the stored user options}
+```
+
+A key that has never been stored therefore takes the file's value — on a fresh
+install and on an install that has been running for months, identically. There
+is **no mechanism in the add-on options system** by which one key can default
+differently for the two. So the card's title, taken at face value, is:
+
+> the next `ha addons update` stops the battery at the reference site, and the
+> only symptom is a battery that has stopped doing anything.
+
+That is strictly worse than every defect shadow mode exists to catch. It is
+refused.
+
+### What was shipped instead
+
+`shadow_mode` is a three-valued `list(auto|on|off)` defaulting to `"auto"`:
+
+| value | resolves to |
+|---|---|
+| `off` | live |
+| `on` | shadow, always |
+| `auto` | shadow **while control is stopped**; live once it is started |
+
+`auto` reads `Controller.auto` — the persisted start/stop state, which a fresh
+install takes from `auto_start` and which the *Start / stop control* button
+moves. No new persisted state, no migration, no guess:
+
+* a **fresh** install ships `auto_start: false`, has no stored `auto` key, and
+  therefore comes up **in shadow mode**. It observes a day of decisions before
+  it is ever allowed to command anything. That is the card's intent, delivered
+  where it is safe;
+* an install that is **controlling** is started, so `auto` resolves to live and
+  **not one watt changes**;
+* an install that is **stopped** keeps its actuator at 0 W exactly as before —
+  the same number, from the same writer, on the same heartbeat. What changes is
+  what the status page and the action log **say**, and that the decision path
+  now runs and is recorded.
+
+⚠️ **Under `auto`, pressing Start leaves shadow mode.** That is the point of
+`auto`: the button means "control the battery". An operator who wants the
+decisions recorded *while the loop runs* — the configuration this card exists
+to make possible — sets `on` explicitly, and cannot reach it by accident.
+
+⚠️ **An unrecognised value resolves to SHADOW, and is REFUSED at startup.**
+`shadow.mode()` fails toward inaction; `validate.py` rule 11 refuses the value
+by name so the reinterpretation is never silent. A typo is not a decision, and
+an install silently left in shadow mode commands nothing indefinitely while its
+status page calmly explains that this is intentional.
+
+---
+
+## 2. "Commands nothing" is a number, not a silence
+
+The inverter holds its last command **forever** — `HANDOVER.md` §6 says so, and
+`firmware/goodwe-master.yaml`'s header records what it cost when a controller
+stopped refreshing: *"Illusmart went silent mid-command and the inverter held
+5000 W for 113 s"*. `firmware/goodwe-master.yaml` states the contract that follows — *"HA
+must now REWRITE the setpoint every ~10 s even when the value has not
+changed"* — because without a refresh, **"stale" and "steady" are the same
+thing on the wire**.
+
+So shadow mode holds the actuator at `shadow.WIRE_W` = **0.0 W**, refreshed on
+the ordinary heartbeat. Two consequences were weighed and are recorded:
+
+* **it is not silence.** A shadow mode that stopped writing would leave the
+  standing command up until the ESP32's 30 s watchdog noticed — and at a site
+  with no such board, forever;
+* **it does not use an alarm as a mode.** Letting that watchdog trip for the
+  duration of a shadow run teaches the operator that `wd_tripped` is normal,
+  which is exactly the training that makes it useless when the add-on has
+  actually died.
+
+### It is not a second writer
+
+SAFETY-28's rule is one actuator, one writer. Shadow mode files **no claim**,
+owns **no transport**, and calls nothing in `hass.py`. It is a **substitution**
+inside `Controller._write_unit()` — the single choke point every write in this
+add-on already reaches, including the heartbeat, the stop button, `shutdown()`
+and `maint_abort()` — in exactly the form of the three substitutions above it
+(non-finite → 0 W, unauthorised → 0 W, clamped → the rating).
+
+It is the **last** of them. Below SAFETY-28's gate and below SAFETY-03's clamp,
+so both still grade the number the decision path actually produced, and a
+shadow run can report *"it would have hit the rating here"*.
+
+---
+
+## 3. What the run records
+
+| 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 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, 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
+a line per cycle would flush the context of the run's own findings inside four
+minutes at the 15 s cycle floor.
+
+---
+
+## 4. The failsafes, one by one
+
+| failsafe | in shadow mode | why |
+|---|---|---|
+| SAFETY-02/30 sign watchdogs | **INERT** | They grade `Inverter.standing_w()` — what this controller has standing on the wire — and shadow mode holds that at 0 W, so they cannot arm. ⚠️ Fed the shadow decision instead they would disagree with a meter that never saw it and **latch a trip that survives into live operation and a restart**: shadow mode would manufacture the failsafe it exists to help debug. ⚠️ **Two rungs hold it there** — `last_write` (the wire gate) and `inv.target` (the re-seed) — which is MUTATION.md's masking shape, so the mutation that reproduces the hazard defeats both as a pair (M6). Driven singly, dropping the re-seed does not reproduce it at all — measured |
+| 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, 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 |
+| inputs missing, non-finite, allocator refusal, arbiter contradiction | **UNCHANGED** | All resolve to 0 W, which is what the wire gets anyway |
+
+⚠️ **A latch that is already up stays up.** Nothing here clears one. The shadow
+banner **names** any standing latch and goes red for it, because a latch that is
+up while the controller is inert is up the moment it stops being inert.
+
+⚠️ **Maintenance is not in that table because shadow mode does not touch it.**
+The state machines are ticked on every cycle whether control is started or not,
+so a stopped install already runs them against a battery that does not move.
+Shadow mode inherits that, unchanged and unimproved. Recorded here rather than
+quietly fixed under another card's name.
+
+---
+
+## 5. The limitation, stated rather than discovered later
+
+`Controller._shadow_settle()` re-seeds the carried command (`self.target` and
+each `inv.target`) to `WIRE_W` at the **end** of every shadow cycle — after
+every in-cycle guard has read the decision. Three machines read that value as a
+statement about the **hardware**: the loop's `prev_w` and integrator,
+`standing_w()`, and SAFETY-42's share comparison. Re-seeded, they track reality,
+and **the exit is safe by construction** — the carried command already equals
+the standing one, so the first live cycle slews from 0 W like any other.
+
+⚠️ **The cost is real.** The loop's `prev_w` is therefore 0 W on every shadow
+cycle, so the loop leg's recorded decision is **one slew step from the standing
+command** and stays there. A shadow run answers *"what would this controller
+command NOW, from where the plant really is"* — a true statement about the
+present — and **not** *"what trajectory would it have followed"*. The trajectory
+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.
+
+⚠️ **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`.
+
+---
+
+## 6. How "nothing reaches the inverter" is graded
+
+**Not on a flag.** A check that asserted `Controller.shadow` would pass on a
+build in which the flag is set and the substitution is deleted — which is
+exactly mutation **M1**.
+
+`test_clamp.py` part 8 drives the **shipped** `Controller.cycle()` and the
+shipped heartbeat against a recording Home Assistant stub, and asserts on what
+reached `set_number()`:
+
+* **the precondition first** — the same stimulus with `shadow_mode: off` puts
+  30 non-zero writes on the wire, the largest 5000 W. MUTATION.md habit 4: a
+  check whose data cannot reach the failure it names is decoration;
+* then `set(writes) == {0.0}`, **and** that there were 26 of them — a check
+  that only said "no non-zero write" would pass on the silent build too;
+* entry and exit are measured on `inv.last_write` — what the inverter is
+  latched on, updated only on an **accepted** write — either side of the
+  boundary, against the same run that never entered shadow mode.
+
+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 |
+|---|---|---|
+| 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** |
+
+**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.
+
+⚠️ **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,
+which drives the real `Controller`. ⚠️ **And the rig's transcribed cycle
+predates SAFETY-45**: `arbitrage.decide()` gained a required
+`charge_headroom_w` after `478ba93`, and the harness supplies it from the
+**shipped** `peakguard.charge_headroom_w()` reading the **shipped** peak
+decision rather than from a constant, so SAFETY-45 stays in the run.
+
+---
+
+## 7. The mutation battery — 22 mutations, no survivors
+
+Harness: `/home/homelab/s10-mut/run.py`, backups beside 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). The full table is in the branch report;
+one per new behaviour, including **M1** (the substitution deleted — a write
+escapes), **M2** (it returns instead of substituting — the inverter is left
+latched), **M3** (it moves above SAFETY-28 and SAFETY-03 — the observers go
+blind), **M8** (`auto` resolves to shadow unconditionally — the literal
+default-on that stops the live install), **M12** (the stop claim is filed in
+shadow — every recorded decision reads `stopped`), **M21** (the substitution
+and the re-seed together) and **M22** (the re-seed moved one line earlier —
+SAFETY-18 grades a 0 W no decision produced and goes permanently blind).
+
+⚠️ **Two findings from driving it, both of the kind MUTATION.md says to expect.**
+
+* **M2 first came back a SURVIVOR and was not one.** The "stop writing
+  altogether" build left `inv.last_write` as `None`, the check did `float()` on
+  it, and the section died with a `TypeError` — grading none of the checks
+  after it and reporting **zero reds**, which reads exactly like a survivor.
+  That is FCST-06's shape. The fixture now hands `None` back and names it as
+  its own check; M2 is red on three.
+* **M6 had to become a PAIR, and only the battery said so.** `standing_w()`
+  prefers `last_write` — the 0.0 W the wire gate accepted — and falls back to
+  `inv.target`, which the re-seed also holds at 0.0. Either rung alone keeps
+  the detector inert, so dropping the re-seed **singly** came back red on the
+  limitation check and on **nothing about the latch**: the hazard it names was
+  not reproduced. TEST-16's rule with a new name on it.
+* **M7/M8/M9/M19 had to MOVE SUITES.** They defeat `shadow.engaged()`, and a
+  defeated default stops `test_clamp.py` part 3's wired run reaching the wire
+  at all — aborting the file with an `IndexError` before part 8 is graded. The
+  red count there was a lower bound naming the saturation freeze. The mode
+  table now lives in `test_validate.py`, which drives no Controller.
+* **`shadow_would_w = float(self.target)` is an EQUIVALENT mutation and was
+  measured as one.** `_shadow_settle()` runs before the re-seed, so at that
+  line `self.target` **is** `resolution.target_w`. It is recorded as equivalent
+  rather than reported as a survivor, and the non-equivalent form of the same
+  defect — the record becoming the **wire** — is driven instead.
+
+### The table
+
+Each row: the mutation, the file, the byte delta, the suite it was graded in,
+and how many **named** checks went red. `⚠️` marks a row whose run did not
+reach the end of its file, so its count is a **lower bound** (MUTATION.md).
+
+| # | mutation | file | Δ | suite | reds |
+|---|---|---|---|---|---|
+| M1 | **a write escapes** — the substitution deleted | `main.py` | −6 B | clamp | 5 |
+| M2 | **silence instead of 0 W** — it returns rather than substituting | `main.py` | −15 B | clamp | 3 |
+| M3 | **the observers go blind** — it moves above SAFETY-28 and SAFETY-03 | `main.py` | +58 B | clamp | 1 |
+| M4 | the site re-seed dropped — the exit resumes from a fiction | `main.py` | −36 B | clamp | 3 |
+| M5 | the per-unit re-seed dropped | `main.py` | −22 B | clamp | 1 |
+| M6 | **PAIRED**: `standing_w()` reads the target **and** the re-seed dropped — the sign latch that survives into live operation | `inverter.py` + `main.py` | −170 B | watchdog | 3 |
+| M7 | `auto` inverted — shadow while started, live while stopped | `shadow.py` | +2 B | validate | 4 |
+| M8 | **default-on for everyone** — `auto` always shadow; the literal reading that stops the live install | `shadow.py` | −15 B | validate | 2 |
+| M9 | an unreadable value resolves to LIVE instead of shadow | `shadow.py` | +1 B | validate | 1 |
+| M10 | `validate.py` stops refusing an unknown value | `shadow.py` | −9 B | validate | 9 |
+| M11 | the loop leg gated on `auto` alone again — the decision path stops running | `main.py` | −17 B | clamp | 1 |
+| M12 | the stop claim filed in shadow — every decision reads `stopped` | `main.py` | −20 B | clamp | 1 |
+| M13 | the banner goes green while nothing is commanded | `shadow.py` | −2 B | clamp | 1 |
+| M14 | the banner loses the standing latch | `shadow.py` | −2 B | clamp | 1 |
+| M15 | the row renders the standing command instead of the decision | `shadow.py` | −8 B | clamp | 1 |
+| M16 ⚠️ | the row disappears when live | `main.py` | +43 B | clamp | 1 |
+| M17 | the record becomes the wire | `main.py` | −6 B | clamp | 7 |
+| M18 | level-logged — the 40-row action log floods | `main.py` | −23 B | clamp | 1 |
+| M19 | the two rungs render identically (masking) | `shadow.py` | +22 B | validate | 1 |
+| M20 | the shipped default moves to `off` in `config.yaml` alone | `config.yaml` | −1 B | defaults_pin | 1 |
+| M21 | **PAIRED**: the substitution **and** the re-seed deleted together | `main.py` | −103 B | clamp | 10 |
+| M22 | the re-seed moved one line earlier — SAFETY-18 grades a 0 W no decision produced and goes permanently blind | `main.py` | +40 B | clamp | 1 |
+
+**Survivors: none.** ⚠️ **M17's `+0 B`-adjacent sibling** —
+`shadow_would_w = float(self.target)` — is recorded in §7 as **equivalent**
+rather than counted here.
@@ -0,0 +1,80 @@
+# SAFETY-103 - no swing on old battery readings after a drain ends
+
+**Status: implemented 2026-10-08, for review.** Tests: `test_safety103.py`.
+
+**The defect** (SAFETY-95 rig test, check 5, F1). While a battery settles
+from its ended drain, SAFETY-95 steers on the house's point: grid + every
+battery's reading - aim. The meter is 1 s old; a battery register can be
+10 s old (the SAFETY-90 register model). At E+13 A's reading said 1238 W
+(6.8 s old) while A was at 616 W, so the house looked ~620 W bigger: B went
+860 -> 1650 -> 870 W. B's own old reading does the same the other way.
+
+**The rule** (`main.py`, `_track_reads()`, `_drain_grid_w()`, N>=2, only
+while a drain's tail settles):
+
+1. Each cycle, per battery: the range its power can be in. That is its last
+   changed reading, widened by every command on its wire since (a lagging
+   battery moves from one toward the others, never beyond). A new reading
+   starts the range again.
+2. A reading that changed this cycle is taken as it reads. So is the side a
+   battery refuses (SAFETY-73): it is not heading that way.
+3. The house point is held (first cycle: the loop's start from SAFETY-95).
+   It moves only as far as the meter proves: to the nearest value of grid +
+   the batteries' ranges - aim.
+
+So the loop no longer moves on a reading that has not caught up. A real
+house step still moves it, as soon as the meter shows more than the
+batteries can explain.
+
+**Why not the tester's rule** ("a battery whose reading is older than its
+last command counts at its command"). B's command changes almost every
+cycle, so B is almost always at its command. That is the plain meter, which
+chases A's tail: B swings 1420 W. A lag model needs the plant's time
+constant, which is not known for a client's inverter. Measured on the plant
+below (N=2, 1200 W, A Off; swing = a move of the others later undone):
+
+| rule | 10 s lag | 5 s lag | 20 s lag | surplus, 5 s lag |
+|---|---|---|---|---|
+| release/1.0 (readings) | 760 | 840 | 150 | 800 |
+| tester's: at the command | 1420 | 1020 | 1600 | 800 |
+| lag model, tau 10 s | 70 | 140 | 80 | 580 |
+| lag model, tau 5 s, plant 20 s | | | 600 | |
+| hold all window | 0 | 0 | 0 | 0 |
+| **this rule** | **0** | **0** | **0** | **130** |
+
+Holding all window ignores a house step: a 2 kW kettle at E+5 s imported
+14.4 Wh over the next 30 s (release 11.5, this rule 11.3); 2 kW more sun
+exported 16.9 Wh (release 8.5, this rule 8.9).
+
+**Before -> after** (`test_safety103.py`, `tools/safety103_plant.py`: 800
+W/s ramp, 10 s lag, meter 1 s, registers 10 s at the rig's phases, B idles
+at -100 W; summed swing of the others in the 23 s after the end):
+
+| case | release/1.0 | after |
+|---|---|---|
+| rig check 5: N=2, 1200 W, A Off | B 1140 -> 850 -> 1630 -> 870, swing 760 W | B holds 1140 W |
+| N=3, 1200 W / 4000 W, A Off | 680 / 630 W | 0 / 0 W |
+| solar surplus, N=2 / N=3 | 890 / 740 W | 130 / 130 W |
+| lag 5 or 20 s, registers 5 or 10 s, N=2 and N=3 | | at most 10 W |
+| registers as fresh as the meter (1 s) | | rows byte-identical |
+| refusal end | | rows byte-identical |
+| N=1, every end | | rows byte-identical (also against the release/1.0 tree) |
+
+**Cost.** In the window, a house change smaller than what the batteries
+could still be doing is not followed until a reading catches up (at most a
+register period) or the window ends (23 s). Under a surplus the others
+still swing up to 130 W, a third of a slew step.
+
+**Not covered.**
+- Outside the drain tail the loop steers on the meter; readings only reach
+  the saturation freeze (SAFETY-96), unchanged.
+- A lost link or a refusal ends the tail at once (A is out of the split, or
+  reads ~0 W). The swing after them is the loop's own on a lagging plant,
+  the same with 1 s registers and on release/1.0: under a surplus up to
+  1.5 kW at N=2 and 3.9 kW summed at N=3; after a lost link about 1 kW
+  even without one. Not this card.
+- A battery that overshoots its command, or a reading offset beyond the
+  range, can put the true power outside the range; the meter then moves the
+  point, as before.
+- The end cycle's start (SAFETY-95 step 2) still uses the readings; the
+  batteries were steady during the drain, so they are current there.
@@ -0,0 +1,96 @@
+# SAFETY-107 - a refusal held under another writer is learned once
+
+**Status: for review.** Tests: `test_safety107.py`. One inverter only; nothing
+changes at N>1 (SAFETY-73's unit refusal has no "another writer" end).
+
+**The defect** (MAINT-13 F5, MAINT-14 "seen again"). A full pack under a
+maintenance charge in a cheap window takes no charge. At N=1 the action log then
+showed "BATTERY REFUSES asked -2500 W ..." and "BATTERY REFUSES ENDED: another
+writer" every cycle: 548 + 548 lines in 15 min on the MAINT-13 rig head,
+652 + 651 in 12 min on its base, 33 + 32 in 60 s in MAINT-14's c2b. The 40-line
+log flooded and the hint under the buttons changed every second, so the
+MAINT-13 notice was gone at once.
+
+**Cause** (`main.py`, the SAFETY-52 block before `compute()`). The end tested
+`self.target != self.loop_w`: the wire differs from the loop's ask. A held
+refusal makes the loop ask 0 W, so any claim that binds (the maintenance
+charge's `hi`, the peak guard's `lo`, a trade's SET) differs from it on every
+cycle. The refusal was ended against the same writer it had been learned
+against. `sat_count` is not reset by that end, so `compute()` learned the same
+refusal again in the same cycle. Nothing about the battery or the wire had
+changed; only the log and the hint did.
+
+**Other writers.** The same flap comes from any writer that holds the wire
+while the loop is refused, as long as the evidence lasts: a trade (a SET at
+P_ARBITRAGE) into a full pack, and the peak guard over an empty pack: 335
+refusal lines in 15 min each at a 5 s meter (`test_safety107.py` part 2, run on
+release/1.0).
+A maintenance drain or hold does not flap: its SET resets `sat_count` each cycle.
+
+**The rule** (`_refusal_update()`, `rejudged`). When another writer held the
+wire, the held refusal is judged afresh: `compute()` gets `refused=0` and no
+probe, exactly as before the change. Then:
+
+1. it finds the same refusal against that writer's ask: the same episode
+   continues, with no line and no hint. The probe clock restarts, as it did on
+   the old end and start: a probe is the loop's ask, and it is not on the wire
+   while another writer is;
+2. it does not: the refusal ends, logged "another writer", or "the battery
+   gives power" when the reading shows it (it was "another writer" before);
+3. it finds the other direction: end, then a new start, as before. In
+   practice 2 comes first: SAFETY-94's evidence restarts when the ask changes
+   sign, so a writer that turns round ends the refusal at once and the other
+   way is learned ~12 cycles later (`test_safety107.py` part 3e).
+
+**Why this rule.** The end now means what SAFETY-52 meant by it: the refusal no
+longer describes what is on the wire, judged by the same test that learns it.
+`compute()` sees the same inputs as before and the state after each cycle is
+the same (`batt_refused`, `batt_refused_at`), so every command is unchanged.
+Keeping the held refusal into `compute()` instead (mutation M5) would also
+stop the lines, but it holds the loop at 0 W where the old law let it ask past
+a writer's limit, which changes commands; it also removes SAFETY-52's
+owner-decided "another writer" exit.
+
+**Evidence.**
+- Differential trace (`goodwe/scratch/SAFETY-107/probe/trace.py`, not in this
+  repo; the real Controller in the CI image, release/1.0 bf3ac79 against this
+  tree): 300 seeds, N=1 (153) and
+  N=2 (147), 1/2/5 s meter, full/empty/dead/healthy battery windows, a stepping
+  house, maintenance charge with the cheap window opening and closing, P1 and
+  the peak guard, trade windows, stop/start; 427 680 cycles, 294 seeds with a
+  refusal held. Every command, site target, integrator, `sat_count`, refusal
+  state and reason is identical. Refusal lines: 100 748 before, 2 188 after.
+- The card's case: 1 line in 15 min at N=1 and N=2, 1/2/5 s meter, house
+  importing or exporting (release/1.0: 335-1 753 at N=1; N=2 was already 1).
+
+**Mutations** (`tools/mutation_run.sh` on purged copies; reds in
+test_safety107 / test_refusal / test_refusal_units; trace = seeds of 300 whose
+commands differ from release/1.0):
+
+| | mutation | reds | trace |
+|---|---|---|---|
+| M1 | `now == rejudged` -> `False` (every such cycle ends: the old flap) | 26 / 0 / 0 | 0 |
+| M2 | `rejudged` always 0 (another writer never ends it) | 5 / 1 / 2 | 29 |
+| M3 | the probe clock is not restarted on a continued episode | 1 / 0 / 0 | 2 |
+| M4 | a probe may open while rejudged | 0 / 0 / 0 | 0 |
+| M5 | the held refusal goes into `compute()` while rejudged | 2 / 1 / 2 | 27 |
+| M6 | an end while rejudged always says "another writer" | 1 / 0 / 0 | 0 |
+
+M4 is equivalent: a probe matters only if `compute()` engages in that call,
+which needs `SETTLE_CYCLES` saturated against the writer, and each of those
+cycles restarted the clock. The line stays because it states the rule.
+
+**Cost.** None in power. A takeover by a different writer while the battery
+still refuses is logged as an end and, ~12 cycles later, a new start against
+that writer (3 lines for the episode, `test_safety107.py` part 3a).
+
+**Not covered.**
+- A perfectly flat reading under a writer. The stale-reading gate trips, stops
+  the site and seeds the refusal (SAFETY-52 decision 3). After the stop the
+  writer's ask returns fresh, `compute()` has no saturation history against it,
+  so the refusal ends at the first cycle and the next trip seeds it again: 2
+  lines per gate cycle (29 in 15 min, house exporting), the same as release/1.0.
+  The gate cycle itself (0 W, then the writer's ask) is the cause; stopping it
+  changes commands. None of the rig runs showed it: real readings move.
+- At N=1 a refusal shapes only the loop. A writer above it still asks the
+  battery; at N>1 SAFETY-73's P_SAFETY claim binds every writer.
@@ -69,6 +69,8 @@ which does not run the startup gate) the absence costs a shave and never a pack.

 ## 3. DECISION 2 — the site verdict is the MAXIMUM of the packs' own floors

+*At N>=2 one pack at its floor no longer stops the others: [[SAFETY-87]].*
+
 `Controller.pack_floor_soc` — the **minimum** measured SoC, the emptiest pack —
 **is unchanged**, exactly as the card instructed. What changed is the floor it is
 graded against. `peakguard.binding_soc_floor()` reduces the roster's per-pack
@@ -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
@@ -0,0 +1,28 @@
+# SAFETY-40: the integrator bound is not a bug
+
+**Decision.** `i_clamped` (the integrator reaching `integrator_max_w`, i.e.
+anti-windup) keeps alarming through the same `ClampWatchdog`: it is counted,
+notified on the same cadence, and escalates on a sustained run
+(SAFETY-41). It gets its own text, a `WARNING` and an amber status row. Only
+`clamped` (a command over `max_w`) and write-path clamps keep the BUG SIGNAL,
+the `ERROR` and the red row.
+
+**Why it still notifies.** On a default install `clamped` is unreachable
+(`control.py`, at the integrator bound), so the integrator bound is the only
+loop-side signal of a runaway such as the 14 768 W one. Silencing it would
+remove that. The card says the same: "the fix is to say the true thing, not to
+say less."
+
+**Why a bug has its own budget.** A genuine over-rating must not wait up to
+`REASSERT_S` behind anti-windup notices. `ClampWatchdog` tracks a separate
+`last_bug_alarm`, and a bug's text is never overwritten by later anti-windup
+text within an episode. Across episodes the WARNING uses its own
+notification id (`goodwe_integrator_bound`), so it cannot replace a BUG SIGNAL
+notice still on screen (review of #130). With only bug engagements, the cadence is the same as
+before (`test_clamp.py` part 9).
+
+**Numbers.** They come from the `Decision` of the clamping tick (`i_bound_w`,
+`requested_w`, `clamped_w`, `target_w`), not from `i_w` or `self.target`.
+
+**Open for the owner.** Whether scattered one-cycle anti-windup episodes should
+notify at all, or only log and count. They notify now, as before.
@@ -0,0 +1,221 @@
+# SAFETY-45 — the trade is SIZED by the capacity guard, not switched by it
+
+**Status: closed.** `peakguard.charge_headroom_w()` publishes the watts the open
+billed quarter can still afford; `arbitrage.decide()` takes it as a required
+keyword-only argument and sizes the BUY leg to it; `main.py` passes the measured
+guard's own number at its one call site. `peakguard.decide()` is **not changed** —
+byte-identical to `release/1.0` at `478ba93`, `sha256(decide) = 200090d0835a3a55`,
+7252 B on both trees.
+
+⚠️ **THE HOUSE LOAD IN EVERY FIGURE BELOW IS SYNTHETIC.** TEST-23 stage 3's
+`priceloop.py` drives a flat modelled house against a modelled pack
+(`plantsim.Plant`, 800 W/s ramp into a 10 s lag, 15 360 Wh). The PRICES are real,
+the decision code is the shipped code, the billed-quarter accumulator is
+`app/p1.py`'s own — the load is not. Nothing here is a measurement of the live
+site at 192.168.2.158, which this work did not touch.
+
+## 0. The defect, measured
+
+TEST-23 stage 3 found a sustained limit cycle with arbitrage armed and a charge
+decision active. Re-measured here on the same rig against the same checkout,
+metrics recomputed rather than copied — a **charge onset** is a cycle at which
+`arbitrage.decide()` transitions into `ARBITRAGE_CHARGE`, which is the edge the
+rig already logs:
+
+| `peak_cap_w` | house | onsets/h | mean period | grid swing | billed quarters (W) |
+|---|---|---|---|---|---|
+| 1500 | 1200 W | **28** | 131.1 s | **−455.5 … +3200.0 W** | 1490.1 / 1496.5 / **1508.8** |
+| 3500 *(shipped)* | 1800 W | 8 | 509.3 s | +127.5 … +3800.0 W | **3511.3 / 3536.0 / 3559.1** |
+| 3500 *(shipped)* | 3000 W | 32 | 114.8 s | +1202.0 … +5000.0 W | **3518.9 / 3542.2 / 3556.7** |
+| 5000 | 1200 W | 1 | — | +1240.6 … +3200.0 W | 3169.5 / 3200.0 / 3200.0 |
+
+The last row is the **negative control**: `load + max_w = 3200 W` never reaches
+the cap, so there is no cycle to remove. The bite rule is `load + max_w >
+peak_cap_w`, which at the shipped `peak_cap_w: 3500` / `max_w: 2000` is any house
+drawing over 1500 W in the cheapest quarter.
+
+§10.1's ordering did win on the money — the guard kept the quarters within tens
+of watts of the cap — but **every billed quarter in the three biting rows
+finished OVER it**, which is the thing §9.1 bills. §10.2: *"an EMS that
+oscillates is worse than no EMS, both for hardware wear and — per §9.1 — for the
+peak it is trying to avoid."*
+
+## 1. ⚠️ The mechanism is NOT mainly the quarter boundary, and the card says it is
+
+The card, and `.cache/s45.md` before it, describe the loop as *"at each quarter
+boundary the projection resets to 0, the guard disengages, and arbitrage re-arms
+at full power."* **That is not what the 28 onsets are.** Their timestamps, off
+the run above:
+
+    1, 231, 351, 471, 581, 696, 806, 896, 1136, 1256, 1371, 1486, 1596,
+    1711, 1811, 2061, 2176, 2296, 2411, 2521, 2626, 2716, 2971, 3091,
+    3206, 3321, 3431, 3541      (s, quarter boundaries at 900/1800/2700)
+
+**23 of the 27 gaps are 90–120 s, mean 111.5 s, entirely inside one quarter.**
+The four long gaps — 230, 240, 250, 255 s — are precisely the four that SPAN a
+boundary, so the boundary **lengthens** the interval rather than causing an
+onset. Only three onsets land within 15 s of a boundary and one of those is
+`t = 1`, the start of the run.
+
+The real cycle, read off the recorded fields at t = 1000…1180 s:
+
+1. the trade charges at `−2000 W`; the meter sits at 3200 W against a 1500 W
+   ceiling; `wanted = batt_w + excess` is **negative** (−132 → −8 W), so
+   `decide()` files **nothing** and arbitrage is not constrained at all;
+2. `wanted` drifts up as the quarter's own history worsens and the `900 /
+   remaining` gain grows, and crosses zero at t = 1055 with **`floor_w = 5.3 W`**;
+3. that 5 W floor flips `arbitrage.guard_state()` to `True`, which refuses the
+   **whole trade** — so the setpoint goes from −2000 W to +5 W and the
+   grid-following loop, which targets grid = 0 and not grid = ceiling, takes the
+   actuator and discharges to **+1870 W**, exporting 420 W;
+4. the projection collapses, `wanted` goes negative, the guard releases, and
+   arbitrage re-arms at **`max_w`**. 115 s later, again.
+
+So the defect is **a binary interlock keyed on a continuous quantity**, and the
+quarter boundary is one of the ways it is crossed rather than the cause. The
+card's other claim — *"projection 3092 W against a 1509 W ceiling, `engaged=False`,
+for 170 consecutive seconds"* — reproduces, but it is the **first** such window
+(`first_engaged_t_s = 151.0`); the steady-state silent window is ~40–65 s.
+
+None of this changes what the fix has to do. It is recorded because a card that
+says "the boundary is the trigger" invites a fix in the boundary handling, and
+such a fix would have removed four of twenty-eight onsets.
+
+## 2. What was rejected, and why
+
+### 2a. Reverting `decide()`'s `wanted <= 0.0` rung — rejected, and it is a trap
+That rung is 2026-08-20's anti-bang-bang. Its own comment records the cost of not
+having it: 17 engage/release cycles in 900 s and a quarter finishing 49 W over
+the limit it had spent a quarter of an hour holding. It is untouched, pinned on
+the AST in `test_peakguard.py` 13g, and `tools/replay_ac3.py` reproduces the same
+190/190, 110 engaged cycles, 5 blind, 878 Wh on this branch as on `478ba93`.
+
+### 2b. Filing the affordable charge as a NEGATIVE `lo` — rejected
+Arithmetically this is the prettiest answer: `lo = wanted` with no sign gate is
+continuous, is exactly the control law `decide()` already computes, and would
+have put the constraint on the arbiter where it binds every claimant rather than
+only arbitrage. It was rejected on two grounds, in this order:
+
+1. ⚠️ **IT CREATES A NEW `lo > hi` CONTRADICTION CLASS AGAINST THE MAINTENANCE
+   SHAPING.** `main.py`'s cheap-window maintenance charge files
+   `Claim.limit("maintenance", P_MAINT_SHAPE, hi=-floor)` — a NEGATIVE `hi`.
+   `arbiter.py` clause 2 applies every limit at or above the winner's priority
+   and takes the most restrictive, with **no notion of one limit out-ranking
+   another**; a peak `lo = −300 W` against a shaping `hi = −1000 W` is `lo > hi`,
+   which resolves to **0 W — the battery parked, in the one quarter of the month
+   that sets the bill**. That is the exact failure `peakguard.shaping_suspended()`
+   exists to prevent, and the only way to close it would be to key that
+   suppression on "a claim exists" — which, on every site this card is about,
+   means the maintenance charge-only shaping is suspended **permanently**. A
+   silent, large change to a different subsystem is not a price this card should
+   pay.
+2. It changes the meaning of `PeakDecision.engaged` at five call sites outside
+   this module — `arbitrage.guard_state()`, `shaping_suspended()`,
+   `claim()`, `main.py`'s edge-logged action line and `main.py`'s status row —
+   each of which today means "the guard is HOLDING" and would silently start
+   meaning "a claim exists".
+
+`test_peakguard.py` part 5's sweep asserts **no negative floor, ever**, and the
+reason it gives ("a `lo` limit is incapable of capping discharge or export only
+while it is non-negative") is, strictly, not the true reason — a `lo` of any sign
+caps neither. The invariant is still right and is still worth holding; §2b above
+is the argument that actually supports it, and it is recorded here rather than
+left for the next person to re-derive.
+
+### 2c. A backoff, cooldown or hysteresis constant in `arbitrage.py` — rejected
+The card asks whether the second half of the fix belongs in arbitrage: *"a trade
+refused at 14:59 and re-armed at 15:00 has learned nothing from the refusal."*
+It does belong there, but as a **size**, not as a memory. `arbitrage.py`'s
+hysteresis note is explicit that the switching decision is "which hour is it" and
+that **no timer is needed and none is invented**; `peakguard.py`'s design note
+spends a paragraph on why it carries no hysteresis constant. A cooldown would be
+a second control loop compensating for a limit the first one declined to file,
+and its constant would outlive whatever it was tuned against. The trade now
+re-arms at `ceiling − load` instead of at `max_w`, which is what "learning from
+the refusal" means when the refusal is a measurement.
+
+## 3. What was done, and the precedent it follows
+
+`control.maintenance_charge_floor()` has capped MAINTENANCE charging at *"the
+headroom left under the site's cap"* since the loop was written, and its
+docstring says why:
+
+> "A maintenance charge is the only thing this system does that is big enough and
+> long enough to set that peak, so it is capped by the headroom left under the
+> site's cap."
+
+⚠️ **THAT SENTENCE STOPPED BEING TRUE WHEN OPT-04 LANDED.** Price arbitrage is a
+second thing that is big enough and long enough — it commands `max_w` for a whole
+tariff interval, deliberately, against the meter — and it was given no such cap.
+This card gives it the same shape, with one difference that matters:
+`maintenance_charge_floor()` sizes itself from `peak_forecast_entity`, which is
+OPTIONAL and empty on a default install — the exact hole SAFETY-25 had to close
+in `shaping_suspended()`. `charge_headroom_w()` comes off `decide()`, which runs
+wherever P1 does.
+
+**The number is `wanted_w` read in the other direction.** `decide()` already
+computes `wanted = batt_w + excess` as the DISCHARGE that lands the quarter on the
+ceiling; a negative `wanted` is a permitted CHARGE of `−wanted`. No new
+arithmetic, no new constant.
+
+Two properties make it safe to hand a strategy, and both are swept rather than
+argued (`test_peakguard.py` part 13):
+
+* ⚠️ **IT IS INVARIANT IN THE BATTERY.** Raise the charge by dW and the meter
+  rises by dW, so `excess` rises by exactly dW while `batt_w` falls by dW:
+  `wanted` does not move. Measured across `batt_w` from −5000 W to +2000 W on one
+  banked quarter — the headroom is 1350.0 W at every one of the six points while
+  the `excess` those runs see moves through six distinct values. It is a
+  **feed-forward** number, so consuming it adds no feedback path around the plant.
+  The fixed point is `charge = ceiling − load`, with the meter ON the ceiling and
+  `wanted` parked a whole `ceiling − load` clear of the engagement boundary.
+* **HOLDING IMPLIES ZERO OR UNKNOWN.** Across 1080 swept combinations, not one
+  ENGAGED decision answers a positive headroom, so the function can never hand a
+  caller permission the guard's own `lo` is at that instant refusing.
+
+## 4. After, on the same rig, same command, same checkout
+
+| `peak_cap_w` | house | onsets/h | grid swing | energy bought | billed quarters (W) |
+|---|---|---|---|---|---|
+| 1500 | 1200 W | 28 → **1** | 3655.5 → **282.0 W** | 180.0 → **285.2 Wh** | **1500.0 / 1500.0 / 1500.0** |
+| 3500 | 1800 W | 8 → **1** | 3672.5 → 1687.6 W | 1652.9 → 1616.1 Wh | **3500.0 / 3500.0 / 3500.0** |
+| 3500 | 3000 W | 32 → **1** | 3798.0 → **474.7 W** | 482.9 → 475.3 Wh | **3500.0 / 3500.0 / 3500.0** |
+| 5000 | 1200 W | 1 → 1 | **identical** | **identical** | **identical** |
+
+* **One onset** means the trade starts once and runs for the whole window. The
+  battery is trading 100 % of the hour where it used to trade 43 %, 92 % and 54 %.
+* **Every billed quarter lands exactly on the cap and none over it**, where every
+  quarter in the three biting rows used to finish over.
+* **The money.** At 1500/1200 the site buys **58 % MORE** energy, because a
+  continuous 300 W trade beats a 2000 W trade that is cancelled for 57 % of the
+  hour. At the two shipped-default rows it buys **2.2 % and 1.6 % less** — and in
+  exchange the worst quarter drops from 59 W over the cap to 0 W over it. The
+  capacity tariff bills the month's single worst quarter with no averaging and no
+  forgiveness (specs.md:583), so that is not a trade-off, it is the ordering
+  §10.1 asks for.
+* The remaining 1687.6 W at 3500/1800 is the opening **ramp**, not a cycle: the
+  pack goes from 0 to 1700 W of charge in about ten seconds and the meter with
+  it. One onset, no export, no reversal.
+* The last row is bit-identical before and after. **This card costs nothing on
+  the installs it is not about.**
+
+## 5. What this does NOT fix, with sizes
+
+* **TEST-23 finding 1 — the export overshoot at the END of a trade** (356–938 W,
+  ≈0.37 × `max_w`) is untouched and is a different card. It happens when the
+  cheap interval ends and the grid-following loop takes back an actuator that was
+  holding a charge; nothing here changes the handover.
+* **A house whose load ALONE exceeds the cap** (`load > peak_cap_w`) still puts
+  `wanted > 0`, still engages the guard, and still refuses the trade outright
+  through the interlock — correctly, since you cannot buy in a quarter you are
+  already over on. The loop then drives to grid = 0 rather than to grid =
+  ceiling, which is more discharge than the guard asked for. Not swept here: all
+  four (cap, load) pairs on the record have `load < cap`.
+* **`arbitrage.claim()` still files the SIZED number, but the ARBITER can clamp
+  it further** and the strategy is not told. The reason line names the guard's
+  headroom, not the arbiter's `bound_by`. Pre-existing; not widened.
+* **The container leg was not re-run.** `hadrive.py` needs `test23s3-addon`
+  started, and that container is deliberately stopped because it is a second
+  writer on the setpoint entity under measurement. The in-process rig's twelve
+  transcribed lines are pinned by `test_arbitrage.py` 3b's AST check on
+  `main.py`'s call site, which is the line this card adds to them.
@@ -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.
@@ -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.
@@ -0,0 +1,110 @@
+# SAFETY-52 - a battery that refuses is asked for 0 W
+
+**Decided 2026-09-27 by the owner, on the phase A plan (option D3). All four
+questions answered yes.**
+
+## The defect
+
+At the BMS cut-out the battery gives ~0 W whatever it is asked. The saturation
+freeze (`control.py`, `frozen`) then holds the request where it stood, and its
+SAFETY-13 exit cannot fire, because a reading of ~0 against a large ask lies
+inside the interval a limit can produce. The request stood at +5000 W for
+11.87 h on 2026-09-06 and at +1940 W for 3 h 55 m on the bus on 2026-09-19. It
+moved again only when the grid error changed sign. SAFETY-48's lead cap only
+changes where `i_w` parks (one slew step ahead instead of at the rail). When
+the request moved after the reading went flat, the stale-reading gate won
+instead and ran SAFETY-59's ~70 s trip cycle.
+
+## What was decided
+
+1. **A refused direction is held at 0 W**, reason `battery refuses`. It engages
+   in `compute()` when the freeze has held `SETTLE_CYCLES` and the reading is
+   below `REFUSED_BELOW_W` (100 W, the probe's own answer) against an ask beyond
+   `saturation_w`. The drop to 0 skips
+   the slew limit (it only removes an ask nobody meets). The direction is
+   carried like `sat_count` (`refused=`, `Decision.refused`).
+2. **A 200 W probe every 15 minutes, 34 s long** (`PROBE_W`, `PROBE_EVERY_S`,
+   `PROBE_S`; twice `BATT_OBLIGED_S`). A reading of at least 100 W in the held
+   direction ends the refusal, during a probe or not. 200 W is below `freshness.MOVE_W` (250 W), so a probe cannot arm
+   the gate. The clock is main.py's `now_mono`; `compute()` stays clockless.
+3. **A gate trip while the loop is frozen on a ~0 W reading is a refusal** for
+   control (`Controller._refusal_from_stale`). This is what stops the ~70 s
+   cycle. The log keeps SAFETY-56's two-explanation wording.
+4. **No SoC in the loop.** SAFETY-25 Option A stands. Nothing reads SoC.
+
+Other exits: the loop wants the other direction (charge is accepted at the
+floor), control stopped or started, another writer on the wire (the arbiter
+reseed). A gap in the readings keeps the refusal, because the gate's own stop is
+what seeds it.
+
+**One inverter only.** At N>1, OPT-09's `pack` limit already closes an empty
+battery's discharge end and moves its share. There, a one-unit gate trip must
+not refuse the site. `compute()` is passed `refused=None` there, and that path
+is release/1.0's law unchanged (the `i_w=None` equivalence sweep in
+`test_control.py` still holds).
+
+## Evidence
+
+`test_refusal.py` drives the real Controller and gate (the 09-06 and 09-19
+shapes, recovery with no sign change, the probe cadence, every exit).
+`tools/replay_refusal.py` replays the 16-day capture, same model as
+`replay_recorded_loop.py`, and should be read for deltas:
+
+| plant | law | gate trips | request >1 kW above delivery | longest held | import / export kWh | worst 15-min |
+|---|---|---|---|---|---|---|
+| fitted | old | 85 | 113.3 h | 16.57 h | 112.0 / 35.2 | 3434 W |
+| fitted | new | 130 (133 after review) | 11.4 h | 0.21 h | 112.3 / 35.4 | 3456 W |
+| offset 0 W | old | 1010 | 102.2 h | 16.58 h | 112.0 / 35.2 | 3434 W |
+| offset 0 W | new | 85 | 6.1 h | 0.33 h | 111.9 / 35.1 | 3434 W |
+
+**Traced in review (#141).** The +22 W worst quarter is the old law's worst
+quarter too. There the old law stands at +2060 W on a pack giving 0 W, and the
+new law asks 0 W, which the fitted plant answers with its -22 W offset: 22 W
+charged from the grid. The fit above the floor reads `batt = cmd - 28 W`, so a
+real inverter asked 0 W may do the same. Of the 71 new-law trips with no
+old-law trip within 2 min, 59 come 85-97 s after an answered probe. The offset has lifted the modelled pack
+just above its floor, the probe is answered, control ramps, the pack empties
+again mid-ramp, and the gate trips, which re-seeds the hold. The other 12
+follow an other-direction exit the same way. On a site this is one
+`STALE_READING` ERROR line per answered probe at most, and only on a battery
+that answers a probe and then cuts out again. Catching the re-cut before the
+gate needs a faster engage than `SETTLE_CYCLES`, which accuses a healthy slow
+battery, so it is left to SAFETY-58/59. After the review changes below the
+fitted-plant row reads 133 trips (the delivery exit now also catches answers
+that arrive after the probe window); the other figures are unchanged. Rejected alternatives and their figures are in
+the phase A plan: bounding the integrator by demand made the worst quarter
+541 W worse or cycled the gate 3368 times, and an SoC envelope needs the
+configured floor to be right and needs SoC.
+
+## Review changes (#141)
+
+- **"Gives nothing" is below 100 W, not below 500 W.** At `saturation_w` a
+  battery derated to 100-499 W (cold, a tapering battery) was held at 0 W for
+  ~93 % of the time: 300 W derated gave 86 Wh in 4 h against 1 200 Wh on the
+  old law. The capture has 0.11 h in that band, so the replay does not move.
+- **Any delivery ends the hold, not only an answered probe.** With
+  `meter_poll_s: 1` the 12 cycles last 12 s, less than a healthy battery's
+  reading lag (up to `BATT_OBLIGED_S`, 17 s). That engaged on a healthy step and
+  held it for 15 min. Now the late reading ends it within seconds (2 s held in
+  `test_refusal.py` part 5b).
+- **N>1 is stated as a limit in DOCS.** The pack limit there covers an empty
+  battery only when its cut-out level is configured right.
+
+## Not covered
+
+A battery that gives a steady part of the ask (e.g. a 500 W keep-alive) is a
+genuine limit (SAFETY-13 case a) and still holds its request.
+
+## What SAFETY-58 and SAFETY-59 must take into account
+
+- **SAFETY-58** (the first read after a rest trips at once): a probe never arms
+  the gate (200 < 250 W), but the refusal seeding reads the trip. If 58 delays
+  the first verdict, the seed arrives later. The 09-19 shape then needs the
+  compute-side engagement (12 cycles) to win, which it does only while the
+  request stands still. Keep `test_refusal.py` part 4 green.
+- **SAFETY-59** (DOCS says a ~70 s pattern proves a failed register): with this
+  change a refusing battery no longer produces the pattern at one inverter. The
+  DOCS text should say so, and that the `battery refuses` reason is the
+  discriminator the add-on now has. At N>1 the old pattern can still occur.
+- If either changes `MOVE_W`, `PROBE_W` must stay below it.
+  `test_refusal.py` part 2 checks the inequality.
@@ -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.
@@ -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.
@@ -0,0 +1,106 @@
+# SAFETY-61 — the control task's death ends the process
+
+## 0. The defect
+
+`amain()` started `run_control()` as a bare task and waited on `stop`. Nothing
+watched the task. An uncaught exception in `read_inputs()`, `cycle()` or
+`publish()` ended the task silently, and `stop` was never set. The web UI, P1
+and tariff tasks kept running, and the Supervisor saw a healthy container. The
+traceback appeared only at shutdown. The ESP32's layer-1 veto zeroed the
+inverter about 30 s later, so the hardware was safe. The pack then sat at 0 W
+indefinitely while the add-on showed green.
+
+`test_control_task.py` reproduces this on the pre-fix tree. The child process
+reaches its 40 s deadline, has written no 0 W, and has logged nothing.
+
+## 1. Decision: exit with status 70 after the ordinary wind-down
+
+A done-callback on the control task (`control_task_done()`) handles the death.
+It logs the traceback at CRITICAL at the moment of death, then sets `stop`.
+`amain()` then runs the same wind-down that SIGTERM runs (`shutdown()` →
+`command_site_zero()`, then cancel, then clean up). After that it raises
+`ControlTaskDied`, and `main()` turns that into `SystemExit(70)` (sysexits
+EX_SOFTWARE). A normal stop and `run_control()`'s own refusal path both set
+`stop` before the task ends, so the callback ignores them. The refusal still
+exits with 78.
+
+**Why not restart the loop in the same process:**
+
+* `cycle()` writes controller state before its awaits: `cycle_at`,
+  `peak_guard`, `allocation`, then `target`/`reason`, then the writes. An
+  exception between those steps leaves the controller half-updated. A loop
+  restarted in the same process would continue from a state that no boot ever
+  produces. A process restart rebuilds the controller from the Store, which is
+  the path every boot already runs.
+* An unbounded retry is the invisible spin the card forbids. A bounded retry
+  would reimplement the Supervisor watchdog's own throttle: 10 restarts per
+  30 min, and 5 attempts with backoff (`apps/const.py`).
+
+## 2. What happens after the exit, verified rather than assumed
+
+* **Exit status reaches Docker.** The add-on image (s6-overlay, `init: false`,
+  `CMD /run.sh`) was run with `exec python3 -c 'raise SystemExit(70)'`.
+  `docker inspect` gave ExitCode 70. The same test with exit 0 gave 0, and an
+  uncaught exception gave 1.
+* **Supervisor 2026.08.0** (`ghcr.io/home-assistant/amd64-hassio-supervisor`,
+  source read from the image):
+  * A non-zero container exit is recorded as `ContainerState.FAILED`
+    (`docker/monitor.py`). The Supervisor logs *"App … exited with non-zero
+    exit code 70"* at ERROR (`apps/app.py container_state_changed`).
+  * The Supervisor restarts the add-on **only if the per-install Watchdog
+    toggle is on**. `watchdog_container()` returns when `not self.watchdog`.
+    The toggle defaults to **off** (`apps/validate.py`:
+    `vol.Optional(ATTR_WATCHDOG, default=False)`).
+  * Add-on containers get **no Docker restart policy**. The only
+    `restart_policy=` in the Supervisor belongs to the observer.
+  * `boot: auto` in `config.yaml` only controls starting at host boot. The
+    `watchdog:` key in `config.yaml` is a health-check URL, not a restart
+    policy, and this add-on does not set it.
+* **So on a default install the add-on stays stopped after this exit.** The UI
+  shows it as stopped, its log holds the traceback, and the Supervisor log holds
+  an ERROR line. The pack is at 0 W, which is the same physical state as before
+  this card. The difference is that 0 W is written immediately instead of after
+  the ~30 s veto, and the add-on no longer shows green. With the Watchdog toggle
+  on, the Supervisor restarts the add-on.
+* **Not verified:** an actual restart by a running Supervisor. That would need a
+  live Supervisor, and the only one available is the live house.
+
+## 3. Left open for the owner
+
+* Whether `DOCS.md` should tell installers to enable Watchdog. DOCS.md is not
+  this card's file.
+* Setting the Watchdog toggle from inside the add-on (`/addons/self/options`)
+  was rejected here, because it would change a user setting without the user
+  knowing.
+
+## 4. Scope: the siblings, and why they are not supervised
+
+* `run_tariff_refresh()` and the P1 HTTP and HA transports already catch
+  `Exception` inside their loops by design, and the values they feed are
+  age-bounded downstream.
+* The P1 MQTT source *returns* on purpose when it is misconfigured. Making every
+  long-lived task's end exit the process would turn that deliberate fail-safe
+  into a restart loop.
+* Only the control task is supervised.
+
+## 5. `hass.py`: an undecodable body is an absence
+
+A non-JSON `200` served as `text/html` was **already** treated as an absence,
+because aiohttp's `ContentTypeError` is a `ClientError`. The reads that actually
+escaped were these three:
+
+* a malformed body labelled `application/json`, which raises `JSONDecodeError`
+  (a `ValueError`);
+* a JSON body that is not an object, which raises `AttributeError` in
+  `number()` and `limits()`;
+* an undecodable error body in `call()`, which raises `UnicodeDecodeError`.
+
+All three were measured against aiohttp 3.13.5. The first two now read as
+`None`, and the third is now a failed write (`False`).
+
+## 6. Status row
+
+`checks()` now starts with a *control loop* row showing how long ago the loop
+last completed a pass. The row turns red once that age exceeds
+`FIRMWARE_INGEST_VETO_S`. The heartbeat is sent from this loop, so past that age
+layer 1 has zeroed the inverter.
@@ -0,0 +1,104 @@
+# SAFETY-73 - a battery that refuses, with two or more inverters
+
+**Decided 2026-09-27 by the owner, on the phase A plan (option R). All four
+new questions answered yes. SAFETY-52's four decisions carry over.**
+
+## The defect
+
+SAFETY-52 held a refusing battery at 0 W at one inverter only. At N>1
+(`main.py` passed `refused=None`) nothing closed a unit that gives ~0 W while
+its state of charge reads above its configured cut-out, so the allocator kept
+handing it its weighted half. Measured on the real `Controller`, two units,
+house 3000 W, A cut out:
+
+| register | law | B gives | grid | A's gate trips / h |
+|---|---|---|---|---|
+| flat -4 W | old | 533 W | +2471 W | 46 (each stops the whole site) |
+| flat -4 W | new | 2000 W (its rating) | +1004 W | 1 |
+| jitter | old | 1910 W | +1094 W | 0 |
+| jitter | new | 2000 W | +1004 W | 0 |
+
+House 1200 W, which B alone carries: old +671 W (flat) and +284 W (jitter)
+standing import, new -16 W. Both cut out: old keeps asking two empty batteries
+(+1910 W each on the jitter shape), new holds the site at 0 W.
+
+## What was decided
+
+1. **A refusing unit is closed in that direction** by its own P_SAFETY unit
+   claim, source `refused`. It engages when the unit gives under
+   `REFUSED_BELOW_W` (100 W) for `SETTLE_CYCLES` (12) cycles, spanning at least
+   `REFUSED_SPAN_S` (22 s), in one direction while asked more than `PROBE_W`
+   (200 W), or when its stale-reading gate
+   trips on a held reading under 100 W. The allocator then hands its share to
+   the others within their own limits (owner decision 1). It is a hard unit
+   limit that always intersects, so OPT-11's P_MODE layer fits inside it.
+2. **It binds every strategy's ask on that unit** (decision 2): peak guard,
+   arbitrage and maintenance are placed around it like the loop.
+3. **A refusal to give power above the configured cut-out** logs INFO plus one WARNING ending
+   in `REFUSES_ABOVE_CUT_OUT` (decision 3). SAFETY-42/43 no longer report such a
+   unit: its share is 0 W, and `account()` treats it as parked.
+4. **All units refusing the same way** pass that sign to `compute()`, so the
+   site holds 0 W with SAFETY-52's law (decision 4). Probes go one unit at a
+   time.
+5. **Probe:** every 15 min for 34 s the claim becomes a pin at +-200 W and the
+   others carry the rest. The pin stands only while the resolved site target
+   asks at least 200 W its way; otherwise it would make a sibling take the
+   opposite direction, so it falls back to the closed limit for that cycle.
+6. **Exits:** a reading of 100 W or more in the held direction (probe or not);
+   100 W or more taken the other way for 12 cycles (charge at the floor; one
+   cycle of the loop overshooting through zero is not enough); stop or start.
+   On every exit the site target and integrator restart from the watts on the
+   wire, or the reopened unit is handed a parked remainder at once.
+
+**Why 200 W and not `saturation_w`.** A unit's share is often small: a 400 W
+night load split two ways asks 200 W of each. With 500 W the empty battery
+kept a phantom share that SAFETY-43's relative arm then reported as not
+delivering, the ERROR decision 3 replaces. Shares of 200 W or less that give
+under 100 W are "too small to call" in `account()`: the sibling covers the
+meter and nothing is asked of the empty battery that matters.
+
+**Why one direction throughout.** On TEST-19's flapping family a command that
+swaps sign each cycle reads ~0 through the plant's lag: 42 engagements in 21
+no-fault runs without the rule, 0 with it.
+
+**N=1 is unchanged.** Every SAFETY-73 path is gated on `len(inverters) > 1`.
+`test_refusal_units.py` part 6 runs SAFETY-52's whole suite with every
+SAFETY-73 method made to raise.
+
+## Evidence
+
+- `test_refusal_units.py`: cases a, b and c on both register shapes against
+  the old behaviour, probes and their spacing, one-at-a-time probing, the
+  recovery reseed, each exit, the small-ask and small-site-target cases, the
+  WARNING, the status row and shadow mode. Mutations U1-U13 in its docstring.
+- **No false engagements.** TEST-19's no-fault campaign (admin/goodwe
+  `sim/delivery_window.py` families, 2640 runs at N=2 and 2640 at N=1, every
+  unit executing its share) graded with the engage clause: 0 engagements, the
+  longest qualifying streak 5 cycles against 12. The grader is
+  `goodwe-session/scratch_s73/s73_nofault.py`.
+- **Recovery.** Case a, A recovering into a house that fell below the parked
+  target: worst grid +0 W with the reseed. Phase A measured -1059 W without the
+  reseed and the site hold.
+
+## Review changes
+
+- **The evidence must span 22 s, not only 12 cycles.** At a 1 s meter the 12
+  cycles were 11 s, shorter than a healthy reading's lag (dead time plus a
+  10-17 s publish). The reviewer's harness (real `Controller`, both units with
+  6 s dead time and a 13-17 s publish, load steps 300/3000 W every 2 min) then
+  refused both healthy units 10-16 times an hour, and each time the site held
+  0 W: +50-85 Wh import an hour and a +4.6 kW grid peak against +3.7 kW without
+  the refusal. At a 2 s tick there were none. `REFUSED_SPAN_S` is
+  `(SETTLE_CYCLES - 1) * LOOP_TICK_S`, so 2 s and slower ticks are unchanged.
+- **The cut-out WARNING is for a refusal to give power only.** A full battery
+  that stops taking charge is always above its cut-out level, and the WARNING
+  told the installer to check a setting that has nothing to do with it.
+
+## Not covered
+
+- A unit that gives a steady part of its ask (100 W or more) is a limit, as at
+  N=1. SAFETY-42/43 still report it.
+- `pack_permissions` stays SoC-based, so the peak guard may size a shave with a
+  refusing battery counted. The shortfall shows as `unmet_w`.
+- A wedged unit (HW-01) reading ~0 W is now shown as a refusal, not reported as
+  not delivering. Its share still moves, which is the gain SAFETY-42 measured.
@@ -0,0 +1,43 @@
+# SAFETY-78 - a maintenance drain at two inverters
+
+**Status: DECIDED 2026-09-29.** Fixes MAINT-05 §6 (OPT-11 P1 F1, UX-13 P3
+check 5, OPT-11 P3 F4). Tests: `test_safety78.py`.
+
+**The defect.** At N>=2 the drain pins its pack (a unit SET at
+`P_MAINTENANCE`) and the site target is split around the pin. Whenever the
+site target was below the pin, the other pack had to charge. The allocator
+refuses opposite directions (SAFETY-25 §0a, SAFETY-31), so the site went to
+0 W and logged `ARBITER: REFUSED` every cycle. That covers a house below the
+drain rate, a grid-charge trade, and a house above it too: after a refusal the
+loop restarts from 0 W and its 400 W slew step is below the pin again.
+
+**The fix.** While a pack drains at N>=2, main.py files a site limit
+`drain`, `lo` = what the pin really places (`allocator.pin_w()`: the drain
+rate inside that pack's own hard limits), at `P_MAINTENANCE`. So the site
+target is never below the pin and the other pack only adds power in the same
+direction. Opposite splits stay forbidden.
+
+- The order is the arbiter's own: a safety SET (100) outranks the limit and
+  the pin, so everything parks; the peak floor (50) and the drain floor are
+  both applied, so the higher wins; a trade or the loop below the drain is
+  lifted to it.
+- Below the drain rate the drained pack exports the rest, as the drain does at
+  N=1 (`maintenance.py`: "forced discharge, exports the surplus"). Holding it
+  to the house load would make N=2 drain differently from N=1; that is an
+  owner question, not this fix.
+- A draining pack that can place nothing (a refusal, a stale link) adds no
+  floor, and the wait is logged once per episode.
+- With battery modes on, no pack is a grid charger while another drains
+  (`modetrade.decide(draining=)`, why `cycle`), and the other battery's card
+  says why (`other_cycle`). Not while the drain waits: no floor is filed
+  then, so the other battery may charge from solar.
+- Not filed at N=1, where the drain is the site SET itself: byte-identical
+  (`tools/safety78_identity.py`, which hashes the claims too).
+
+**Not changed (measured in the PR #154 review, follow-ups).**
+- At N=1 a drain (60) outranked the peak floor (50): a 5000 W house imported
+  3000 W against a 2500 W limit. Fixed by [[SAFETY-83]].
+- At N=2 a maintenance CHARGE in a cheap window has the same stall: the
+  charging pack's `hi = -floor` against the loop asking the other to give is
+  refused on 141 of 261 cycles. The mirror fix is a site `hi`, which can meet
+  the peak floor's `lo` (0 W), so it is not this card. Fixed by [[SAFETY-84]].
@@ -0,0 +1,41 @@
+# SAFETY-79 — the peak guard keeps a margin below the peak limit
+
+**Status: DECIDED 2026-09-28 (owner decision).**
+
+## Decision
+
+The peak guard aims `peak_margin_w` under the limit it holds: under
+`peak_cap_w`, or under a month peak already banked above it
+(`quarter_target_w()`). `peak_margin_w` is a setting: default 50 W, range
+0-500 W, whole watts. An install without the key gets 50.
+
+**Why (owner):** the guard aimed exactly at the cap, and in the OPT-11 P1 test
+a quarter banked 3501.9 W against a 3500 W limit (OPT-11-P1-test-report.md,
+check 4). A peak even 1 W over still sets the billed peak. It is a setting and
+not a constant because the add-on is sold to several sites.
+
+**Banked peak (review, 2026-09-29):** the PR first aimed at a banked month
+peak as it stood. That can bank a few W over it, which raises the bill the
+same way; and a peak banked between cap - margin and the cap (common in the
+month an install upgrades, since the old guard held quarters at the cap) was
+aimed at exactly, so one overshoot went over the cap. The margin now applies
+under it too. Cost: up to `peak_margin_w` of a peak already paid for goes
+unused (more discharge, less charge headroom); no bill cost. Undo is one line
+in `quarter_target_w()`.
+
+## What uses which number
+
+- **the aim:** `peakguard.decide()` (the claim's floor, and so arbitrage's
+  `charge_headroom_w()` and OPT-11's give-way, which read it), and, as cap -
+  margin, `shaping_suspended()` and `maintenance_charge_floor()` (the forecast
+  checks, via `Controller.peak_aim_w()`).
+- **the real cap (reporting and billing):** `PeakTracker` (month peak,
+  headroom, 80 % warning), the decision's `ceiling_w` and every notice and
+  status row built from it, Home's limit, and `validate.config_notes()`.
+
+## Checks
+
+`peak_margin_w: 0` is byte-identical to ed739d4 (test_peak_margin.py part 1,
+digests from tools/safety79_identity.py, which also runs a maintenance charge
+with a forecast). validate.py rule 12 refuses a value outside 0-500, not
+whole, or not below `peak_cap_w`.
@@ -0,0 +1,63 @@
+# SAFETY-81 — no false "Load too high for battery" alarms
+
+**Status: 2026-09-29, owner go for the card. Review kept the 10 W tolerance
+as a constant and added the 10 s hold.**
+
+## Defect
+
+The SAFETY-79 test (SAFETY-79-test-report.md, F1/F2) saw 6 false alarms in 7.
+The alarm fired whenever `decide()` clamped its floor to the rating
+(`saturated`). Three things set that while the quarter landed on target:
+
+- **Double count.** `decide()` sizes from the held meter reading plus the
+  battery reading. When the meter sample predates the battery's last increase,
+  the increase is counted twice. It happens under noise, and at each quarter
+  start, where the battery is back while the held sample is still the spike.
+- **The aim, not the cap.** `saturated` is graded against cap − margin, so at
+  margin 50 noise needs 50 W less to trip it (F2).
+- **Last seconds.** The gain 900 / remaining turns a few W over the aim into
+  thousands of W wanted, with the battery far from its rating.
+
+## Decision
+
+The alarm needs `saturated` and `peakguard.load_too_high()`: with the battery
+at full power from now on, the quarter still ends more than `ALARM_MISS_W`
+(10 W) over the real limit (`ceiling_w`). That is the miss itself, without the
+gain. The battery reading it uses is the lower of this cycle's and the last
+one's. It must hold for `ALARM_HOLD_S` (10 s). At most one notification per
+quarter, because near the threshold the test flickers with the meter; the
+ERROR log line is written for every episode.
+
+**Why 10 W:** at margin 0 the guard itself lands up to +5.7 W over (SAFETY-79
+test, check 5), and those misses are real but tiny; the alarm would fire in
+the last second of most guarded quarters. The margin (default 50) is the fix
+for them. Cost: a real miss of 10 W or less is not alarmed; at a capacity
+tariff of the order of EUR 50 per kW a year, 10 W in one month is cents.
+Review measured +13 W on a 10 kW two-unit site at margin 0, not saturated, so
+no alarm: the tolerance only matters when the battery is at its rating. A
+constant, not an option: `peak_margin_w` is the owner's knob.
+
+**Why the hold (review):** the test assumes the load now lasts the rest of
+the quarter. A load over cap + battery for ~5 s every 30 s (`sine4500_fast`,
+a cycling hob or heater) alarmed at each quarter start while the quarter
+landed under the aim. The hold stops that.
+
+**Cost:** a real alarm comes 10-12 s later than on 5a4cdc2 (`step6500` at
+1211 s, not 1201 s); a slow ramp 20 s later (`ramp6500`), as it waits for the
+real cap. While the battery refuses or its reading is lost, the alarm waits
+until the quarter is lost even at full battery (27-60 s later in review runs);
+those faults have their own alarms. A load over cap + battery for more than
+10 s still alarms even if the quarter later lands under. `ALARM_HOLD_S = 0`
+removes the hold.
+
+## Not changed: the 1 s spike itself
+
+The cycle after a quarter boundary and before the new quarter's first meter
+sample still sees 0 s left, files no claim, and an Off battery drops to 0 W for
+one cycle. That is the same edge tick as OPT-15 F1, so it is left to OPT-15.
+Control is unchanged here: every command in `tools/safety81_sim.py` is
+byte-identical to 5a4cdc2 (test_safety81.py part 1).
+
+The double count also moves control, not only the alarm: on a late sample the
+guard asks for the full rating for one cycle (edge4600 at 902 s: 2000 W where
+1150 W holds the aim). Left to a follow-up card.
@@ -0,0 +1,34 @@
+# SAFETY-83 - the peak guard outranks the maintenance drain at N=1
+
+**Status: DECIDED 2026-09-29 (owner go, P1).** Follows SAFETY-78's "Not
+changed" list. Tests: `test_safety83.py`.
+
+**The defect.** At N=1 the drain is the site SET at `P_MAINTENANCE` (60). The
+peak floor is a limit at `P_PEAK` (50), and clause 2 applies only limits at or
+above the winner, so the floor was ignored and the house imported what the
+drain left. A 5000 W house under a 2500 W limit and a 2000 W drain banked
+3000 W quarters; on the owner's settings (limit 3500, drain 2500, margin 50) a
+breach starts at about 5950 W.
+
+**The fix.** While a drain owns the setpoint at N=1 and the peak floor asks
+for more than the drain rate, `main.py` (`_peak_over_drain()`) refiles that
+peak claim at `P_MAINTENANCE`. The arbiter then applies it: the target is the
+floor, still inside the safety limits, and a safety SET (100) still parks
+everything. Where the floor is at or below the drain rate nothing changes.
+
+- The order in effect is now the same at N=1 and N=2: safety limits and the
+  SAFETY-73 refusal > peak guard (with the SAFETY-79 margin) > maintenance >
+  modes > trade > loop (`arbiter.py`, beside the priorities).
+- The drain keeps counting: the battery discharges at least the drain rate on
+  every cycle, so the cycle is not reset or stalled; it only ends sooner.
+- Below the drain rate the rest is still exported (owner, 2026-09-29).
+- Identity: `tools/safety78_identity.py --diff` against 35cdffe changes only
+  cycles where the guard asked for more than the drain; after such an episode
+  the commands are identical again and only the log and the idle loop's
+  integrator differ. N=2 is unchanged.
+
+**Not changed.**
+- Between the drain rate and the peak aim, the house still imports what the
+  drain leaves (N=1 behaviour kept by the identity). At N=2 the loop covers it.
+- A maintenance HOLD (0 W, 120 min, battery full) still outranked the peak
+  guard at N=1. Fixed by [[SAFETY-86]].
@@ -0,0 +1,46 @@
+# SAFETY-84 - a maintenance charge at two inverters
+
+**Status: DECIDED 2026-09-30.** Follows SAFETY-78's "Not changed" list.
+Tests: `test_safety84.py`; identity: `tools/safety84_identity.py`.
+
+**The defect.** In a cheap window the charging pack files its own
+`hi = -charge` (P_MAINT_SHAPE). At N>=2 the loop's site target sat above it
+(a house to cover, or its 400 W slew step from 0 W), so the other pack had to
+give while this one charged. The allocator refuses opposite directions
+(SAFETY-31), so the site sat at 0 W whatever the house
+(`tools/safety84_identity.py` on 9d5b7d1: 436 of 480 cycles refused). N=1
+was fine.
+
+**The fix.**
+- While a pack's own limits make it charge at N>=2, `main.py` files a site
+  limit `charge`, `hi` = what that pack's own `hi` places
+  (`allocator.hi_w()`, whole W as the allocator rounds). The site target is
+  never above it, so the other pack only adds power in the same direction.
+  Opposite splits stay forbidden. Mirror of SAFETY-78's `drain` floor.
+- Peak guard first (owner order, SAFETY-83). The charge is sized to the
+  quarter's headroom under the aim (`charge_headroom_w()`, cap or banked peak
+  minus `peak_margin_w`), so it charges less instead of stopping: the meter
+  sits on the aim and the guard does not need to step in. Where the house
+  alone is over the aim the guard engages, the shaping is suspended as before
+  (`shaping_suspended()`) and no `charge` is filed, so the guard's `lo` and
+  this `hi` never meet in one cycle (no `lo > hi`, no park at 0 W).
+  Without the headroom sizing the aim still held (the suspension did it), but
+  a battery gave power back on 285 of 540 cycles at a 3000 W house
+  (test_safety84.py part 2).
+- A site stop (a safety SET above P_MAINT_SHAPE) sizes the charge to 0 W:
+  the unit `hi` is a hard limit, so a charge under a 0 W stop needs the other
+  pack to give. It was refused, with an ARBITER line, on most cycles of the
+  stop (test_safety84.py part 4). The stop still parked the site at 0 W.
+- A pack that cannot take the charge (a refusal, a full pack, a stale link)
+  files no ceiling; the other pack follows the loop.
+- Not filed at N=1: byte-identical (`tools/safety84_identity.py`, which hashes
+  every claim, in and out of a cheap window and under a banked peak).
+
+**Not changed.**
+- At N=1 the charge is not sized to the headroom: the guard still suspends it
+  and the battery gives until the quarter is safe. The same sizing would fit
+  there; that is an owner question, not this fix.
+- Outside a cheap window (`hi = 0`, solar only) nothing is filed, at any N.
+- A HOLD (later fixed by [[SAFETY-86]]) and the "Battery is not keeping up"
+  alarm (SAFETY-85) are untouched. In the identity runs that alarm's log line
+  comes as often at N=2 as at N=1 (2 in 480 cycles).
@@ -0,0 +1,91 @@
+# SAFETY-85 - no false "not keeping up" while another owner sets the battery
+
+**Status: implemented 2026-10-01, for review.** Tests: `test_safety85.py`.
+
+**The defect.** "Battery is not keeping up" (SAFETY-40, `goodwe_integrator_bound`)
+fired about every 2.5 min during maintenance (drain, charge, HOLD) and under the
+peak guard, while the battery gave exactly what it was told. Each warning
+re-created the HA notification. Rig counts: 24 in an hour (SAFETY-83 F1), 43 in
+7 episodes (SAFETY-86), 35 in 16 (SAFETY-87), 12 in 6 (SAFETY-84). The page
+counter counted cycles (861), not episodes.
+
+**Cause, measured on the real Controller.**
+- N=1: when a higher claim decides, `cycle()` re-seeds the integrator from the
+  target each cycle, then `compute()` adds `gain * error` for a grid error the
+  loop does not own. Target + kick crosses the rail and sets `i_clamped`. The
+  carried integrator is not wound (SAFETY-48 caps the lead at one slew step),
+  so control comes back one slew step at a time.
+- N>=2: a maintenance pin is a unit claim. The loop stays the site winner and
+  winds to its rail for watts the pinned battery may not give. When the pin
+  lifts, the site jumps: 2500 W in one cycle when a HOLD ends under a 4500 W
+  house, 1390 W when a charge pin lifts (`s84 n2_charge_dear`, t=1800 s).
+
+**Decision.** Three rules; the alarm, its text and its id are unchanged.
+1. **The loop's clamp counts only on a cycle the loop decided.** The winner is
+   the loop. Its number is on the wire, or only a rating (`device`,
+   `supervised`) cut it. No bound held it, and nothing was unmet.
+   (`Controller._loop_alarm_input`.)
+2. **A battery another owner set to discharge alarms when it gives less than
+   it was told.** This covers every battery on a cycle the loop did not
+   decide, and a battery with its own pin otherwise. The test is more than
+   `saturation_w` short of the least it stood at over `SHORT_CYCLES` cycles
+   and `SHORT_SPAN_S` (the plant's measured settle, SAFETY-13/73), for
+   `saturation_cycles` cycles in a row (`clamp.delivery_short`). It covers a
+   real shortfall during maintenance or under the peak guard. Before, that
+   shortfall was silent unless the kick happened to reach the rail (house
+   1000 W, drain 2000 W, battery gives nothing: 0 warnings before, 4 in 10 min
+   now).
+3. **At N>=2, while maintenance holds a battery, the loop is bounded** by
+   OPT-11's `loop_bound()` (what the batteries may place). It does not wind,
+   and control comes back one slew step a cycle. Why maintenance only: that is
+   where the jump was measured and where the owner order puts maintenance
+   above the loop. Other N>=2 limits (pack cut-out, SAFETY-73 refusal) keep
+   the old law. Rule 1 still silences them (the target is unmet), so they no
+   longer warn either.
+
+Fixing the windup was chosen over only ignoring the wound part, because at
+N>=2 the wound integrator moves real watts at hand-back. At N=1 there was
+nothing to fix: re-seeding already prevents windup.
+
+**What SAFETY-03/40 protect is kept.** With the loop in charge, the integrator
+bound still warns (a runaway, a house above the rating), and a saturated
+inverter under the loop's own command still does not alarm (SAFETY-03 AC 2):
+rule 2 grades only batteries another owner set.
+
+**The counter.** `ClampWatchdog.bound_episodes` counts episodes that had a
+bound engagement. The status row shows it ("N times since start").
+`bound` (cycles) stays for the log and the tests.
+
+**Re-pinned digests.** Every change is intended; nothing at N=1 moves a watt.
+
+| digest | what changed |
+|---|---|
+| s78 `n1_drain_owner` | the false clamp rows are gone from the log; commands identical |
+| s78 `n2_drain`, s84 `n2_charge`, `n2_charge_banked`, s79 `n2_maint` (test_peak_margin) | loop reason (`mode-bound`), integrator and loop claim while bounded; commands identical |
+| opt11 `n2_maint` (test_modes) | A drops out at t=1655 s: B follows the house at once, 8 cycles differ (max 920 W) |
+| s84 `n2_charge_dear` | A's pin lifts at t=1800 s: 400 W a cycle, not a 1390 W jump; the surplus step after it; 98 cycles |
+
+test_safety86's "without the ceiling the log floods" now needs the ceiling
+and the bound both removed: either one alone keeps the loop inside what the
+batteries can give. The `alarmed()` helpers in test_safety84/86 also read
+SAFETY-81's quarter stamp, because ALLOCATOR rows can push its row out of
+the 40-row log.
+
+**Review (PR #163).** The first draft graded each battery against last
+cycle's command and graded charges too. On plantsim's battery (10 s lag) at
+the live 2 s meter, every drain or charge start warned once, and an N=2 drain
+or HOLD under the peak guard with a stepping house warned 15 times an hour. A
+maintenance charge tapering near full warned 11 times in 50 min, which
+SAFETY-42 section 7 had ruled out. With the settle window and discharge only:
+0 in all of those cases. A battery that gives nothing still warns, lagging
+or not. At a hypothetical 20 s lag, it warns at most twice an hour. The cost:
+a battery that does not take a charge another owner set is not named by this
+alarm (the same gap SAFETY-42 states; the charge has its 36 h timeout).
+`test_safety85.py` part 7.
+
+**Not changed, open for the owner.**
+- With the loop in charge and the house above the batteries' total rating,
+  it still warns (SAFETY-40). On the rig's 2 x 2000 W N=2, most of SAFETY-84's
+  count came from houses of 4500 and 6500 W.
+- TEL-10's `Loop reason` reads `mode-bound` while the maintenance bound holds
+  the loop, with modes off. DOCS lists the value with both meanings.
@@ -0,0 +1,47 @@
+# SAFETY-86 - the peak guard outranks the maintenance HOLD
+
+**Status: DECIDED 2026-09-30 (owner).** Follows SAFETY-83's "Not changed"
+list. Tests: `test_safety86.py`.
+
+**The defect.** The HOLD (battery resting full after the maintenance charge)
+is a SET of 0 W at `P_MAINTENANCE` (60), above the peak floor (`P_PEAK`, 50),
+so the floor did not bind. At N=1 a 6500 W house banked 6500 W quarters and
+'Load too high' fired (SAFETY-83 rig test, check 4). At N=2 only the other
+battery gave: 4500 W against a 3950 W aim (SAFETY-84 rig test, check 6).
+
+**The fix** (`main.py`, `_peak_over_hold()`).
+- N=1: during a HOLD a peak floor above 0 W is refiled at `P_MAINTENANCE`, as
+  for a drain (SAFETY-83). The battery gives the floor; the Why reads "raised
+  for the peak limit".
+- N>=2: the holding battery's pin is raised to the floor minus what the other
+  live batteries may place (their hard `hi`, or their pin). The others give
+  first, the holding one only the shortfall. Why this split and not the
+  allocator's shares: the hold is maintenance and outranks the others' use
+  (owner order), and the owner rule for an Off battery is the same, "give way
+  only for the shortfall". A battery Off by its mode (P_MODE, below
+  maintenance) therefore still gives before the holding one.
+- N>=2, while the holding battery gives: a site `hold` ceiling at the floor
+  (P_MAINTENANCE), so the loop does not ask for watts the hold keeps back.
+  Without it the moving pin re-logged the ALLOCATOR "could not be placed"
+  row each cycle and filled the action log (review, PR #161).
+- Below the aim nothing changes: the floor is 0 W, the hold is 0 W, the rows
+  are identical to before (test_safety86.py part 2).
+- A site stop (a SET above `P_PEAK`) decides alone: nothing is raised at N>=2,
+  and the refiled floor at N=1 stays under `P_SAFETY`. If another battery is
+  pinned to charge (a SAFETY-73 probe) the pin is not raised, so the site is
+  never split both ways.
+- The hold resumes by itself: the rule is evaluated each cycle, so when the
+  guard lets go the command is 0 W again.
+
+**The level dips below the target: the hold finishes anyway.** Owner
+decision 2026-10-01: the HOLD ends on its clock (`maintenance_hold_min`) even
+when the peak guard pulls the level down; no top-up. A top-up would re-enter
+CHARGE (up to 36 h, `CHARGE_TIMEOUT_MIN`) and keep the site's one maintenance
+slot meanwhile.
+
+**Not changed.**
+- The peak guard still grades the emptiest battery (SAFETY-32): at N=2 with
+  B under `peak_soc_floor` the floor is limited and A holds even when it is
+  full (SAFETY-87).
+- "Battery is not keeping up" during maintenance (SAFETY-85), the N=2 charge
+  flapping (SAFETY-88) and the N=1 charge headroom sizing are untouched.
@@ -0,0 +1,83 @@
+# SAFETY-87 - the peak guard uses every battery that can still give
+
+**Status: DECIDED 2026-10-01 (owner card).** Follows SAFETY-86's "Not
+changed" list. Tests: `test_safety87.py`; identity:
+`tools/safety87_identity.py`.
+
+**The defect.** At N>=2 the guard graded the emptiest battery against the
+highest floor ([[SAFETY-32]] §3). One battery under `peak_soc_floor` made the
+whole site floor-limited: the claim asked for 0 W and the reserve alarm fired,
+even with the other battery full. Measured: a maintenance charge (A at 11 %)
+raised the alarm 10 times while both batteries gave 2000 W and the quarter
+landed on the aim (SAFETY-84 rig test, check 3); a HOLD (A at 99 %, B at
+15 %) left A at 0 W and banked 4051 W, raising the month peak (SAFETY-86
+review; rig case 7a: 4563.8 W).
+
+**The fix.**
+- `decide()` and its call are unchanged. At N>=2 `Controller._peak_on_able()`
+  then grades each battery on its own floor (`peakguard.reserve_split()`).
+  One at or under it is *held*. The others that are live and not refusing
+  (SAFETY-73) are *able*.
+- A floor-limited decision is re-taken on the able batteries
+  (`peakguard.place_on_able()`): their own permission (min SoC against max
+  floor, among them), and a floor of `min(need, able_w)`. `able_w` is their
+  rating plus the drain a held battery gives anyway (its maintenance pin).
+- The held batteries weigh 0 in the split while the site gives
+  (`arbiter.resolve(reserve=)`), so the floor lands on the able ones. During a
+  HOLD, a held battery is not counted among the "others" (`_peak_over_hold()`),
+  so the holding battery covers the need.
+- Floor-limited now means: some battery is held and the able ones cannot hold
+  the aim. The claim still asks them for `able_w`. The alarm fires only if
+  they miss the real limit at full power for `ALARM_HOLD_S`, the same test as
+  'Load too high' (`_reserve_short()`), so a one-cycle miss at a quarter's end
+  is not an alarm. With nothing able (all held, or the rest refusing or
+  dropped) it is the old state: 0 W, immediate alarm.
+- The alarm and the row name `held`, each battery graded on its own floor. The
+  old code named batteries against the site's highest floor.
+- Page: the two peak rows carry `runs`. A red `runs` row gives the banner its
+  title without "Not ready", and the Home page is not shown as held at 0 W.
+  Rows that do stop control still outrank it.
+
+**How SAFETY-32's concern is still covered.** SAFETY-32 took min(SoC) against
+max(floor) so the guard never sizes a forced discharge a battery's own BMS
+stops. Now no battery at or under its own floor is asked for the peak: it is
+graded on its own floor, and an unread SoC or unknown cut-out counts as held.
+The min/max pairing still decides permission, over the able batteries. The
+roster verdict `decide()` echoes (`soc`, `soc_floor`) is kept, so SAFETY-32's
+call-site and reduction checks still bite. What changed is only that one held
+battery no longer stops the others. One exception, with battery modes on: see
+Open.
+
+**Maintenance pins beside a held battery** (review). A draining battery that
+may still give is raised from its drain rate towards its rating for the peak
+floor, after the others (`_drain_over_reserve()`; peak > drain), else the
+floor's rest landed on the held battery. In a HOLD, a held battery counts its
+own pin (a drain) among the others, and a held battery pinned to charge stops
+the raise (never split both ways).
+
+**Before -> after** (test_safety87.py, rig of 2 x 2500 W, aim 3450 W):
+
+| case | before | after |
+|---|---|---|
+| charge, A 11 %, house 4500 | 3 reserve alarms, quarter 3450 | 0 alarms, 3450 |
+| HOLD, A 99 % / B 15 %, house 5500 | A 0 W, B 2488 W, 3 alarms | A 2054 W, B 0 W, 0 alarms, 3450 |
+| HOLD, house 6500 | A 0 W, B 2488 W, 4051 W | A 2500 W, B 0 W, 4014 W, 1 alarm (A alone is short) |
+| HOLD, month peak 4000, house 6000 | A 0 W, B 2488 W, 3551 W, alarms | A 2054 W, B 0 W, 3950 (peak - margin), 0 alarms |
+| both under the reserve | alarm | alarm (unchanged) |
+| N=1, every scenario | | byte-identical |
+
+**Open, for the owner.**
+- The loop still draws a held battery (SAFETY-25 option A: the reserve binds
+  the peak guard only). It gives last, after the able ones. So with house 6500
+  in the charge case, B alone cannot hold the aim, the alarm fires as
+  specified, and the loop then lands the quarter on the aim from A. The text
+  says "cannot keep … alone", not "will go over", so it stays true.
+- Battery modes on, A Off and B held: when B alone can place the floor, OPT-11
+  keeps A resting and B gives it. When B cannot, A gives first. Making Off give
+  before a held battery in the first case needs a third allocator tier. The
+  same at N=3: A Off, B held, C able, floor 4000 W gives C 2500, B 1500, A 0.
+  Until then, with modes on, a held battery can give for the peak.
+- The notification and row text live in `messages.py`, which has no NL layer
+  yet (UX-19). The Home page text, which has NL, is unchanged.
+
+**Not changed.** N=1. 'Load too high' (SAFETY-81). SAFETY-85, -88, -89, -90.
@@ -0,0 +1,81 @@
+# SAFETY-90 - the peak guard goes on after a P1 meter gap
+
+**Status: DEV 2026-10-05, for review.** Tests: `test_safety90.py`.
+
+**The defect.** A meter gap longer than `meter_max_age_s` leaves seconds the
+quarter average does not count (`p1.QuarterAverager`, on purpose: a guess must
+not reach the bill record). `peakguard.blindness()` then called the projection
+blind for the rest of the quarter, so the floor was 0 W. During a HOLD the
+battery gave nothing and the quarter went over: SAFETY-86 rig case 7b, N=2,
+3964.8 W against a 3450 W aim, the month peak raised; N=1, 3701 W (review).
+The page still read "Keeping the grid near zero". At start-up mid-quarter the
+same rule left the start-up quarter blind, and a held battery was drawn as last
+resort (SAFETY-91 test, O2).
+
+**The fix** (`peakguard.fill_gaps()`, `peakguard.gap_w()`,
+`Controller._fill_peak_gaps()`).
+- Once readings are back, every second of a silence longer than
+  `meter_max_age_s` counts at `gap_w = max(the limit, the import just before
+  the gap, the import just after it)`, where "import" is the grid plus the
+  batteries' discharge, i.e. with the batteries at 0 W. The gap's first
+  `meter_max_age_s`, which the averager credits at the last reading, is topped
+  up to `gap_w` too. The guard then grades the quarter as usual, so it is not
+  blind and gives what keeps the quarter at the aim.
+- **The bound.** The count is at or above the true import as long as, during
+  the gap, the house load (less solar) stayed at or under the higher of the loads seen just
+  before and just after it, or under the limit, and the batteries did not
+  start charging (during a gap they hold their last command, then go to 0 W).
+  It never counts the gap below the limit. A load that rises above all three
+  only inside the gap is the one case it can miss.
+- **Cost of the bound.** It is conservative: with the house at 6500 W, a 30 s
+  to 5 min gap lands the quarter 100-180 W under the aim (table below), paid in
+  battery energy.
+- **While the gap lasts** nothing changes: the reading is too old to steer by,
+  the guard is blind (floor 0 W) and the "inputs missing" stop sets 0 W, as
+  before.
+- **Before the first reading** (start-up or restart mid-quarter) the
+  add-on was down, so the batteries were at 0 W (it sets 0 W when it stops,
+  the ESP32 watchdog after 30 s). Those seconds count like a gap, at
+  `gap_w(the limit, the import seen first)`; after a restart the restored
+  reading's held `meter_max_age_s` is topped up the same way. The bound is
+  the gap's, with only the "after" side known. A load the batteries cannot
+  make up then raises "Load too high", which is true: that quarter is going
+  over. The page says so: the status row "Peak guard: part of this
+  15-minute period was not measured, counted as high use" and the home line
+  "Part of this 15-minute period was not measured." / "Een deel van dit
+  kwartier is niet gemeten." until the quarter ends.
+  *Review:* the first version counted them at the aim, with "nothing is
+  known" as the reason. The first reading does show the load, and with the
+  batteries at 0 W the import was that load, not the aim: a 60 s restart
+  during a 6500 W HOLD landed 3653 W against 3450 W.
+- The bill record (`quarter_blocks`) is unchanged: it still banks only what
+  was measured. The estimate steers the guard and is never banked.
+- The action log gets one `PEAK_GUARD_GAP` row per gap, with the seconds and
+  the watts it was counted at.
+- No option. The threshold is `meter_max_age_s`, the limit and the aim are
+  `peak_cap_w` and `peak_margin_w`.
+
+**Before -> after** (`test_safety90.py`, quarter as the meter really averages
+it, gap starting 300 s in; 10 s battery lag; aim 3450 W):
+
+| case | before | after |
+|---|---|---|
+| N=1 HOLD 6500 W, gap 30 s / 60 s | 3456.6 / 5329.2 | 3346.2 / 3272.2 |
+| N=1 HOLD 5500 W, gap 5 min | 4717.9 | 3330.6 |
+| N=2 HOLD, B able, 6500 W, gap 30 s / 60 s | 3456.6 / 3865.6 | 3346.3 / 3272.7 |
+| N=2 HOLD, B able, 5500 W, gap 5 min | 3745.4 | 3288.9 |
+| N=2 HOLD, B held, 5500 W, gap 60 s | 3254.9, B drawn 2500 W | 3335.4, B 0 W |
+| gap across the edge, next quarter, N=1 / N=2 | 4100.0 / 3621.2 | 3446.3 / 3382.2 |
+| house 3000 -> 6500 W inside a 60 s gap, N=1 | 5255.6 | 3368.3 |
+| house 6500 -> 2000 W late in a 5 min gap, N=1 | 3629.2 | 3145.1 |
+| start-up 450 s in, N=1, house 5000 W (batteries at 0 W before it) | 5000.0 | 3450.0 |
+| restart, down 60 s / 150 s, N=1, house 6500 W | 4039.1 / 5483.3 | 3450.0 / 3450.0 |
+| meter never drops, N=1 and N=2 | | rows identical |
+
+**Not changed.** The late-reading edge (SAFETY-91 test, O1): a reading late by
+less than `meter_max_age_s` is not a gap, and the seconds since it are not
+counted in the projection (on any quarter, not only after a gap). Near a
+quarter's end the 900/remaining gain turns that into a large negative excess
+and the floor drops for a cycle or more. Counting those seconds at the held
+reading would fix it, but it changes every quarter's last seconds on a
+healthy meter; it is handed back as its own card.
@@ -0,0 +1,74 @@
+# SAFETY-91 - a held battery is drawn only after the others are full
+
+**Status: DECIDED 2026-10-01 (owner: held battery last, SAFETY-25 option A
+kept).** Follows SAFETY-87. Tests: `test_safety91.py`.
+
+**The defect** (SAFETY-87 rig test, F1 and F2). At N>=2 a battery at or under
+its own peak reserve was held back (weight 0) only on cycles where the peak
+guard asked for power.
+- F1: B draining at 1000 W, A held at 15 %, house 5500. Once the grid was
+  near zero the loop set the target, A had its normal weight and B's drain
+  pin bound, so the loop drew A at 2500 W for the whole quarter (15.0 ->
+  10.7 %) while B stayed at 1000 W. In the next quarter A reached its
+  cut-out, and B stayed pinned at the peak floor (~2422 W), not its 2500 W.
+- F2: in a HOLD (A holding, B held), at a quarter's edge the guard saw a block
+  with no seconds left and asked for nothing for one cycle. The HOLD's
+  ceiling lapsed, A went back to 0 W and the loop's target went to B: 2500 W
+  for 1 s.
+
+**The fix** (`main.py`, N>=2 only).
+- `_held_back()`: the batteries at or under their own reserve while another
+  can still give (live, not refusing), graded as in `_peak_on_able()`. They
+  weigh 0 in every split where the site gives, not only for the peak. With
+  nobody able (all held, or the rest refusing or dropped) nobody is held back
+  and the split is as before.
+  Review: once held back, a battery stays so until its SoC reads more than 1
+  point above its reserve. A reading flipping 20/21 % otherwise swapped
+  ~1000 W between the batteries on each flip (grid +-500 W with A 10 s and
+  B 3 s lag). The guard's own permission (SAFETY-87) is unchanged.
+- `_drain_rise()`: while a battery is held back, a draining battery's pin
+  becomes a floor at its drain rate (`lo`), so it rises towards its rating
+  before the held one gives. Not for a held battery's own drain, not under a
+  site stop, not for a battery that is not live.
+- `tariff.next_quarter()`: past a block's end, before the next block's first
+  telegram, the guard grades the next quarter, projected from the held
+  reading (the averager credits it there). Not when that reading is too old
+  to be credited (`max_hold_s`).
+
+**What stays.** SAFETY-25 option A: once every able or draining battery is
+at full power, the loop still draws a held battery (`allocator._fill()`'s
+last-resort pass). With house 5500 and 2 x 2500 W, A still gives 2500 W
+after B is full. Nothing is placed on a battery at its cut-out: OPT-09's
+pack limit closes it (`hi = 0`), and the drain rise lets B take the rest.
+
+**Before -> after** (`test_safety91.py`, 2 x 2500 W, lagging battery 10 s):
+
+| case | before | after |
+|---|---|---|
+| B drain 1000, A held, house 4000 | A 2500, B 1000 | A 1500, B 2500 |
+| same, house 5500 | A 2500, B 1000 | A 2500, B 2500 (option A) |
+| cycles A asked while B not full | 612 of 900 | 0 |
+| A at its cut-out, house 5500: B | 1572 W mean | 2500 W, A 0 W |
+| HOLD, late telegram at the edge | A 0, B 2470 for 1 cycle | A 2050, B 0 |
+| idle, A held, house 2000 | A 1005, B 1005 | A 0, B 2020 |
+| N=1, every scenario | | byte-identical |
+
+**Why N>=2 only.** At N=1 there is no other battery to give first. The edge
+roll would also fix the N=1 one-cycle dip at a quarter's edge (SAFETY-86
+rig, "A dropped to 0 W for 1 s"), but this ticket keeps N=1 byte-identical;
+extending it is a one-line change for a later ticket.
+
+**Re-pinned.** `test_modes.py` `n2` and `n2_off`: from t=1600 battery A is
+at its 20 % reserve, so B carries the house and A gives last (100 of 540
+cycles differ). With SAFETY-87's held rule both are a5dddad's again, and the
+test grades that.
+Two fixtures changed with it: `test_safety87.py` part 10's "without the
+raise" run also turns off `_drain_rise()` (else B rises anyway), and
+`test_peakguard.py` 10g and `test_watchdog.py`'s two-inverter rig give
+their second battery a cut-out, as rule 8 requires (an unknown cut-out is held, so A alone would carry the cycle).
+
+**Not changed.** The peak guard's own rules (SAFETY-87). A drain with
+nobody held stays a pin (SAFETY-78). An Off battery beside a held one
+(SAFETY-87 Open). The first cycle after start, before any quarter is
+measured, can still put the loop's first step on a held battery in a HOLD.
+SAFETY-88, -89, -90, -92, -93, -94.
@@ -0,0 +1,60 @@
+# SAFETY-93 - the maintenance charge end hands back smoothly
+
+**Status: implemented 2026-10-02, for review.** Tests: `test_safety93.py`.
+
+**The defect** (SAFETY-85 rig test, check 4; also on 9358781). At N=2, when
+A's maintenance charge ended, B went 0 -> -1600 W in one cycle and charged
+from the grid with the house at 6000 W. The HOLD end was already smooth
+(SAFETY-85).
+
+**Cause.** During the charge the site target holds A's charge (SAFETY-84's
+`charge` ceiling, -2000 W). At the end A gets its HOLD pin (0 W), but the
+loop starts its next step from last cycle's site target. The slew limit
+moves the site total by 400 W (-2000 -> -1600), and the only battery left
+to place it on is B. The same happens when the charge times out or the
+battery is switched Off (A free, its -2000 W shared out). With the charge
+suspended by the guard and A giving under the loop, B took A's share in
+one step (675 W).
+
+**The fix** (`main.py`, `_reseed_charge_end()`, N>=2 only). On the cycle a
+battery leaves CHARGE, the loop's start point (`self.target`, and the
+integrator with it) is what the other batteries stood at plus that
+battery's new command: its pin (HOLD or abort, 0 W), or, if it is free, its
+last discharge (a charge stops). The loop then moves from there one slew
+step a cycle. The ending battery's own step (-2000 -> 0 W) is maintenance's
+pin, as before; it lowers the grid import. The end is kept until the loop
+next runs, so a missed poll on that cycle (the input hold) does not lose it.
+
+Review: a charge also ends, for the site, when the battery is still in
+CHARGE but can no longer be placed: a stale link or a refusal (SAFETY-73)
+drops it, and its -2000 W landed on B the same way (B 0 -> -1600 W at a
+1200 W house). So the end is noted after the unit claims are filed: a
+battery leaves the charge when it leaves CHARGE, is not live, or its own
+claims contradict. The guard suspending the charge (SAFETY-84) is no end.
+
+Why a start-point reseed, and not a per-battery slew in the allocator: the
+jump comes from one stale number at one edge, the kind of edge SAFETY-73
+(`_unit_refusal_end`) and OPT-11 P3 (`_reseed_run_edge`) already reseed.
+The change stays at that edge; nothing else at N>=2 moves.
+
+**Before -> after** (`test_safety93.py`, 2 x 2500 W, 10 s lag, 2 s meter):
+
+| case | before | after |
+|---|---|---|
+| rig case: house 6000, A charges 2000 to the end | B 0 -> -1600, charges 4 cycles | B 0 -> 400 -> 800 ..., never charges |
+| house 1200 | B 0 -> -1600 (2800 W from the grid) | B steps of 400, never charges |
+| charge times out / A switched Off | B 0 -> -1600 | B 0 -> 400 |
+| guard suspended the charge, A gives 1825 | B step 675 W | B step 395 W |
+| missed poll on the end cycle | B 0 -> -1600 a cycle later | B 0 -> 400 |
+| A dropped mid-charge (stale link, refusal), house 1200 | B 0 -> -1600 | B 0 -> 400 |
+| N=1, both charge ends above | | byte-identical |
+
+No pinned digest moved: the 46 digests of `tools/*identity*.py` (N=1 and
+N=2) are byte-identical to f3e409c; none of their scenarios reaches a
+charge end.
+
+**Not changed.** The peak guard's floor still moves the site in one step
+when it engages (a house step, a quarter edge): the guard outranks the slew
+(owner order). A HOLD pin still drops the holding battery to 0 W at once
+and SAFETY-86 gives way to the others first. SAFETY-88 (charge flapping
+above the aim) is untouched.
@@ -0,0 +1,102 @@
+# SAFETY-94 - a battery that lags or reverses is not frozen or refusing
+
+**Status: implemented 2026-10-03, for review.** Tests: `test_safety94.py`
+(rig: `tools/safety94_rig.py`). Also closes SAFETY-58. SAFETY-74 stays open.
+
+## The defects
+
+1. **Stale-reading gate (SAFETY-37).** Its 35 s ran from the register's last
+   change. After a rest that clock was already past 35 s, so the first read
+   after a new command tripped it, before the register could answer. Live
+   2026-10-03 (0.14.0, N=2): 17:39:16 B and 17:39:25 A (load ramp after a
+   rest), 19:00:04 A (drain start), 21:21:22 B (drain -> charge). Each was
+   1 s after its command; each register answered within 11 s. This is
+   SAFETY-58's shape.
+2. **Refusal at N=1 (SAFETY-52).** `compute()` engaged after `SETTLE_CYCLES`
+   frozen cycles if the reading was under 100 W at that moment. The frozen
+   cycles include a reversal through the battery's lag. At a 1 s meter the
+   12th cycle comes as a battery reversing out of a charge passes 0 W
+   (SAFETY-85 rig, O1: "gave -20 W for 13 cycles"). The refusal then held
+   0 W, the battery settled at 0 W, never gave 100 W, and waited for the
+   15-minute probe. N>1 already required 22 s in the band, so it was safe
+   at a 10 s lag but not at 20 s.
+
+## What changed
+
+- **The gate counts only time the register was asked to move**
+  (`freshness.Freshness._oblige`). A read counts the time since the last
+  read when, at that read, the command is 250 W or more and has moved 250 W
+  from where it stood at the register's last change. A register change
+  (or a SAFETY-57 release) restarts the count. A command flapping in and
+  out of the ask still adds up (frozen register, 0/1500 W every 5 s: trip
+  at 69 s). The conjunction, `MOVE_W` and `RELEASE_S` are unchanged.
+- **The bound is unchanged at 35 s and now means what its derivation
+  says.** The floor was always "how long a healthy register takes to answer
+  a command": 6 s plant + 10 s publish + 1 s read = 17 s. The band
+  `[2 x 17, 0.5 x 75] = [34, 37.5]` holds. Live answers measured: 1.4, 3,
+  6 and 11 s after the command.
+- **Refusal evidence is the same at every roster size**
+  (`main.Controller._gave_nothing`, SAFETY-73's count moved into a method).
+  The reading must stay under 100 W, one way, while asked over 200 W, for 12
+  cycles spanning 22 s. At N=1 `compute()` gets this as `gave_nothing` and
+  needs it on top of its own freeze test. `None` (compute alone) keeps the
+  old law.
+- **The evidence restarts when the reading moves 50 W towards the ask**
+  (`REFUSED_PROGRESS_W`). A refusing battery reads flat (-3/-4 W live). Live
+  readings wander by under 25 W at rest. A first-order lag crossing the band
+  gains 50 W in at most 0.4 tau, so it cannot fill 22 s unless tau > 54 s.
+  This also covers B, whose reading is 100 W below its power.
+
+## Bounds and worst-case catch
+
+| fault | before | after | budget |
+|---|---|---|---|
+| register frozen, then asked to move | 0-35 s after the ask (often 1 s) | 35 s after the ask (+1 read) | SAFETY-37: 35 s, under the 75/85 s consumer holds |
+| register frozen at rest reading ~0 W | stale 1 s after the ask | refused or stale, 0 W within 23-35 s | the same |
+| refusing battery, 1 s meter, N=1 | 11-16 s | 22-28 s | SAFETY-73's 22 s span (+ one 10 s publish) |
+| refusing battery, 2 s meter | 22-28 s | 22-28 s | unchanged |
+| refusing battery, 5 s meter | N=1 35-41 s, N=2 41-55 s | N=1 40-45 s, N=2 50-55 s | 12 cycles = 55-60 s |
+
+Rig: `test_safety94.py` part 3. A release after SAFETY-57 still exposes
+the held number for one 35 s window of asking, so 35 < 75 < 85 still holds.
+
+## Before -> after
+
+- Live replay (part 1): 4 trips -> 0.
+- Refusing B (its -100 W idle reading): see SAFETY-97.
+- Rig, 10 s lag, N=1 and N=2, 1/2/5 s meters, two register shapes, 48 runs
+  (part 2): before 27 stale trips and 1 refusal, after 0 and 0.
+- Reversals, lag 10 and 20 s, 1 s meter (part 2): before N=1 6 stale / 3
+  refused, N=2 6 / 1; after 0 / 0.
+- 16-day loop capture (`test_freshness.py` part 8): 93 trips -> 59. Trips
+  answered within 20 s: 21 -> 1. Two of the removed trips were not quick:
+  a register held 351 s under a command hovering at the 250 W travel edge
+  (under 35 s of asking before it moved; survivor 2's shape), and a
+  refusing battery the gate had caught only on a passing ramp (SAFETY-52's
+  refusal covers it).
+
+## SAFETY-58 and SAFETY-74
+
+- **SAFETY-58 is fixed** by this change: its card asks for the clock to
+  start with the obligation and for the bound to be re-derived. Both are
+  done above. `test_freshness.py` survivor 5 is now graded as closed.
+- **SAFETY-74 is not fixed.** A battery capped at 300 W with a perfectly
+  flat reading, 5 s meter, house stepping: 50 trips/h at N=1 and 80 at N=2
+  before, 37 and 60 after. With +-1 W dither: 0. A flat reading under a
+  command that moved is exactly what the gate is for; telling "limited"
+  from "frozen" needs a second signal (the meter, or SoC).
+
+## Known gaps
+
+- ~~B's standby offset (-95 to -118 W at idle) puts a refusing B outside the
+  100 W band, so a refusing B never latched (review F1: at N=1 new, at N=2
+  as before).~~ **Fixed by SAFETY-97 in the same PR:** the band is centred
+  on each unit's learned idle reading. `SAFETY-97-idle-offset.md`.
+- A command that asks only part of the time (a fraction d) is caught after
+  35 s of asking, which is 35/d s of wall time (0/1500 W every 5 s: 69 s).
+  SAFETY-30's per-unit check restarts when its command stops opposing the
+  held reading, which a lapsing ask normally does, so 35 < 85 holds there.
+  SAFETY-31's circulation check (75 s) ignores the command, so its margin
+  holds only while d >= 0.47.
+- A register frozen under a command that stays near the 250 W travel edge
+  is caught late or not at all (survivor 2).
@@ -0,0 +1,69 @@
+# SAFETY-95 - a maintenance drain that ends hands back smoothly
+
+**Status: implemented 2026-10-06, for review.** Tests: `test_safety95.py`.
+
+**The defect** (SAFETY-93 review, O1). At N=2, when A's drain ended (A
+switched Off, say) with the house at 1200 W, B went 0 -> +1600 W in one
+cycle and exported. It is the mirror of SAFETY-93 on the drain end.
+
+**Cause.** During a drain the site target carries A's drain floor
+(SAFETY-78, `drain`, 2000 W) above what the house needs. At the end A's
+command drops (pin, Off, abort, stale link, refusal), but the loop slews
+from last cycle's target (2000 -> 1600) and only B is left to place it.
+Under a solar surplus B gave 1600 W into the export.
+
+**The rule** (`main.py`, `_reseed_drain_end()`, `_drain_grid_w()`, N>=2
+only). On the cycle a drain ends:
+
+1. The start point is what the others stood at plus A's new command (its
+   pin, else 0 W; a dropped battery is sent 0 W), as SAFETY-93 does.
+2. If the house needs more, the start is raised to the house's own point
+   (live batteries' readings + grid - target, as `_reseed_run_edge()`),
+   but never above last cycle's start. So the others cover the house at
+   once and never take over the drain's export.
+3. While A settles (SAFETY-96's window: within the deadband, at most
+   `PLANT_SETTLE_DOWN_S`), the loop's error is the house's point minus its
+   start, not the meter. The meter still shows A's tail and the others'
+   climb; chasing it sent B down and then up again.
+4. Then the loop moves one slew step a cycle.
+
+A drain ends when its battery leaves DRAIN, is not live, its claims
+contradict, or it will not give (SAFETY-73's limit outranks the pin
+without a contradiction, so the refusal is read from the battery; +1 only,
+as `_held_back()`). Today a contradiction on a drain only arises through
+a refusal; the clause stays because a contradiction sends A 0 W, which is
+an end (tested directly). The end is kept
+until the loop runs (a missed poll). A dropped draining battery is this
+rule's, not `_reseed_drop()`'s. Order in one cycle: drop/rejoin
+(SAFETY-96), charge end (SAFETY-93), drain end (this) last; each moves the
+start by its own battery, and the drain end's raise reads the start the
+others left.
+
+**Why not SAFETY-93's rule alone** (step 1, then slew). Measured on the
+same plant: at 1200 W the grid imports 849 W and B goes to -465 W
+(charging) while the loop chases A's tail; at N=3 and 4000 W it imports
+784 W where base imports 42 W, as the others give up A's share of the house.
+The house point keeps the grid at its aim; the cap at last cycle's start
+keeps it from exporting.
+
+**Before -> after** (`test_safety95.py`, 2500 W batteries, 10 s lag, 2 s
+meter; base = the same tree with the change taken out):
+
+| case | before | after |
+|---|---|---|
+| drain done / Off / timeout, N=2, 1200 W | B 0 -> 1600, +390 W commanded export, grid then +559 W | B 0 -> 1210, grid within 40 W of its aim |
+| the same, N=3, 1200 W | B, C 0 -> 800, grid +695 W | 0 -> 605, grid +39 W |
+| the same, solar surplus | B gives 1600 W into the surplus | B never gives; site moves 400 W a cycle |
+| refusal, N=3, 1200 W | B, C step 1020 W, +2000 W commanded export | step 20 W, +70 W |
+| N=3, 4000 W | others take A's share at once | the same (grid +1 W, base +42 W) |
+| abort (site zeroed by the operator) | climbs from 0, grid +669 W | climbs from 0, grid +16 W |
+| stale link (board watchdog 25 s) | | as base, but N=3 4000 W: grid +676 W (base +786) |
+| N=1, every drain end | | byte-identical |
+
+`tools/opt11_identity.py` n2_maint moved on purpose (A's drain refused at
+1655 s; B stays at the house's 1420 W instead of 2500 W). Re-pinned in
+`test_modes.py`. The other 45 digests are byte-identical.
+
+**Not changed.** The peak guard's floor still binds (arbiter, after the
+loop). Held batteries still give last; the idle clamp and the freeze test
+are as they were. A charge end (SAFETY-93) and a trade end are unchanged.
@@ -0,0 +1,59 @@
+# SAFETY-96 - a battery the loop cannot move does not freeze it
+
+**Status: implemented 2026-10-06, for review.** Tests: `test_safety96.py`.
+
+**The defect** (SAFETY-93 rig test). At N=2 the saturation freeze compares
+the site target with the site sum of the readings. After A's link went
+stale, A was out of the split but its reading (-2000 W, still charging) was
+in the sum: "saturation freeze (800 W vs -1903 W)", B held at 1200 W for
+~236 cycles until the circulation trip. After a charge timeout or Off at
+6000 W the loop froze ~14 s at 800 W while A came out of its charge. At a
+drop, B also took A's whole share in one step.
+
+**The rule** (`main.py`, `_held_out_w()`, `_reseed_drop()`, N>=2 only).
+A battery is held out of the freeze test, counted at its command instead of
+its reading, while:
+
+- it is out of the split (writes refused for `LINK_STALE_S`);
+- its last write was refused (its board may have gone to 0 W on its own
+  watchdog);
+- it settles after a step the loop did not make: a charge end (SAFETY-93:
+  HOLD, timeout, Off, refusal, stale link) or a rejoin (then every battery,
+  as the split is made again). Settling ends when its reading is within the
+  deadband of its command, or after `PLANT_SETTLE_DOWN_S` (23 s, the
+  measured plant settle).
+
+Its real power is not lost and not counted twice: the meter sees it, and
+the loop follows the meter. Only the freeze stops reading it as the loop's.
+The freeze still fires on the other batteries' own lag and on unplaced
+watts.
+
+At a drop the battery's share leaves the loop's start point, so the others
+take over one slew step a cycle. At a rejoin it enters at its reading.
+
+**Not a drop.** A missing reading or a stale register stops the site
+(`inputs_ok`), as before. A refused battery (SAFETY-73) stays in the sum:
+it is asked ~0 W and reads ~0 W. A watchdog-stopped battery (SAFETY-02/30)
+is pinned at 0 W and stays in the sum. New: no refusal is learned on a
+battery whose writes are refused; its board going to 0 W is no refusal. Its
+count is kept, not reset, so a link that refuses 1 write in 3 does not hide
+a battery that really refuses (review).
+
+**Before -> after** (2 x 2500 W, 10 s lag, 2 s meter; freeze cycles not
+about the remaining battery's own lag):
+
+| case | before | after |
+|---|---|---|
+| A drops while giving, A holds 1200 W | 128, B steps 1210 W | 0, B stays |
+| A drops while charging, A holds -2000 W | 78 | 0 (circulation trip stays: 4 kW goes round) |
+| A drops while charging, board to 0 W | 5 | 0 |
+| A drops then comes back, A holds 1200 W | 46, grid +1.1 kW | 0, grid within 250 W |
+| charge timeout at 6000 W | 7, B held at 400 W | 0, B climbs |
+| A switched Off at 6000 W | 6, B held at 800 W | 0, B climbs |
+| N=1, N=2 with no drop | | byte-identical |
+
+**Not changed.** At a rejoin the allocator splits again at once (A 0 ->
+1205, B 2410 -> 1205 W); the site total does not step. A battery that keeps
+charging on its own after its link drops still trips the circulation check
+(it is real circulation). A trade end (`_reseed_run_edge`) still starts
+from the full site sum.
@@ -0,0 +1,118 @@
+# SAFETY-97 - "gives nothing" is graded against each battery's idle reading
+
+**Status: implemented 2026-10-04, folded into PR #171 (SAFETY-94), for
+review.** Owner decision 2026-10-04: the band's centre is clamped to
+-75 W (see Bounds). Tests: `test_safety97.py` (rig: `tools/safety94_rig.py`).
+Closes SAFETY-94 review finding F1.
+
+## The defect
+
+B's power reading (board B's `inverter_ac_power`, 0x0518) shows -95 to -118 W
+at idle: its standby draw (the GoodWe app shows 0 W). A's shows -2 to -4 W.
+Every "the battery gives nothing" test was `|reading| < 100 W`, so a refusing
+B sat on the band's edge and never latched:
+
+- N=2: never caught, before or after SAFETY-94.
+- N=1: the old one-instant check caught it in 17-105 s; SAFETY-94's shared
+  rule (12 cycles in the band in a row) never did (review probe, 1200 s).
+
+## Design
+
+- **Offset source: learned per unit** (`app/idle.py`, `Inverter.idle`). No
+  new option: a required one is a setup step every client gets wrong, and an
+  optional one is a second source to reconcile. An override can be added
+  later if a site needs one.
+- **When it learns:** control runs; the unit is not refused (unit or site),
+  stale or sign-tripped; its command has been within 50 W (`IDLE_ASK_W`) for
+  120 s (`IDLE_QUIET_S`, 6 lags of 20 s). A refusing battery is asked more
+  than 50 W, and while refused it does not learn, so its refusal cannot be
+  learned as idle. A capped battery under a big ask is not sampled either.
+- **How:** the first value is the mean of 120 s of samples; then it follows
+  drift with a 30 min time constant. A sample beyond 250 W (`IDLE_SAMPLE_W`)
+  is dropped (a register held at a giving value). The band is centred on
+  the value clamped to 75 W (`IDLE_MAX_W`; owner decision below).
+- **Restart:** saved per unit (`unit/<name>/idle_w`, on first learn and each
+  5 W move) and restored, clamped to 250 W. Without it a battery refusing from the
+  start is never quiet, so never learned, so never caught.
+- **Until learned the idle reading is 0 W**: the rule as it was.
+
+## Not chosen: the GoodWe LAN integration's DC battery power
+
+Both inverters also appear through HA's GoodWe integration (B:
+`sensor.kelder_dyness_battery_power`, 0 W at idle; found read-only on the
+live HA 2026-10-04). Pointing `batt_entity` at it removes B's offset by
+configuration, but:
+
+- the band must be safe without it: other installs may not have it;
+- it is polled over UDP on the inverter's Wi-Fi, a second channel that can
+  drop while the board keeps reading (HW-01 lost both once); a missing
+  reading stops the site;
+- SAFETY-37's 35 s bound is derived from the board's 10 s publish; the
+  integration's poll interval (believed 10 s, not checked here) and latency
+  are not measured;
+- DC power is not 0x0518, which SAFETY-30/31/42 were measured against.
+
+It stays an install choice to test on the rig, not a code change here. With
+it, the learned idle reading is simply ~0 W.
+
+## Where it applies
+
+Every test of "gives nothing / gives / takes" now uses `reading - idle`:
+
+| check | change |
+|---|---|
+| shared refusal evidence `_gave_nothing` (N=1 and N>=2) | centred |
+| N=1 engage and end in `compute()` (`idle_w`, the site sum) | centred |
+| N=1 end in `_refusal_update` | centred |
+| N>1 unit end (probe answered, takes the other way) | centred; uncentred, B's idle -100 W read as "takes 100 W" and ended a charge refusal at once |
+| stale-path refusal (`_refusal_from_stale`, N=1 and N>1) | centred |
+| SAFETY-42 "parked" (small ask, gives nothing) | centred |
+| SAFETY-37 stale gate | unchanged: it grades register changes against command travel, not a level |
+| SAFETY-57 release | unchanged: it reads the command only |
+| SAFETY-30 per-unit sign | unchanged: opposition needs both over 250 W; B's 100 W idle cannot make or hide one alone |
+| SAFETY-42 shortfall | unchanged: B reads ~100 W short at every power, which errs towards reporting (report only) |
+
+## Bounds: owner decision 2026-10-04 (review R1)
+
+Band: `|reading - centre| < 100 W`, centre = idle clamped to +-75 W.
+
+- **Why a clamp under the band.** A wrong idle reading (taught during a
+  rest while the reading shows something else, e.g. a grid top-up of a unit
+  held at 0 W, or restored onto a swapped inverter) more than about 100 W off
+  hid every refusal on that battery, at N=1 and N=2; with the first +-250 W
+  clamp the rig missed a refusing A whenever the error was 110-250 W. At
+  +-75 W the band always keeps 0 W +-25 W, so a battery reading about 0 W
+  while refusing is caught whatever was learned or restored, and a wrong idle
+  cannot refuse a healthy 0 W battery (its ask is over 200 W).
+- **The trade-off.** Options: keep +-250 W (covers idle readings to about
+  +-350 W, any 100 W mis-learn hides refusals); clamp to +-75 W (chosen);
+  "old band or centred band" (rejected: a correct B would need to give 200 W
+  to answer its 200 W probe).
+- **Cost.** A battery whose idle reading is beyond about +-170 W is centred
+  at most 75 W out, so its refusal falls outside the band: it behaves as in
+  0.14.0 (not caught by this rule). B (-95 to -118 W) reads 20-43 W from its
+  clamped centre. B is caught across -150..+90 W of error in its idle
+  reading; learned 110 W or more too high it is missed, as in 0.14.0 at N=2.
+- A frozen register is still caught by the stale gate at 35 s of asking.
+- Recovery from a wrong value needs quiet time: tau 30 min.
+
+## Catch times (rig, refusing from 200 s after a 400 s rest, +-4 W)
+
+| refusing | meter 1 s | 2 s | 5 s |
+|---|---|---|---|
+| A, N=1 | 28 s (before 28) | 28 (28) | 65 (65) |
+| A, N=2 | 28 (28) | 28 (28) | 110 (110) |
+| B, N=1 | 28 (never) | 28 (never) | 65 (never) |
+| B, N=2 | 24 (never) | 24 (never) | 60 (never) |
+
+A at N=2 on a 5 s meter is 110 s here because the rig's grid goes flat once
+A is cut, so the loop cycles on the 15 s floor; the same run on the PR before
+SAFETY-97 gives 110 s. B restored after a restart, refusing from the start:
+24 s; with nothing saved: never.
+
+## Before -> after
+
+- Healthy B with its offset, SAFETY-94's four scenarios, N=1 and N=2, 1/2/5 s
+  meters, both register shapes, idle learned or restored (96 runs): 0 stale,
+  0 refused. Reversals, lag 10/20 s, idle restored: 0.
+- Live replay (SAFETY-94 part 1): 0 trips (the gate is untouched).
@@ -0,0 +1,230 @@
+# TARIFF-07 — three plugins that never fetched a price, and the one mechanism they leave behind
+
+**Status: DECIDED 2026-09-13 — withdraw `engie_dynamic`,
+`totalenergies_dynamic` and `eneco_eddy`. Keep `PriceProduct.REALTIME` and the
+widening machinery. Refuse a retired id by name rather than aliasing it.**
+
+Filed with TARIFF-07. Follows [[TARIFF-08]], which found the same class of
+defect one layer down — a parser graded against its own guess — and left the
+question of these three open.
+
+---
+
+## 1. The endpoints, verified rather than taken on report
+
+The card said the three endpoints were dead. They were re-checked by hand on
+**2026-09-13** before anything was deleted, because "the endpoint is dead" is
+exactly the kind of claim this repository keeps finding to be second-hand:
+
+| id | endpoint | observed |
+|---|---|---|
+| `engie_dynamic` | `https://api.engie.be/dynamic/be` | **HTTP 404**, body `{"message":"no Route matched with those values","request_id":"..."}` — a Kong gateway with no route configured |
+| `totalenergies_dynamic` | `https://api.totalenergies.be/prices/dynamic` | **TLS failure**. The handshake completes and the server presents `CN=pge-apigee-dev.direct-energie.com`; `api.totalenergies.be` is not in the SAN list, so the connection is closed before any request is sent |
+| `eneco_eddy` | `https://api.eneco.be/eddy/prices` | **HTTP 404**, `content-length: 1`, `server: Microsoft-IIS/10.0` — an empty body from a live host that does not serve this path |
+
+All three failed. Had any one of them answered, this card would have stopped
+and asked, because an endpoint that answers changes the decision from
+"withdraw" to "fix the parser".
+
+## 2. Why this is not "unfinished", and why no replacement can be written
+
+An unfinished plugin has a right endpoint and a wrong parser. These have
+neither, and the reason is structural:
+
+* **ENGIE's dynamic price is `(B × eSpot_15) − A`, and `B` and `A` are
+  PER-CONTRACT.** They live behind the customer's klantenzone login. No
+  unauthenticated public URL can return *a given customer's* price, so the
+  endpoint this plugin wanted cannot exist for anybody to build.
+* **There is no regulator index to read the coefficients from.** CREG's
+  tariff-card pages 404; VREG was unreachable. Every coefficient found in
+  research came from a supplier's own PDF, which is a document, not a feed.
+* **"Eddy" is not an Eneco product at all.** Eneco's dynamic product is
+  **"Zon & Wind Dynamisch"**, and it is indexed to **Belpex/EPEX day-ahead** —
+  not to imbalance. The plugin was wrong about the product, the product type
+  and the URL simultaneously.
+
+So the three were not withdrawn for being broken. They were withdrawn for
+describing tariffs that no public endpoint can serve.
+
+## 3. What a site configured on one of these has actually been running
+
+⚠️ **This is the half that decides what the migration is.** §11.4 turns a
+failed fetch into a silent fall back: static profile, plan provisional, no
+arbitrage. That is the *correct* degradation, and it says nothing at all about
+the cause. Every fetch these three ever made raised `SourceUnavailable`.
+
+Therefore a site configured on one of them has been running on
+`static_profile` — **or on nothing at all, where no profile was set** — since
+the day the id was entered, and **nothing on its status page has ever differed
+from a working provider that simply never found a cheap hour**.
+
+The migration is therefore **not** "keep their prices working". There were no
+prices. It is *"tell them their prices never worked"*, which is why the answer
+is a refusal and not a fallback.
+
+### Why not a silent alias to `generic_dayahead`
+
+It is the friendlier-looking option and it is wrong. These published **retail**
+prices; `generic_dayahead` reads **wholesale**. Aliasing needs the site's own
+`B` and `A`, which §2 has just established nobody has. An alias would have to
+**invent the numbers a battery is priced against** — the same defect as a
+parser graded against its own guess, one layer further from anything that
+reports. The scalar `price_markup_eur_kwh` cannot stand in for `B` either: it
+is an addend, not a multiplier, and it is `float(0,1)` so it cannot even hold a
+negative `A`.
+
+## 4. ⚠️ The `config.yaml` schema is deliberately WIDER than the registry
+
+`price_provider` is a `list(off|…)` enum, and the Supervisor validates the
+options file against it **before the add-on starts**.
+
+So the obvious edit — delete the three ids from the enum along with the classes
+— has a consequence that runs exactly opposite to this card's purpose:
+
+```
+operator's config says  price_provider: eneco_eddy
+        |
+        +-- id NOT in the schema enum
+                |
+                +-- Supervisor rejects the options file
+                        |
+                        +-- add-on never starts
+                                |
+                                +-- validate.py never runs
+                                        |
+                                        +-- the named refusal is NEVER SEEN
+```
+
+The operator gets an opaque `expected one of ...` from a layer they did not
+configure, on **exactly the sites the withdrawal exists to inform**.
+
+**Decision: keep all three ids in the schema enum.** `PROVIDERS` shrinks to
+two; the enum stays at six. The cost is that the dropdown still offers three
+dead ids to a *new* operator — and that is the cheaper failure, because
+choosing one is refused at the next startup **by name**, with the endpoint, the
+observation and the alternative, which is strictly more than a schema
+rejection would say. Both translations label them withdrawn in the option
+description.
+
+`app/price.py`'s `RETIRED_PROVIDERS` is the list. `test_price.py` section 1
+asserts the schema offers exactly `PROVIDERS | RETIRED_PROVIDERS | {"off"}` —
+derived, not typed — and `register()` refuses to re-register a retired id, so
+the registry and the retired table cannot both claim one and the refusal cannot
+be taken away by an `@register` somebody adds back.
+
+## 5. ⚠️ `PriceProduct.REALTIME` and the widening path are KEPT with no shipped declarer
+
+`eneco_eddy` was the **sole** declarer of `PriceProduct.REALTIME`. Deleting it
+orphans:
+
+* `_WIDE = frozenset({PriceProduct.REALTIME})`
+* `Uncertainty.REALTIME_PRODUCT`
+* `WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT] = 2.5`
+
+**They stay.** The reasoning, stated here so the next reader finds intent
+rather than an apparent dead branch:
+
+1. A reviewer finding a mechanism with **zero callers** would reasonably delete
+   it. That is good instinct applied to a missing fact, and this file is the
+   fact.
+2. It is the **AC2 seam**. The whole point of `capabilities().product` is that
+   a new supplier is a new class and nothing else: declare `REALTIME`, get the
+   wide regime, edit no framework code. Deleting the enum member would mean the
+   first genuine imbalance product has to **rebuild** that seam — and rebuilding
+   it is precisely the "editing the optimiser to add a supplier" that AC2
+   forbids.
+3. It costs nothing. Two enum members and a dict entry.
+
+**⚠️ NO SHIPPED PLUGIN DECLARES `PriceProduct.REALTIME` UNTIL ONE DOES.** Both
+shipped plugins (`generic_dayahead`, `manual_csv`) are day-ahead. §9.2's row 2
+is unoccupied. That is not the same as it having no mechanism, and the
+difference is what this section exists to record.
+
+It is **pinned, not merely documented**. `test_price.py` section 5 asserts:
+
+* that **no shipped plugin** declares `REALTIME` — so if one ever does, the
+  check goes red and the right fix is to **edit this record**, not to delete
+  the seam;
+* that the widening still works **from a declaration alone** —
+  `volatility_regime`, `uncertainty_of` and `widen_factor` are graded on a
+  `ProviderCapabilities` the test file builds;
+* and section 10 registers `_NewSupplier`, a class defined **outside
+  `price.py`** that declares `REALTIME` and is asserted to land in the wide
+  regime. That class is now the only live declarer in the tree, which makes the
+  seam something this suite exercises end to end rather than a constant it
+  reads.
+
+## 6. What else went, and one thing that did not
+
+`_points_from_json()` went with the three. It read a `{"data": [{...}]}`
+row-per-point document that **no feed anybody here has ever reached
+publishes** — the shape was invented alongside these plugins, and the only
+bodies ever fed to it were fixtures written from the same guess. TARIFF-08
+found that loop on the response side for `generic_dayahead`; this is the rest
+of it. `needs_credentials` went too: the three were its only setters and
+nothing read it.
+
+The shape survives in **one** place and in one direction: `row_shape_body()` in
+`test_price.py`, feeding `generic_dayahead` so that section 9 grades a row
+document as a **failure** for it rather than a second dialect it might sniff.
+It is named for what it is.
+
+⚠️ **One check had to be rebuilt rather than deleted, and saying so matters.**
+`test_price.py` section 4b proved that `code_leaks()`'s docstring strip is
+load-bearing by finding a shipped docstring that a raw text scan would
+false-positive on. The docstring that did that was **`engie_dynamic`'s** — it
+spelled `price_markup_eur_kwh` in full. With it gone, no shipped docstring
+spells a full framework key, so the check would have **passed on a tree with
+the strip deleted**: a check that had quietly stopped being one, which is the
+third failure mode in `MUTATION.md`. The stimulus is now constructed in the
+test file (`_DocumentedPlugin`), and the shipped set is asserted clean
+separately.
+
+## 7. Mutations driven
+
+Every check added or rebuilt here was driven red. Harness:
+`/home/homelab/.cache/t07-mut/`, which rebuilds the tree from the worktree and
+purges `__pycache__` per `MUTATION.md`'s rule.
+
+| | mutation | Δ | red on |
+|---|---|---|---|
+| M1 | delete the retired branch from `_price_problems()` | −2785 B | 7 checks in `test_price.py` |
+| M2 | move the retired branch **after** the unknown-id branch | **+0 B** | the same 7 |
+| M3 | make `been_running` constant (drop the empty-`static_profile` case) | −212 B | 2 |
+| M4 | drop the "WHAT TO DO" half of the refusal | −874 B | 1 |
+| M5 | `RETIRED_PROVIDERS = {}` | −1099 B | 5, then a traceback |
+| M6 | drop the three ids from `config.yaml`'s enum — §4's trap | −47 B | 2 |
+| M7 | delete `register()`'s retired guard | −1101 B | 2, then a traceback |
+| M8 | `_WIDE = frozenset()` | −23 B | 3 + 4 across two suites |
+| M9 | `WIDEN_FACTOR[REALTIME_PRODUCT]` 2.5 → 1.5 | **+0 B** | 1 + 1 |
+
+⚠️ **M2 and M9 have a byte delta of zero**, which `MUTATION.md` names as the
+risky case. The harness rebuilds the tree from source on every run and purges
+`__pycache__`, so there is no inherited cache to read; and stale bytecode
+manufactures **survivors**, never reds, so a red from a `+0 B` mutation is not
+at risk from that defect. M2's grep confirmed the branch had moved on disk.
+
+⚠️ **M5 and M7's red counts are LOWER BOUNDS.** Both runs ended in a traceback
+with checks after it ungraded — FCST-06's rule: read the output, not the count.
+M7's traceback is itself informative: with the guard gone the re-registration
+**succeeds**, `PROVIDERS` is polluted with a class that has no fixture, and the
+suite dies downstream. That is the failure the guard prevents, arriving loudly.
+
+## 8. What this card did not do
+
+* **It did not pick a version number.** The change is backward-incompatible — a
+  config legal on the current version is refused on the next — and the
+  CHANGELOG says so prominently, in the shape PKG-07 established for `slew_w`.
+  Which number it belongs to depends on whether the current image has already
+  been built and pulled, which is a fact about the live box that this branch
+  cannot observe. Whoever deploys decides.
+* **It did not implement the formula provider.** `B × spot + A` with per-site
+  coefficients is the real answer for a Belgian dynamic customer and is a
+  separate card. `DOCS.md` references it as planned and is explicit about what
+  `generic_dayahead` can and cannot express in the meantime — in particular
+  that it cannot represent a negative offset, and that
+  `price_markup_eur_kwh: float(0,1)` could not hold one anyway.
+* **It did not rewrite released CHANGELOG history.** The two historical entries
+  that called `eneco_eddy` an imbalance product are annotated in place with a
+  correction naming this card, rather than silently edited. The record of what
+  the project believed is part of the record.
@@ -0,0 +1,141 @@
+# TARIFF-09 — asking the feed for the horizon, and what `price_feed_url` means
+
+Two decisions. The first had no defensible alternative once it was measured;
+the second did, and the alternative is argued below rather than dismissed.
+
+---
+
+## 0. The measurement this card exists for
+
+`generic_dayahead.fetch()` accepted `since` and `until` and requested the bare
+`https://api.energy-charts.info/price?bzn=BE`. That URL names no range, and the
+feed answers **one Brussels day**.
+
+Measured on the merged tree (`4257e38`) at 2026-09-10 09:00 CEST, 48 h horizon,
+live feed, yesterday seeded through the shipped read path:
+
+```
+60 firm points (15 whole hours) + 33 carried hours of 48 requested
+carried: 24 h on 2026-09-11, 9 h on 2026-09-12
+arbitrage(0.10): allowed, spread 0.4645, buy 11:45 and sell 19:45 -- BOTH on 2026-09-10
+firm local days = [2026-09-10]
+```
+
+Everything past today was carry-forward, flagged provisional, and §8.3 drops
+provisional hours from the trade set. **The optimiser never saw tomorrow as
+firm, at any hour.** The ceiling was structural rather than incidental: with a
+one-day window, at hour *H* of the local day a 48 h horizon is at most
+**24−H hours firm and 24+H carried** — 15/33 at 09:00, and **1/47 at 23:00**,
+where the remaining firm spread (0.0464 EUR/kWh) no longer even clears the
+default 0.10 round-trip threshold and arbitrage is refused outright.
+
+That is not what FCST-04's fill was built for. FCST-04 covers the
+pre-publication window until the ~13:00–14:00 CET auction, after which a
+healthy feed hands over tomorrow in full.
+
+**The data exists and the endpoint serves it.** Verified 2026-09-10T07:45:49Z:
+`?bzn=BE&start=2026-09-09&end=2026-09-10` returns **192 quarter-hours across
+two local days**, committed unmodified as
+`scenarios/energy-charts-be-price-2026-09-09_2026-09-10-twoday.json`. The
+plugin simply never asked.
+
+After the change, same code path, same window, a feed serving both days:
+**39 firm hours and 9 carried**, firm across **two** Brussels days, and the
+permitted cycle buys on one day and sells on the other. Graded in
+`test_price_history.py` section 1c against both feed states.
+
+---
+
+## 1. The range is derived on the **Brussels** calendar, from `since`/`until`
+
+`since` and `until` are **instants**; the API takes **dates**. Those are not
+the same question, and the conversion is where the day gets lost.
+
+`brussels_date_range()` returns two inclusive `date`s:
+
+* the first is `brussels(since).date()`. **Not `since.date()`, and not the UTC
+  date.** 22:30 UTC in summer is already tomorrow in Belgium, so a UTC-derived
+  start asks for the day the controller has just left and drops the day it is
+  standing in — for the last one or two hours of *every* day. This is
+  `price_history._bdate()`'s lesson one layer up, with a worse consequence:
+  `_bdate()` misfiles an hour, this never fetches it.
+* the last is `brussels(until).date()`, **stepped back a day when `until`
+  falls exactly on local midnight**, because `until` is exclusive and that
+  instant is the first tick of a day nobody asked for. Without it every
+  whole-hour horizon requests one extra day — harmless on this feed, but it
+  makes the request a claim the caller never made.
+* an empty or inverted window collapses to a single day rather than producing
+  a backwards range, which no feed has a defined answer for.
+
+Both ends are graded, and both are driven red by mutation — including the two
+that swap `brussels()` for the UTC date (`test_price.py` section 2c).
+
+---
+
+## 2. `price_feed_url` is the **exact URL**, used as given. The plugin appends
+   nothing.
+
+The alternative — merge our `start`/`end` into whatever query string the
+operator supplied — was considered and rejected. Three reasons, in the order
+they decided it:
+
+1. **`start`/`end` are energy-charts' spelling, and this provider declares a
+   second host.** `generic_dayahead.capabilities().egress_hosts` is
+   `("api.energy-charts.info", "web-api.tp.entsoe.eu")`. That second host's
+   day-ahead date parameters have not been verified by this card and are not
+   guessed at here — but they are not `start`/`end`. So an override to the
+   *other declared host* — a case the declaration itself anticipates — is
+   exactly where merging appends two parameters that host ignores, producing
+   the short horizon anyway, with a URL nobody typed as the receipt.
+2. **Merging means re-serialising a URL somebody else wrote.** Parsing and
+   rebuilding reorders parameters, collapses duplicates and re-escapes values.
+   "Override the feed" is what the option already says it means, and an
+   override that is silently rewritten is not one.
+3. **Blind appending is not on the table at all.** `dated_feed_url()` refuses
+   to add a query string to a base that already has one, so
+   `?bzn=BE?bzn=BE&start=…` cannot be produced by this module even by a later
+   edit that folds the parameters back into the constant.
+
+⚠️ **The cost is real and it is therefore NOT a doc footnote.** An overriding
+operator gets exactly the short horizon this card exists to fix. So the plugin
+emits a `WARNING` on the shipped `goodwe.price` logger at **fetch time**, naming
+the consequence — one Brussels day, the rest carried and flagged, §8.3 dropping
+them from the trade set — and naming the `start..end` it *would* have asked
+for. §11.4 is what makes a price defect quiet; an operator who has taken the
+short horizon has to be able to find out from the log that they did.
+
+The warning is graded, with a control that the default path stays silent, and
+a mutation that downgrades it to `debug()` takes that check red.
+
+**Fetch time rather than startup**, because that is where the URL actually in
+use is known. The trade-off is one line per refresh (the tariff task, not the
+30 s control tick). If the status page ever grows a price-source row, this is
+the sentence it should carry.
+
+---
+
+## 3. The plugin contract: `fetch(self, opts, since, until, transport)`
+
+The signature promises every plugin the range, and until this card **none of
+the four networked plugins used it**. The obvious follow-up is to enforce the
+promise. It is **not** enforced, and the reason is TARIFF-08's:
+
+Three of the five shipped plugins point at endpoints nobody has ever verified
+(TARIFF-07 is the open decision on withdrawing them). A rule obliging them to
+pass a date range would be satisfied by an **invented parameter name** — which
+is the parser-graded-against-its-own-guess defect moved from the response to
+the request, and it would ship looking like a guarantee.
+
+What exists instead is a **roster pin** in `test_price.py` section 2c: which
+plugins reference their `since`/`until` is asserted as a literal, derived from
+the registry and the AST. A sixth supplier, or a change to any of the three,
+has to edit that line and make the decision rather than inherit the silence.
+It is named as a source-shape pin, not as evidence that any feed parses;
+`generic_dayahead`'s behaviour is graded separately by the URL it really
+requests.
+
+**Recommendation for whoever picks up TARIFF-07:** enforce it at the moment
+those three endpoints are either verified or withdrawn, not before. If they are
+withdrawn, `generic_dayahead` and `manual_csv` are the whole roster and the
+rule is one line — `manual_csv` reads a whole file and is windowed downstream,
+so it would be the single documented exemption.
@@ -0,0 +1,277 @@
+# TARIFF-10 — fetching a price and trading on one are two decisions
+
+**Status: DECIDED 2026-09-12 — Option A. If a price provider is configured,
+prices are fetched. Trading stays a separate switch (`arbitrage_enabled`), and
+this card moves nothing that moves energy.**
+
+Filed with TARIFF-10. Follows [[TARIFF-09]] and [[FCST-04]]; §4 settles the
+limitation FCST-04 recorded and did not decide.
+
+---
+
+## 1. The defect, and why it was invisible
+
+`app/main.py`'s `amain()` read:
+
+```
+if arbitrage.enabled(opts):
+    tasks.append(asyncio.create_task(controller.run_tariff_refresh()))
+```
+
+`run_tariff_refresh` is the **only** caller of `resolve_tariff()`, which is the
+**only** caller of `price_history.carry()`. `arbitrage_enabled` ships `false`.
+
+So on a shipped install with a provider configured:
+
+* no HTTPS request was ever made to the feed;
+* no plan was ever resolved, so `self.tariff_plan` stayed `None` forever;
+* `/data/price_history.json` was never created;
+* the *Price history* status row read `empty` for the life of the install;
+* TARIFF-09's short-horizon warning could not fire, because it is logged on a
+  fetch and there was no fetch.
+
+Measured, not inferred — a 40 h soak, two instances, one feed:
+
+| | shipped default + provider | same, arbitrage armed |
+|---|---|---|
+| feed requests | **0** | fetching |
+| `/data/price_history.json` | `present: false`, **802/802 samples** | written |
+| resolved plan | none | 132 points |
+
+⚠️ **AND FOUR SURFACES ALREADY DESCRIBED THE FIXED BEHAVIOUR.** `DOCS.md`
+§*Energy price providers*: *"With `arbitrage_enabled: false`, which is the
+shipped default, turning a provider on still fetches, validates and publishes
+prices and changes no charging decision."* `config.yaml` and both translations
+said the same, and additionally carried a claim that had gone stale in the other
+direction — *"nothing consumes the price series yet"*, untrue since OPT-04
+shipped the consumer. The code was the only surface that disagreed with all of
+them, and no check compared the two.
+
+The dating is worth being exact about, because it says this was never a
+regression. `git log -S` puts the refresh task, its `arbitrage.enabled()` guard
+**and** the DOCS sentence in the *same commit* — OPT-04, `bdd7f18`;
+`config.yaml`'s version of the claim goes back further, to TARIFF-02,
+`852fc7c`. The prose and the code disagreed from the moment both existed.
+
+## 2. Why a check on the `if` would not have caught it
+
+The `if` was exactly what somebody meant to write, and its comment argued for
+it honestly:
+
+> ⚠️ STARTED ONLY WHEN ARBITRAGE IS ARMED. Nothing else in the add-on reads the
+> resolved plan … so on a default install this task would be network traffic in
+> aid of an attribute nobody reads.
+
+That was true when OPT-04 wrote it and stopped being true when FCST-04 gave the
+plan a *store* and a *status row*. A pin on the expression would have gone red
+on the fix and green on the defect. What was wrong is the **set of
+configurations from which a fetch is reachable**, so that is what
+`test_price.py` section 13 grades:
+
+1. the guards on every `asyncio.create_task` in `amain()` are **evaluated**
+   against real option dicts — whatever the guard is spelled as;
+2. the call graph under `app/` is walked to see whether the coroutines those
+   guards start can arrive at `resolve_tariff()` — wherever it has moved to;
+3. and then the fetch is **driven**, with a counting transport, a real
+   `Controller` and a real store path, because a reachability graph is an
+   argument and a counted request is an observation.
+
+⚠️ **Step 3 grades the gate only because it starts the task the way `amain()`
+would.** The driver asks `_fetchers(opts)` — the evaluated guard — before it
+calls the coroutine. Measured: with the shipped defect restored **and** that one
+line defeated (`if False and "run_tariff_refresh" not in names:`), the four
+driven rows go **green** while only the structural rows stay red. Without it
+they are decoration, which is MUTATION.md's habit 4 in a harness.
+
+What the instrument **cannot** see is printed on every run: a coroutine started
+by anything but `create_task`; a guard that is not an enclosing `if` in
+`amain()`; anything outside `app/`; and — because the graph is keyed by **name**
+— two same-named functions as one node, which makes every *reachable* answer an
+**upper** bound and every *not reachable* answer the strong one.
+
+## 3. The gate, and why it is an `or`
+
+```
+def tariff_refresh_wanted(opts: dict) -> bool:
+    return provider_configured(opts) or arbitrage.enabled(opts)
+```
+
+The first term is what this card adds. **The second term is the old gate, kept
+verbatim, and it is not there for symmetry.**
+
+`price_provider: off` + a `static_profile` + `arbitrage_enabled: true` is a
+configuration `validate.py` explicitly **accepts** (rule 7 refuses only the
+no-prices-at-all case), and it **trades**. Measured on this branch:
+
+```
+opts: price_provider off, arbitrage_enabled true,
+      cycle_cost_threshold_eur 0.05,
+      static_profile 0.20 night / 0.284 day
+plan : static_profile from static_profile, 48 h, 48 points
+WITH  the plan -> ARBITRAGE_CHARGE -5000.0 W
+                  "cheapest firm hour at 0.2000 EUR/kWh, 0.0840 below the
+                   dearest and clear of the 0.0750 this cycle had to cover"
+WITHOUT the plan -> None  "no tariff plan has been resolved yet"
+```
+
+Gating the refresh on the provider **alone** — which is the literal reading of
+the ticket's second acceptance criterion — would leave that site's
+`tariff_plan` at `None` forever and answer *"no tariff plan has been resolved
+yet"* on every cycle. That is a strategy the UI says is running and that cannot
+fire: the exact state `validate.py`'s OPT-04 rules exist to refuse, arrived at
+from inside the code instead of from the configuration.
+
+So the gate is a **strict widening**: every configuration that started the task
+before still starts it, and `test_price.py` grades that as its own row rather
+than leaving it to prose.
+
+⚠️ **The AC's stated harm is still fully met, and it is worth being exact about
+this rather than quietly declaring victory.** The criterion reads *"with
+`price_provider: off`: no fetch task at all, whatever `arbitrage_enabled` says
+— an operator with no provider must not acquire a periodic HTTPS call."* The
+letter of it is not met in one configuration (provider off, trading armed),
+because that configuration keeps the task it already had. The harm it names is:
+
+* with `price_provider` off, `resolve_tariff()` returns `static_plan()` — pure
+  arithmetic, **no socket**. Driven and counted: **0 requests**.
+* the true shipped default — no provider, no trading — starts **no task at
+  all**.
+
+Nobody *acquires* a periodic HTTPS call from this card, and the only thing that
+decides whether a request leaves the machine is `price_provider`. **If the
+owner wants the literal reading instead, it is a one-token change** (drop the
+`or` term) **and it costs the site in the measurement above its trading.** That
+is the trade, stated rather than chosen silently.
+
+## 4. `TariffPlan.cheap_now()` — available, and deliberately NOT consumed
+
+**Decision: do not wire it in this card. `self.cheap` stays on
+`static_status()`.**
+
+FCST-04 recorded that `cheap_now()` has no production caller on the provider
+plan: `main.read_inputs()` assigns `self.cheap, self.tariff_words =
+static_status(o, now)`, which builds its **own** static plan and calls
+`cheap_now()` on that. Under Option A a provider-backed plan now exists on every
+configured site, so the limitation stops being structural and becomes a choice.
+
+**It is not cosmetic, and that is the whole reason for the decision.**
+`self.cheap` is read in `cycle()` by the maintenance cycle's cheap-window grid
+top-up — the add-on's one shiftable load, and the one place a *price* reaches
+something that **moves energy** on an install that has not armed trading.
+
+⚠️ **And the direction it would move is not "a slightly different window".**
+`static_status()` returns `(False, "no static profile")` whenever
+`static_profile` is empty, so today a provider-only site — a plausible shape
+for a dynamic-tariff install, and the shape this card makes work — has
+`self.cheap = False` on **every** cycle and never forces a paid grid top-up at
+all. Wiring `cheap_now()` would take that from *never* to *sometimes*. That is
+a strictly larger behaviour change than this card's headline, and it belongs to
+whoever owns the maintenance cycle rather than to the ticket that made it
+reachable.
+
+Three further reasons, in the order they would bite:
+
+1. **Two sources, one attribute, and the loser is silent.** `validate.py`
+   already refuses `static_profile` alongside the Home Assistant price
+   entities *because* `read_inputs()` picks one and the other disappears. A
+   provider plan would be a third writer of the same attribute with no rule
+   saying which wins.
+2. **The freshness question is not answered for this consumer.** The plan
+   retires after `TARIFF_MAX_AGE_S` and `fresh_tariff_plan()` returns `None`.
+   Arbitrage has an answer for that (refuse). The maintenance top-up has none:
+   "the plan expired" would have to mean *not cheap*, and *not cheap* on this
+   path means **wait for sun**, which is a real decision nobody has taken.
+3. **The comparison basis changes, and so does the answer on a bad feed.**
+   `cheap_now()` is strictly-below-the-mean-of-the-**firm**-hours, and it is
+   `False` when THIS hour is provisional or is not in the series at all
+   (FCST-03's rule: this hour decides, not the whole plan). So a feed that
+   published nothing, or an hour the §8.3 fill could not cover, reads *not
+   cheap* where a `static_profile` reads whatever the clock says. Defensible
+   either way — and it is a change to the shipped maintenance cycle that needs
+   its own measurement rather than a side effect of this one.
+
+**What adopting it would take**, so the next card does not start from scratch:
+
+* a rule for which source wins when both a provider plan and a
+  `static_profile` are configured, enforced in `validate.py` the way the
+  entity/profile conflict already is;
+* a decision on what an **expired** or **absent** plan means for the grid
+  top-up, stated as a default rather than left to `None`;
+* `read_inputs()` splitting `self.cheap` from `self.tariff_words`, which are
+  currently one assignment from one function;
+* a check that the maintenance top-up actually fires and does not fire on the
+  provider plan — driven through `cycle()`, not asserted on the attribute;
+* and the *Tariff* status row, which FCST-04 pinned as a **pair** with
+  `DOCS.md` in `test_price_history.py` §9: it does not report the provider
+  plan, DOCS does not claim it does, and moving one without the other is
+  already red.
+
+## 5. The *Arbitrage* status row, re-read and left alone
+
+`main.status_payload()` renders `("Arbitrage", "off (arbitrage_enabled)" if
+self.arb is None else self.arb.explain())`. `self.arb` is assigned only inside
+`if arbitrage.enabled(self.o):` and `arbitrage.decide()` never returns `None`,
+so `self.arb is None` **iff** the option is off. The string still names the
+option that is actually off, and under Option A it gains a job it did not have:
+on a site with a provider configured it is the row that tells an operator the
+prices arriving on the *Price history* row above are moving nothing. Unchanged,
+with a note at the call site saying it was checked.
+
+## 6. What this card did not do
+
+* It did not touch `run_tariff_refresh()`'s body (TARIFF-12 is there).
+* It did not change `cycle()`'s `if arbitrage.enabled(self.o):`, the sizing,
+  the thresholds, the SoC bounds or the peak interlock.
+* It did not wire the provider plan into the *Tariff* status row or into
+  `self.cheap` — §4.
+* It did not pick a version number (PKG-06).
+
+## 7. Mutation ledger
+
+Every mutation applied to a **fresh `cp -a`** of the clean worktree rather than
+reverted (habit 18: there is no revert to verify and no shared scratch path),
+`__pycache__` purged, tree mounted `:ro`, run under `python3 -B`.
+
+| id | mutation | Δ bytes | result |
+|---|---|---|---|
+| M1 | the shipped defect: gate back to `arbitrage.enabled(opts)` | **-4 B** | **RED**, 7 named checks |
+| M2 | drop the `or arbitrage.enabled(opts)` term | -27 B | **RED**, 2 named checks (strict-widening + the static-profile row) |
+| M3 | `tariff_refresh_wanted` -> always `True` | +8 B | **RED**, the AC2 reachability row |
+| M4 | `provider_configured`: `"off"` counts as configured | -6 B | **RED**, the AC2 reachability row |
+| M5 | `cycle()`'s trading gate -> `if True or arbitrage.enabled(self.o)` | +8 B | **RED**, both AC3 rows (`-5000 W` with trading off) |
+| M6 | instrument: `_reaches()` always `True` | **+0 B** | **RED**, 4 checks incl. its own calibration row |
+| M7 | instrument: `_task_sites()` returns `[]` | **+0 B** | **RED**, 10 checks incl. "it found 0 sites" |
+| M8 | fixture: 5 minutes of telegrams instead of a whole quarter | **+0 B** | **RED**, the peak-guard precondition and both armed rows |
+| M9 | M1 **plus** the harness's guard-driven start defeated | -4 B | the four DRIVEN rows go **GREEN** — see §2 |
+| M10 | `provider_id()` drops `.strip()` | -8 B | **survivor**, then CLOSED — see below |
+| M11 | `provider_configured()` -> `return True` | -32 B | **RED**, 4 checks |
+| M12 | DOCS.md's sentence reverted to the old, vaguer claim | +0 B (docs) | **RED**, the AC4 pairing row (`fetches = True, DOCS says = False`) |
+| M13 | the Dutch translation left behind while English moved | +0 B (docs) | **RED**, the both-languages row |
+
+⚠️ **M10 was a real survivor and is recorded as one.** Dropping `.strip()` left
+`test_price.py`, `test_price_history.py`, `test_static_tariff.py` and
+`test_validate.py` all green: nothing in the repository fed a `price_provider`
+with surrounding whitespace, and the `.strip()` predates this card — it was
+carried into `provider_id()` from the three call sites it replaced. The
+Supervisor's `list(off|…)` schema cannot produce `"  off  "`, but
+`validate_startup_config()` is also `sim/inject.py`'s entry point and takes any
+dict at all. Closed in the same commit by the padded-id pair in section 13;
+re-run as **M10b**, red on two named checks.
+
+⚠️ **M8 is the fixture defect this card walked into and then fenced.** The
+first draft fed five minutes of telegrams. Whether that **covers** the current
+billing quarter depends on where the wall clock sits inside it, so the peak
+guard was blind and engaged on some runs and not others — and `decide()` refuses
+outright while the guard is holding (§9.1 over §10.1). On those runs the armed
+baseline did not trade, and "trading off never trades" would have been graded
+on a fixture in which nothing could trade either way. It is now 900 s of
+telegrams, and the guard's clear state is a **check** rather than an assumption.
+
+## 8. What is still open
+
+* The literal reading of AC2 (§3). One token, and it costs a measured trading
+  configuration its plan. **Owner's call.**
+* `cheap_now()` (§4). Owner's call, with the adoption list above.
+* The *Tariff* status row still shows the static-profile sentence on a
+  provider-backed site; the provider plan's own line goes to the log. Pinned as
+  a pair with `DOCS.md` by FCST-04 and untouched here.
@@ -0,0 +1,252 @@
+# TARIFF-12 — a returned degradation is not a refresh
+
+Three decisions. The first is what the ticket put up for judgement; the second
+and third are what fall out of it and would otherwise be decided by accident.
+
+---
+
+## 0. What was actually wrong, stated once
+
+`run_tariff_refresh()`'s docstring:
+
+> ⚠️ **AND A FAILURE DOES NOT CLEAR THE PLAN.** … Zeroing the plan here would
+> replace a coarse tariff with no tariff, which is the opposite of what §11.4
+> asks for.
+
+The guarantee was real. The condition it was enforced on was not:
+
+```python
+try:
+    plan = await resolve_tariff(...)
+    self.tariff_plan, self.tariff_at = plan, now     # unconditional
+except Exception as err:
+    _LOG.warning("tariff refresh failed (%s); keeping the plan ...")
+```
+
+`load_prices()` says in its own docstring that it **"RETURNS, NEVER RAISES, for
+every failure a site can actually have"**, because a degradation arriving as a
+traceback into the planning tick would stop the controller regulating over an
+expired certificate. So a supplier outage — the case the docstring names first —
+is a **return**: the `try` succeeds, `_degrade()` hands back a §11.4 plan, and
+the good plan is overwritten. The `except` is reachable only by something
+nobody expected, and nothing in the shipped path produces it.
+
+This is the fourth card in one family: FCST-04's M4 (`not ok` only), FCST-05's
+HIGH (`(JSONDecodeError, OSError)` only), FCST-06 (`not self.ok` only), and now
+`except Exception` only, for a path that never raises. **A guarantee enforced on
+the condition someone thought of, rather than the condition that occurs.**
+
+Reproduced before the fix, driving the shipped chain with nothing stubbed but
+the socket — 48 h horizon, `static_profile` empty, one good fetch then a
+`ClientConnectorError` 1800 s later, `TARIFF_MAX_AGE_S` = 5400 s:
+
+```
+after a good fetch      origin='provider'  n_points=48  'dynamic_dayahead from generic_dayahead, 48 h'
+after the failed fetch  origin='none'      n_points=0   'no tariff - generic_dayahead: ClientConnectorError: ...'
+tariff_at moved: True
+```
+
+and after it:
+
+```
+after the failed fetch  origin='provider'  n_points=48  'dynamic_dayahead from generic_dayahead, 48 h'
+tariff_at moved: False
+```
+
+---
+
+## 1. The question is asked ONCE, after the attempt, from the evidence that exists
+
+FCST-06's answer, one module over, and for the same reason: **the enumeration
+of failure conditions cannot be completed.** There is no pre-check that a feed
+will answer which is not itself a guess, and adding one would be a second
+symptom test beside the `except`. So the predicate is an **outcome**, read off
+the object the attempt produced:
+
+```python
+standing = self.fresh_tariff_plan(now)
+keep = (not plan.from_feed
+        and standing is not None and standing.from_feed)
+```
+
+Two facts, both of which exist by the time the question is asked:
+
+* **`plan.from_feed`** — did *this* resolution observe the configured provider?
+  `TariffPlan.origin` already names the four ways a plan is obtained; this
+  collapses them to the one question a caller holding a previous plan has to
+  ask. It lives on `TariffPlan` rather than as an `origin == "provider"` at the
+  call site for `fresh_tariff_plan()`'s own stated reason — *a check has to be
+  able to assert on the shipped expression rather than on a transcription that
+  drifts* — and because `origin`'s vocabulary belongs to `static_tariff.py`.
+* **`fresh_tariff_plan(now)`** — is a standing observation still current. It
+  already existed, it is already the one place the age is judged, and it is
+  **reused, not transcribed**. `test_arbitrage.py` 8b pins that reuse on the
+  AST; a copy of the comparison behaves identically until the day the two
+  drift, which is a claim about the code's shape, so a shape check is what
+  grades it (FCST-06's precedent for the one source check among driven ones).
+
+### What was NOT done
+
+* **Not `except Exception` widened, or a second `if` beside it.** That is the
+  defect's own shape — a place where the rule is spelt twice, so a fifth cause
+  needs a fifth branch. The `except` stays, relabelled *"not the outage path"*,
+  keeps the plan on the same terms, and is now honestly the
+  something-nobody-expected branch.
+* **Not the persisted price store as a cache.** Out of scope by the product
+  owner's call, and it is the right call: FCST-03 exists precisely to stop
+  stale prices being acted on, and "recent" is not "current". Keeping the last
+  **fetched** plan until it ages out is a different promise from serving the
+  store, and that one needs its own ticket.
+* **Not a `no_data`-only guard.** `not plan.has_prices` is the tempting
+  spelling and it is wrong — see decision 2. It leaves the §11.4 fallback free
+  to replace a fresh observation, and it is a 1-byte edit from the shipped
+  line, which is why it is in the mutation table rather than in a comment.
+
+---
+
+## 2. A §11.4 static fallback does NOT replace a fresh provider plan
+
+The ticket asked this directly, because the fallback is *not* nothing: it is
+the operator's own configured profile, with real prices, for the requested
+window. The answer is still no, and the reason is not that it is worse data —
+it is that **nothing may be acted on it, and it is no more current.**
+
+* Every point `_degrade()` builds carries `provisional=True`. So
+  `firm_points()` is empty, `arbitrage()` finds fewer than two firm hours and
+  refuses, and `cheap_now()` is False. Both of the two things `TariffPlan`
+  exposes for a consumer to act on are already off.
+* A day-ahead price for a given hour **does not change once published**. A plan
+  fetched 30 minutes ago is exactly as true about 19:00 as one fetched now; at
+  most `TARIFF_MAX_AGE_S` of its horizon has elapsed. The observation is not
+  stale in any sense the fallback is fresher than.
+
+So replacing the observation with the fallback trades a plan with firm hours
+for a plan with none, and buys no currency with it. The fallback takes over
+when the observation **retires** — which is exactly the row §11.4 describes,
+arrived at when there is no longer an observation to prefer.
+
+### And the rule is deliberately NOT symmetrical
+
+`standing.from_feed` is a term in its own right. A standing plan that is itself
+a degradation **is** replaced by the next degradation, and its timestamp moves.
+Without that term:
+
+* an outage on a static-profile site would freeze the operator's profile at the
+  window it was first generated for, and the guard would be *"never overwrite"*
+  wearing a bound's name;
+* and on a `price_provider: off` install — the shipped default — the plan would
+  flip between kept and re-derived every `TARIFF_MAX_AGE_S`, for no behavioural
+  gain, changing which reason the status page prints on a two-hour cycle.
+
+Each of the three terms is the only false one in some check in 8b, which is
+MUTATION.md habit 17's test for whether a suite can tell an `AND` from an `OR`.
+
+---
+
+## 3. `tariff_at` does not move on a kept plan
+
+The docstring's other half is that a plan must not *"freeze at its last value
+and look current forever"*. `tariff_at` is what makes that work: it is the
+moment of the fetch that produced the plan standing, and `fresh_tariff_plan()`
+judges the age from it.
+
+Re-stamping it on a kept plan would be this task asserting the feed answered
+when it did not. The plan would be re-certified as current at every refresh, an
+outage of any length would never retire it, and `TARIFF_MAX_AGE_S` would be
+**exactly as dead as it was before this card** — reachable only by the refresh
+task itself dying. Leaving it alone is what makes the bound govern: the plan is
+served for the age bound after its own fetch, and no longer.
+
+It is also the whole of **"distinguishable from a freshly-fetched one"**. A
+kept plan and a fetched plan are the same object shape; what separates them is
+that one's timestamp advanced and the other's did not, and every consumer that
+asks how old the plan is already reads that number. The kept case additionally
+logs at WARNING, naming the degradation's own reason, the fetch it is keeping,
+its age, and the deadline it retires at.
+
+⚠️ **What this does not give the operator, and why it is not here.** The status
+page has no row for "the last refresh failed" — the banner/level not moving
+when the plan is lost is separately carded, and the ticket rules it out of
+scope. This card's change makes that surface *more* truthful, not less: during
+the first `TARIFF_MAX_AGE_S` of an outage there is now a real plan behind the
+Arbitrage row instead of a no-plan refusal, so the row says something true for
+longer. The no-plan state is entered later by up to 5400 s; it is not removed,
+and the 30-minute lag reported on that row is untouched by anything here.
+
+---
+
+## 4. Merged after TARIFF-10 — what the wider gate changed, and what it did not
+
+TARIFF-10 landed on `release/1.0` while this card was open. It changed **which
+installs run this task** — `if arbitrage.enabled(opts)` became
+`tariff_refresh_wanted(opts)`, i.e. `provider_configured(opts) or
+arbitrage.enabled(opts)` — while this card changed **what the task does on a
+failed fetch**. Git auto-merged the two hunks, which is exactly when the
+interaction needs reading rather than trusting.
+
+**Nothing in the decisions above changed.** Two configurations are newly
+reachable, and both are now driven in `test_arbitrage.py` 8b rather than
+reasoned about:
+
+* **A provider configured with trading DISARMED** — TARIFF-10's headline case.
+  This is precisely the configuration the guard was designed for: the plans are
+  `origin == "provider"`, and a dead feed must not delete one that is still
+  inside `TARIFF_MAX_AGE_S`. It needs no second fixture, because **nothing on
+  this path reads `arbitrage_enabled` at all**, and that is asserted rather
+  than assumed — over the AST's symbols and the non-docstring string constants,
+  because two earlier drafts of that check were **red against a correct tree**:
+  the first matched the docstring paragraph that *says* `arbitrage_enabled` is
+  not read, the second matched the log line's "arbitrage, where it is armed".
+  A substring test over a function grades its prose as much as its behaviour,
+  which is habit 4 in a third costume. A fixture that set the option and
+  asserted no difference would have been the other defect — comparing a thing
+  against itself.
+* **`price_provider: off` + a `static_profile`** — the configuration TARIFF-10's
+  `or` exists to protect, and the one where a latching guard would do real harm.
+  `resolve_tariff()` returns `static_plan(provisional=False)`, whose origin is
+  `"static"`: the CONFIGURED product, not a §11.4 row. So `standing.from_feed`
+  is false on every refresh, `keep` is false on every refresh, and the plan is
+  regenerated for the current window every 30 minutes exactly as before this
+  card. **Driven, twice in a row**, because a guard that latched here would
+  freeze a static site's plan at its first window for the life of the install —
+  and mutation M3, which drops the `standing.from_feed` term, is red on that
+  check as well as on the fallback one.
+
+Two further facts settle the rest of the interaction:
+
+* **This decision is strictly downstream of every side effect.** The §8.3 carry
+  into `price_history` happens inside `resolve_tariff()`, on the `series`
+  branch, before `keep` is computed — so which of two plans is kept can neither
+  add nor lose a recorded day, and TARIFF-10's *Price history* row is
+  unaffected either way.
+* **The kept-plan log line was reworded.** It said "arbitrage stops with it",
+  which after TARIFF-10 is false on a site that fetches without trading; it now
+  says "arbitrage, **where it is armed**, stops with it".
+
+All eleven mutations were **re-driven on the merged tree** rather than carried
+over — the surrounding code changed, so a red against the old base is not
+evidence about the new one. Eleven red, no survivors, every revert
+fingerprinted. The added member is M11: making the guard conditional on
+`arbitrage.enabled(self.o)` (+86 B), red on five named checks.
+
+⚠️ **And one process note that belongs in this file.** This card's mutation
+harness was written to a shared scratchpad path and was **overwritten mid-run
+by another agent's harness for a different card**, pointing at a different
+worktree. That is MUTATION.md habit 18's second bullet almost verbatim. It was
+caught because the harness fingerprints the tree after every revert and the
+runs are what proved this worktree was never left mutated; the harness now
+lives at a card-specific path. **A harness that edits source must not share a
+name, a directory or a backup path with another one.**
+
+---
+
+## What this does not change
+
+* **Nothing on the 30 s tick.** `cycle()` still reads two attributes and awaits
+  no fetch; the AST pin in `test_arbitrage.py` section 8 is unchanged and green.
+* **Nothing about the prices themselves.** No series is invented, extended,
+  re-stamped or carried. The only question this card answers is *which of two
+  plans the controller holds*.
+* **A `price_provider: off` install is bit-for-bit unaffected.** Its standing
+  plan is never `origin == "provider"`, so `keep` is false on every refresh it
+  will ever run, and the assignment happens exactly as it did before.
@@ -0,0 +1,225 @@
+# TARIFF-13 — the coverage of a peak, and which quarter gets the credit
+
+Two decisions. §1 is the defect the ticket was raised on; §2 is the smaller
+question it asked to be settled deliberately rather than left as an accident.
+§3 is what this branch deliberately did **not** do, and why.
+
+---
+
+## 0. What was actually wrong, stated once
+
+`main.py`'s capacity-tariff status row prints a peak read from SQLite and a
+coverage figure read from **process memory**:
+
+```python
+_pk = self.peak.peak(when)                      # SQLite, durable
+...
+ f"; {self.peak.recorded} quarter(s) banked"   # an int on the tracker
+```
+
+`PeakTracker.recorded` was `self.recorded = 0` in `__init__`, incremented once
+per block inside `sync()`. A 40-hour soak caught what that means at a driven
+restart, on both instances independently:
+
+```
+before: 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit; 120 quarter(s) banked
+after : 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit;   0 quarter(s) banked
+```
+
+Reproduced here before anything was changed, through the real `Controller`, the
+real `P1Ingest`, and a **real restart** — a second `Controller` object against
+the same file on disk, never a re-read of the first:
+
+```
+before: 2026-09: peak 365 W, set by the quarter at 2026-09-10T09:00:00+00:00
+        - 10 % of the 3500 W soft limit; 12 quarter(s) banked
+after : 2026-09: peak 365 W, set by the quarter at 2026-09-10T09:00:00+00:00
+        - 10 % of the 3500 W soft limit;  0 quarter(s) banked
+
+    peak survives the restart: True
+    count survives the restart: False       (12 -> 0, store held 12 rows)
+```
+
+**TARIFF-01's argument, one column over.** That module's whole design is that
+an unreadable store must not read as a zero peak, *because a zero peak is
+disarming*. A coverage figure of zero is disarming in exactly the same way and
+about the same number: the count is what says how much of the billing month the
+watt figure actually covers, and 365 W over 120 quarters and 365 W over 0
+quarters are different claims about the same 365 W. After a restart the page
+made the weaker claim while displaying the stronger one's value. It did not
+under-report the peak — it under-reported **its own evidence**.
+
+Two further defects fell out of the same variable once it was driven, neither
+of them in the ticket:
+
+* **it was never scoped to a month.** It counted every block the *process* had
+  banked, so on 1 October the row read September's tally beside October's "no
+  completed quarter recorded yet". Measured, on the shipped tree:
+  `2026-10: no completed quarter recorded yet - 0 % of the 3500 W soft limit;
+  1 quarter(s) banked`.
+* **it missed the block `restore()` banks.** A stale block closed from the
+  checkpoint goes into `quarter_blocks` without passing through `sync()`, so
+  the counter never saw it.
+
+---
+
+## 1. Decision: the count is READ FROM THE TIER THE PEAK IS READ FROM
+
+The acceptance criterion allowed either route — make the count durable, or stop
+printing a number that silently resets. **Durable**, because the count is the
+useful half of the row and removing it would have cost the operator the one
+thing that says whether the peak means anything yet.
+
+`PeakStore.banked_count(month)` asks the database `SELECT COUNT(*) FROM
+quarter_blocks WHERE month=?`, and `PeakTracker.recorded` is a property over it
+rather than an attribute. Three consequences, and all three are the defects
+above:
+
+* a restart re-reads the same rows, so the figure survives it;
+* the count is per **month**, so it agrees with the peak it is printed beside;
+* a block banked by `restore()` is a row like any other and is counted.
+
+Three things this route deliberately does **not** do:
+
+* **it does not count `len(blocks_in(month))`.** `blocks_in()` returns `[]` on a
+  read error — safe there only because no caller reads its emptiness as a peak,
+  which its own docstring says — so taking its length would rebuild the
+  disarming zero one call further out. `banked_count()` returns **`None`** when
+  the database will not answer.
+* **it does not count `monthly_peak`.** That tier holds one row per *month* and
+  would answer `1` for every month ever measured — wrong by exactly the amount
+  that makes it look plausible. The two tables are proven equal on the **peak**
+  by `recompute_month()`; they were never equal on the **count**.
+* **it does not remove the dedupe.** `_seen` is still what stops `cycle()`'s
+  once-a-second `sync()` re-banking a block that `P1Ingest.blocks` keeps for a
+  day, and `sync()`'s return value is still the number newly banked. What moved
+  is only where the *status page* reads its figure. ⚠️ The check that graded the
+  dedupe used to assert `recorded == 1` — the dedupe and the figure reporting it
+  were the same variable. Counting rows in `quarter_blocks` cannot see a
+  re-bank at all (it is a PRIMARY KEY no-op), so that check is now graded on
+  `sync()`'s **return**, with the store's tally as the second half.
+
+### ⚠️ The unreadable case renders a WORD, not a number
+
+`banked_count()` returns `int | None`; `recorded_in()` renders the `None` as
+the module constant `COUNT_UNREADABLE = "an unreadable number of"`, so the
+sentence reads
+
+```
+... ; an unreadable number of quarter(s) banked
+```
+
+`0` was never available. `None` was rejected too: `f"{None} quarter(s) banked"`
+renders **"None quarter(s) banked"**, which an operator reads as the same zero.
+This is the `PeakReading` trade — no `peak_w_or(default)`, ever — applied to the
+coverage figure: a caller that formats it gets a true sentence in both states,
+and a caller that does arithmetic on it gets a `TypeError`, which is loud.
+
+"0 quarter(s) banked" remains a **true and reachable** sentence: it is what a
+month nothing has been written to says, and part 11 asserts that the two states
+are spelled differently.
+
+---
+
+## 2. Decision: at EQUAL wattage, the EARLIEST quarter keeps the attribution
+
+**First, not most recent.** The reasoning, in the order it matters:
+
+1. **It is not a money question.** The utility bills the wattage; the timestamp
+   is not part of the bill. So the decision is settled entirely on what the
+   status row is *for*.
+2. **The row answers "when did my monthly peak happen".** An operator reading it
+   goes and looks at one event — what was running, what the weather was. A
+   stable answer is the one that can be investigated; "most recent wins"
+   guarantees the answer moves every time the wattage recurs, and an operator
+   who looked yesterday is sent somewhere else today for no reason.
+3. **It is what one reader already did unconditionally.** `recompute_month()`
+   is `ORDER BY offtake_avg_w DESC, quarter_start ASC LIMIT 1` — earliest wins.
+   Choosing "most recent" would have meant changing both readers; choosing
+   "earliest" meant making the other one say out loud what it was already doing
+   by accident.
+
+### ⚠️ And the two readers DID diverge, which is why this is a code change
+
+The `monthly_peak` upsert was `WHERE excluded.peak_w > monthly_peak.peak_w` —
+strictly greater, so an exact tie never wrote and the row kept whichever tied
+block was **written first**. That coincides with *earliest* only while blocks
+arrive in time order. Fed four equal 365 W blocks newest-first, measured on the
+shipped tree:
+
+```
+ascending arrival    monthly_peak -> 09:00:00   recompute_month -> 09:00:00   agree=True
+DESCENDING arrival   monthly_peak -> 09:45:00   recompute_month -> 09:00:00   agree=False
+```
+
+That is a divergence in the derived record that part 8 of `test_tariff.py`
+exists to prove cannot happen — latent, because nothing in the shipped path
+banks out of order today. The upsert now carries the tie term explicitly:
+
+```sql
+WHERE excluded.peak_w > monthly_peak.peak_w
+   OR (excluded.peak_w = monthly_peak.peak_w
+       AND excluded.quarter_start < monthly_peak.quarter_start)
+```
+
+**`peak_w` is untouched.** The `>` term is exactly as it was, no tie can move
+the billed number, and SAFETY-07's guard reads the same watt figure it read
+before. The second term moves only the timestamp.
+
+### ⚠️ AND THE SOAK'S DRIFT WAS NOT A TIE AT ALL
+
+The ticket's reading — "ties at the same wattage are re-attributed to the most
+recent matching quarter" — is **false**, and driving it is what showed that.
+Six exactly-equal 365.0 W quarters on the shipped tree moved the attribution
+**zero** times, because `>` is strict.
+
+What the soak saw was a genuine new maximum **smaller than the row's own
+resolution**. The row renders `{peak_w:.0f}` — whole watts — so 365.0000001 W is
+a new peak to the database and the same `365 W` to the reader:
+
+```
+q0  fed 365.0        -> renders 365 W, attributed 09:00:00
+q1  fed 365.0000001  -> renders 365 W, attributed 09:15:00
+q2  fed 365.0000002  -> renders 365 W, attributed 09:30:00
+```
+
+**Decision: left alone, deliberately.** It is the instrument behaving correctly
+— the peak really did rise — and the alternative, printing more decimal places,
+puts noise in the one row an operator reads at the moment the guard engages, to
+explain a movement that is real. Both cases are pinned in part 12 so that
+neither can be changed by accident, and the distinction is recorded here so the
+next reader does not re-diagnose it as a tie.
+
+---
+
+## 3. What this branch did NOT do, and who owns it
+
+**`main.py`'s status row was not touched.** TARIFF-11 holds `main.py`'s status
+rows on a concurrent branch, and the standing instruction is to stop rather than
+race there. Everything above is in `app/tariff.py`, and the row picks the fix up
+without editing, because `self.peak.recorded` is an attribute access and is now
+a property.
+
+**The residual, stated with its scope.** `recorded` answers for
+`datetime.now()`. The peak beside it follows `checks(when=...)`. The shipped
+install has **exactly one** call site — `self.checks()` with no argument, at
+`main.py:4359` — where the two are the same month, so **the live page is correct
+and durable**. They part company only under the `when=` affordance TEST-17 added
+for the suite, and the mismatch there is strictly smaller than the one it
+replaces (this month's tally, rather than a process-wide total across all
+months).
+
+`PeakTracker.recorded_in(when)` is the scoped form and is shipped. Moving the
+row onto it is:
+
+```python
+- + f"; {self.peak.recorded} quarter(s) banked"
+ + f"; {self.peak.recorded_in(when)} quarter(s) banked"
+```
+
+one token, on one line, inside the block TARIFF-11 owns. `test_tariff.py`
+part 10 **pins the present behaviour** — graded against a row count taken
+straight from `quarter_blocks`, not against the property that produces it — so
+the gap goes red if it changes and cannot be quietly forgotten.
@@ -0,0 +1,349 @@
+# TARIFF-14 — how long one price point covers, and what the last one does
+
+One defect and one genuinely open decision. The defect had no defensible
+alternative once it was measured; the decision — the **last** point's window —
+did, and the alternative is argued below rather than dismissed.
+
+---
+
+## 0. The measurement this card exists for
+
+`_Series.at()` asked `s <= u < s + 1 h` of every point **in list order** and
+returned the **first** match. Run against the shipped code at `5059e28` on a
+quarter-hourly series:
+
+```
+series: 02:00=0.10  02:15=0.11  02:30=0.12  02:45=0.13  03:00=0.14 ...
+
+ask + 0min -> 02:00  0.10
+ask +15min -> 02:00  0.10   <-- WRONG (wanted 02:15)
+ask +30min -> 02:00  0.10   <-- WRONG
+ask +45min -> 02:00  0.10   <-- WRONG
+ask +60min -> 02:15  0.11   <-- WRONG (wanted 03:00)
+ask +75min -> 02:30  0.12   <-- WRONG (wanted 03:15)
+```
+
+**Two failure modes, not one.** Inside the first hour the `:00` point wins
+because its hour has not run out. From the second hour on the answer is not
+even the top of the hour — the first point still inside its own hour wins — so
+**the error compounds with depth into the series**.
+
+Same code, same run, after the fix:
+
+```
+ask + 0min -> 02:00  0.10        ask +60min -> 03:00  0.14
+ask +15min -> 02:15  0.11        ask +75min -> 03:15  0.15
+ask +30min -> 02:30  0.12        ask +90min -> 03:30  0.16
+ask +45min -> 02:45  0.13        ask+120min -> 04:00  0.18
+```
+
+An hourly series is **unchanged at every instant**, before and after — which is
+the whole reason nothing caught this. Every price fixture in this repository
+before TARIFF-08 was the invented hourly row shape, `static_tariff.py` emits
+hourly points, and the DST checks count points on the 23- and 25-hour days
+without ever asking `at()` for a quarter-hour. **The suite had been exercising
+the one resolution on which the broken rule and the right one agree.**
+
+Belgium moved to a 15-minute MTU on 2025-10-01 and the live day-ahead feed
+returns **96 points at 900 s**, so this is reachable only down the dynamic path
+TARIFF-08/09 just made work. Static sites are immune.
+
+## 0.1 What it cost, which is not "a slightly wrong price"
+
+`arbitrage._act()` calls `_point_at(plan, now)` → `series.at(now)` and then
+tests `here.start == v.cheapest.start` / `== v.dearest.start` to decide whether
+this interval is the buy one or the sell one. That is an **identity test
+between the matched point and the point the verdict was built from**, and on a
+quarter-hourly series it almost never matched — so the strategy idled through
+exactly the interval it exists to trade, reporting *"this hour is neither the
+buy hour nor the sell hour"*. It also read `here.provisional` (§8.3) and §17's
+`price < 0` off that same wrong point.
+
+---
+
+## 1. The rule
+
+> **A point covers from its own start until the next point's start, and never
+> more than one hour.**
+
+* **900 s** → each point covers its own quarter.
+* **3600 s** → each point covers its own hour. Identical to what shipped.
+* **MIXED** → **each point takes its own gap.** FCST-04's carry-forward emits
+  hourly carried points beside quarter-hourly firm ones, and the soak measured
+  spacing `[900, 3600]` in **70 % of samples** — so a window derived from one
+  global spacing would be wrong in the **normal steady state**, not in an edge
+  case.
+
+### 1.1 Why the one-hour cap is not decoration
+
+FCST-04 **leaves holes on purpose**: an hour with no published price and no
+yesterday value is left *out* of the series, and `price_forecast.py`'s module
+note names `at()` raising `Absence` for it as the behaviour that sends the
+caller to the static profile (§11.4 for that hour).
+
+Uncapped, "until the next point's start" stretches the point **before** a
+three-hour hole across the whole hole and answers every instant in it with a
+stale price. Filling holes is the defect this module exists to refuse, and it
+would have been introduced **by the fix for a different one**. Graded in
+`test_price.py` 14d; the mutation that removes the cap is red there.
+
+---
+
+## 2. The decision: what the **last** point covers
+
+There is no next start, and §9.3 says nothing about how wide the final interval
+is — a `PricePoint` has **three fields** and must not learn a fourth, because
+that is the wire format every store, replay, fixture and captured body in this
+repository is written against. So the tail is a **choice**, and both candidates
+are defensible.
+
+**Chosen: the last point is given the same span as the point before it** (one
+hour when it is the only point).
+
+| | flat one hour | the span in front of it (**chosen**) |
+|---|---|---|
+| 96-point 900 s day, `at(23:50)` | answers 23:45 | answers 23:45 |
+| the same day, `at(00:30)` **tomorrow** | **answers with today's 23:45 price** | `Absence` |
+| 24-point hourly day, `at(23:50)` | answers 23:00 | answers 23:00 |
+| mixed series ending at the firm/carried seam | answers for an hour | `Absence` after 15 min |
+
+**The second row is why.** A flat one-hour tail reaches across a day boundary
+and prices tomorrow morning with yesterday's last print — which is
+"reaching for a neighbouring one", the single thing the `Absence` message has
+always refused to do. The chosen rule never extends a point past a span the
+series itself demonstrates.
+
+### 2.1 The cost of the choice, stated rather than buried
+
+On a **mixed** series whose last point is a carried **hourly** one sitting
+behind quarter-hourly firm ones, the tail is **900 s**, and the last 45 minutes
+of the horizon raise `Absence` for an hour something did carry a value for.
+
+That is accepted, not tolerated, and the direction is the safe one:
+
+* the caller falls back to the static profile (§11.4) instead of trading on a
+  span the series never demonstrated;
+* the point is **carried**, so §8.3 forbids any irreversible action resting on
+  it regardless;
+* it is at the far end of a 48 h horizon, where nothing is decided at 30 s.
+
+Under-covering costs a missed decision. Over-covering prices a real interval
+with a number that does not describe it. Those are not symmetric.
+
+### 2.2 The degenerate case
+
+A series of **one** point has no gap in front of it to copy and gets **one
+hour** — the shipped behaviour, kept deliberately. `test_price.py` 14e states
+it as its own check so it cannot decay into an accident.
+
+---
+
+## 3. Does `at()` now depend on sortedness? Yes — and it establishes it itself
+
+The old rule read one point at a time and did not care about order. The new one
+reads a point's **neighbours**, so it *would* depend on the series being
+ascending.
+
+It does not, because **the lookup index is sorted by UTC start at construction**
+(`_cover_table()`, called once from `_Series.__init__`). No caller's list order
+can reach `at()`.
+
+That matters because the three things that "guarantee" order today each
+guarantee it somewhere else:
+
+| | what it guarantees | where |
+|---|---|---|
+| `_validate_raw()` | strictly increasing starts | the `load_prices()` path only |
+| `price_history._parse_points()` | re-sorts by instant | the store read path only |
+| FCST-04's fill | emits ascending | that one producer only |
+| `PriceRead.series()` | **nothing** | every other caller, including tests |
+
+Three producers agreeing today is not an invariant; it is a coincidence with
+good references. `test_price.py` 14f drives a series handed its 96 points in
+**reverse** order and asserts `at()` answers identically at every one of them —
+red the moment the sort is removed.
+
+**Duplicated starts** (refused by `_validate_raw()`, constructible by hand) give
+the earlier list entry a zero-width window and the later one the real span. One
+of the pair becomes unreachable through `at()`; **nothing raises**, at
+construction or on the 30 s control path. Stated as a check rather than left to
+be discovered.
+
+---
+
+## 4. `covers()` shared it. `window()` did not
+
+* **`covers()`** has no window rule of its own — it calls `at()` — so it shared
+  the defect exactly and the same change fixes it. It is kept as a delegation
+  for that reason: a second copy of the rule is a second place for it to be
+  wrong.
+* **`window(since, until)`** grades a point's **start** against a half-open
+  range and never asks how long a point lasts, so it carries no resolution
+  assumption at all. It is **not** a coverage query — a point that starts before
+  `since` and runs into it is absent from its result by design. That is now
+  said in its docstring and pinned by a check, because the next reader will ask.
+  It has **no callers** in `app/`.
+
+---
+
+## 5. What this card does NOT fix, with its shape
+
+`price_forecast._walk()` — §8.3's irreversible-action gate — iterates
+`committed_hours()`, which steps in **whole hours**, and asks `series.at(u)` at
+each. On a quarter-hourly series that now reliably returns the hour's `:00`
+point (it previously returned something earlier and arbitrary), so the gate
+reads **one point per hour** and never looks at the `:15`/`:30`/`:45` flags.
+
+A partially-provisional hour would therefore be gated on its first quarter
+alone. **Two things keep it off every shipped install, and both are
+circumstantial rather than structural:** `price_permits()`/`begin_phase()` have
+**no caller in `app/main.py`** — the §12 price-justified entry point is built
+and not yet wired — and FCST-04 carries **whole** hours while
+`generic_dayahead` publishes whole days, so the four quarters of an hour are
+firm or carried together anyway. Both are facts about the *callers and
+producers*, not properties of the *gate*, so this is written down here rather
+than left for the first sub-hourly feed or the first wiring-up to find. Fixing it means teaching
+`committed_hours()` about resolution, which is a data-model question this card
+deliberately does not open.
+
+---
+
+## 6. Mutations
+
+Eight, each purged before the run (TEST-15), each reverted with the tree
+fingerprint checked afterwards (MUTATION.md habit 18), backup at a `mktemp`
+path per invocation.
+
+⚠️ **Re-driven in full on the MERGED tree** after TARIFF-10 landed on
+`release/1.0` (base `88c59a9` -> `559f0eb`). All eight give the same verdicts
+and the same red-check counts as before the merge, which is the answer that
+matters: TARIFF-10 added 650 lines of checks to `test_price.py` and none of
+them moves under any of these edits, because they grade `resolve_tariff()`'s
+*reachability from a configuration* and not the lookup. Clean `app/price.py` on
+the merged tree = **`90d8ca31f7c0109d`, 85953 B** (pre-merge it was
+`30d1a56f0117e571`, 83742 B; the difference is TARIFF-10's `provider_id()` /
+`provider_configured()`, which this card does not touch).
+
+| | mutation | Δ | red in |
+|---|---|---|---|
+| M1 | `at()` back to the shipped fixed one-hour scan over `self.points` | +68 B | **24 named checks**: `test_price.py` 14b ×4, 14c ×3, 14d, 14e ×3, 14f, 14g; `test_arbitrage.py` 10b ×6, 10c ×3, 10d ×2 |
+| M2 | drop the one-hour cap | −68 B | `test_price.py` 14d |
+| M3 | flat one-hour tail instead of the span in front | **+0 B** | `test_price.py` 14e ×3, 14g — 4 checks |
+| M4 | trust the caller's list order — drop the sort | −61 B | `test_price.py` 14f |
+| M5 | `covers()` grows its own hour-wide rule | +95 B | `test_price.py` 14e, 14g |
+| M6 | `window()` becomes a coverage query | −37 B | `test_price.py` 14g |
+| M7 | the window's end becomes inclusive | +1 B | `test_price.py` 14b ×4, 14c ×4, 14d, 14e ×4, 14f ×2, 14g — 16 checks |
+| M8 | the window's start becomes exclusive | −1 B | `test_price.py` 14b ×4, 14c ×4, 14d, 14f ×2, 14g, 14h, plus the pre-existing section 6 check — 14 checks |
+
+**M3 is the zero-byte one and it is the tail decision itself** — the case
+MUTATION.md names as the risky size, caught by the check written for it.
+
+**What the arbitrage file does NOT see, with sizes.** M2, M4, M5, M6 and M8
+leave `test_arbitrage.py` green, and that is honest rather than a gap to round
+off: they are `at()`-level properties (holes, caller order, `covers()`,
+`window()`, the start boundary) that no arbitrage fixture reaches, because the
+probes are seven minutes into a slot and the plans have no holes. The one that
+matters end to end — M1, the shipped rule — is red in **both** files, on the
+named check `THE PROPERTY THE DEFECT BROKE`.
+
+---
+
+## 7. TARIFF-10 landed on the base while this was open — what it changes here
+
+Base moved `88c59a9` → `559f0eb` mid-card. The question is not whether the
+branches merge; it is whether TARIFF-10 makes any sentence above **false**.
+
+**In `app/price.py` the two do not meet.** TARIFF-10 added `provider_id()` and
+`provider_configured()` beside `price_option()` and routed `load_prices()`
+through them. That is the option-reading layer; it touches nothing in
+`_Series`, `at()`, `covers()`, `window()` or `_cover_table()`. Git merged the
+file without a conflict, and the merged `at()` is byte-identical to the one the
+mutations above were driven against.
+
+**Behaviourally it widens who has a series at all, and that cuts one way only.**
+`run_tariff_refresh()` now runs on installs with `arbitrage_enabled` **off**, so
+a provider-configured site has a standing plan — and therefore a `_Series` —
+where before it had none. **It does not add a new `at()` consumer to the 30 s
+tick**, which is the claim worth checking rather than assuming:
+
+| caller of `at()`/`covers()` | reached by a non-trading install? |
+|---|---|
+| `arbitrage._point_at()` (`arbitrage.py:300`) | no — trading only |
+| `static_tariff.TariffPlan.price_at()` / `.words` `here` (`:750`, `:819`) | on the tick these are reached through `static_status()`, which builds a **`static_plan`** — hourly points, immune. `main.py` calls only `plan.words` on the fetched plan, which counts points and never looks one up |
+| `price_forecast._walk()` (`:562`, `:568`) | **`price_permits()` and `begin_phase()` have no caller in `app/main.py` at all** — §12's price-justified entry point is built and not yet wired |
+
+So TARIFF-10 neither creates nor closes any exposure this card is about. What it
+does do is make the defect's reach larger the moment such a site arms trading,
+because the series it would trade against now exists on every configured
+install rather than only on armed ones. That strengthens the case for the fix
+and changes nothing in its reasoning.
+
+**In `test_price.py` both cards appended a section 13.** Nothing is dropped:
+TARIFF-10's stays **13**, this card's is renumbered **14** (which is also this
+card's number), and the temp-directory teardown TARIFF-10 put at the end of the
+file stays at the end of the file. The two sections share no fixture, no option
+dict and no helper name; TARIFF-10's grades `resolve_tariff()`'s *reachability
+from a configuration* and drives real fetches with a counting transport, and
+**none of its checks moves under any of the eight mutations above** — measured,
+not assumed.
+
+---
+
+## 8. TARIFF-12 landed too — a plan may now be 90 minutes old when it is asked
+
+Base moved `559f0eb` → `a6e64fb` while this was open. TARIFF-12 stops a
+returned §11.4 degradation from overwriting a standing plan that is still
+inside `TARIFF_MAX_AGE_S`, so **a served plan can now be up to
+`3 × TARIFF_REFRESH_S = 5400 s` old** where before it was at most one refresh
+interval. `at()` is what answers *"what does it cost right now"* out of that
+older plan, so the question is fair and the answer is written out rather than
+assumed.
+
+**Per-point span: unaffected, structurally.** Every window is derived from the
+neighbouring points' **absolute `start` instants**. Those are `datetime`s inside
+a frozen dataclass inside a tuple — they cannot move, and `_cover_table()` runs
+once at construction over data that cannot change afterwards. A plan's *age* is
+a property of `fetched_at` / `tariff_at`, never of a window. **The index cannot
+go stale**, which is a small positive under TARIFF-12 rather than a risk: a kept
+plan now lives longer, and there is nothing in it that needed recomputing.
+
+**The one-hour cap: unaffected.** It bites only where a gap exceeds an hour,
+i.e. at a hole FCST-04 left. Walking further into a series crosses more windows;
+each is still resolved on its own neighbours.
+
+**The tail: reachable for the first time, and the choice made in §2 is the one
+that survives it.** This is the half worth spelling out.
+
+* At the **shipped 48 h horizon** the tail is unreachable by staleness. A plan
+  is served for at most 90 minutes, so `now` is at most 90 minutes into a
+  ~48 h series — the last point is still about 46½ hours away.
+* But `price_horizon_h` is `int(1,72)` in `config.yaml`, so an operator **can**
+  configure a **1 h** horizon. A 90-minute serve-stale window against a 1 h
+  series puts `now` genuinely past the end. That is not hypothetical; it is a
+  supported configuration meeting a supported outage.
+* Under the **chosen** rule a quarter-hourly 1 h series ends at `:45` and that
+  point's window closes at the top of the next hour: `at()` raises `Absence`,
+  `_point_at()` returns None, `_act()` idles with its "no price for this
+  instant" reason, and §11.4 sends the site to the static profile.
+* Under the **rejected** flat one-hour tail the same stale plan would have gone
+  on trading against the `:45` print for **up to 45 minutes after the interval
+  it describes had ended** — pricing an outage with a number for a quarter that
+  is over.
+
+So TARIFF-12 does not weaken the tail decision. It is the first thing that makes
+it reachable on a shipped configuration, and it independently selects the same
+answer. ⚠️ **Note which direction that runs**: the more stale a plan is allowed
+to be, the more the tail rule is doing real work, so it should be re-read if
+`TARIFF_MAX_AGE_S` is ever widened again.
+
+**`TariffPlan.from_feed` cannot produce a series this code has not seen.** It is
+a pure predicate on `origin` (`== "provider"`), and TARIFF-12's decision keeps or
+replaces a **whole plan object**. It never splices two reads into one series, so
+it cannot hand `at()` an unsorted or duplicated point list — the case §3 covers
+defensively and that nothing shipped produces.
+
+**Re-graded on this base.** All 29 files green. `app/price.py` is byte-identical
+to the TARIFF-10 merge (`90d8ca31f7c0109d`, 85953 B) because TARIFF-12 does not
+touch it. **M1** re-driven: +68 B, red on the same **24 named checks** across
+both files. **M3** re-driven: **+0 B**, red on the same 4. This branch
+contributes **zero diff** to `app/main.py` and `app/static_tariff.py`.
@@ -0,0 +1,166 @@
+# TARIFF-15 — the operator's own tariff card, and why the card has to grade it
+
+**Status: DECIDED 2026-09-13 — ship `custom_formula` with FIXED coefficients and
+a REQUIRED `card` block whose printed price the add-on reproduces at startup or
+refuses to run. No expression evaluation, ever. Declare `{ENERGY, MARKUP}`,
+never `ALL_IN`.**
+
+Filed with TARIFF-15. Follows [[TARIFF-07]], which withdrew three per-supplier
+plugins and named a formula provider as the answer it could not give.
+
+---
+
+## 1. Why a formula rather than more plugins
+
+TARIFF-07 established the negative half: a per-supplier plugin has no source
+for its numbers. This card establishes the positive one.
+
+* **There is no machine-readable source of Belgian tariff coefficients
+  anywhere.** CREG's consumer tariff-card pages 404. CREG Scan is a
+  JavaScript-only wizard. The annual report carries the supplier list and no
+  per-product coefficients. VREG was unreachable. Every coefficient found in
+  research came from a supplier's **own PDF**, one of them image-only.
+* So there is nothing to scrape, and fourteen plugins would still have no
+  source for their numbers — they would be fourteen copies of the invention
+  TARIFF-07 deleted three of.
+* **The customer is the only party who can see their own coefficients**, and
+  the card they read them from **is the only artefact that can grade them**.
+  That second clause is the whole design; everything below follows from it.
+
+## 2. The shape is the market's published arithmetic
+
+Both suppliers whose 2026 cards were readable print three things on one line:
+the formula, the reference index it assumes, **and the resulting price**.
+
+| | computed | the card prints |
+|---|---|---|
+| Eneco `(0.102 × 133.9905 + 1) × 1.06` | **15.5471** | **15,55** |
+| ENGIE `(0.1 × 61.96 + 0.9) × 1.06` | **7.5218** | **7,522** |
+
+Two independent suppliers, reproduced to the last printed digit, through the
+shipped code (`test_price.py` 15a runs both, and then runs both again end to
+end through `load_prices()`).
+
+That third column is not a nicety. It is the only externally-published number
+in this whole feature, and it is what makes the design safe.
+
+## 3. The double-counting risk, and which half of it is new
+
+`price.py`'s trap 1 already mechanises that a **plugin** cannot double-count:
+`PluginOptions` refuses the framework keys, `code_leaks()` refuses a plugin
+whose *code* mentions them, `assemble()` adds the complement exactly once.
+
+`custom_formula` introduces a risk none of those can see, **because it is not
+in code**: the **operator** double-counting, by folding their network charges
+into `offset` while `price_taxes_eur_kwh` also carries them. `code_leaks()`
+scans code. This is config, typed by a person reading a PDF.
+
+It is a real reading of a real card, not a hypothetical. A Belgian card's
+`Tariefformule` line is the **energy component alone** — Eneco tabulates
+network tariffs in one table and levies in a second; ENGIE states in so many
+words that the formula excludes network, distribution, transport, grid levies
+and excise. An operator who wants "the price I actually pay" and adds ~12
+c€/kWh to `offset` has done something entirely reasonable and is now billed for
+network charges twice, on every hour, with §11.4 making the whole class of
+price defect invisible.
+
+**Decision: the card grades it.** At startup `validate.py` recomputes the
+card's own printed price from the operator's coefficients and refuses to start
+unless the two agree to within `0.01` — which is the last digit a card prints.
+An inflated `offset` cannot pass, because the printed estimate is by
+construction the energy component: 15.55 becomes 28.27 and the add-on stops and
+says why.
+
+**And the limit, stated in the same sentence as the claim**, exactly as
+`price.py` states trap 1's: *it grades the coefficients against the card, not
+the card against reality.* A consistent-but-wrong pair — both numbers off the
+wrong product, or off a card the contract has since rolled over from — agrees
+with itself perfectly and passes. Nothing here or anywhere else can catch that.
+
+### 3b. The one unit error the card check cannot see
+
+A factor applied to **both** sides — coefficients *and* printed price — cancels
+out of a comparison between them. That is a second quantity, so it is a second
+refusal: the card's own point must land inside 0.02–1.00 EUR/kWh.
+
+⚠️ **Its floor is applied to the ENERGY figure and not to the all-in one, and
+that asymmetry was found by a mutation rather than by reasoning.** The shipped
+`price_taxes_eur_kwh` was 0.06 — three times the floor — so a card read a
+hundred times too small comes out at 0.0016 EUR/kWh of energy, is carried over
+0.02 by the flat tax addend alone, and passes a band applied to the total. The
+hundredfold error is exactly what the band exists for. Graded from both
+directions in `test_price.py` 15e/15i and driven red as M10. *(Annotated
+2026-09-13: TARIFF-18 raised the default to 0.11736, nearly six times the
+floor. The asymmetry is unchanged in kind and larger in degree — the flat
+addend that carries a hundredfold-small card over 0.02 got bigger.)*
+
+## 4. Fixed coefficients. No expression evaluation of any kind
+
+**Decided: never a grammar.** Two arguments, and the second is the one that
+decides it.
+
+* **Security.** The add-on serves `POST config/save` → `POST
+  /addons/self/options` on its own ingress page, so `price_formula` is
+  **settable over HTTP**. `eval` on it is remote code execution in a root
+  container holding `SUPERVISOR_TOKEN`, with `homeassistant_api` and
+  `hassio_api`, driving an inverter over RS485. `eval(s, {"__builtins__": {}})`
+  is not a sandbox and this repository is not going to pretend otherwise.
+* **⚠️ AND THE DECIDING ARGUMENT IS NOT SECURITY: AN EXPRESSION IS
+  UNVERIFIABLE.** Two coefficients can be graded against the card's printed
+  estimate. An arbitrary expression cannot be graded against **anything** — so
+  it makes the invisible-wrong-coefficient problem *strictly worse*, which is
+  the exact failure this provider exists to prevent. An expression would buy
+  the operator freedom to be wrong in a way nothing could report.
+
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B × index + A`, so an expression buys nothing the market needs either.
+
+**Future shapes become NAMED FIELDS** — `clamp_lo`, `factor_negative`,
+`offset_bands` — each individually refusable and each individually gradeable
+against a card. `parse_price_formula()` therefore **refuses an unknown key**
+rather than ignoring it: an operator who types `"expr"` is told it does not
+exist, instead of being priced on the fields they also typed with the one they
+believed in dropped in silence.
+
+`test_price.py` 15f walks the module's AST for `eval`, `exec`, `compile`,
+`__import__` and `literal_eval`, and exercises the scanner's **red** direction
+on every run so it cannot become a scanner that scans nothing.
+
+## 5. `{ENERGY, MARKUP}`, not `ALL_IN`
+
+The contract's formula **is** the supplier's markup — that is what `B` and `A`
+are — but it is not the levies. Declaring `ALL_IN` would lie on behalf of every
+operator who typed exactly what their card says and would drop
+`price_taxes_eur_kwh` from every hour: measured at 0.2125 → 0.1555 EUR/kWh.
+`price_markup_eur_kwh` is therefore **ignored** under this provider, and logged
+as ignored, which is the framework's existing rule rather than a new one.
+
+## 6. What was reused rather than rebuilt
+
+The index path is `generic_dayahead`'s: same EPEX BE feed, same
+Brussels-calendar range, same columnar parser, same declared egress hosts. The
+override/range decision moved into one shared `dayahead_feed_url()` that both
+plugins call, because two copies of that rule would be two places for the
+short-horizon defect TARIFF-09 fixed to come back in only one of them.
+
+`resolution: hourly` averages each hour's members. ⚠️ **That is not
+`_Series.at()`'s hourly assumption returning (TARIFF-14):** it decides how many
+points are *emitted*; the window each point covers is still derived from its
+neighbours in `_cover_table()`. A feed that is already hourly averages one
+member per hour — the identity — so the option cannot silently assume the
+granularity it was handed. Graded.
+
+## 7. What this card did NOT do
+
+* **The injection leg.** Eneco uses `0,102` on consumption and `0,100` on
+  injection, and injection is VAT-exempt where consumption is at 6 % — a second
+  per-contract formula, not a second copy of this one. Separate card.
+* **The hour-varying network charge that bites Wallonia.** Separate card.
+* **Raising `price_taxes_eur_kwh` from 0.06 to ~0.12.** Separate card, and an
+  owner's decision. Note §3b: the band's floor is deliberately insensitive to
+  whatever that number becomes. *(Annotated 2026-09-13: that card is
+  **TARIFF-18** and it shipped on this branch at **0.11736** — the Eneco
+  residential card for Flanders, September 2026, incl. 6 % VAT, summed from
+  Fluvius Antwerpen distribution 5,35 + bijzondere accijns 4,876 + bijdrage
+  groene stroom en WKK 1,51 c€/kWh. §3b held: the floor is still on the energy
+  figure and nothing in this module needed a new number.)*
@@ -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.
@@ -0,0 +1,353 @@
+# 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`
+
+> Reversed by TEL-14 (flag and negative caution): `DECISIONS/TEL-14-pv-sign.md`.
+
+### 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.
@@ -0,0 +1,361 @@
+# 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.
+
+**Superseded in part (UX-08, 2026-09-27):** the PV status rows no longer read 0.11.0's sentences at one entity. The owner ruled out entity ids on status rows, so 2/5 now holds for the control document only. See `UX-08-short-notifications.md`, phase 2b item 3.
@@ -0,0 +1,83 @@
+# TEL-14 — the PV sign, declared per entity
+
+Owner report on 0.12.0: `sensor.espressif_vermogen` (ESPHome clamp) and
+`sensor.kwh_meter_actueel_vermogen` (kWh meter in the PV circuit) read
+**positive for consumption, negative for production**. At night the page said
+"✓ PV production: 13 W" — standby draw. By day production would publish negative.
+
+## 1. This reverses TEL-11 §2, and why
+
+TEL-11 §2 refused a `pv_invert` on two grounds. "PV is read by nothing in the
+control path" still holds: the flip lives in `pv.total()`, and `test_pv.py`
+part 12 re-runs part 6's 40-cycle identity with a flip set. "A reversed sensor
+announces itself" did not survive a real site: these sensors follow a different
+convention, read a plausible small positive number at night, and the only other
+fix is a template sensor, the place TEL-12 §2 says goes quietly wrong.
+
+## 2. The shape: a parallel list, `pv_invert_entities`
+
+Measured by `tools/supervisor_shape_probe.py` §H (Supervisor 2026.08.0, against
+a 0.12.0 blob); re-run it for the transcript.
+
+| shape | schema | why it lost / won |
+|---|---|---|
+| (a) `-sensor.x` prefix | accepted | invisible: the sign is a syntax only the description explains, in a field an installer fills with the entity picker's text |
+| (b) parallel list | accepted, 0.12.0 blob unchanged | **ships**: its own labelled, translated field ("PV entities whose sign is reversed"); an installer lists the odd ones out |
+| (c) dicts on `pv_entities` | **refuses 0.12.0's stored strings** | bricks the upgrade — TEL-12's trap again |
+| (c2) dicts as a third key | accepted | per-entry labels render raw (`entity`, `invert`) — probe §F; and a third PV surface |
+| (d) global bool | accepted | one sign cannot describe inverter + meter in one roster |
+
+(b)'s known cost is a typo in the second list: `pv.stray_inverts()` turns it into
+a named caution. `[]` in `options:` is load-bearing (§H, isolated counterfactual).
+Default `[]` flips nothing, so every 0.12.0 install is byte-identical (part 12).
+
+## 3. The negative caution: per entity, below −50 W
+
+The owner's two meters draw ~13 W at night, so a *correctly* signed meter reads
+about −13 W then. −50 W clears that with room for a few such devices behind one
+entity; a reversed sensor by day reads hundreds to thousands of watts below
+zero. It is tested **per entity, not on the total** (a deviation from the brief):
+three correct meters at −20 W sum to −60 W and must stay quiet, while a reversed
+−1500 W hidden inside a positive total must not. It is a caution, never `bad`;
+a wrong threshold costs a spurious or missed caution, never data. The text says
+ADD (unflipped) or REMOVE (already flipped).
+
+## 4. Mutations
+
+Fresh `cp -a` each, `__pycache__` purged, CI image, `:ro`, `--network none`;
+`test_pv.py` only unless stated. T1-T12 at 7559d21; M2/M5 are review #1628's,
+red since B1 (merged into release/1.0 @ 43b2740).
+
+| # | mutation | bytes | reds |
+|---|---|---|---|
+| T1 | flip ignored in `total()` | −45 | 9 |
+| T2 | flip applied to every member | −7 | 6 |
+| T3 | `0.0 - w` → `-w` | −5 | 1 |
+| T4 | flip written as `abs()` | −1 | 2 |
+| T5 | `_read_pv()` stops passing the flip | −26 | 7 |
+| T6 | caution threshold −50 → 0 W | −17 | 3 |
+| T7 | `[sign inverted]` marker dropped | −39 | 3 |
+| T8 | negative caution made `bad` | +1 | 1 |
+| T9 | `stray_inverts()` always empty | −50 | 1 |
+| T10 | `inverted()` stops stripping | −8 | 1 |
+| T11 | ADD/REMOVE advice swapped | +4 | 2 |
+| T12 | `pv_invert_entities: []` deleted from `options:` | −25 | 2 test_translations + 17 probe |
+| M2 | `stray_inverts()` roster ignores `pv_entity` | +15 | 2 (REPORTED CASE, PADDING) |
+| M5 | `_read_pv()` flip set not stripped | +25 | 1 (PADDING) |
+
+## 5. History
+
+OPT-10's `sensor.goodwe_pv_power` recorded since 2026-09-24 on an install with
+such sensors carries the old sign; nothing rewrites it.
+
+## 6. CHANGELOG entry for the next PKG cut
+
+Not written into `CHANGELOG.md`: `test_version_gate.py` 11b/11d refuse an
+`## Unreleased` heading (measured on this branch: 4 reds). For PKG to paste:
+
+> **`pv_invert_entities` (TEL-14).** A PV sensor that reads negative while
+> producing — typically a kWh meter or power clamp in the PV circuit — can now
+> be listed under *PV entities whose sign is reversed* in the Configuration tab;
+> its sign is flipped before the sum and the status page marks it. Empty (the
+> default) changes nothing. ⚠️ PV history recorded before you set it keeps the
+> old sign.
@@ -148,6 +148,11 @@ exits 78 and the panel goes with it. Recovery is the Configuration tab. That is
 the reason it stays, and the reason the panel refuses to write a blob the
 validator rejected: this surface must never be the thing that removes itself.

+*Amended by [[UX-15-setup-only-mode]] (2026-09-28):* one refused configuration
+keeps the panel: options that name no inverter at all and have no other
+refusal, which is what a new install ships. The add-on then serves the page in
+setup-only mode and commands nothing. Every other refusal still exits 78.
+
 **The panel shows fewer refusals than the startup gate can, never more.** Two
 of `validate.py`'s rules compare a configured ceiling against the setpoint
 device's *own* reported range, which is only knowable by asking Home Assistant.
@@ -0,0 +1,92 @@
+# UX-08 phase 2a: short notifications, and what moved out of them
+
+The owner decided on 2026-09-27: a title of at most about 5 everyday words and a one-sentence body. A red safety alarm may use up to 3 sentences, so no action-relevant information is lost. Titles are neutral, with no "GoodWe:" prefix. HA entity ids appear only in refusals. The rule is `STYLE.md` at the repository root, the texts are in `app/messages.py`, and `test_messages.py` enforces both. The detail each notification used to carry is in DOCS.md under "Notifications", and the body links to it.
+
+**Unchanged:** every `notification_id`, every trigger and cadence (edges, SAFETY-34 re-announce, per-unit ids), every log line and every status row. The status banner and rows are phase 2b, refusals and option texts 2c, logs 2d; `ux08_allowlist.txt` lists them until then.
+
+## Where a choice was made
+1. **Severity of "not delivering" (SAFETY-42).** The notification is an *alarm*, so it may use 3 sentences. Its log line is ERROR and the alarm is latched. The page banner stays amber, as SAFETY-42 decided, because control keeps running; the two answer different questions (is control running / must a person act) and HA shows no colour on a notification. The three checks stay in their original order. Clearing it takes stop then start, and the body says so.
+2. **Figures left the bodies** of the frozen-meter card (the rail and the command), the circulating-power card (the watts and the time window) and the peak cards (the projection). None of them is needed to act, and all of them are still in the reason text that the log line and the status row carry. `test_freeze.py` and `test_watchdog.py` now pin that. The frozen-meter card can therefore no longer quote a wrong rail (SAFETY-20), because it quotes none.
+3. **The over-rating alarm keeps its numbers** (asked, sent, and which limit cut it), because they are what a fault report needs. `ClampWatchdog.facts` carries them under the same keep-the-bug rule as `reason`, so the words and the numbers always describe the same tick, with asked before sent (SAFETY-40, `test_clamp.py` part 6).
+4. **SAFETY-25 stays in the peak-reserve alarm** as its last sentence ("the reserve only limits peak shaving … down to its cut-out level"). The alarm now gives each branch its own action: at the reserve, lower it; battery level unread, check the sensor; floor unknown, set the cut-out level. That last branch is `soc_floor is None`, which happens when an inverter's cut-out level is missing, not the peak reserve (that option always has a value). Before, every branch said "lower peak_soc_floor". The title, "Battery stopped limiting the peak", is true on all three branches.
+5. **SAFETY-32 at a roster of one.** The body no longer ends in a separate "WHICH PACK" paragraph. The pack's name is part of the first sentence ("The battery of inverter-b …"), and at a roster of one that is the only difference.
+6. **Dropped as background, now in DOCS:** "charging stays blocked" (peak reserve), "why no other guard fired" (circulating power, not delivering), and the saturation-freeze distinction (over-rating). "The meter cannot see this" stays in the circulating-power card, as the owner asked.
+7. **The Details link** opens the add-on's documentation page (`/hassio/addon/<slug>/documentation`, with the slug taken from the container hostname) and names the section. A `#heading` anchor was not used because nobody has checked that Home Assistant's documentation tab renders heading ids; if it does, adding one is a one-line change. Outside an add-on container it names the section without a link.
+
+# Phase 2b: status rows and page banners
+
+Every row of the Commissioning list and every banner is now in `app/messages.py` (`row_*`, `banner_*`), and `test_messages.py` checks a rendering of each. The row and banner kinds are gone from `ux08_allowlist.txt` (200 → 168 entries). DOCS.md "Status page" explains the rows. **Unchanged:** every row's colour (ok / warn / bad), which rows show when, and the banner cascade order.
+
+## Where a choice was made
+1. **A red row may use 3 sentences (30 words).** STYLE.md gave rows 15 words; the owner allows red safety states 3 sentences. A red row needs room for what happened, the state (0 W) and how it clears. STYLE.md now says so, and the test applies it by colour.
+2. **Figures left the rows, not the product.** The reason texts (freeze, sign, circulating, delivery, peak guard) carry reason codes and limits; they stay on the ERROR/WARNING log line and the event list, as before. Rows keep the numbers a reader acts on: the stall age and the 0 W deadline, the meter age and limit, asked and sent for an over-rating, the peak limit, and "opposite for 12 of 60 seconds" while a check counts. So 2a item 2 ("also on the status row") no longer holds, and DOCS.md says "in the add-on log".
+3. **No entity id on any row**, even the green ones that used to print `sensor.x = 54`. The sensor rows name the setting (*Battery power for inverter-b*). Solar sources are numbered in the order of the settings list (*source 2 of 3*, *entry 1 of the reversed-sign list*). This retires TEL-12's rule that a one-entity site reads 0.11.0's sentence byte for byte. A `tools/tel11_pv_trace.py --compare` against a pre-UX-08 tree therefore shows the PV rows as changed telemetry, and the control documents stay equal. The per-source watts and units left the multi-source row. The total, the count and which source is missing remain.
+4. **UX-07 item 1.** `ClampWatchdog` now also counts `over_rating` and `bound` separately. After an episode, each count shows under its own alarm's title ("Power request too high: 2 times since start, not now", "Battery is not keeping up: …"). A site with both gets two amber rows where it had one.
+5. **The "Not ready" banner** is the first red row's own `banner`, or else its first sentence. The peak-reserve and over-rating rows set `banner` to their notification title. The three trips keep their own banner branches, reworded (e.g. "Inverters worked against each other. Every inverter is set to 0 W.").
+6. **How a latch clears stays on the row**, shortened: "Only starting control clears this", "A restart does not clear this", "only stopping and starting control clears this" (not delivering). SAFETY-25's sentence stays on the peak-reserve row.
+7. **Rows got an `id`** (`meter_frozen`, `direction`, `pv`, …), so tests find a row by what it is, not by its words. The page ignores it.
+8. **Left for later:** texts that rows embed from other modules and that were not flagged as rows (the month-peak line, `peakguard.explain()`, the liveness and stale notes, `shadow.banner()`). The month-peak row only lost its semicolons.
+
+# UX-09: fixes after the phase 2a test
+
+1. **The Details link follows the Home Assistant version.** HA 2026.2 added the built-in `app` panel (core #157554, frontend #28245), whose add-on pages are `/config/app/<slug>/documentation`. 2026.5 stopped registering the `hassio` panel, so `/hassio/addon/<slug>/documentation` is a 404 there (TEST-23, HA 2026.9.1). 2026.1 and older have only the old path. The one path valid on both, `/_my_redirect/supervisor_addon?addon=<slug>`, opens the Info tab, not Documentation. So the add-on reads its slug (`GET /addons/self/info`) and the HA version (`GET /info`) at start, and picks the path. An unknown version gets the current path. The hostname stays as a fallback for the slug. Phase 2a item 7 is replaced by this.
+2. **Shadow mode says "would".** The over-rating alarm and row said "sent X W" while 0 W was on the wire, and the peak alarm said "the battery is giving all it can". Both now take `shadow=`, and in shadow mode say what would have been sent and that the inverters stay at 0 W. Severity, id and cadence do not change with the mode.
+3. **"Controller" is gone from texts.** "The add-on" names who decides, and "control" names what it does, as in the existing "start control". The add-on is what the reader sees in Home Assistant, and "controller" was easy to confuse with the control board.
+4. **One term per setting, matching its label.** Four labels changed instead of the texts, because the texts' words were plainer: “Peak reserve (%)” (was "Peak guard will not discharge below"), “Battery level entity (%)” (was "Battery charge level"), and “Solar production entity / entities, per inverter / Reversed-sign solar entities” (was "PV …"). The Dutch labels already said "Zonneproductie". Option descriptions are phase 2c and were not changed, so some still say "PV".
+5. **The shadow banner and the inverter notes** are now `messages.banner_shadow()` and `row_no_setpoint` / `row_not_controllable` / `row_commands_refused`, so `test_messages.py` checks them. The red shadow banner no longer lists the latches, because 12 words cannot carry them. It says a safety stop stays on, and each latch keeps its own red row, which names it and says how it clears. The colour of a liveness row now comes from `is_live()`, not from matching "NOT COMMANDABLE" in the text.
+6. **DOCS "Notifications" and "Status page"** are written for a home owner, and the card ids, keys and log detail moved to a "For installers" part of each.
+
+# UX-08 phase 2c: refusals, error texts and option texts
+
+Validator refusals, the parse errors they carry, and every option name and description are now short. No rule, key, schema, default or exit code changed. Over 36 spoiled configurations the old and new validators refuse the same number of times. The allowlist went from 167 entries to 43, and only log lines (phase 2d) remain on it.
+
+1. **A refusal names the setting by its label and then its key**, as `messages.setting()` writes it: “Inverter rating” (max_w). The key has to stay, because `configui.problems_by_field()` shows a reason beside every key its text names. A test checks each label against en.yaml. A few reasons no longer mention keys they only named in passing, such as `price_markup_eur_kwh` in the withdrawn-provider reason, so the panel shows those reasons beside fewer settings. Each reason still names the setting that fixes it. A setting of one inverter in the list is written “Inverter rating” for inverter-b (inverters.max_w), so the panel shows it beside `inverters`, where that value is changed, and not only beside the flat `max_w` that a list does not read.
+2. **Citations moved to DOCS.** Option descriptions say "Measured value, leave it unchanged" or similar, and the record behind the value is under "For installers: where the numbers come from". The UX-01 citation check in `test_translations.py` now checks the tab for that instruction and DOCS for the record.
+3. **What left the refusals:** the shipped default in the peak-reserve reason, the superseded-default note in the levy-table reason (DOCS already covers it), the endpoints of the withdrawn providers (DOCS "Energy price providers"), the plant measurement behind `slew_w` (DOCS, beside the setting), and the leg-specific paragraphs of the tariff-formula errors. Each reason keeps the rejected value, the limit and what to change.
+4. **Not rewritten:** errors that only a code defect can raise, such as plugin-contract and argument-type checks in `price.py`, `price_forecast.py`, `static_tariff.py`, `arbitrage.py` and `main.py`, which a home owner never reads. INFO lines such as the tariff-formula preview were also left.
+
+# UX-08 phase 2d: log lines, the rest of the status page, and DOCS
+
+The allowlist is empty and its cap is 0 (43 → 0). Every WARNING and ERROR line is one plain line of at most 25 words, with no card ids, capitals or semicolons (the semicolon rule now covers log lines too). **Unchanged:** every log level, every trigger and cadence, every notification id, every row's colour and when it shows, the banner cascade, and every refusal count.
+
+1. **No code prefixes on log lines.** Nothing outside the repositories greps them, except `/home/homelab/clampwatch.sh`, a one-off site watch from 2026-09-05 that greps `OUTPUT_CLAMP` and `Engagements so far`. `OUTPUT_CLAMP` is still in the reason the line quotes; "Engagements so far" is now "Cut back N times so far". The tests that found a line by its card id (`SAFETY-37`, `SAFETY-44`, `CONTROL LOOP DIED`, `UNGRADED`) now find it by its words.
+2. **Reason texts keep their codes.** A line quotes a watchdog's reason (`%s`), such as `STALE_READING: …` or `OUTPUT_CLAMP: …`. Those are the evidence an installer searches for and many tests pin them, so they were not rewritten. The line around them is plain.
+3. **Reasoning moved to DEBUG, not deleted,** for the 10 lines marked DROP-to-DEBUG (for example the 14 768 W history behind the over-rating alarm, why SAFETY-42 reports and does not act, and the Eneco card advice). The 25-word line keeps the action and the numbers. SAFETY-57's promise stays on the ERROR line, as an ordered pair: "until it changes, or 17 s after the command drops below 250 W".
+4. **The line under the buttons** showed the newest raw action-log entry (`OUTPUT_CLAMP …`, `FAILSAFE …: SIGN_DISAGREEMENT`, `ALLOCATOR …`). Each `log_event()` call now also names a plain hint from `messages.HINTS`, and the page shows that. The action log itself is unchanged, because tests and later analysis read it, and the page no longer shows it. It stays reachable as `events` in the `status` JSON (review of #136), because some entries are written nowhere else: a dropped inverter's reason, the unplaced watts, the peak guard's projection and the shadow decision.
+5. **The top table.** *Why* is `messages.why()`: the arbiter's winner and limit in words ("Keeping the grid near zero: 440 W, held back by the peak limit"). `self.reason` keeps `Resolution.explain()` for the log and the checks. *Tariff*, *Price history*, *Arbitrage* and *Shadow mode* keep every figure TARIFF-11 and SAFETY-47 put there, each in its own slot, in words. Labels: *Battery level*, *Solar production*, *Power request*.
+6. **The month-peak row became two rows**, because one sentence of 15 words cannot hold the peak, its time, its share of the limit and TARIFF-13's coverage figure. The store's state at start (`restore_state`) left the row: it is the INFO line at start.
+7. **The peak guard rows** name the projection first and the limit second, as before (SAFETY-38). The blind row says what it means for the owner: the battery does not charge until the period can be measured again.
+8. **Wording that changed meaning-carrying words**: "command and meter point opposite ways" is now "the power went the wrong way" (banner) and "…went against what the add-on asked" (row). The N=1 banner still names the meter, the N≥2 texts still say "own power". The inverter range reads "up to 5 000 W each way" instead of "-5 000 W to 5 000 W".
+9. **Refusals are counted as shown.** Setting placeholders are expanded to label and key, and the long cases the 2c test found are driven through the validator. Seven refusals were shortened. The card refusals no longer show `c_eur_per_kwh`, `vat_pct` or "its own card", and a text that does not parse says "not valid near character N" instead of the parser's words. A missing value shows as *empty*, not `None`.
+10. **The panel's key match** no longer files `inverters.max_w` under the flat `max_w`.
+11. **The Supervisor question at start** is one INFO line with a real reason (a timeout's own text is empty, so the error type is named).
+12. **DOCS**: a glossary ("Words used on this page") explains control board, isolator and Developer Tools once. Card ids left the headings and sit on a *For installers* line under each. The links to the renamed headings were updated.
+
+# UX-10: the last plain-language leftovers (after the 2d test)
+
+**Unchanged:** every safety behaviour, every alarm's log level (WARNING and ERROR stay), every notification id, trigger and cadence, the banner cascade, and every row colour except the meter row right after a start (item 6).
+
+1. **Why the 2d scan missed the clamp lines.** Part 3 reads a log call's own literal and counts `%s` as one word. The clamp lines are `"…software fault: %s …"`, and the text in `%s` was built elsewhere, by `loop_clamp_note()` and `ClampResult.describe()`. So the scan passed a line whose logged text had a semicolon, "BUG SIGNAL", "clamped" and "1 times". The same was true of every quoted reason. Part 6 closes the gap. It lists every dynamic part of every WARNING+ line as data (a number, a name, a path, a library's own error text) or as a built text, and a new part in neither list fails. Each built text is produced by the real code (the watchdogs, `decide()`, `loop_clamp_note()`, `MigrationReport.explain()`) or, for a family of builders, by every template of it (`PriceRead.no_data`, `Gate.block`). The text and the line as logged are then checked. A mutation shows the 2d clamp text is caught on both clamp lines.
+2. **A quoted reason gets the red-alarm shape**, 3 sentences of at most 30 words, and not the 25-word line limit. It is the evidence behind an alarm, and it keeps its code and its limits, which the owner asked to keep. The alarm shape is STYLE.md's existing rule for the texts behind a safety stop, so no new limit was made up. Rewritten: `OUTPUT_CLAMP` (both kinds), `METER_FROZEN`, `CIRCULATING_POWER`, `STALE_READING` (SAFETY-56's two explanations and "cannot tell which" kept, in order), the peak guard's reasons, the state-migration report, the price feed and price history reasons, and the maintenance and trading gate reasons. "Software fault" left the clamp reason, because the ERROR line around it already says it.
+3. **Codes are one token.** `PEAK GUARD`, `PEAK GUARD FLOOR-LIMITED` and `PEAK GUARD BLIND` read as capitals, so they are now `PEAK_GUARD`, `PEAK_GUARD_FLOOR_LIMITED` and `PEAK_GUARD_BLIND`, like `OUTPUT_CLAMP`. Nothing in admin/goodwe or in the scripts under `/home/homelab` greps them (checked). `/home/homelab/clampwatch.sh` greps `OUTPUT_CLAMP`, which stays.
+4. **Top table.** *Price history* writes "96 prices over 24 hours for 26 Sep", joined by commas. *Tariff* writes the spacing as "one every 15 minutes or every hour". "Not final yet" was dropped, because a plan is provisional exactly when it holds an estimated price (`n_carried` counts the provisional points), so the estimated count already says it.
+5. **Levels and noise.** The shadow line of every cycle is DEBUG, and "Shadow mode is on/off" is INFO: it follows a setting or a button, and the banner, hint and event are unchanged. aiohttp's access log is on only at log level debug. A settings warning is logged once per start (a filter on `goodwe.config`, WARNING only, so refusals are untouched), because the validator runs twice at start. When Home Assistant restarts, `hass.Outage` says so in one WARNING line for the REST API and the meter websocket together, puts the library's text on DEBUG, and says at INFO when both answer again. INFO lines lost "§8.3", ISO timestamps, "banked" and "keys ARE", and error texts lost "NOT_OBSERVED", "did NOT land" and "AND".
+6. **Display bugs.**
+   - "Why: Other" during a latched per-inverter stop: `main.py` turns a safety winner into its claim's reason, and "sign disagreement" (and "unsplit", main.py's own refusal to split) had no entry in `WHY_WINNER`. The mapping is now `main.why_key()`, and part 7 finds every `Claim.set()` in the code and checks that every key it can produce has words.
+   - Red "Meter: no reading for 0 seconds" after a restart: until the first reading arrives, `P1Ingest.stale` is true, and the age is the time since start. The row now reads amber "waiting for the first reading" while that age is inside the limit. **Colour change, justified:** red at 0 s contradicted the limit the same row prints, and once readings exist the row is red only past that limit. Amber, not green, because control waits for the reading. Past the limit it is red as before. `stale` itself, which gates control, is unchanged.
+   - "A reading is missing for 0 seconds" stuck at 0: with the meter reading gone, the grid value stops changing, so the loop runs a cycle only every `cycle_floor_s`, and the line was computed once per cycle. The age is now counted when the page asks. The hold and its 15 s escalation are unchanged.
+7. **Review: the line as logged gets the shape too.** Part 6 first checked the quoted reason alone, so a title, a 2-sentence reason and two tails still logged as 4 sentences ("Power request too high …: OUTPUT_CLAMP: … +5000 W. The command this cycle was +1000 W. Control is still running. Cut back 1 time so far."). Part 6 now also checks the whole line: at most 3 sentences, none over 30 words. The wrappers became one sentence each, the circulation and peak guard reasons two, and `STALE_READING`'s fixed limits moved from the reason to a DEBUG line beside the ERROR (its release clause stays, pinned by test_freshness). The clamp lines for one inverter are pinned at 30 words at most: `OUTPUT_CLAMP: computed +9000 W, cut to the +5000 W rating, command now +2000 W`. Several clamped inverters read as one sentence of asked/sent pairs; which limit bound each is on its own action-log row and in the notification. Totals above 30 words remain on the direction, delivery, frozen-meter and stale lines (up to 74 words). Shortening them is a follow-up: the direction and delivery reasons are also persisted in state.json, and the direction one is pinned byte-for-byte in test_watchdog.
+8. **Home Assistant 400 while it loads** now reads "Home Assistant refused number.set_value for number.x (error 400, no details). The entity may still be loading, or the value is out of range." A body with more than "400: Bad Request" is still quoted. Still WARNING, still once a minute, still a failed write.
+9. **Witness** (admin/goodwe): the resolved push says "after no answers from … to …", as the resolved card does. The YAML with every title and message stripped is identical.
+
+# UX-11: safety log lines give the code, the figures go to DEBUG
+
+**Unchanged:** every trigger, latch, threshold and alarm log level (the WARNING and ERROR lines stay), every notification id and cadence, every row colour and the banner cascade. No notification is added.
+
+1. **One plain sentence and the code.** A WARNING/ERROR line that reports a safety reason (direction, delivery, stuck meter, stale reading, peak guard, circulation, over-rating) now ends in the reason's code, taken by `messages.reason_code()`. The reason itself, figures and limits included, is on a DEBUG line logged right after it ("Evidence for inverter-a: …"), and the action log entry carries it as before. Part 6 checks that pairing in the code. Circulation and the clamp lines were not among the five named, but they break the same 25-word rule, so they follow the same pattern. The clamp numbers stay in the notification (phase 2a item 3).
+2. **The reasons and `state.json` are unchanged.** `reason` stays the evidence text, so what is saved has the same format as before. An old state file therefore loads and displays like a new one: every saved reason has opened with its code since it was first written (checked in the git history), and that code is all the ERROR line reads. The saved text goes on the DEBUG line. A stop saved without a reason shows `REASON_NOT_SAVED`. `test_messages.py` part 7 restarts from a state file holding the old long texts. `test_watchdog.py` pins the meaning (the code first, then command, reading, time and both limits, in that order) and, since the text did not change, still the bytes.
+3. **The 25-word rule is checked as logged.** Part 6 fails any WARNING+ line over 25 words with its built text filled in. Nine non-safety families still run long (tariff plan words, price feed reasons, the state migration report, write refusals and claim scope errors that only a software fault raises, maintenance, trading gate and price history reasons). They are listed with a reason in `LONG_LINE_OK`, capped at 9, and a listed family that gets shorter fails until it is removed. Shortening them is a follow-up.
+4. **The meter row's "the add-on log shows why" is now true.** When the meter goes quiet past its limit, the add-on logs one WARNING per episode, not one per cycle, and an INFO line when readings return. A meter that flaps (on `ha_signed` a healthy meter under a flat load can go 42–97 s between changes) logs at most one such pair per 10 minutes, and the episodes in between go to DEBUG. This is a new log line, not a new alarm: it has no notification and changes no decision.
+5. **The Why line past the 15 s hold** names the missing reading ("No usable meter reading for over 15 seconds: 0 W", or the battery power or level of an inverter), instead of "A reading is missing: 0 W".
+6. **Action log:** "25 engagement(s)" is "25 engagements", and "SHADOW MODE OFF - …" is "Shadow mode off: …". "SHADOW MODE ON" was not named in the card and is left as it is.
+7. **Review: after a restart the figures go on the action log too.** `log_level` defaults to `info`, so the DEBUG evidence line is not seen by default, and `events` starts empty. Each restored stop (direction per inverter and site, delivery, circulation) now also writes its saved reason to the action log ("FAILSAFE inverter-a, saved before the restart: …"), and the page's event line gets the same plain words the live stop gives. `LONG_LINE_OK` also refuses a key whose text is a safety reason, not only a `reason_code` key.
@@ -0,0 +1,104 @@
+# UX-13 — one layout table, and why UI code may now name an option key
+
+**Status: DECIDED 2026-09-27 (owner approved the UX-13 design and mockup).**
+Card 6ab979852f3eca02fb40f69e. Amends [[UX-02]] §3.1. Design note and
+mockup: `goodwe-session/UX-13-design.md`, `UX-13-mockup.html`.
+
+## 1. What UX-02 said, and why it no longer fits
+
+UX-02 built the configuration panel from the Supervisor's schema, so
+`app/configui.py` contains "no option key, no label and no rule", and
+test_selfconfig.py part 5 checks that the page script names no key. That kept
+a second copy of the option surface from drifting, and it is why the panel is
+a flat list of fields in schema order.
+
+UX-13 needs things a schema cannot say: groups and sub-groups, a slider in kW
+for a value stored in W, a picker for an entity, a field shown only for one
+meter source, locked measured values, a Simple view and a setup wizard. It
+also needs page fields that are not options at all: one inverter card that is
+stored as six flat keys, solar rows that become `pv_entity` or `pv_entities`,
+a contract and two prices that become `static_profile` JSON, and a region
+that becomes the levies figure. None of that can be read off the schema, so
+some code has to name option keys.
+
+## 2. The decision
+
+Option keys may appear in UI code in exactly two files:
+
+- **`app/uilayout.py`**, the layout table: screen → group → part → field, with
+  control, unit, display scale, step, entity kind, when it is shown, whether it
+  is on the Simple view or a wizard step, and whether it applies now or after a
+  restart. Every option in `config.yaml` is a field, `DERIVED` or `HIDDEN`,
+  exactly once.
+- **`app/uimodel.py`**, the derivations the table names: `options_to_ui()` and
+  `ui_to_options()`. It may name only the keys it writes.
+
+What UX-02 made authoritative stays authoritative:
+
+- **Ranges** come from the schema (`uilayout.range_of()`); the table writes
+  none. A unit holds no digit.
+- **Labels and help** come from `translations/*.yaml` by key. Page-only fields,
+  group titles and choices are in `app/ui_text/*.json`, held to STYLE by
+  test_messages.py.
+- **Rules** stay in `validate.py`. It gains a warning tier (`validate.Note`,
+  "warn" or "info") for the page. A note never blocks a save, and passing the
+  notes list does not change the refusals returned.
+- **The stored blob** is still the one truth. The page model carries the stored
+  values of every derived key (`keep`). A derivation whose page fields are
+  unchanged writes those values back untouched, so a blob the page cannot
+  express survives a save of another field.
+
+## 3. How it is held
+
+- test_uilayout.py fails when `config.yaml` gains an option, or an inverter
+  field, that the table does not place. It also checks that uimodel.py names
+  only the keys it writes and that web.py and haentities.py name none.
+- test_uimodel.py round-trips options → page model → JSON → options for every
+  validator call the suite made at 652097a (`scenarios/ux13/`), the TEST-23
+  option files and config.yaml's defaults. All must be identical.
+- `tools/ux13_validator_calls.py compare` runs those calls through the old and
+  new validator. At P0: 261 calls, 158 refused, no refusal changed.
+- test_selfconfig.py part 5 still checks the old page script; P1 moves the page
+  into `app/static/` and the same check applies there.
+- P2: the Installer view (`app/static/settings.js`) draws from
+  `app/uipage.py`, which serialises the table and names no key itself
+  (test_uilayout part 5, test_settings part 2). The view posts its page model
+  to the existing `/config/validate` and `/config/save`, which turn it into
+  options with `ui_to_options()` before the shipped validator runs. No route
+  was added.
+- P4: the setup wizard draws the same model by each field's `wizard` step.
+  Its tables (`KETTLE`, `SHADOW`) are in `uilayout.py`, and its live checks
+  are rules, so they are in `validate.py` (`setup_checks`). settings.js still
+  names no key. See [[UX-13-setup-wizard]].
+- P5: the page words are in `app/ui_text/en.json` and `nl.json`, one key set,
+  loaded by `app/uitext.py` with an English fallback per key. The page picks
+  Dutch when the browser's language is `nl`, as the classic page does. Home's
+  sentences moved from `homeview.py` into `home_words`, so `/status?lang=nl`
+  builds them in Dutch. Status rows, banners, hints and validator sentences
+  (`messages.py`, `validate.py`) stay English: they are shared with
+  notifications, the log and the start refusal. `test_ui_text.py` checks both
+  files against STYLE.md and each other, using the rules in
+  `tools/style_rules.py`, which it shares with test_messages.py.
+- P5: "Other time windows" is a list editor (`ui.periods`, control
+  `period_list`). `uimodel._periods_json()` builds `static_profile` and names
+  the first bad time, empty price, overlap or gap. Its tiling rule matches
+  `static_tariff._check_tiling`. A stored profile whose days the editor has no
+  choice for (for example "mon,wed") is still kept as stored and edited in the
+  Configuration tab. Supervisor 2026.08.0's `AppOptions` accepted all 133
+  wizard blobs, 17 of them with time windows
+  (`tools/ux13_wizard_blobs.py --supervisor`, run offline on 2026-09-28).
+- P3: Settings, Simple draws the fields the table marks `simple`, with an
+  optional `note` under each (words in `settings.simple.note`), plus the
+  batteries' switches and modes. Those are store state set through the
+  existing `/action` values, not options, so the table places no key for
+  them. The Batteries screen's Now, Today and Why lines are built in
+  `homeview.py` from what the add-on knows this cycle; the plan per mode is
+  OPT-11 P3/P4, so until then Today says "Not planned yet" when no block
+  is planned for the battery (`test_batteries_screen.py`).
+
+## 4. What this costs
+
+The table is a second place that knows the option surface, which UX-02 set
+out to avoid. The cost is bounded by the coverage test: an option added to
+config.yaml and not placed here fails CI, rather than silently missing from
+the page. Changing a key's type or range needs no change here.
@@ -0,0 +1,101 @@
+# UX-13 P4 — the setup wizard, and when it opens by itself
+
+**Status: DECIDED 2026-09-28 (P4 dev; the design and mockup were approved
+2026-09-27).** Card 6ab979852f3eca02fb40f69e. Builds on
+[[UX-13-one-layout-table]]. Design note: `goodwe-session/UX-13-design.md` §1, §3.6.
+
+## 1. What the wizard is
+
+The Setup tab draws the Installer view's page model one step at a time: a
+field is on step *n* when its `uilayout.Field` says `wizard=n`. It uses P2's
+controls, `/config/validate` and `/config/save`. No route was added.
+`uilayout.py` holds what a field cannot say: the kettle table (`KETTLE`), the
+optional step and the shadow switch (`SHADOW`). Step 5 has no battery modes
+yet (OPT-11); it says they come later.
+
+A step moves on when no refusal is anchored to one of its shown fields
+(`uipage.step_problems`). A refusal on a hidden field, a field on no step or
+no field at all blocks the last step, which lists every refusal.
+
+## 2. When it opens by itself (`uipage.setup_needed`)
+
+The page opens `#setup` only when it is opened with no route, and only when
+`/config/model` gives a reason:
+
+- **`no_power_request`**: the stored options name no inverter to control.
+- **`first_start`**: this boot found no `/data/state.json` (`Store.fresh`), the
+  Store has no `setup_done` and no `auto` key, and control is not started.
+  `auto` is the key Start/Stop writes. Neither the startup gate's exit 78 nor
+  setup-only mode (UX-15) writes the Store, so a new install's first good boot
+  is fresh.
+
+"Never started" alone is not enough: both TEST-23 add-ons have `auto_start`
+off and no `auto` key, and one has run in shadow for weeks (review of PR #146,
+R1). So a Store read from a file is an old site, and it is never sent to the
+wizard. A new install that restarts before the page is opened is not sent
+either, and its Setup tab still works. A site that runs control, or ever
+started or stopped it, is never sent. Without a Store the answer is no. The wizard's save writes
+`setup_done` (an ISO time) to the Store. A save from the Installer view does
+not.
+
+**Decided since, in [[UX-15-setup-only-mode]] (owner, 2026-09-28):** a
+brand-new install ships `setpoint_entity: ""`, and it no longer exits 78. When
+naming no inverter is the gate's only refusal, the add-on serves the page in
+setup-only mode, which commands nothing, and the wizard opens with
+`no_power_request`. Setup-only mode writes no Store file, so the first-run
+rule above still holds for an install set up on the Configuration tab.
+
+## 3. The kettle test and the sign checks
+
+Step 1 reads the meter's entities now (`GET ha/entities?entity=`, one
+`hass.state()` read, in W) before and after a kettle is switched on. The
+change, not the sign, decides: a rise of at least 500 W keeps `meter_invert`
+off, a fall turns it on. For a net entity or import and export, a fall cannot
+be fixed by an option, so the step is not passed and the page says what to
+check. A meter the add-on reads itself (HomeWizard, MQTT) cannot be read by
+the page, so the test is skipped and Home shows the direction after the
+restart. The installer may skip the test, because a cloud can fake a fall;
+the last step then warns, and after a fall it says the reading went down.
+
+The battery and solar signs cannot be forced from the page, which never
+commands an inverter. The last step reports each battery's reading with its
+direction ("reads 800 W charging now, so check the inverter shows the same")
+and warns when a solar entity reads below zero without its "reads negative"
+switch. It also warns when meter + solar + battery, all known, add up to a
+house using less than -300 W: a battery sensor reversed while giving power.
+An idle or charging battery cannot be judged that way.
+
+## 4. The last step
+
+`validate.setup_checks()` sits beside the rules because it names option keys.
+It reads nothing itself: `web.py` passes a Home Assistant entity list at most
+5 s old, the running options, the running meter reading and today's price
+count. Tiers are ok, info, warn and bad. A power request entity missing from
+Home Assistant is **bad**, because a write to it is answered 200 (SAFETY-77)
+and only the entity list can tell. So is Home Assistant not answering, since
+the list is then unknown. The wizard does not save while anything is
+bad. It then saves through P2's path (`setup: "done"`) and asks for the
+restart as the second, confirmed request, with a dialog that names the 0 W.
+The shadow switch is on by default and writes `shadow_mode: on`, which holds
+every inverter at 0 W after a restart even if control is started. Off keeps the
+stored value, or `auto` if that was `on`. The switch goes only on the model the
+wizard posts, never into the page model the Installer view also saves.
+
+## 5. The stale save lists only what moved (P2 test, finding a)
+
+`/config/model` remembers the last 16 blobs it handed out, by fingerprint. On a
+stale save the add-on compares that blob with what is stored now, so the banner
+lists only the other surface's changes. `changed` (stored against the posted
+blob) is unchanged for the classic page's "theirs → mine" list. When the
+fingerprint was not handed out by this process, it falls back to `changed`.
+
+## 6. How it is held
+
+- test_setup.py: the steps and tables, the kettle logic (and the page's copy of
+  it), step blocking, the first-run rule on new and TEST-23 sites, the live
+  checks, the save through the P2 path, the stale fix, and the words.
+- tools/ux13_wizard_blobs.py produces every blob the wizard can save from a new
+  install and three TEST-23 sites (88 accepted by the shipped validator).
+  UX-15 added the shipped defaults as a start (setup-only mode). At P4
+  all 88 were accepted by Supervisor 2026.08.0's `AppOptions`, offline, 78
+  keys each.
@@ -0,0 +1,114 @@
+# UX-15 — setup-only mode: a new install serves the wizard
+
+**Status: DECIDED 2026-09-28 (owner decision; UX-15 dev).** Card
+6aba0053d27a32cb3f210dcc. Changes the CFG-01 startup gate and closes the open
+question in [[UX-13-setup-wizard]] §2. Amends [[UX-02-two-config-surfaces]] §4.
+
+## 1. The rule
+
+`config.yaml` ships `setpoint_entity: ""`, so a new install's options are
+refused by rule 1 of `validate_startup_config()`: no inverter to control.
+Until now that was exit 78 before any page was served, and the installer had
+to fill in the entity on the Configuration tab before the wizard could open.
+
+The add-on now starts in **setup-only mode** when, and only when
+(`setuponly.applies()`):
+
+- the options name no inverter at all: no flat `setpoint_entity` and no
+  `inverters` entry, and
+- rule 1's refusal (`no_power_request_problem()`) is the gate's **only**
+  refusal.
+
+In setup-only mode it serves the page, says it is in setup (banner, `/status`
+`setup_only: true`, a WARNING log line) and opens the wizard when the page is
+opened with no route (`setup_needed` is `no_power_request`). After the
+wizard's save and restart the normal gate applies to the saved options.
+
+## 2. What still exits 78, and why
+
+Everything else the gate refuses, including:
+
+- a complete configuration that is refused, e.g. `maintenance_charge_w` above
+  `max_w`;
+- no power request entity **and** any other refusal;
+- an `inverters` list whose entry has a blank power request entity.
+
+These are configurations somebody edited. The Configuration tab stored them,
+the log's refusal banner names each problem, and the tab is where they are
+fixed (UX-02 §4). Serving the wizard there would put a six-step setup in
+front of someone who needs to change one field. A narrow rule also keeps the
+setup-only decision to one comparison against one known sentence, so a new
+validator rule cannot widen it by accident: any other refusal fails the
+equality and exits 78.
+
+The cost: an installer who first sets, say, a DSMR meter with no entities on
+the Configuration tab and leaves the power request entity empty gets exit 78,
+not the wizard. The log then names both fields.
+
+## 3. Why it cannot command
+
+Setup-only mode builds nothing that commands. `amain()` branches to
+`setuponly.serve()` before the MQTT broker, the controller, the meter task and
+the tariff task are built, and it returns from there when the Supervisor
+stops it. What serves the page is `SetupOnly`, which holds no inverter.
+
+Three checks make it structural rather than a convention:
+
+1. **The HomeAssistant is read-only** (`HomeAssistant(read_only=True)`).
+   `call()` refuses before it sends anything, and every service call goes
+   through it: `number.set_value` (`set_number()`), notifications, all of
+   them. The flag is fixed at construction, and there is no setter.
+2. **`SetupOnly` refuses a HomeAssistant that can write, and `Controller`
+   refuses one that cannot.** So neither can be built on the wrong one.
+3. **`/action` answers 409** in setup-only mode, before
+   `handle_action()`. Start, Stop and the battery cycle do nothing.
+
+No MQTT client is created, so nothing is published. The page's other routes
+already read only, or write the add-on's own options (UX-02 §6).
+
+Setup-only mode writes no Store file. The wizard's save writes `setup_done`,
+as in any mode. So a new install that is set up on the Configuration tab
+instead still has a fresh Store on its first normal boot, and the first-run
+rule (UX-13 §2) sends it to the wizard as before.
+
+## 4. How it is held
+
+- `test_setup_only.py` part 1: when it applies, including the three exit-78
+  cases above. Part 2: the read-only write path refuses with nothing sent,
+  and the two constructors refuse. Part 3 boots the real `main()` on the
+  shipped defaults against a fake Supervisor and Home Assistant over HTTP and
+  logs every request: the page is served, `/status` says setup-only, Start
+  and the cycle get 409, and there are 0 service calls and no MQTT request,
+  also with `auto_start` on and a Store that says control was started. The
+  wizard's save is then booted: it passes the normal gate, does not open the
+  wizard again, and every write is 0 W (shadow). Part 4: the refused
+  configurations exit 78 and serve nothing.
+- Mutations, each red: `applies()` always false or always true, the
+  read-only refusal removed, the Controller's check removed, `amain()` giving
+  setup-only mode a writable HomeAssistant, `/action`'s 409 removed, and the
+  `return` after `serve()` removed.
+- TEST-23 (PR #147 review, 2026-09-28): the add-on image on the shipped
+  defaults and an empty `/data` made 0 service calls and no MQTT request in
+  3.5 minutes of setup-only mode, counted in both the stand-in and the rig
+  shim logs. The wizard save then passed Supervisor 2026.08.0's `AppOptions`,
+  and after the restart it ran in shadow: 11 of 11 writes were
+  `set_value 0.0`.
+
+## 5. The wizard fixes in the same card
+
+- **F1.** `/config/validate` converts what it can of a page model
+  (`uimodel.ui_to_options_partial()`), so a conversion error blocks its own
+  step beside its field and the live checks still run on the rest. A refusal
+  about a key the failed conversion writes is left out, because it would
+  judge the stored value. The save still refuses such a model (422, with
+  `steps`).
+- **F2.** A save from the page model sends `base`, the model it opened. The
+  add-on writes only the keys whose value differs from `base`, onto the blob
+  stored now (`uipage.only_edits()`). So "save again to keep yours" after a
+  409 keeps the other surface's changes. A key both surfaces changed takes
+  this page's value, which is what the second press after the banner means.
+- **Meter entity.** On the last step a meter entity Home Assistant does not
+  have is red, like a missing power request entity, so a skipped kettle test
+  cannot let it through. In the Installer view it stays a warning.
+- **Step 1 after a skip.** When the kettle test saw the reading fall and was
+  then skipped, step 1 says the reading went down. The skip stays (UX-13 §3).
@@ -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
@@ -734,6 +772,216 @@ Cheap habits fall out of it, and all of them are now used in this repository:
    a no-op, and the mutation that proves the rendering is real belongs on
    `assemble()`, where it is now aimed.

+20. ⚠️ **A FIXTURE GRADES THE RESPONSE. NOTHING ABOUT THE REQUEST IS REACHABLE
+    FROM ONE, AND THE TRANSPORT HAD BEEN RECORDING IT ALL ALONG.** TARIFF-09,
+    and it is habit 19's closed loop with the other half still shut.
+    `generic_dayahead.fetch()` took `since` and `until` and asked for the bare
+    `?bzn=BE`, which answers ONE Brussels day - so §8.3 dropped every hour past
+    today from the trade set as provisional and the optimiser never saw
+    tomorrow as firm, at any hour of any day. Measured at 09:00: **15 firm
+    hours and 33 carried of 48**, both ends of the permitted cycle inside one
+    calendar day; at 23:00, **1 and 47**, with the firm spread no longer
+    clearing the round-trip cost.
+
+    TARIFF-08 had just fixed the RESPONSE side of this same plugin by
+    committing real bytes. It could not have caught this: a captured body is
+    the answer to a URL, and **no property of any body says which URL was
+    asked for**. `canned()` in `test_price.py` had recorded `(url, timeout_s)`
+    on every call since TARIFF-02 and not one check had ever asserted on the
+    first element - so the harness *knew* the plugin was ignoring its arguments
+    and nothing asked it. The fix is one line of habit: **where a plugin takes
+    arguments that shape a request, assert on the REQUEST off the injected
+    transport, not only on what comes back.** Section 2c does, and the
+    shipped-defect mutation (restore the bare URL, `-173 B`) is red on six
+    named checks in `test_price.py` and two in `test_price_history.py`.
+
+    ⚠️ **AND A MUTATION THAT TURNS A READ INTO `no_data` CRASHES A SUITE
+    INSTEAD OF NAMING A CHECK, UNLESS THE CHECK EXPECTS IT.** `_NoData.points`
+    raises `Absence` by design, so `derived(...) < derived(...)` over two
+    absent reads is a `TypeError` and `[p for p in plan.read.points]` is a
+    traceback - habit 5's shape with an exception in place of a hang. The
+    mutation that matters here is the "defensive" one somebody writes after
+    reading this card: *refuse when the feed returned fewer days than we asked
+    for*. It is exactly what a healthy feed does every morning before the
+    ~13:00-14:00 CET auction, and switching arbitrage off for it would be a
+    worse defect than the one being fixed. It is red BY NAME in
+    `test_price.py` (33 checks, the AC's own line among them) and takes
+    `test_price_history.py` down at **FCST-04's section 1**, whose `_before`
+    read is unguarded - a red, but an unnamed one. That is recorded rather than
+    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
@@ -741,6 +989,92 @@ static routing pin catches. The *bound* variant — right actuator, wrong
 numbers — is a different defect with a different fix, and it was absent. Both
 are in the table now.

+## TARIFF-15 — the card-graded formula, mutation by mutation
+
+Twenty-two mutations, one per check the card added, **run** rather than
+reasoned about. Harness: `/home/homelab/.cache/t15-mut/run.py`, backups beside
+it rather than in a shared scratchpad — two agents' harnesses collided in one
+this week. Each run restores from backup, purges `__pycache__` **on the host**
+first, and grades through the CI image with the tree bind-mounted `:ro`, so the
+interpreter cannot write a cache into the tree under test at all (TEST-15's
+structural immunity, borrowed).
+
+**No survivors.** Two entries are `+0 B` and are called out as such, per the
+reporting rule.
+
+| | mutation | file | Δ | red |
+|---|---|---|---|---|
+| M1 | `CARD_TOLERANCE` widened to 100 — the self-check stops checking | `custom_formula.py` | +1 B | **8** |
+| M2 | `CARD_TOLERANCE` tightened to 0 — the other direction, so the tolerance is a number and not a shape | `custom_formula.py` | −1 B | **16** |
+| M3 | `units` becomes optional | `custom_formula.py` | +10 B | 1 |
+| M4 | the `factor == 0` rung removed | `custom_formula.py` | −8 B | 1 |
+| M5 | the `factor < 0` rung removed | `custom_formula.py` | −7 B | 1 |
+| M6 | the `vat_pct` band widened to ±1000 | `custom_formula.py` | +6 B | 2 |
+| M7 | the non-finite rung removed from `_finite()` | `custom_formula.py` | −26 B | 2 |
+| M8 | the non-numeric rung removed from `_finite()` | `custom_formula.py` | −16 B | 4 |
+| M9 | an unknown top-level field ignored instead of refused | `custom_formula.py` | −2 B | 1 |
+| M10 | the plausibility **floor** applied to the all-in figure instead of the energy one | `custom_formula.py` | **+0 B** | 2 |
+| M11 | `hourly` stops averaging and emits the feed's own points | `custom_formula.py` | +12 B | 3 |
+| M12 | the hourly bucket takes the FIRST quarter instead of the mean | `custom_formula.py` | −11 B | 1 |
+| M13 | the preview drops the index column from each row | `custom_formula.py` | −13 B | 1 |
+| M14 | the preview is emitted on every refresh rather than once | `price.py` | −8 B | 1 |
+| M15 | `custom_formula` declares `ALL_IN` — the double-counting lie | `price.py` | −41 B | **10** |
+| M16 | a stale card never warns | `custom_formula.py` | −8 B | 1 |
+| M17 | a stale card REFUSES instead of warning | `validate.py` | −3 B | 1 |
+| M18 | the empty-formula refusal removed from the startup gate | `validate.py` | −38 B | 1 |
+| M19 | the index scaled to EUR/kWh before the formula — the factor-1000 | `price.py` | +2 B | **7** |
+| M20 | an `eval` call planted in `app/custom_formula.py` | `custom_formula.py` | +14 B | 1 |
+| M21 | `custom_formula` stops passing the caller's range to the feed | `price.py` | **+0 B** | 1 |
+| M22 | **PAIRED**: M1 *and* the plausibility band removed, together | `custom_formula.py` | −60 B | **12** |
+
+### The four that are worth reading rather than counting
+
+**M13 was a SURVIVOR of the whole suite on the first attempt, at −13 B.** The
+check read `"index EUR/MWh -> all-in EUR/kWh" in log` — which is the preview's
+**heading**. Deleting the index column from every **row** left the heading
+saying it prints something it no longer printed, and nothing went red. That is
+this file's third failure mode arriving in the check written to close it: the
+assertion ran, the sentence was true, and the data could not reach the failure
+it named. It is graded on a rendered ROW now, built here from the captured
+document (`'  216.080 ->   0.30123'`), and M13 is red.
+
+**M10 is `+0 B` and it is a real defect, not a synthetic one.** It came out of
+writing the mutation rather than out of review: `implausible_all_in()`'s floor
+was applied to the all-in figure, and `price_taxes_eur_kwh` shipped at 0.06 —
+**three times the 0.02 floor** — so a card read a hundred times too small
+(0.0016 EUR/kWh of energy) is carried over the floor by the flat tax addend
+alone and passes. The hundredfold error is exactly what that band exists for.
+The floor is applied to the **energy** figure now and the ceiling to the all-in
+one, both directions are graded, and the trap is stated as a check in its own
+right so the asymmetry cannot be "tidied up" later. *(Annotated 2026-09-13:
+TARIFF-18 raised that default to 0.11736, **nearly six times** the floor. The
+addend that does the carrying got BIGGER, so the trap is wider than when M10
+was measured and the asymmetry is more load-bearing rather than less.)*
+
+**M15 is the one the framework CANNOT catch, and the reds say which half does.**
+Declaring `ALL_IN` makes `assemble()` add nothing, and section 3's all-in check
+is *derived from the declaration* — so it passes on the lie, exactly as
+`price.py`'s trap 1 says no code can catch a misdeclaration. What goes red is
+the **docstring/declaration agreement** check, the card reproductions, and the
+`sources` pin: ten reds, none of them from the arithmetic. That is the
+guarantee at its true size — the two claims are held to agree, and whether
+either is true about somebody else's tariff remains human.
+
+**M22 is the paired run (TEST-16).** The card self-check and the plausibility
+band both answer a unit error, so each could be masking the other. Weakened
+**together** they produce twelve reds rather than the eight M1 alone produces,
+and the band's own checks stay red — so neither rung is doing the other's work.
+
+### What this battery does NOT establish
+
+It does not establish that a card is the right card. Every mutation above moves
+the relationship between the coefficients and the printed price; **none of them
+can move the relationship between the printed price and the operator's actual
+contract**, because nothing in this repository observes that. A
+consistent-but-wrong pair passes every one of these checks, by construction,
+and `DECISIONS/TARIFF-15-the-card-is-the-grader.md` §3 says so in the same
+sentence as the claim.
+
 ## Where each surface stands

 * **Local and dev-harness runs — the exposed one.** This is where FCST-03 hit
@@ -791,6 +1125,7 @@ commit and PR bodies.
 | **SAFETY-03** reviewer survivor: `abs()` dropped from `clamp_to_rating`'s limit (6aabb83) | **re-verified — still a survivor** | re-run the same way, all 15 green. Also as recorded: unreachable under the `int(100, 5000)` schema. |
 | **MAINT-05 round 3**, `migrate_maint_keys()` marker gate `if rep.ok:` → `if rep.ok or rep.kept:` (`+12 B`) | **was a survivor — now CLOSED** | measured against head `65cddf3` under the purge, tree mounted `:ro`, `19/19 PASS`. It stamps the schema marker on a migration that LOST state, defeating the older `lost` guard as well as the new `misdirected` one, because every check that reached the marker did so on a store whose `kept` list was empty. Closed by `test_maintenance.py` **9d**; the mutation is now red on three named checks. |
 | **MAINT-05 round 3**, `migrate_unit_keys()` marker gate `if rep.ok:` → `if rep.ok or rep.kept:` (`+12 B`) | **found here — SAFETY-02's half, now CLOSED** | the SAME mutation one function up, on the LATCH migration rather than the history one. Measured a survivor against this branch under the purge, `:ro`, `19/19 PASS`, then closed by `test_inverter.py` part 10's new fixture — a store with `unit/inverter-a/sign_reason` already present (so `kept` is non-empty) whose `sign_tripped: true` write is dropped. Shipped: marker withheld. Mutant: marker stamped on a **disarmed latch**, and the next start skips the migration that would have re-armed it. |
+| **TARIFF-09** 11 mutations over `app/price.py` and the two-day capture, all red, no survivors | **not at risk** | direction, and method: every mutation was applied to a FRESH `cp -a` of the clean worktree rather than reverted, so there is no revert to verify (habit 18) and no shared scratch path two runs could collide on. Each ran through `tools/mutation_run.sh`, which purges and fingerprints. Byte deltas recorded on the PR; one is **+0 B** - a single price digit edited inside the committed capture, the risky delta - and the re-derived sha256 catches it. |
 | **TARIFF-01**'s other three survivors, **SAFETY-03**'s `describe()` survivor, **TARIFF-02**'s M3/M5/M7, **SAFETY-18**'s three | **still unverified** | recorded before the purge discipline, with no byte delta on the record, so a `+0 B` same-second revert cannot be excluded. All are survivors, which is the direction this defect fabricates. TARIFF-02's and SAFETY-18's were **closed by later commits whose claims are reds**, so what is unverified is the *diagnosis*, not the current state of the code. |

 **Nothing here says a past result is wrong.** The two survivors re-run above
@@ -98,6 +98,12 @@ DROP_STALE = "stale link"
 DROP_CONTRADICTION = "contradicts itself"
 DROP_NO_INTEGER = "no integer setpoint in its interval"

+# OPT-11: why a unit's MODE layer was not applied this tick. Only the first is
+# a fault; the other two are the rule working.
+MODE_FAULT = "mode range leaves out 0 W"
+MODE_RELEASED = "mode released by a higher claim"
+MODE_OUTRANKED = "hard limit leaves no room for the mode"
+
 REFUSE_SCOPE = "mis-routed claim"
 REFUSE_EMPTY = "no unit available"
 REFUSE_SIGN = "opposite directions"
@@ -213,6 +219,10 @@ class Allocation:
    # that calls `plan()` for its arithmetic gets None and does not care;
    # main.py stamps every record it puts on the write path.
    tick: int | None = None
+    # OPT-11: ((unit, why), ...) for each unit whose mode range left out 0 W
+    # this tick. That mode was dropped (see `unit_interval()`); main.py logs it
+    # as a software fault. Empty on every tick without a mode.
+    mode_faults: tuple = ()

    @property
    def ok(self) -> bool:
@@ -246,11 +256,11 @@ class Allocation:
        block the failsafe is worse than the hole it closes.
        """
        if tick is None or self.tick is None or self.tick != tick:
-            return (f"the allocation record on hand was made on tick "
-                    f"{self.tick!r} and this is tick {tick!r} - a record whose "
-                    f"envelopes have moved cannot authorise a write")
+            return (f"the power split on hand is from tick {self.tick!r}, "
+                    f"not this tick {tick!r}, and an old split cannot allow a "
+                    f"write")
        if not self.ok:
-            return f"the allocator refused this tick ({self.explain()})"
+            return f"no power split was possible this tick ({self.explain()})"
        if unit not in self.shares:
            return (f"{unit} has no share in this tick's allocation "
                    f"({self.explain()})")
@@ -290,6 +300,99 @@ class Allocation:
        return out


+def unit_interval(b, deciding_priority=None):
+    """OPT-11. `(lo, hi, note)`: the interval a unit is allocated into.
+
+    The hard limits (`b.lo`, `b.hi`) always apply. The unit's MODE range
+    (`b.mode_lo`, `b.mode_hi`) narrows them unless `deciding_priority` is
+    above the mode's own priority (arbiter._unit_modes() passes None when the
+    modes hold, and the yielding limit's priority when they give way). `note` says why the
+    mode did not apply, or is None when it did or there is none:
+
+    * MODE_FAULT: the mode range leaves out 0 W. A mode may forbid a direction
+      and never force one, so this is a software fault and the mode is dropped.
+      It is what keeps REFUSE_SIGN unreachable from a mode: the fill below
+      moves every free unit away from 0 in ONE direction, and it starts from 0
+      only while every interval holds 0.
+    * MODE_RELEASED: a higher claim (the peak floor) decided the target.
+    * MODE_OUTRANKED: the hard limits and the mode do not overlap. The hard
+      limits win, as they always do.
+
+    A unit without mode fields (`mode_priority` absent or None) gets its hard
+    limits, unchanged: that is every unit when battery modes are off.
+    """
+    lo, hi = b.lo, b.hi
+    prio = getattr(b, "mode_priority", None)
+    if prio is None:
+        return lo, hi, None
+    mlo, mhi = b.mode_lo, b.mode_hi
+    if not (mlo <= 0.0 <= mhi):
+        return lo, hi, MODE_FAULT
+    if deciding_priority is not None and deciding_priority > prio:
+        return lo, hi, MODE_RELEASED
+    nlo, nhi = max(lo, mlo), min(hi, mhi)
+    if nlo > nhi:
+        return lo, hi, MODE_OUTRANKED
+    return nlo, nhi, None
+
+
+class _Narrowed:
+    """A unit's bounds with its interval replaced by `unit_interval()`'s."""
+    __slots__ = ("lo", "hi")
+
+    def __init__(self, lo, hi):
+        self.lo, self.hi = lo, hi
+
+
+def pin_w(b):
+    """The watts a unit's own SET places once held inside its hard limits,
+    as `plan()` places a standing pin, or None when the unit has no SET."""
+    pv = getattr(b, "pinned_w", None)
+    if getattr(b, "gate", None) is None or pv is None:
+        return None
+    lo, hi = _int_envelope(b)
+    return float(pv) if lo > hi else float(_clamp_int(round(float(pv)), lo, hi))
+
+
+def hi_w(b):
+    """A unit's upper hard limit as `plan()` narrows it to whole W (SAFETY-84)."""
+    return float(_int_envelope(b)[1])
+
+
+def loop_bound(bounds, live=None):
+    """OPT-11. `(lo, hi)`: what the units can place when the LOOP decides.
+
+    The sum, over live units that do not contradict themselves, of each unit's
+    interval with its mode applied (`unit_interval()` with no higher claim). A
+    pinned unit adds the span from 0 to its pin, so a probe or a maintenance
+    pin stays reachable. Every term holds 0, so the sum does too.
+
+    `compute()` keeps the site target inside this, so the loop never asks for
+    watts no battery may give: the allocator would report them as unmet and the
+    saturation freeze would park the target on them (SAFETY-73 section 1).
+    Pure, like `plan()`: it reads numbers and intervals and nothing else.
+    """
+    lo_sum, hi_sum = 0.0, 0.0
+    for u in sorted(bounds):
+        b = bounds[u]
+        if live is not None and u not in live:
+            continue
+        if getattr(b, "contradiction", False):
+            continue
+        p = pin_w(b)
+        if p is not None:
+            lo_sum += min(0.0, p)
+            hi_sum += max(0.0, p)
+            continue
+        lo, hi, _ = unit_interval(b)
+        lo, hi = _int_envelope(_Narrowed(lo, hi))
+        if lo > hi:
+            continue
+        lo_sum += min(0.0, lo)
+        hi_sum += max(0.0, hi)
+    return lo_sum, hi_sum
+
+
 def _int_envelope(b):
    """A unit's interval, narrowed to the integers a 1 W register can hold.

@@ -385,7 +488,8 @@ def _fill(order, weights, cap, amount):


 def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
-         site_priority=None, site_key="site", tick=None) -> Allocation:
+         site_priority=None, site_key="site", tick=None,
+         deciding_priority=None) -> Allocation:
    """Divide the site grid target `target_w` across the units in `bounds`.

    `bounds`   unit name -> that unit's interval for THIS TICK (arbiter stage 1,
@@ -411,6 +515,9 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
    `site_priority` the priority of the SITE claim that chose `target_w`. It is
               what a unit's own winning SET is weighed against - see PINS.
    `site_key` the name to use when there are no units at all.
+    `deciding_priority` OPT-11: the priority that decided `target_w`
+               (`Resolution.deciding_priority`). Each unit's mode range applies
+               only at or below it - see `unit_interval()`. None applies them.
    `tick`     an opaque token identifying the tick this record is FOR, handed
               straight back on the record. SAFETY-28's write gate compares it
               against the tick it is writing on, so that a record cannot be
@@ -497,6 +604,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
    dropped = []
    ilo, ihi = {}, {}
    considered = []
+    mode_faults = []
    for u in units:
        b = bounds[u]
        if live is not None and u not in live:
@@ -512,7 +620,12 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
            # has no interval to allocate into.
            dropped.append((u, DROP_CONTRADICTION))
            continue
-        lo, hi = _int_envelope(b)
+        # OPT-11: the mode layer, when it applies, narrows the hard limits.
+        # A unit with no mode gets exactly its hard limits, as before.
+        nlo, nhi, note = unit_interval(b, deciding_priority)
+        if note == MODE_FAULT:
+            mode_faults.append((u, MODE_FAULT))
+        lo, hi = _int_envelope(_Narrowed(nlo, nhi))
        if lo > hi:
            # An interval that contains no integer. The register is 1 W, so
            # there is no number this unit could be commanded that both bounds
@@ -526,7 +639,7 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),
        return Allocation(
            target_w=float(target_w), sum_w=sum_w, shares={}, plans=(),
            dropped=tuple(dropped), unmet_w=sum_w, quantisation_w=quant,
-            refused=why, tick=tick)
+            refused=why, tick=tick, mode_faults=tuple(mode_faults))

    # --- REFUSAL 2: nobody is available ------------------------------------
    if not considered:
@@ -659,4 +772,5 @@ def plan(target_w, bounds, *, weights=None, live=None, scope_errors=(),

    return Allocation(target_w=float(target_w), sum_w=sum_w, shares=shares,
                      plans=tuple(plans), dropped=tuple(dropped),
-                      unmet_w=int(unmet), quantisation_w=quant, tick=tick)
+                      unmet_w=int(unmet), quantisation_w=quant, tick=tick,
+                      mode_faults=tuple(mode_faults))
@@ -76,6 +76,12 @@ from . import allocator
 P_SAFETY = 100        # stopped, inputs missing, shutting down, device limits
 P_MAINTENANCE = 60    # maintenance owns the actuator outright (drain, hold)
 P_PEAK = 50           # capacity-tariff peak shaving - costs real money
+# The order in effect: safety limits and the SAFETY-73 refusal > the peak
+# guard > maintenance > modes > trade > loop. A peak floor above a drain still
+# binds: the `drain` site floor at N>=2 (SAFETY-78), refiled at P_MAINTENANCE
+# at N=1 (SAFETY-83); over a HOLD, `_peak_over_hold()` (SAFETY-86).
+# A cheap-window charge is suspended while the peak guard holds and, at N>=2,
+# sized to the quarter's headroom (SAFETY-84).
 P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
 # OPT-04. §10.1 priority 3 - price arbitrage. ⚠️ ITS POSITION IS THE SPEC, NOT A
 # preference: P_PEAK (50) is ABOVE it so clause 2 lets the capacity-tariff floor
@@ -86,8 +92,17 @@ P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
 # because trading against the meter is the entire point - the grid-following
 # loop would otherwise cancel every charge the moment it created import.
 P_ARBITRAGE = 30      # price arbitrage - trades against the meter on purpose
+# OPT-11. A battery's mode (Solar first, Leftover solar, Off): a SOFT unit
+# limit, kept apart from the hard ones. Above arbitrage, so a trade stays inside
+# each battery's mode; below the peak guard, to which a mode gives way only as
+# far as the floor needs (`_unit_modes()`, `_site_mode()`).
+# DECISIONS/OPT-11-battery-modes.md.
+P_MODE = 35
 P_LOOP = 10           # ordinary grid-following

+# The one source filed at P_MODE. pre_resolve() keeps it out of the hard limits.
+MODE_SOURCE = "mode"
+
 SET = "set"
 LIMIT = "limit"

@@ -175,6 +190,22 @@ CLAIM_SCOPE = {
    # the banner and the claim an install has had since SAFETY-02 shipped.
    # `Controller.cycle()` does not even arm the site detector there.
    "sign_site": SCOPE_SITE,
+    # main.py: `Claim.limit("drain", P_MAINTENANCE, lo=...)`, SAFETY-78. At
+    # N>=2, while a pack's maintenance drain is pinned, the site target may
+    # not go below what that pin places: below it a sibling would have to
+    # charge against the drain (circulation, refused, 0 W). A site `lo`,
+    # never filed at N=1. DECISIONS/SAFETY-78-drain-at-two.md.
+    "drain": SCOPE_SITE,
+    # main.py: `Claim.limit("charge", P_MAINT_SHAPE, hi=...)`, SAFETY-84. The
+    # mirror of `drain` for a cheap-window maintenance charge at N>=2: the site
+    # target may not go above what the charging pack's own `hi` asks, or a
+    # sibling would have to give against it. Never filed at N=1.
+    # DECISIONS/SAFETY-84-charge-at-two.md.
+    "charge": SCOPE_SITE,
+    # main.py: `Claim.limit("hold", P_MAINTENANCE, hi=...)`, SAFETY-86. While a
+    # holding pack gives the peak shortfall at N>=2, the site target stays at
+    # the peak floor, what the pin and the others place. Never filed at N=1.
+    "hold": SCOPE_SITE,

    # --- UNIT: about one pack, one inverter, one device -------------------
    # main.py: `Claim.limit("device", P_SAFETY, self.dev_min, self.dev_max,
@@ -226,12 +257,25 @@ CLAIM_SCOPE = {
    # reaches the allocator, so a unit-scoped claim is the shape that sentence
    # asks for rather than an evasion of it.
    "pack": SCOPE_UNIT,
+    # main.py: `Claim.limit("refused", P_SAFETY, ...)` and, during a probe,
+    # `Claim.set("refused", P_SAFETY, +-PROBE_W)`. SAFETY-73: THIS battery gives
+    # nothing in one direction, measured on THIS unit's own reading. A hard unit
+    # limit that always intersects, so the share goes to the siblings. Filed at
+    # N>1 only; at N=1 SAFETY-52's law in compute() does the same job.
+    "refused": SCOPE_UNIT,
    # main.py: `Claim.set("maintenance", P_MAINTENANCE, ...)` when the cycle owns
    # the setpoint, and `Claim.limit("maintenance", P_MAINT_SHAPE, hi=...)` when
    # it only shapes. §12's monthly recalibration is a PACK procedure - drain
    # this pack to its floor, charge this pack to full, recalibrate this pack's
    # coulomb counter. Two packs recalibrate on their own schedules.
    "maintenance": SCOPE_UNIT,
+    # main.py: `Claim.limit("mode", P_MODE, lo, hi, ...)`, OPT-11. THIS
+    # battery's mode, chosen per battery by its owner. A unit claim that never
+    # enters a `lo > hi` test with a site limit: stage 1 keeps it apart from the
+    # hard limits, and it gives way to a site limit above P_MODE only as far as
+    # that limit needs (`_unit_modes()`). At N=1 it routes to the site, and
+    # `resolve()` takes it out of stage 2 for the same reason.
+    "mode": SCOPE_UNIT,
 }


@@ -359,6 +403,13 @@ class UnitBounds:
    pinned_w: float | None = None
    pinned_by: str | None = None
    contradiction: bool = False
+    # OPT-11: the mode layer, APART from `lo`/`hi` above, which stay the hard
+    # limits. `mode_priority` is None when no mode claim applies. Whether the
+    # mode binds is decided at stage 3 (`allocator.unit_interval()`), because it
+    # depends on the priority that decided the SITE target.
+    mode_lo: float = -inf
+    mode_hi: float = inf
+    mode_priority: int | None = None

    def explain(self) -> str:
        if self.contradiction:
@@ -404,6 +455,15 @@ class Resolution:
    # rules drifting apart: this is set by the same line that picks the winner
    # `explain()` names.
    winner_priority: int | None = None
+    # OPT-11. The higher of the winning set's priority and the priority of the
+    # limit that bound `target_w`. Whether the modes hold is decided from the
+    # limits themselves (`_site_mode()`, `_unit_modes()`): a mode gives way
+    # only as far as a limit above it (the peak floor) needs, so a mode `hi`
+    # never meets a site `lo`.
+    deciding_priority: int | None = None
+    # OPT-11 at N=1: why the site's mode layer was dropped this tick, or None.
+    # At N>1 the same fact is on `allocation.mode_faults`, per unit.
+    mode_fault: str | None = None

    def explain(self) -> str:
        """One line an operator can act on - this is the point of the module."""
@@ -427,7 +487,8 @@ def pre_resolve(unit_claims: list) -> UnitBounds:
    of the fault this card removes, and the reason `resolve()` partitions rather
    than filters twice.
    """
-    sets = sorted((c for c in unit_claims if c.kind == SET),
+    sets = sorted((c for c in unit_claims
+                   if c.kind == SET and c.source != MODE_SOURCE),
                  key=lambda c: c.priority, reverse=True)
    gate = pinned_w = pinned_by = None
    if sets:
@@ -435,19 +496,30 @@ def pre_resolve(unit_claims: list) -> UnitBounds:

    lo, hi = -inf, inf
    lo_src = hi_src = None
+    # OPT-11: a mode claim never joins the hard limits, so a mode cannot make a
+    # unit contradict itself or narrow a pin. A mode SET is not a thing: only
+    # limits are read. The lowest mode priority is kept (the first to release).
+    mode_lo, mode_hi, mode_priority = -inf, inf, None
    for c in unit_claims:
        if c.kind != LIMIT or (gate is not None and c.priority < gate):
            continue
+        if c.source == MODE_SOURCE:
+            mode_lo, mode_hi = max(mode_lo, c.lo), min(mode_hi, c.hi)
+            mode_priority = (c.priority if mode_priority is None
+                             else min(mode_priority, c.priority))
+            continue
        if c.lo > lo:
            lo, lo_src = c.lo, c.source
        if c.hi < hi:
            hi, hi_src = c.hi, c.source
    return UnitBounds(lo, hi, lo_src, hi_src, gate, pinned_w, pinned_by,
-                      contradiction=lo > hi)
+                      contradiction=lo > hi, mode_lo=mode_lo, mode_hi=mode_hi,
+                      mode_priority=mode_priority)


 def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
-             scope_errors=(), site_priority=None) -> tuple:
+             scope_errors=(), site_priority=None,
+             deciding_priority=None) -> tuple:
    """STAGE 3. THE SEAM, AND SINCE ALLOC-01 IT IS OCCUPIED. `(shares, allocated)`.

    ⚠️ THE ALLOCATOR ITSELF IS `app/allocator.py` AND THE REASONING LIVES THERE.
@@ -485,11 +557,13 @@ def allocate(target_w: float, bounds: dict, *, weights=None, live=None,
    """
    return allocate_record(target_w, bounds, weights=weights, live=live,
                           scope_errors=scope_errors,
-                           site_priority=site_priority)[:2]
+                           site_priority=site_priority,
+                           deciding_priority=deciding_priority)[:2]


 def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
-                    scope_errors=(), site_priority=None, tick=None) -> tuple:
+                    scope_errors=(), site_priority=None, tick=None,
+                    deciding_priority=None) -> tuple:
    """`allocate()` plus the record - `(shares, allocated, allocation)`.

    `tick` is SAFETY-28's freshness token: it identifies the tick the record is
@@ -501,7 +575,7 @@ def allocate_record(target_w: float, bounds: dict, *, weights=None, live=None,
    rec = allocator.plan(target_w, bounds, weights=weights, live=live,
                         scope_errors=scope_errors,
                         site_priority=site_priority, site_key=ACTUATOR_SITE,
-                         tick=tick)
+                         tick=tick, deciding_priority=deciding_priority)
    return rec.shares, rec.ok, rec


@@ -538,23 +612,30 @@ def site_resolve(claims: list) -> Resolution:
    considered = [f"{c.source}:{c.kind}" for c in claims]

    if lo > hi:
+        # OPT-11: 0 W here, and every limit that took part counts as deciding.
        return Resolution(0.0, winner.source, bound_by=None,
                          contradiction=True, considered=considered,
-                          winner_priority=winner.priority)
+                          winner_priority=winner.priority,
+                          deciding_priority=max(winner.priority,
+                                                lo_src.priority,
+                                                hi_src.priority))

    target = max(lo, min(hi, winner.value))
    bound_by = None
+    deciding = winner.priority
    if target != winner.value:
        binder = lo_src if target == lo else hi_src
        if binder is not None:
            bound_by = f"{binder.source}({binder.reason})" if binder.reason else binder.source
+            deciding = max(deciding, binder.priority)

    return Resolution(float(target), winner.source, bound_by, False, considered,
-                      winner_priority=winner.priority)
+                      winner_priority=winner.priority,
+                      deciding_priority=deciding)


 def resolve(claims: list, *, units=None, weights=None, live=None,
-            tick=None) -> Resolution:
+            tick=None, reserve=()) -> Resolution:
    """The three stages, in order, over one cycle's claims.

    `units` is the site's roster of inverters. Left None it is derived from the
@@ -600,6 +681,12 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
    written down.
    """
    site_claims = [c for c in claims if c.actuator == ACTUATOR_SITE]
+    # OPT-11: a mode claim on the site (N=1, where every source routes there)
+    # never enters stage 2's `lo > hi` test. It is applied after it, below, by
+    # the same release rule stage 3 uses.
+    site_modes = [c for c in site_claims if c.source == MODE_SOURCE]
+    if site_modes:
+        site_claims = [c for c in site_claims if c.source != MODE_SOURCE]
    if units is None:
        units = {c.actuator for c in claims if c.actuator != ACTUATOR_SITE}
    units = tuple(sorted(units))
@@ -611,6 +698,8 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
    # STAGE 2 - the site claims become the grid target. At N=1 `site_claims` IS
    # `claims`, so this is the shipped arbiter on the shipped list.
    out = site_resolve(site_claims)
+    if site_modes:
+        _site_mode(out, site_modes, site_claims)

    # STAGE 3 - the seam, and since ALLOC-01 the allocator behind it.
    #
@@ -643,10 +732,132 @@ def resolve(claims: list, *, units=None, weights=None, live=None,
    # nothing. See `packshare.weights()` on the residual this leaves (the fill's
    # own direction can differ from the target's sign under a pin, in which case
    # the weighting is a worse preference and still cannot be unsafe).
+    # OPT-11: whether each unit's mode holds this tick (`_unit_modes()`).
+    # Before the weights, because a limit above the modes may move the target.
+    gate, held = _unit_modes(out, site_claims, bounds, live)
    if callable(weights):
        weights = weights(out.target_w)
+    # SAFETY-87/91: units under their peak reserve weigh 0 while the site
+    # gives, so the others carry the target first. An Off battery gives the
+    # peak's shortfall, so it goes before them when no other unit is left.
+    reserve = set(reserve) if out.target_w > 0.0 else set()
+    if held and reserve and not set(bounds) - held - reserve:
+        held = set()
+    held = held | reserve
+    if held:
+        weights = {u: (0.0 if u in held else
+                       (1.0 if weights is None else weights.get(u, 1.0)))
+                   for u in bounds}
    out.shares, out.allocated, out.allocation = allocate_record(
        out.target_w, bounds, weights=weights, live=live,
        scope_errors=out.scope_errors, site_priority=out.winner_priority,
-        tick=tick)
+        tick=tick, deciding_priority=gate)
    return out
+
+
+def _limits_above(site_claims: list, prio: int) -> tuple:
+    """OPT-11: `(lo, lo_src, hi, hi_src)` over the site LIMITs above `prio`.
+
+    These are what a mode may never take the site target outside of: the peak
+    guard (P_PEAK), maintenance shaping (P_MAINT_SHAPE) and the hard limits.
+    """
+    lo, hi = -inf, inf
+    lo_src = hi_src = None
+    for c in site_claims:
+        if c.kind != LIMIT or c.priority <= prio:
+            continue
+        if c.lo > lo:
+            lo, lo_src = c.lo, c
+        if c.hi < hi:
+            hi, hi_src = c.hi, c
+    return lo, lo_src, hi, hi_src
+
+
+def _yield_to(out: Resolution, t1: float, above: tuple):
+    """OPT-11: the target `t1` the modes allow, moved only as far as the limits
+    above the mode need (`_limits_above()`). Returns the claim that moved it,
+    or None when `t1` already satisfies them, and sets `out.target_w`."""
+    lo, lo_src, hi, hi_src = above
+    t2 = max(lo, min(hi, t1))
+    out.target_w = float(t2)
+    if t2 == t1:
+        return None
+    binder = lo_src if t2 == lo else hi_src
+    out.bound_by = (f"{binder.source}({binder.reason})" if binder.reason
+                    else binder.source)
+    out.deciding_priority = max(out.deciding_priority or binder.priority,
+                                binder.priority)
+    return binder
+
+
+def _site_mode(out: Resolution, modes: list, site_claims: list) -> None:
+    """OPT-11 at N=1: the one battery's mode bounds the SITE target, after stage 2.
+
+    A SET above the mode (a safety stop) decides alone. Otherwise the target is
+    clamped into the mode range and then back into the site limits above the
+    mode, so the mode gives way only as far as those limits need: a peak floor
+    of 2000 W over an Off battery asks it for 2000 W, whether a trade or the
+    loop won stage 2, and a charge the peak guard merely caps stays at 0 W. A
+    range without 0 W is a software fault that drops the mode
+    (`out.mode_fault`). Clamping one number cannot contradict anything.
+    """
+    out.considered = out.considered + [f"{c.source}:{c.kind}" for c in modes]
+    lims = [c for c in modes if c.kind == LIMIT]
+    if not lims or out.contradiction:
+        return
+    lo = max(c.lo for c in lims)
+    hi = min(c.hi for c in lims)
+    prio = min(c.priority for c in lims)
+    if not (lo <= 0.0 <= hi):
+        out.mode_fault = f"mode range [{lo:.0f}, {hi:.0f}] leaves out 0 W"
+        return
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return
+    before = out.target_w
+    t1 = max(lo, min(hi, before))
+    if _yield_to(out, t1, _limits_above(site_claims, prio)) is None \
+            and t1 != before:
+        c = lims[0]
+        out.bound_by = f"{c.source}({c.reason})" if c.reason else c.source
+
+
+def _unit_modes(out: Resolution, site_claims: list, bounds: dict, live):
+    """OPT-11 at N>1: `(gate, held)` for stage 3.
+
+    `gate` is the `deciding_priority` handed to the allocator: None applies
+    every unit's mode, a number above P_MODE releases them. `held` is the set
+    of units whose mode holds them back in the target's direction; while the
+    modes are released they weigh 0, so they carry only what the other units
+    cannot (the allocator's last-resort pass).
+
+    The rule matches N=1: a SET above the mode decides alone. Otherwise the
+    target is clamped into what the units can place with their modes
+    (`allocator.loop_bound()`) and back into the site limits above the mode.
+    If that point is still placeable with the modes, they hold and the target
+    is unchanged (what they cannot place is reported unmet, as before). If a
+    limit above the mode needs more, the target moves only that far, and the
+    modes are released for it.
+    """
+    mode_units = [u for u, b in bounds.items()
+                  if getattr(b, "mode_priority", None) is not None]
+    if not mode_units or out.contradiction:
+        return out.deciding_priority, set()
+    prio = min(bounds[u].mode_priority for u in mode_units)
+    if out.winner_priority is not None and out.winner_priority > prio:
+        return out.deciding_priority, set()
+    clo, chi = allocator.loop_bound(bounds, live)
+    t1 = max(clo, min(chi, out.target_w))
+    before = out.target_w
+    binder = _yield_to(out, t1, _limits_above(site_claims, prio))
+    if binder is None:
+        out.target_w = float(before)
+        return None, set()
+    held = set()
+    for u in mode_units:
+        b = bounds[u]
+        nlo, nhi, note = allocator.unit_interval(b)
+        if note is not None:
+            continue
+        if (nhi < b.hi) if out.target_w > 0 else (nlo > b.lo):
+            held.add(u)
+    return binder.priority, held
@@ -184,6 +184,17 @@ IDLE_OFF_PEAK_HOUR = "this hour is neither the buy hour nor the sell hour"
 IDLE_NO_SIZE = (
    "no pack's state of charge permits this side of the trade, so it is sized "
    "at 0 W - and a 0 W arbitrage claim is a park order, not a trade")
+# SAFETY-45. THE BUY LEG'S SIZE, AND ONLY THE BUY LEG'S - §9.1: "Discharge and
+# export are never capped by the peak guard; only charging and import are."
+IDLE_NO_HEADROOM = (
+    "the capacity-tariff guard has measured this billed quarter and it can "
+    "afford no charging at all, so a trade of any size would push it over the "
+    "ceiling - and a 0 W arbitrage claim is a park order, not a trade")
+IDLE_HEADROOM_UNMEASURED = (
+    "the capacity-tariff guard did not size this quarter's charging headroom "
+    "this cycle, and an UNMEASURED headroom is not an unlimited one - charging "
+    "creates the billed quantity (§9.1) and nothing is measuring the quarter "
+    "this one would land in")
 NEGATIVE_PRICE = (
    "§17: the sell hour is priced BELOW ZERO, so discharging into it would give "
    "energy away and pay for the privilege. Arbitrage must not export at a "
@@ -251,10 +262,8 @@ def threshold_eur_kwh(opts: dict) -> float:
    v = float(price_option(opts, "cycle_cost_threshold_eur"))
    if not math.isfinite(v) or v < 0:
        raise ValueError(
-            f"cycle_cost_threshold_eur is {v!r}. It is what a round trip COSTS, "
-            f"in EUR/kWh, so it is non-negative and finite - a negative "
-            f"threshold is one every spread clears, which is arbitrage with the "
-            f"brake removed.")
+            f"“Battery cycle cost” (cycle_cost_threshold_eur) is {v!r}. Set "
+            f"it to 0 or more, in EUR/kWh.")
    return v


@@ -303,7 +312,7 @@ def _point_at(plan, when: datetime):
        return None


-def decide(plan, now: datetime, *, peak_guard_active, soc,
+def decide(plan, now: datetime, *, peak_guard_active, charge_headroom_w, soc,
           min_spread_eur_kwh, uncertainty, charge_w, discharge_w,
           soc_floor_pct, soc_ceiling_pct) -> ArbitrageDecision:
    """Should the battery trade this cycle, and how hard.
@@ -314,6 +323,18 @@ def decide(plan, now: datetime, *, peak_guard_active, soc,
    None refuses, because the alternative is a strategy that creates the billed
    quantity while the thing that would have limited it is switched off.

+    ⚠️ `charge_headroom_w` IS SAFETY-45's SECOND, CONTINUOUS ANSWER FROM THE
+    SAME GUARD, AND IT IS NOT A DUPLICATE OF THE FIRST. `peak_guard_active` is a
+    SWITCH - it says whether the guard is holding - and a switch keyed on a
+    continuous quantity is what made the loop oscillate: the guard engaged at a
+    5 W floor, this module refused the whole trade, the loop took the actuator,
+    the meter fell, the guard released and the trade re-armed AT FULL POWER
+    130 s later. 28 times an hour, measured. `peakguard.charge_headroom_w()` is
+    the watts the billed quarter can still afford; sizing the buy leg to it means
+    the trade is CLAMPED rather than switched, which is the same shape
+    `control.maintenance_charge_floor()` has always given a maintenance charge.
+    ⚠️ None IS NOT UNLIMITED here either - see IDLE_HEADROOM_UNMEASURED.
+
    ⚠️ EVERY OTHER ARGUMENT IS KEYWORD-ONLY AND HAS NO DEFAULT, for
    `TariffPlan.arbitrage()`'s reason. A defaulted `soc_floor_pct` is a reserve
    floor this module asserted rather than one the operator configured, and the
@@ -330,10 +351,12 @@ def decide(plan, now: datetime, *, peak_guard_active, soc,
    return verdict.match(
        refused=lambda v: _idle(v.reason),
        allowed=lambda v: _act(plan, now, v, soc, charge_w, discharge_w,
-                               soc_floor_pct, soc_ceiling_pct))
+                               soc_floor_pct, soc_ceiling_pct,
+                               charge_headroom_w))


-def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct):
+def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct,
+         headroom_w):
    """The permitted case: which hour is this, and may the pack do it."""
    here = _point_at(plan, now)
    if here is None:
@@ -403,18 +426,110 @@ def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct):
            f"nowhere to put the cheap energy", **common)
    if not abs(float(charge_w)) > 0.0:
        return _idle(IDLE_NO_SIZE, **common)
+    # SAFETY-45. THE BILLED QUARTER IS ASKED LAST, AND THE PLACEMENT IS
+    # DELIBERATE: every refusal that existed before this card keeps the
+    # precedence it had, so no sentence an operator already reads changes when
+    # it fires, and the two added here are placed where they cannot displace
+    # one. The pack's reasons come first because they are properties of the
+    # hardware in the cupboard; this one is a property of the fifteen minutes
+    # the trade would land in.
+    if headroom_w is None:
+        # ⚠️ NOT "the guard is clear". This is `guard_state()`'s None argument
+        # one layer down: a headroom nothing measured is not an unlimited one,
+        # and charging at max_w creates the billed quantity (§9.1).
+        return _idle(IDLE_HEADROOM_UNMEASURED, **common)
+    asked_w = abs(float(charge_w))
+    size_w = min(asked_w, max(0.0, float(headroom_w)))
+    if not size_w > 0.0:
+        # ⚠️ NOT IDLE_NO_SIZE, WHICH IS THE LINE ABOVE AND BLAMES THE PACKS.
+        # `asked_w > 0` is already established here, so the pack may be empty
+        # and willing and it is the billed quarter that has run out. A refusal
+        # naming the wrong subsystem sends an operator to the wrong page
+        # (§10.2), and these two are a whole quarter-hour apart in what they
+        # ask a human to do about them.
+        return _idle(IDLE_NO_HEADROOM, **common)
+    # ⚠️ THE SENTENCE CARRIES BOTH NUMBERS IN THEIR OWN SLOTS, not one figure
+    # twice. MUTATION.md habit 14: two values in one sentence can be transposed
+    # by a ZERO-BYTE edit that no byte delta and no shape pin can see, so the
+    # trade's own size and the guard's headroom are each named by the literal
+    # text around them.
+    capped = size_w < asked_w
    return ArbitrageDecision(
-        action=CHARGE, power_w=-abs(float(charge_w)),
+        action=CHARGE, power_w=-size_w,
        reason=(f"{CHARGE}: this is the cheapest firm hour at "
                f"{price:.4f} EUR/kWh, {v.spread_eur_kwh:.4f} below the dearest "
                f"and clear of the {v.required_spread_eur_kwh:.4f} this cycle "
-                f"had to cover; charging {abs(float(charge_w)):.0f} W from "
-                f"{soc:g} %"),
+                f"had to cover; charging {size_w:.0f} W from {soc:g} %"
+                + (f" - SIZED BY THE CAPACITY-TARIFF GUARD: the trade asked for "
+                   f"{asked_w:.0f} W and this billed quarter can afford "
+                   f"{float(headroom_w):.0f} W (§9.1, §10.1 priority 2)"
+                   if capped else "")),
        spread_eur_kwh=v.spread_eur_kwh,
        required_eur_kwh=v.required_spread_eur_kwh,
        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.

@@ -325,12 +325,13 @@ class CirculationWatchdog:
            return False

        self.tripped = True
+        # UX-10: plain sentences, every figure kept (test_messages.py part 6).
        self.reason = (
            f"CIRCULATING_POWER: {circ_w:.0f} W measured going round between "
-            f"the inverters (peak {self.peak_w:.0f} W) for {held:.0f} s "
-            f"continuously - the meter cannot see it, because it nets to zero "
-            f"there (limits: over {self.cfg.min_w:.0f} W, held over "
-            f"{self.cfg.hold_s:.0f} s)")
+            f"the inverters for {held:.0f} s, peaking at {self.peak_w:.0f} W, "
+            f"over the limits of {self.cfg.min_w:.0f} W and "
+            f"{self.cfg.hold_s:.0f} s. The meter cannot see it, because it "
+            f"nets to zero there")
        return True

    def held_s(self, now: datetime) -> float:
@@ -73,6 +73,7 @@ An alarm wired only to this module's `ClampResult.engaged` would therefore be
 silent on the exact configuration the whole ticket is about. The winding is
 visible one layer up, at the integrator bound, and that is why `Decision` now
 carries `i_clamped` / `clamped` BOOLEANS and the caller ORs them in here.
+They alarm in different words: see `loop_clamp_note()` (SAFETY-40).

 AND WHY BOOLEANS RATHER THAN `Decision.reason`. `reason` is a single string that
 later stages overwrite: a cycle that clamps the integrator and is then slew
@@ -141,6 +142,8 @@ import math
 from dataclasses import dataclass
 from datetime import datetime

+from . import messages
+
 # The reason code, distinct from any saturation-freeze code by construction:
 # nothing else in this add-on uses it. See "DISTINCT FROM SATURATION".
 REASON_CODE = "OUTPUT_CLAMP"
@@ -200,9 +203,8 @@ REASON_CODE = "OUTPUT_CLAMP"
 # ceiling rests on one number a test author chose; if that number is ever
 # revisited, this constant moves with it.
 #
-# ⚠️ THIS IS A STOP-GAP AND DOES NOT MAKE THE ALARM CORRECT. The message still
-# calls the integrator bound a BUG SIGNAL and still pairs a request from one
-# moment with a `self.target` read at another - SAFETY-40. Nothing here is
+# ⚠️ THIS WAS A STOP-GAP; the wording and the numbers were SAFETY-40's, fixed
+# in `loop_clamp_note()` below. Nothing here is
 # suppressed: every engagement is still counted, the action-log row is written on
 # every engaged cycle regardless, and the rising edge of every episode alarms
 # unconditionally, so no alarm is DROPPED - only delayed.
@@ -234,6 +236,62 @@ CLEAR_CYCLES = 3
 SUSTAINED_CYCLES = 3


+# UX-10: the reasons below are quoted by a WARNING or ERROR line, so they
+# follow STYLE.md's rule for a quoted reason (test_messages.py part 6): no
+# final full stop, the line adds it. The line around them says "software
+# fault" for an over-rating, so the reason does not. Each is one sentence, so
+# the logged line stays within 3 sentences and about 30 words.
+
+
+def loop_clamp_note(d) -> str:
+    """The loop-side alarm text for one `control.Decision`, or "".
+
+    SAFETY-40: the integrator bound is anti-windup doing its job and says so;
+    only a command over the rating is a software fault. Every number is the
+    decision's own, i.e. from the tick that clamped.
+    """
+    if d.clamped:
+        return (f"{REASON_CODE}: computed {d.requested_w:+.0f} W, cut to the "
+                f"{d.clamped_w:+.0f} W rating, command now {d.target_w:+.0f} W")
+    if d.i_clamped:
+        return (f"{REASON_CODE}: the correction the add-on builds up reached "
+                f"its {d.i_bound_w:+.0f} W limit, command now "
+                f"{d.target_w:+.0f} W")
+    return ""
+
+
+def shortfall_note(named) -> str:
+    """SAFETY-85: the alarm text while another owner sets the batteries.
+    `named` is `[(inverter name or None, asked W, given W)]`, one per battery
+    that gave less than asked."""
+    return f"{REASON_CODE}: " + ", ".join(
+        f"{name or 'the battery'} gives {given:+.0f} W of the {asked:+.0f} W "
+        f"asked" for name, asked, given in named)
+
+
+def delivery_short(asked_w, given_w, margin_w) -> bool:
+    """SAFETY-85: did a battery asked to discharge give more than `margin_w`
+    less? A charge is never short: a full pack tapers (SAFETY-42 section 7)."""
+    asked, given = float(asked_w), float(given_w)
+    return asked > 0.0 and asked - given > abs(float(margin_w))
+
+
+def write_clamp_note(named) -> str:
+    """The write-side alarm text: `named` is `[(inverter name or None,
+    ClampResult)]` for every inverter whose write was cut back this cycle.
+
+    One inverter reads as `describe()`. Several read as one sentence of
+    asked/sent pairs, so the line stays one sentence however many inverters
+    there are. Which limit cut each one back is on its own action-log row
+    (`describe()`) and in the notification."""
+    if len(named) == 1:
+        name, r = named[0]
+        return f"{name}: {r.describe()}" if name else r.describe()
+    return f"{REASON_CODE}: " + ", ".join(
+        f"{name} asked {r.requested_w:+.0f} W and sent {r.applied_w:+.0f} W"
+        for name, r in named)
+
+
@dataclass(frozen=True)
 class ClampResult:
    """What the guard did, with the RAW value preserved.
@@ -250,10 +308,12 @@ class ClampResult:
    bound: str = ""          # "" | "max_w" | "device" - which stage bit

    def describe(self) -> str:
-        return (f"{REASON_CODE}: the computed setpoint {self.requested_w:+.0f} W "
-                f"was clamped to {self.applied_w:+.0f} W by the {self.bound} "
-                f"bound (rating {self.limit_w:.0f} W) - something upstream is "
-                f"winding")
+        # The sent value IS the limit that bound, so the rating is not
+        # repeated: on "max_w" it equals the rating, and on "device" the
+        # rating was not what cut it back.
+        return (f"{REASON_CODE}: asked {self.requested_w:+.0f} W and sent "
+                f"{self.applied_w:+.0f} W, "
+                f"{messages.LIMIT_WORDS.get(self.bound, self.bound)}")


 def is_commandable(value) -> bool:
@@ -333,32 +393,80 @@ class ClampWatchdog:
    def __init__(self):
        self.active = False
        self.engagements = 0      # every engagement, never deduplicated
+        # UX-08: the same count split by alarm type, so the status page names
+        # each with its own alarm's title after the episode clears.
+        self.over_rating = 0      # bug=True: "Power request too high"
+        self.bound = 0            # bug=False: "Battery is not keeping up"
        self.episodes = 0         # rising edges
+        # SAFETY-85: episodes with a bug=False engagement. The status row
+        # counts these; counting cycles read 861 on one rig run.
+        self.bound_episodes = 0
+        self._bound_counted = False
        self.since: datetime | None = None
        self.last_alarm: datetime | None = None
        self.reason = ""
+        # UX-08: the numbers behind `reason`, for the notification - set under
+        # the same rule as `reason`, so both always describe the same tick.
+        self.facts = ()
        self.clean_cycles = 0
        # SAFETY-41. Consecutive engaged cycles, and whether THIS episode has
        # spoken yet - the two the escalation clause needs.
        self.run_len = 0
        self.spoken = False
+        # SAFETY-40. Did this episode include a genuine over-rating (`bug`), and
+        # has THAT spoken? A bug has its own budget, so anti-windup notices can
+        # never delay it; with bug=True throughout, cadence is as before.
+        self.bug = False
+        self.bug_spoken = False
+        self.last_bug_alarm: datetime | None = None

-    def note(self, engaged: bool, reason: str, now: datetime) -> bool:
+    def _due(self, last, now) -> bool:
+        return last is None or (now - last).total_seconds() >= REASSERT_S
+
+    def _speak(self, now, bug) -> bool:
+        self.last_alarm = now
+        self.spoken = True
+        if bug:
+            self.last_bug_alarm = now
+            self.bug_spoken = True
+        return True
+
+    def note(self, engaged: bool, reason: str, now: datetime,
+             bug: bool = True, facts=()) -> bool:
        """Advance one cycle. True when the caller should raise the alarm.

        `now` is the caller's clock, the same discipline as
-        `SignWatchdog.evaluate()` and `FreezeWatchdog.evaluate()`.
+        `SignWatchdog.evaluate()` and `FreezeWatchdog.evaluate()`. `bug` False
+        is the integrator bound (SAFETY-40): counted and notified like the
+        rest, but it never replaces a bug's text within an episode.
        """
        if engaged:
            self.engagements += 1
+            if bug:
+                self.over_rating += 1
+            else:
+                self.bound += 1
            self.clean_cycles = 0
-            self.reason = reason
            self.run_len += 1
-            if not self.active:
+            rising = not self.active
+            if rising:
                self.active = True
                self.since = now
                self.episodes += 1
                self.spoken = False
+                self.bug = False
+                self.bug_spoken = False
+                self._bound_counted = False
+            if not bug and not self._bound_counted:
+                self._bound_counted = True
+                self.bound_episodes += 1
+            if bug or not self.bug:
+                self.reason = reason
+                self.facts = tuple(facts)
+            self.bug = self.bug or bug
+            if bug and not self.bug_spoken and self._due(self.last_bug_alarm, now):
+                return self._speak(now, True)
+            if rising:
                # ⚠️ SAFETY-41. THE RISING EDGE IS RATE-LIMITED TOO, and it did
                # not used to be. It fired unconditionally, so a condition that
                # engages and clears repeatedly raised one notification PER
@@ -384,11 +492,8 @@ class ClampWatchdog:
                # still written on every engaged cycle, and a genuine runaway -
                # which by definition keeps engaging - is picked up by the
                # re-assert path within REASSERT_S. Delay, not loss.
-                if (self.last_alarm is None
-                        or (now - self.last_alarm).total_seconds() >= REASSERT_S):
-                    self.last_alarm = now
-                    self.spoken = True
-                    return True
+                if self._due(self.last_alarm, now):
+                    return self._speak(now, self.bug)
                return False
            # ⚠️ THE ESCALATION. An episode that has not yet spoken because the
            # budget was spent by an EARLIER, unrelated episode speaks anyway
@@ -396,15 +501,10 @@ class ClampWatchdog:
            # engages every cycle and reaches it; the scattered one-cycle
            # railing that produced the live flood never does.
            if not self.spoken and self.run_len >= SUSTAINED_CYCLES:
-                self.last_alarm = now
-                self.spoken = True
-                return True
+                return self._speak(now, self.bug)
            # Still engaged: re-assert on the slow cadence, not every cycle.
-            if (self.last_alarm is None
-                    or (now - self.last_alarm).total_seconds() >= REASSERT_S):
-                self.last_alarm = now
-                self.spoken = True
-                return True
+            if self._due(self.last_alarm, now):
+                return self._speak(now, self.bug)
            return False

        self.run_len = 0
@@ -420,5 +520,7 @@ class ClampWatchdog:
            # above. The episode ends; the notification budget does not reset
            # with it.
            self.reason = ""
+            self.facts = ()
+            self.bug = False
            self.clean_cycles = 0
        return False
@@ -24,7 +24,7 @@ since the status page shipped; this file has five more chances to get it wrong.

 ⚠️ AND IT IS BUILT FOR A PHONE FIRST. This is the screen someone stands in
 front of the inverter with: one column, big touch targets, sections that start
-collapsed so 71 options do not arrive as one wall, and the refusal block pinned
+collapsed so 72 options do not arrive as one wall, and the refusal block pinned
 where it cannot be scrolled past.
 """

@@ -413,10 +413,9 @@ function showProblems(payload){
  save.disabled = total > 0;
  if(total){
    note(banner, 'bad', 'This configuration would not start.',
-      'The add-on refuses to run on it and would stop with exit 78. '
-      + 'Saving is blocked until these are fixed; nothing has been written. '
-      + 'Each message below is the add-on\\u2019s own words, from the same '
-      + 'check that runs at startup.');
+      'The add-on would refuse to start on it. Saving is blocked until these '
+      + 'are fixed, and nothing has been written. Each message below comes '
+      + 'from the same check that runs at start.');
    banner.insertBefore(banner.lastChild, banner.firstChild);
    msg(total + (total === 1 ? ' problem' : ' problems')
        + ' - saving is blocked', 'bad');
@@ -289,7 +289,10 @@ def problems_by_field(problems, keys):
    cross-field rule is about all of its fields, and hiding it from one of them
    would be this card's own defect in miniature.
    """
-    patterns = [(key, re.compile(r"(?<![A-Za-z0-9_])" + re.escape(key)
+    # ⚠️ `.` BEFORE THE KEY DOES NOT COUNT (UX-08 2d): `inverters.max_w`
+    # names a setting of one inverter in the list, which is changed under
+    # `inverters`, and it must not also land beside the flat `max_w`.
+    patterns = [(key, re.compile(r"(?<![A-Za-z0-9_.])" + re.escape(key)
                                 + r"(?![A-Za-z0-9_])")) for key in keys]
    by_key, unanchored = {}, []
    for problem in problems:
@@ -17,6 +17,7 @@ exists because its absence produced a specific, observed failure.
 """

 import math
+from math import inf
 from dataclasses import dataclass

 # ---------------------------------------------------------------------------
@@ -191,6 +192,112 @@ 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
+
+# ---------------------------------------------------------------------------
+# SAFETY-52. A BATTERY THAT REFUSES IS ASKED FOR 0 W, NOT HELD AT ITS LAST ASK.
+#
+# At the BMS cut-out the pack delivers ~0 W whatever it is asked, so the
+# saturation freeze below holds the command where it stood (the recorded
+# 09-06 case: +5000 W for 11.87 h) until the grid error changes sign. The
+# freeze's own exit cannot help: a reading of ~0 against a large ask is inside
+# the interval a limit can produce. So a refused DIRECTION is held at 0 W,
+# carried between cycles like `sat_count`, and left again when the loop wants
+# the other direction, when a small probe is answered, or when the caller
+# resets it (stop, start, another writer). The record is DECISIONS/SAFETY-52.
+#
+# PROBE_W is below freshness.MOVE_W (250 W) on purpose: a probe that small can
+# never arm the stale-reading gate, so it cannot start the gate's ~70 s cycle.
+# test_refusal.py pins the inequality. The cadence and length are the owner's
+# 2026-09-27 answer (every 15 minutes) and freshness.BATT_OBLIGED_S twice over
+# (17 s is how long a healthy reading needs to show a command).
+REFUSED = "battery refuses"
+PROBING = "battery probe"
+PROBE_W = 200.0
+PROBE_ANSWER_W = PROBE_W / 2
+# "Gives nothing" is below the probe's own answer, not below `saturation_w`: a
+# pack derated to 100-499 W is a limit, and at 500 W it kept ~7 % of its power
+# (review of #141). The capture's refusals read -4 W.
+REFUSED_BELOW_W = PROBE_ANSWER_W
+PROBE_EVERY_S = 900.0
+PROBE_S = 34.0
+
+# OPT-11. The loop's reason when the battery modes, not the meter, set the
+# command: every battery that may move this way is at its mode's limit.
+MODE_BOUND = "mode-bound"
+

@dataclass(frozen=True)
 class Tuning:
@@ -266,6 +373,18 @@ class Decision:
    # the comment at the bound below, and clamp.py.
    i_clamped: bool = False
    clamped: bool = False
+    # SAFETY-40. The alarm's numbers, taken at the clamp so they are one tick's:
+    # the bound the integrator reached, and the command before/after the
+    # rating clamp. `target_w` is this tick's emitted command.
+    i_bound_w: float = 0.0
+    requested_w: float = 0.0
+    clamped_w: float = 0.0
+    # SAFETY-52. The refused direction to carry back in (+1 discharge, -1
+    # charge, 0 none), or None when the caller does not carry it.
+    refused: int | None = None
+    # SAFETY-85. The `bound` held the integrator or the command this cycle,
+    # so the batteries' limits, not the loop, decided it.
+    held: bool = False


 def slew_limit_w(tuning: Tuning) -> float:
@@ -362,6 +481,11 @@ def compute(
    tuning: Tuning,
    sat_count: int = 0,
    i_w: float | None = None,
+    refused: int | None = None,
+    probe: bool = False,
+    bound: tuple | None = None,
+    gave_nothing: bool | None = None,
+    idle_w: float = 0.0,
 ) -> Decision:
    """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).

@@ -369,8 +493,34 @@ def compute(
    `grid_w`   net grid power, + = importing
    `actual_w` what the inverter reports it is doing, + = discharging
    `i_w`      the carried integrator, or None to seed it from `prev_w`
+    `refused`  SAFETY-52's carried refused direction, or None to leave it out
+               (the `i_w=None` equivalence path does)
+    `probe`    the caller's clock says a refused direction may try PROBE_W now
+    `bound`    OPT-11: `(lo, hi)`, what the batteries may place this tick with
+               their modes applied (`allocator.loop_bound()`), or None. See
+               MODE_BOUND below. None is the law as it was.
+    `gave_nothing` SAFETY-94: the caller's span check - the reading stayed
+               under REFUSED_BELOW_W, one way, for SETTLE_CYCLES spanning
+               REFUSED_SPAN_S. A refusal engages only with it. None leaves it
+               out (compute() alone, as before).
+    `idle_w`   SAFETY-97: what `actual_w` reads while the batteries give
+               nothing (app/idle.py). The refusal's band and its end are
+               centred on it. 0 is the law as it was.
    """
    reason = "tracking"
+    # OPT-11: a bound that leaves out 0 W would FORCE a direction, which no
+    # mode may do. It is dropped rather than obeyed (a software fault, and
+    # main.py never builds one: every term of `loop_bound()` holds 0).
+    if bound is not None and not (bound[0] <= 0.0 <= bound[1]):
+        bound = None
+    # ...and a side of it that reaches the rail is left to the rail, so that
+    # SAFETY-03's `i_clamped` still fires when the loop winds into it. With
+    # every battery on, the bound IS the rail, and the law is exactly as it was.
+    if bound is not None:
+        _rail = min(tuning.max_w, tuning.max_w if tuning.integrator_max_w is None
+                    else tuning.integrator_max_w)
+        bound = (float(bound[0]) if bound[0] > -_rail else -inf,
+                 float(bound[1]) if bound[1] < _rail else inf)

    # --- saturation, WITH the duration term -------------------------------
    # Command and actual diverging means the inverter cannot follow - it is at
@@ -473,6 +623,17 @@ def compute(
        else:
            i_w = max(moved, i_w)

+    # OPT-11: the integrator does not wind past what the modes let the
+    # batteries place. Only a side tighter than the rail is left in `bound`
+    # (above), so this never takes SAFETY-03's `i_clamped` away from the rail.
+    held_by_bound = False
+    if bound is not None:
+        held = max(float(bound[0]), min(float(bound[1]), i_w))
+        if held != i_w:
+            i_w = held
+            reason = MODE_BOUND
+            held_by_bound = True
+
    # ⚠️ Applied EVERY cycle, frozen or not: the freeze is conditional, this
    # bound is not. It is what makes the worst-case unwind time finite and
    # knowable instead of a function of how long the error happened to stand.
@@ -489,6 +650,7 @@ def compute(
        # winding, "clamped" is a command that came out over the rating anyway.
        reason = "i-clamped"
    i_w = bounded
+    i_bound_w = bounded if i_clamped else 0.0
    want = i_w

    # ⚠️ Maintenance shaping (charge-only, cheap-window floor) used to live
@@ -500,6 +662,7 @@ def compute(
    # An early draft applied a floor after the clamp and let demand escape it.
    target = max(-tuning.max_w, min(tuning.max_w, want))
    clamped = target != want
+    clamped_w = target
    if clamped:
        reason = "clamped"

@@ -507,6 +670,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:
@@ -580,6 +820,49 @@ def compute(
            target = min(target, prev_w) if prev_w > 0 else max(target, prev_w)
            reason = "saturated-freeze"

+    # --- SAFETY-52: a refused direction is held at 0 W ----------------------
+    # Engages only where the freeze has held for SETTLE_CYCLES and the unit
+    # delivers ~nothing: a reading below REFUSED_BELOW_W against an ask beyond
+    # `saturation_w` is a refusal, not a slow plant. The drop to 0 skips the slew
+    # limit because it only removes an ask the battery is not meeting.
+    if refused is not None:
+        # SAFETY-94: and only when the reading has given nothing for the
+        # whole span, not just now. `sat_count` also counts the cycles a
+        # healthy battery spends reversing through its lag (-2000 W towards
+        # +800 W): at a 1 s meter its 12 cycles end as the reading passes 0.
+        if (refused == 0 and frozen and sat_count >= SETTLE_CYCLES
+                and abs(prev_w) > tuning.saturation_w
+                and abs(actual_w - idle_w) < REFUSED_BELOW_W
+                and gave_nothing is not False):
+            refused = 1 if prev_w > 0 else -1
+        if refused and refused * i_w < 0:
+            refused = 0                          # the loop wants the other way
+        elif refused and refused * (actual_w - idle_w) >= PROBE_ANSWER_W:
+            refused = 0                          # it delivers: a probe answered,
+            #                                     or a slow reading arriving
+        elif refused:
+            wants = refused * i_w > 0
+            i_w = 0.0
+            target = refused * PROBE_W if probe and wants else 0.0
+            reason = PROBING if probe and wants else REFUSED
+
+    # --- OPT-11: the command stays inside what the modes allow -------------
+    # Applied after the slew limit and the freeze, so a mode that closes drops
+    # the ask at once rather than one slew step per cycle. That moves no
+    # battery further than the allocator would: it places at most this bound
+    # when the loop decides. What it removes is the unmet part, which would
+    # otherwise hold `prev_w` away from `actual_w` and trip the saturation
+    # freeze on watts no battery was allowed to give.
+    if bound is not None:
+        inside = max(float(bound[0]), min(float(bound[1]), target))
+        if inside != target:
+            target = inside
+            reason = MODE_BOUND
+            held_by_bound = True
+        # SAFETY-48's lead cap above may pull the integrator back toward the
+        # slewed command; what is CARRIED stays inside the bound too.
+        i_w = max(float(bound[0]), min(float(bound[1]), i_w))
+
    # --- quantise ----------------------------------------------------------
    # 10 W. The register is 1 W and the inverter reports at 1 W, but its
    # response lands on a coarser ladder (~17.6 W measured at ~900 W, consistent
@@ -587,9 +870,17 @@ def compute(
    # 10 W simply avoids a visible staircase on dashboards.
    step = max(1, int(tuning.step_w))
    target = round(target / step) * step
+    if bound is not None:
+        # OPT-11: rounding must not step outside the bound. The bound holds
+        # 0 W, so one step toward 0 is always inside it.
+        if target > bound[1]:
+            target -= step
+        elif target < bound[0]:
+            target += step

    return Decision(float(target), sat_count, frozen, reason, float(i_w),
-                    i_clamped, clamped)
+                    i_clamped, clamped, float(i_bound_w), float(want),
+                    float(clamped_w), refused, held_by_bound)


 def maintenance_charge_floor(
@@ -0,0 +1,911 @@
+"""TARIFF-15 - the customer's own tariff card, as two fixed coefficients.
+
+WHAT THIS IS FOR, in one sentence: a Belgian dynamic contract prices energy as
+`B x index + A` with coefficients that exist in exactly one place - the tariff
+card in the customer's klantenzone - so the customer types those two numbers
+and the add-on does every unit conversion and the VAT multiplication itself.
+
+WHY A FORMULA AND NOT FOURTEEN MORE PLUGINS (§9.2, TARIFF-07)
+=============================================================
+There is NO machine-readable source of Belgian tariff coefficients anywhere.
+CREG's consumer tariff-card pages 404, CREG Scan is a JS-only wizard, the
+annual report carries the supplier list and no per-product coefficients, and
+VREG was unreachable. Every coefficient found in research came off a supplier's
+own PDF, one of them image-only. So there is nothing to scrape and a
+per-supplier plugin would have no source for its numbers - fourteen plugins
+would be fourteen copies of the same invention, which is the defect TARIFF-07
+withdrew three plugins for. THE CUSTOMER IS THE ONLY PARTY WHO CAN SEE THEIR
+OWN COEFFICIENTS, and the card they read them from is the only artefact that
+can grade them.
+
+THE SHAPE IS THE MARKET'S PUBLISHED ARITHMETIC, NOT OUR APPROXIMATION
+====================================================================
+Both suppliers whose 2026 cards were readable print the formula, the reference
+index they assumed AND the resulting price, so the arithmetic below is
+reproducible against something they published rather than against our own
+guess:
+
+    Eneco   (0.102 x 133.9905 + 1.00) x 1.06 = 15.5471   card prints  15,55
+    ENGIE   (0.100 x  61.96   + 0.90) x 1.06 =  7.5218   card prints   7,522
+
+Two independent suppliers, reproduced to the last printed digit, in
+c EUR/kWh. test_price.py section 13 runs both through the SHIPPED code.
+
+⚠️ THE DOUBLE-COUNTING MECHANISM, AND WHY THIS DESIGN IS SAFE AT ALL
+====================================================================
+This provider declares `sources = {ENERGY, MARKUP}` and NOT `ALL_IN`. A Belgian
+card's `Tariefformule` line is THE ENERGY COMPONENT ONLY: Eneco puts network
+tariffs in one table and levies in a second, and ENGIE states in so many words
+that the formula "does not include fixed network/distribution costs, transport,
+grid levies, or excise duties". Declaring ALL_IN would lie on behalf of every
+user who typed what their card says, and would silently drop ~12 c EUR/kWh.
+
+price.py already mechanises that a PLUGIN cannot double-count (`PluginOptions`,
+`FRAMEWORK_KEYS`, `code_leaks()`). This provider introduces a risk none of those
+can see, because it is not in the code: THE OPERATOR double-counting, by folding
+their network charges into `offset` while `price_taxes_eur_kwh` carries them as
+well. `code_leaks()` scans code. This is config.
+
+So the card is the grader:
+
+    At startup validate.py computes
+    `(factor x card.index_eur_per_mwh + offset) x (1 + vat_pct/100)` and
+    REFUSES TO START unless it equals `card.expect_incl_vat` to within
+    CARD_TOLERANCE, naming the discrepancy.
+
+An `offset` inflated by network charges CANNOT PASS: the card's printed estimate
+is by construction the energy component alone, so adding ~12 c EUR/kWh moves
+15.55 to ~27 and the add-on refuses. The same check catches VAT omitted, VAT
+applied twice, a transposed digit, and a UNIT MISMATCH BETWEEN THE TWO SIDES -
+coefficients read off the formula line while the expected price is typed in
+another convention, which is the factor-10/100/1000 class as it actually
+happens.
+
+⚠️ THE ONE UNIT ERROR THE CARD CHECK CANNOT SEE IS THE ONE APPLIED TO BOTH
+SIDES AT ONCE, and saying so is the difference between a guard and a slogan:
+scaling the coefficients AND the expected price by the same 100 cancels out of
+a comparison between them. That is what `implausible_all_in()` is for, and it
+is a SEPARATE refusal on a SEPARATE quantity - the card's own point, all-in,
+against the band a Belgian retail tariff can occupy.
+
+⚠️ AND THE LIMIT, IN THE SAME BREATH AS THE CLAIM, exactly as price.py's trap 1
+states its own: THE CHECK GRADES THE COEFFICIENTS AGAINST THE CARD, NOT THE CARD
+AGAINST REALITY. A consistent-but-wrong pair - both numbers copied off the wrong
+product, or off last year's card - reproduces its own printed price perfectly
+and passes. Nothing here or anywhere else can catch that; what is mechanised is
+that the two coefficients and the printed estimate AGREE, which is the whole of
+the unit/VAT/decimal-point class and none of the "wrong contract" class.
+
+⚠️ FIXED COEFFICIENTS. NO EXPRESSION EVALUATION OF ANY KIND.
+============================================================
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B x index + A`, so an expression buys nothing the market needs. Against that:
+
+  * the add-on serves `POST config/save` -> `POST /addons/self/options` on its
+    own ingress page, so this string is SETTABLE OVER HTTP. `eval` on it is
+    remote code execution in a root container holding SUPERVISOR_TOKEN, with
+    `homeassistant_api` and `hassio_api`, driving an inverter over RS485.
+    (`eval(s, {"__builtins__": {}})` is not a sandbox and never was.)
+  * ⚠️ AND THE DECIDING ARGUMENT IS NOT SECURITY - AN EXPRESSION IS
+    UNVERIFIABLE. Two coefficients can be graded against the card's printed
+    estimate. An arbitrary expression cannot be graded against anything, so it
+    makes the invisible-wrong-coefficient problem STRICTLY WORSE, which is the
+    exact failure this provider exists to prevent.
+
+Future shapes become NAMED FIELDS - `clamp_lo`, `factor_negative`,
+`offset_bands` - each individually refusable and each individually gradeable
+against a card. Never a grammar. `parse_price_formula()` therefore REFUSES AN
+UNKNOWN KEY rather than ignoring it, so a user who types `"expr"` is told it
+does not exist instead of being silently priced on the fields they also typed.
+test_price.py section 13f walks this module's AST and fails if `eval`, `exec`,
+`compile`, `__import__` or `literal_eval` ever appears in it.
+
+WHERE THE NUMBERS COME FROM AND WHERE THEY GO
+=============================================
+`index` names the reference series. `epex_be` is the EPEX BE day-ahead curve in
+EUR/MWh, which is what `generic_dayahead` already fetches - same feed, same
+`brussels_date_range()` request, same columnar parser, same declared egress
+hosts. No new parser and no new failure mode.
+
+`resolution` says which series the contract is written against:
+
+  * `quarter_hourly` - the 96 points the feed publishes since Belgium's
+    15-minute MTU (2025-10-01), emitted as they are;
+  * `hourly`         - the four quarters of each hour averaged into one point.
+
+⚠️ NEITHER IS AN HOURLY ASSUMPTION IN `_Series.at()`'s SENSE (TARIFF-14). The
+hourly option changes how many POINTS are emitted and their spacing; the window
+each point covers is still derived from its neighbours by `_cover_table()`, and
+nothing here tells anything downstream how long a point lasts. A feed that is
+already hourly averages one member per hour, which is the identity - so the
+option cannot silently assume the granularity it was handed.
+
+`units` is NOT bureaucracy. Two suppliers publish the same shape in different
+units and the market aggregator prints both conventions in one column, so the
+add-on has to be told which one the card is in - and the unit conversion is the
+add-on's job precisely because it is one of the two steps that silently costs a
+factor of 10, 100 or 1000. The other is VAT, which is also the add-on's.
+
+TARIFF-16 - THE SECOND LEG, AND WHY IT IS THIS PARSER AND NOT A SECOND ONE
+==========================================================================
+A Belgian dynamic contract has TWO published lines, not one, and the second is
+what the site is PAID for export:
+
+    Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c EUR/kWh
+    ENGIE Dynamic                (B x eSpot_15) - A
+    Aspiravi (non-dynamic)       0,07 x Belpex - 2
+
+Same `B x index + A` shape - which is why `price_export_formula` is this
+module's parser with ONE argument moved (`option`), exactly as TARIFF-17 made
+`parse_static_profile()`'s option name a parameter rather than forking the
+period grammar. What differs between the two legs is FOUR numbers and a
+handful of sentences, and all of them are rows of `_LEGS`:
+
+  * its OWN factor - Eneco 0,102 on consumption against 0,100 on injection,
+    Aspiravi 0,07 against ~0,10. NOT the consumption `B` with a sign flip;
+  * a NEGATIVE offset, which `factor`/`offset` already allow and which
+    `price_markup_eur_kwh: float(0,1)` cannot express at all;
+  * `vat_pct: 0` - "Injectietarieven zijn vrijgesteld van btw" - against 6 on
+    consumption, which is a SIX PERCENT ASYMMETRY between the buy leg and the
+    sell leg and is representable only because `vat_pct` is PER SPEC;
+  * a price that goes BELOW ZERO with no floor, in the hours a PV household
+    exports. `implausible_injection()` is the band that accepts that and still
+    refuses an implausible one; `implausible_all_in()` is NOT it, and its
+    docstring says why.
+
+⚠️ AND THE CARD CANNOT ALWAYS GRADE IT. Eneco's injection formula is printed
+with NO price beside it, so on that card there is nothing to reproduce. The
+`card` block is therefore OPTIONAL on this leg and REQUIRED on the other, the
+self-check runs wherever there is a printed estimate, and validate.py says at
+startup when a leg is ungraded. Inventing an estimate to grade against would
+be grading arithmetic against itself, which is the defect MUTATION.md habit 4
+is about; TARIFF-15 demonstrated two tariffs end to end rather than three for
+the same reason.
+
+⚠️ NOTHING TRADES ON THIS TODAY, AND SAYING SO IS PART OF SHIPPING IT.
+`arbitrage.py` does not read `export_price_eur_kwh` at all - its own comment
+says so, citing §9.3's near-zero Belgian injection price - and both hours it
+compares are all-in CONSUMPTION prices. So this is not a wrong-trade defect
+and must not be described as one. What it changes is what an operator is told,
+and what a future export-aware strategy would rest on.
+"""
+
+import json
+import math
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+
+from . import messages
+
+
+class FormulaInvalid(Exception):
+    """`price_formula` cannot be used. Raised by the parser, refused by
+    validate.py at startup - never at 03:00 on a fetch."""
+
+
+# --------------------------------------------------------------------------- #
+# The enumerations. Every one of these is a CLOSED set, and that is the point:
+# an unknown value is refused by name rather than guessed at.
+# --------------------------------------------------------------------------- #
+
+# unit -> how many EUR/kWh one of it is. ⚠️ THE WHOLE FACTOR-1000 CLASS LIVES
+# HERE, so the table is tiny, explicit, and has no "default".
+UNITS: dict = {
+    "c_eur_per_kwh": 0.01,      # eurocent per kWh - Eneco and ENGIE print this
+    "eur_per_kwh": 1.0,         # some aggregators print this
+    "eur_per_mwh": 0.001,       # the wholesale convention, occasionally reused
+}
+
+RESOLUTIONS: tuple = ("hourly", "quarter_hourly")
+
+# index id -> the human name of the series it refers to. One entry today; a
+# second index is a new row here plus a fetch path, not a new grammar.
+INDEXES: dict = {
+    "epex_be": "Belgian day-ahead price, EUR/MWh",
+}
+
+# ⚠️ 0.01 IN THE CARD'S OWN UNITS, WHICH IS THE LAST DIGIT BOTH REAL CARDS
+# PRINT. Eneco prints 15,55 against a computed 15.5471 (0.0029 out) and ENGIE
+# prints 7,522 against a computed 7.5218 (0.0002 out), so the tolerance has to
+# absorb the card's own rounding and nothing more. Every error class this check
+# exists for - a factor of 10, of 100, of 1000, a missing or doubled 1.06, a
+# transposed digit, ~12 c EUR/kWh of network charge folded into `offset` - is
+# at least two orders of magnitude bigger than this.
+CARD_TOLERANCE = 0.01
+
+# The all-in plausibility band, EUR/kWh. `MAX_PLAUSIBLE_EUR_KWH` in price.py
+# bounds only prices that are too LARGE; this is the other end, and it is the
+# one the factor-1000 error falls off.
+PLAUSIBLE_LO_EUR_KWH = 0.02
+PLAUSIBLE_HI_EUR_KWH = 1.00
+
+# ~6 months. ⚠️ A WARNING, NEVER A REFUSAL: ENGIE freezes a contract's
+# coefficients for its duration, so a card two years old can be exactly right
+# and a site refused over one would be a site that cannot start.
+CARD_STALE_DAYS = 183
+
+_CARD_KEYS = ("month", "index_eur_per_mwh", "expect_incl_vat")
+_TOP_KEYS = ("index", "resolution", "factor", "offset", "units", "vat_pct",
+             "card")
+
+# --------------------------------------------------------------------------- #
+# TARIFF-16 - the SECOND leg, and the one parameter that carries it
+# --------------------------------------------------------------------------- #
+
+EXPORT_FORMULA_OPTION = "price_export_formula"
+
+# ⚠️ THE PASS-THROUGH FRACTION, WHICH IS WHY THE NEXT TWO BOUNDS CAN BE
+# INDEX-FREE. One EUR/MWh IS 0.001 EUR/kWh, so `factor x UNITS[units] / 0.001`
+# is the dimensionless share of the wholesale price the contract passes
+# through - 1.00 for Eneco's injection leg (0,100 c EUR/kWh per EUR/MWh), 0.70
+# for Aspiravi's (0,07). A coefficient typed a hundred times too small or too
+# large moves this by a hundred, whatever the index and whatever the sign of
+# the price.
+EUR_KWH_PER_EUR_MWH = 0.001
+
+# The two plausibility bounds for an INJECTION leg. ⚠️ NEITHER LOOKS AT THE
+# SIGN OF THE PRICE, AND THAT IS THE WHOLE POINT - see
+# `implausible_injection()`.
+PASSTHROUGH_LO = 0.10       # 10% of the wholesale price
+PASSTHROUGH_HI = 10.0       # 1000% of it
+INJECTION_OFFSET_MAX_EUR_KWH = 0.20
+
+
+@dataclass(frozen=True)
+class _Leg:
+    """What ONE option's coefficients price, as sentences its refusals read.
+
+    ⚠️ TARIFF-16 MADE `option` A PARAMETER RATHER THAN FORKING THE PARSER,
+    exactly as TARIFF-17 made `option`/`means` parameters of
+    `parse_static_profile()` rather than forking the period grammar. A second
+    copy of this parser would be a second `_finite()`, a second unknown-key
+    rule, a second unit table and a second `to_resolution()` - and the two
+    would diverge first on the 23- and 25-hour days, where nobody looks.
+    Everything that differs between the consumption leg and the injection leg
+    is a STRING in this table; the arithmetic, the enumerations, the card
+    comparison and the resolution rule are ONE implementation with one set of
+    checks over it.
+    """
+
+    option: str
+    what: str            # "consumption" / "injection", for a sentence
+    example: str         # a VALID blob for this leg, in the JSON-error hint
+    when: str            # when this option is read at all
+    flat: str            # where a FLAT price of this kind already lives
+    zero_factor: str     # what a factor of 0 actually costs on this leg
+    neg_factor: str      # why a negative FACTOR is wrong on this leg
+    card_required: bool
+    card_note: str       # why it is required, or what is lost without it
+    card_causes: str     # the leg-specific tail of `card_refusal()`
+
+
+_LEGS = {
+    "price_formula": _Leg(
+        option="price_formula",
+        what="consumption",
+        example=('{"index":"epex_be","resolution":"hourly","factor":0.102,'
+                 '"offset":1.00,"units":"c_eur_per_kwh","vat_pct":6,'
+                 '"card":{"month":"2026-09","index_eur_per_mwh":133.9905,'
+                 '"expect_incl_vat":15.55}}'),
+        when="Leave it empty unless “Dynamic price source” is 'custom_formula'.",
+        zero_factor=" and trading never finds a price difference",
+        flat="use “Fixed or day/night tariff” (static_profile) instead",
+        neg_factor="Put the minus sign on the offset, not on the factor",
+        card_required=True,
+        card_note="The add-on needs it to check your two numbers",
+        card_causes=("the units, the VAT, and that network charges are not "
+                     "in the offset"),
+    ),
+    EXPORT_FORMULA_OPTION: _Leg(
+        option=EXPORT_FORMULA_OPTION,
+        what="injection",
+        example=('{"index":"epex_be","resolution":"hourly","factor":0.1,'
+                 '"offset":-1.188,"units":"c_eur_per_kwh","vat_pct":0}'),
+        when="Fill it in only if your injection price follows the market.",
+        zero_factor="",
+        flat="use “Injection price” (export_price_eur_kwh) instead",
+        neg_factor="Put the minus sign on the offset, not on the factor",
+        card_required=False,
+        card_note=("It is optional here. Without it the add-on only checks "
+                   "the size of your two numbers"),
+        card_causes="the units, and that the VAT is 0 for injection",
+    ),
+}
+
+
+
+@dataclass(frozen=True)
+class FormulaSpec:
+    """One contract's published arithmetic. SEVEN numbers and no code.
+
+    ⚠️ EVERY FIELD IS A FIXED, NAMED SCALAR. There is deliberately no field
+    that holds an expression, a callable, a lambda or a template, and there is
+    no place to put one: `parse_price_formula()` refuses an unrecognised key.
+    """
+
+    index: str
+    resolution: str
+    factor: float
+    offset: float
+    units: str
+    vat_pct: float
+    card_month: str = ""            # "YYYY-MM", as the card is dated
+    card_index_eur_per_mwh: float = None
+    card_expect_incl_vat: float = None   # in `units`, as the card prints it
+    # TARIFF-16. Which OPTION this spec was read from, so a refusal, a log line
+    # and `card_graded` name the leg the operator actually typed.
+    option: str = "price_formula"
+
+    @property
+    def unit_to_eur_kwh(self) -> float:
+        return UNITS[self.units]
+
+    @property
+    def card_graded(self) -> bool:
+        """Is there a printed estimate to grade these coefficients against?
+
+        ⚠️ FALSE IS A REAL, SHIPPED STATE ON THE INJECTION LEG and is reported
+        rather than defaulted: Eneco's injection formula is printed with no
+        price beside it. Never False on `price_formula`, where `_card()`
+        refuses an absent block.
+        """
+        return self.card_expect_incl_vat is not None
+
+    @property
+    def passthrough(self) -> float:
+        """The dimensionless share of the wholesale price this passes through.
+
+        `factor x UNITS[units] / 0.001`. 1.00 for Eneco's injection leg, 0.70
+        for Aspiravi's. ⚠️ INDEX-FREE AND SIGN-FREE, which is what lets
+        `implausible_injection()` bound a leg whose price legitimately goes
+        below zero.
+        """
+        return self.factor * self.unit_to_eur_kwh / EUR_KWH_PER_EUR_MWH
+
+    @property
+    def offset_eur_kwh(self) -> float:
+        """The offset in EUR/kWh, whatever units the card printed it in."""
+        return self.offset * self.unit_to_eur_kwh
+
+
+# --------------------------------------------------------------------------- #
+# The arithmetic. Two functions, and the SECOND one is the contract.
+# --------------------------------------------------------------------------- #
+
+def in_card_units(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
+    """`(factor x index + offset) x (1 + vat_pct/100)`, in the card's units.
+
+    This is the line the card prints, spelled exactly as the card spells it,
+    and it is the only place the coefficients are combined. The card
+    self-check and the price path both go through here, so a mutation to it
+    cannot move the price without also moving the self-check.
+    """
+    return ((spec.factor * float(index_eur_per_mwh) + spec.offset)
+            * (1.0 + spec.vat_pct / 100.0))
+
+
+def price_eur_kwh(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
+    """The energy+markup price for one index value, in EUR/kWh.
+
+    ⚠️ THE UNIT CONVERSION IS THE ADD-ON'S JOB AND IT HAPPENS HERE, ONCE. The
+    user types what their card prints, in the card's own units; every step
+    from there to EUR/kWh is code, because those steps are exactly the ones
+    that silently cost a factor of 10, 100 or 1000 when a human does them.
+    """
+    return in_card_units(spec, index_eur_per_mwh) * spec.unit_to_eur_kwh
+
+
+def card_discrepancy(spec: FormulaSpec) -> float:
+    """How far the coefficients land from the card's own printed estimate.
+
+    In the card's units, signed: positive means the formula computes MORE than
+    the card prints, which is the direction an `offset` carrying network
+    charges moves it.
+
+    ⚠️ RAISES ON A SPEC WITH NO CARD RATHER THAN RETURNING 0.0 (TARIFF-16). An
+    ungraded injection leg has no printed estimate, and a discrepancy of zero
+    is exactly what "the coefficients reproduce the card" looks like - so a
+    silent zero here would report the strongest possible result for the one
+    state in which nothing was compared at all.
+    """
+    if not spec.card_graded:
+        raise FormulaInvalid(
+            f"{spec.option} has no card block, so there is no printed "
+            f"estimate to measure a discrepancy against. Ask "
+            f"`spec.card_graded` before calling this.")
+    return in_card_units(spec, spec.card_index_eur_per_mwh) \
+        - spec.card_expect_incl_vat
+
+
+# --------------------------------------------------------------------------- #
+# Reading the option
+# --------------------------------------------------------------------------- #
+
+def _finite(value, field: str, option: str = "price_formula") -> float:
+    """A real, finite number - or a refusal naming the field.
+
+    ⚠️ SAME CLASS AS `_validate_raw()`'s NaN RULE, one layer earlier. A NaN
+    factor makes every price NaN, every comparison False, and an arbitrage
+    strategy that silently never fires; `True` is an `int` in Python and would
+    price the whole day at the index.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise FormulaInvalid(
+            f"{option}.{field} is {value!r}, which is not a number. Write a "
+            f"plain number, for example 0.102.")
+    if not math.isfinite(float(value)):
+        raise FormulaInvalid(
+            f"{option}.{field} is {value!r}, which is not finite. Write a "
+            f"plain number, for example 0.102.")
+    return float(value)
+
+
+def _card(raw, leg: _Leg = None) -> tuple:
+    """The `card` block: the estimate the coefficients are graded against.
+
+    ⚠️ REQUIRED ON THE CONSUMPTION LEG AND OPTIONAL ON THE INJECTION ONE, and
+    the asymmetry is a fact about the CARDS rather than a relaxed rule. See
+    `_LEGS[EXPORT_FORMULA_OPTION].card_note`: Eneco's injection formula is
+    printed with no price beside it, so on that card there is nothing to grade
+    against. `("", None, None)` is the ungraded answer and
+    `FormulaSpec.card_graded` is how every caller asks.
+    """
+    if leg is None:
+        leg = _LEGS["price_formula"]
+    if raw is None:
+        if not leg.card_required:
+            return ("", None, None)
+        raise FormulaInvalid(
+            f"{leg.option} has no \"card\" block. {leg.card_note}. Copy "
+            "the three figures from your tariff card, for example "
+            "{\"month\": \"2026-09\", \"index_eur_per_mwh\": 133.9905, "
+            "\"expect_incl_vat\": 15.55}.")
+    if not isinstance(raw, dict):
+        raise FormulaInvalid(
+            f"{leg.option}.card is {type(raw).__name__}, not an object with "
+            f"{', '.join(_CARD_KEYS)}.")
+    unknown = sorted(set(raw) - set(_CARD_KEYS))
+    if unknown:
+        raise FormulaInvalid(
+            f"{leg.option}.card has unknown field(s) {unknown}. It takes "
+            f"only {list(_CARD_KEYS)}.")
+    month = str(raw.get("month", "") or "").strip()
+    if not _month_date(month):
+        raise FormulaInvalid(
+            f"{leg.option}.card.month is {raw.get('month')!r}. Write the "
+            f"month of the card as \"YYYY-MM\", for example \"2026-09\".")
+    return (month,
+            _finite(raw.get("index_eur_per_mwh"), "card.index_eur_per_mwh",
+                    leg.option),
+            _finite(raw.get("expect_incl_vat"), "card.expect_incl_vat",
+                    leg.option))
+
+
+def _month_date(month: str):
+    """`"2026-09"` -> the first of that month, or None if it is not one."""
+    try:
+        year, mon = str(month).split("-")
+        return date(int(year), int(mon), 1)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_price_formula(value, *, option: str = "price_formula"):
+    """`price_formula` -> a `FormulaSpec`, or None when unset.
+
+    ⚠️ `option` IS TARIFF-16'S WHOLE REUSE, and it is TARIFF-17's move. It
+    selects a row of `_LEGS` and nothing else: the enumerations, the
+    arithmetic, `to_resolution()`, the unknown-key rule and the card
+    comparison are shared, and every pre-existing call site - which passes no
+    `option` at all - lands on the consumption row and reads byte-identical
+    sentences. `parse_export_formula()` is a two-line wrapper, not a fork.
+
+    Accepts what the option can actually arrive as, exactly as
+    `parse_static_profile()` does:
+
+      * `None` / `""` / `"null"`   - unset.
+      * a JSON string              - what config.yaml's flat `str?` option
+                                     carries on a Supervisor install.
+      * a dict                     - already parsed, from a future nested
+                                     schema, from sim/inject.py, or a check.
+
+    Raises `FormulaInvalid`; never returns a half-built spec.
+
+    ⚠️ THE CARD SELF-CHECK IS PART OF PARSING, not a separate step a caller
+    may forget. Both callers - validate.py's startup gate and the plugin's own
+    fetch - go through this one function, so there is no route to a price that
+    has not been graded against the card.
+    """
+    leg = _LEGS[option]
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text or text.lower() in ("null", "none", "off"):
+            return None
+        try:
+            value = json.loads(text)
+        except ValueError as e:
+            raise FormulaInvalid(
+                f"{messages.not_valid(option, e)}. Copy the example from the "
+                f"documentation. {leg.when}")
+    if not isinstance(value, dict):
+        raise FormulaInvalid(
+            f"{option} is {type(value).__name__}, not a JSON object with "
+            f"{', '.join(_TOP_KEYS)}.")
+
+    # ⚠️ AN UNKNOWN KEY IS REFUSED, NOT IGNORED, AND THIS IS THE HALF THAT
+    # KEEPS THE "NEVER A GRAMMAR" PROMISE HONEST. A future shape is a NAMED
+    # field - clamp_lo, factor_negative, offset_bands - added here and
+    # refusable on its own. Ignoring unknown keys would mean a user who typed
+    # "expr" or "formula" gets priced on the fields they also typed, with the
+    # one they believed in dropped in silence.
+    unknown = sorted(set(value) - set(_TOP_KEYS))
+    if unknown:
+        raise FormulaInvalid(
+            f"{option} has unknown field(s) {unknown}. It takes only "
+            f"{list(_TOP_KEYS)}.")
+
+    index = str(value.get("index", "") or "").strip()
+    if index not in INDEXES:
+        raise FormulaInvalid(
+            f"{option}.index is {value.get('index')!r}. The add-on can only "
+            f"fetch "
+            f"{', '.join(f'{k!r} ({v})' for k, v in sorted(INDEXES.items()))}.")
+
+    resolution = str(value.get("resolution", "") or "").strip()
+    if resolution not in RESOLUTIONS:
+        raise FormulaInvalid(
+            f"{option}.resolution is {value.get('resolution')!r}. Choose one "
+            f"of {list(RESOLUTIONS)}, as your tariff card says.")
+
+    # ⚠️ `units` IS REQUIRED AND HAS NO DEFAULT. A default here would be the
+    # factor-1000 class with a friendly face: the add-on would silently assume
+    # a convention the card never stated, and the card self-check would then
+    # be graded in units nobody chose.
+    units = str(value.get("units", "") or "").strip()
+    if units not in UNITS:
+        raise FormulaInvalid(
+            f"{option}.units is {value.get('units')!r}. Choose one of "
+            f"{sorted(UNITS)}, as printed beside the formula on your card.")
+
+    factor = _finite(value.get("factor"), "factor", option)
+    offset = _finite(value.get("offset"), "offset", option)
+    vat_pct = _finite(value.get("vat_pct"), "vat_pct", option)
+
+    # ⚠️ ZERO IS NOT "NO INDEXATION", IT IS A FIXED TARIFF WEARING A DYNAMIC
+    # ONE'S CLOTHES. Every hour comes out at the same price, so every spread is
+    # 0, arbitrage can never clear any threshold, and a strategy that never
+    # fires is indistinguishable from one that is switched off (§14's warning
+    # box). The add-on already has a first-class way to say "one price": point
+    # the operator at it rather than let them build it by accident.
+    if factor == 0.0:
+        raise FormulaInvalid(
+            f"{option}.factor is 0, so every hour gets the same {leg.what} "
+            f"price{leg.zero_factor}. For one flat price, {leg.flat}.")
+
+    # ⚠️ A NEGATIVE FACTOR INVERTS THE MARKET, and the direction is the danger:
+    # the dearest hour becomes the cheapest one, so the battery is told to
+    # charge into the evening peak and to discharge at 03:00. That is not a
+    # mispriced site, it is a site actively trading against itself.
+    if factor < 0.0:
+        raise FormulaInvalid(
+            f"{option}.factor is {factor:g}, which turns the market upside "
+            f"down. {leg.neg_factor}.")
+
+    # ⚠️ 0 IS LEGITIMATE AND MUST STAY SO: injection is VAT-exempt in Belgium,
+    # and some cards are already quoted VAT-inclusive. The bound exists for the
+    # 106 / 1.06 / 6 confusion, not to make VAT compulsory.
+    if not 0.0 <= vat_pct <= 30.0:
+        raise FormulaInvalid(
+            f"{option}.vat_pct is {vat_pct:g}. Write a percentage between 0 "
+            f"and 30, for example 6.")
+
+    month, card_index, card_expect = _card(value.get("card"), leg)
+    spec = FormulaSpec(index=index, resolution=resolution, factor=factor,
+                       offset=offset, units=units, vat_pct=vat_pct,
+                       card_month=month, card_index_eur_per_mwh=card_index,
+                       card_expect_incl_vat=card_expect, option=option)
+
+    # ⚠️ THE CARD SELF-CHECK STILL RUNS WHEREVER THERE IS A CARD TO RUN IT
+    # AGAINST, on either leg, with the same tolerance. What TARIFF-16 adds is
+    # the honest answer for the leg where the card prints no estimate: NOT a
+    # weakened comparison and NOT an estimate computed here, but two bounds on
+    # the COEFFICIENTS that need no printed price - see
+    # `implausible_injection()` - and a startup line saying the leg is
+    # ungraded.
+    if spec.card_graded:
+        delta = card_discrepancy(spec)
+        if abs(delta) > CARD_TOLERANCE:
+            raise FormulaInvalid(card_refusal(spec, delta))
+    if option == EXPORT_FORMULA_OPTION:
+        band = implausible_injection(spec)
+        if band:
+            raise FormulaInvalid(band)
+    return spec
+
+
+def parse_export_formula(value):
+    """`price_export_formula` -> the INJECTION leg's `FormulaSpec`, or None.
+
+    TARIFF-16. THE DEFECT THIS EXISTS TO CLOSE: `price.py` modelled injection
+    as ONE scalar, and the market publishes a line with four properties a
+    scalar cannot hold. Verbatim off the cards:
+
+        Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c EUR/kWh
+            "Het injectietarief is dynamisch en kan per uur wijzigen"
+            - identical on the January and the September 2026 cards
+        ENGIE Dynamic                (B x eSpot_15) - A       c EUR/kWh
+        Aspiravi (non-dynamic)       0,07 x Belpex - 2
+
+      1. ITS OWN FACTOR. Eneco uses 0,102 on consumption and 0,100 on
+         injection; Aspiravi 0,07 against ~0,10 on its consumption leg. It is
+         NOT the consumption `B` with a sign flip.
+      2. A NEGATIVE OFFSET - `- 1,188`, `- 2`. Note that
+         `price_markup_eur_kwh: float(0,1)` cannot express a negative markup
+         at all, so the offset has no home on the consumption side either.
+      3. VAT-EXEMPT. "Injectietarieven zijn vrijgesteld van btw", while
+         consumption is at 6% - a SIX PERCENT ASYMMETRY between the buy leg
+         and the sell leg, which a single scalar cannot even state.
+      4. IT GOES NEGATIVE, WITH NO FLOOR. Eneco's injection price is negative
+         for any BELPEX-H below 11,88 EUR/MWh, and a PV household exports
+         precisely in the hours most likely to be negative. You can be charged
+         to export.
+
+    ⚠️ AND WHAT THIS DOES **NOT** AFFECT TODAY, SAID HERE SO NOBODY READS THE
+    ABOVE AS A TRADING BUG. `arbitrage.py` does not read
+    `export_price_eur_kwh` at all - its own comment says so, and gives §9.3's
+    near-zero Belgian injection price as the reason the economically sound
+    trade on this market is charge-cheap-to-displace-expensive-IMPORT. Both
+    hours it compares are all-in CONSUMPTION prices. So no trade the add-on
+    takes today is decided by this number, and this card is not a correction
+    of a wrong trade. What it changes is what an operator is told, and what
+    any future export-aware strategy would rest on: OPT-06 and any export
+    logic would otherwise inherit a scalar that cannot represent the market,
+    and the 6% VAT asymmetry would be invisible in the arithmetic.
+
+    ⚠️ THE SCALAR IS NOT REPLACED. `export_price_eur_kwh()` is untouched and
+    still answers for every site with a flat injection price, which is every
+    site that exists today; this option ships "". That is `price.py`'s own
+    prediction coming true rather than a new design - "when it does land, an
+    injection curve gets a `PriceProvider` of its own and this scalar becomes
+    its FIXED-product default; the seam is already the right shape for that."
+    """
+    return parse_price_formula(value, option=EXPORT_FORMULA_OPTION)
+
+
+def card_refusal(spec: FormulaSpec, delta: float) -> str:
+    """The sentence an operator reads when their formula misses its own card.
+
+    It names both numbers and what to check. The usual causes are in DOCS.md,
+    because each of these errors looks like a working tariff on the status page.
+    """
+    got = in_card_units(spec, spec.card_index_eur_per_mwh)
+    leg = _LEGS[spec.option]
+    return (
+        f"{spec.option} gives {got:.4f} "
+        f"{messages.UNIT_WORDS.get(spec.units, spec.units)}, the card says "
+        f"{spec.card_expect_incl_vat:g}. Check {leg.card_causes}.")
+
+
+# --------------------------------------------------------------------------- #
+# The two questions the PLUGIN cannot ask, because they need framework numbers
+# --------------------------------------------------------------------------- #
+
+def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
+    """The card's own point, if its LEVEL cannot be a Belgian retail price.
+
+    Returns a refusal sentence or None. ⚠️ CALLED FROM validate.py AND FROM
+    NOWHERE ELSE, because it reads a FRAMEWORK-owned number: a plugin that
+    could see `taxes` could add it a second time, which is price.py's trap 1.
+
+    ⚠️ THE LOW END IS GRADED ON THE ENERGY COMPONENT AND THE HIGH END ON THE
+    ALL-IN FIGURE, AND THAT ASYMMETRY IS THE CHECK RATHER THAN AN OVERSIGHT.
+    `price_taxes_eur_kwh` ships at 0.11736 (TARIFF-18; it was 0.06 before, and
+    the argument was already decisive at that figure), which is nearly SIX
+    times the low bound - so a card read a HUNDRED times too small comes out at
+    0.0016 EUR/kWh of energy, is carried over the floor by the flat tax addend
+    alone, and passes a band applied to the all-in total. The hundredfold error
+    is precisely what this exists to catch, so the floor is applied where it
+    can still see it. ⚠️ Raising the default made this trap WIDER, not
+    narrower: the addend that does the carrying got bigger. The ceiling is
+    applied to the all-in figure because that is the number the site is really
+    billed at, and taxes only push it up.
+
+    ⚠️ AND THE LIMIT, WITH THE CLAIM. This grades the CARD'S OWN POINT - one
+    price, at the monthly index the card assumed - and not every hour of every
+    day. A live EPEX hour can and should fall outside this band (a negative
+    hour is the best charging opportunity of the year, and §17 keeps a
+    regression case for it), so the band is deliberately NOT applied to the
+    fetched series. What it catches is a formula whose whole LEVEL is wrong,
+    which is the factor-of-1000 class arriving from the end
+    `MAX_PLAUSIBLE_EUR_KWH` does not bound.
+
+    ⚠️ AND IT IS THE CONSUMPTION LEG'S BAND ONLY - TARIFF-16 DELIBERATELY DID
+    NOT POINT IT AT THE INJECTION LEG. Two reasons, and the second is an
+    acceptance criterion rather than a preference:
+
+      * it adds `taxes_eur_kwh`, and `price_taxes_eur_kwh` is a CONSUMPTION
+        component. Nothing is added to what a site is PAID for export, so the
+        `all_in` half would be adding a number the injection leg never carries;
+      * its floor is `energy >= 0.02 EUR/kWh`, and a REAL Eneco injection price
+        is negative for any BELPEX-H below 11,88 EUR/MWh - the hours a PV
+        household actually exports in. Applied to injection this floor would
+        refuse the market, and refuse it hardest in the hours where knowing the
+        number matters most. `implausible_injection()` is the injection band
+        and it is deliberately NOT this function with a lower floor.
+    """
+    energy = price_eur_kwh(spec, spec.card_index_eur_per_mwh)
+    all_in = energy + float(taxes_eur_kwh)
+    if energy >= PLAUSIBLE_LO_EUR_KWH and all_in <= PLAUSIBLE_HI_EUR_KWH:
+        return None
+    return (
+        f"{spec.option} gives {energy:.5f} EUR/kWh for energy and "
+        f"{all_in:.5f} EUR/kWh with “Distribution, levies and VAT” "
+        f"(price_taxes_eur_kwh), outside the plausible band of "
+        f"{PLAUSIBLE_LO_EUR_KWH}-{PLAUSIBLE_HI_EUR_KWH} EUR/kWh. Check \"units\" against the unit beside your formula.")
+
+
+def implausible_injection(spec: FormulaSpec):
+    """The INJECTION leg's plausibility band. Returns a refusal or None.
+
+    ⚠️ A NEGATIVE INJECTION PRICE IS ACCEPTED, NOT REFUSED, AND NEITHER RUNG
+    BELOW LOOKS AT THE SIGN OR THE LEVEL OF A PRICE. Eneco's published line
+    `0,1 x BELPEX-H - 1,188` is negative for any BELPEX-H under 11,88 EUR/MWh;
+    those are the midday hours a PV household exports in, so a band with a
+    floor above zero - which is what `implausible_all_in()` has, for the
+    consumption leg's own good reasons - would refuse the real market and
+    would hide it in exactly the hours it costs money. You CAN be charged to
+    export. The add-on says so rather than declining to represent it.
+
+    THE PROBLEM THAT LEAVES, STATED BEFORE THE SOLUTION. The consumption
+    floor was not decoration: it is what catches a whole card read a hundred
+    times too small, the one unit error the card self-check cannot see because
+    it cancels out of a comparison between the two sides. A band that spans
+    zero cannot catch it - 0.00132 EUR/kWh is inside any interval that
+    contains -0.03. So the bound moves OFF the price and ONTO the
+    coefficients, where it is index-free and sign-free:
+
+      * PASS-THROUGH. `factor x UNITS[units] / 0.001` is the dimensionless
+        share of the wholesale price the contract passes through, because one
+        EUR/MWh IS 0.001 EUR/kWh. Eneco's injection leg is 1.00 and Aspiravi's
+        is 0.70. A factor typed 100x too small reads 0.01 and 100x too large
+        reads 100, whatever the index and whatever the sign of the result.
+      * OFFSET MAGNITUDE. Eneco's is 1,188 c EUR/kWh = 0.01188 EUR/kWh and
+        Aspiravi's is 2 c = 0.02. A hundredfold error is 1.188 EUR/kWh, which
+        is not an injection tariff in any direction. The bound is on the
+        ABSOLUTE value, so a negative offset of a believable size passes and
+        that is the normal case on this leg.
+
+    ⚠️ TWO RUNGS THAT CAN BOTH ANSWER ONE STIMULUS, SO THEY ARE GRADED ON
+    THEIR REASONS AND MUTATED TOGETHER (MUTATION.md, TEST-16). A whole card
+    read 100x too large trips both. The fixtures in test_price.py 17d are
+    built so that each rung is the ONLY one that fires on its own stimulus.
+
+    ⚠️ AND WHAT THIS CANNOT SEE, WITH THE CLAIM (habit 13). It bounds the
+    SHAPE of the coefficients, never their truth: a contract really written
+    against a different index, or last year's coefficients, passes both rungs
+    and reproduces any card typed beside them. Where a card DOES print an
+    estimate the self-check grades the pair against it; where it does not -
+    which is Eneco's injection line - these two bounds are the whole of what
+    is mechanised, and validate.py says so at startup.
+    """
+    if not PASSTHROUGH_LO <= spec.passthrough <= PASSTHROUGH_HI:
+        return (
+            f"{spec.option}.factor passes through {spec.passthrough:.4g}x the "
+            f"market price, outside {PASSTHROUGH_LO}-{PASSTHROUGH_HI}x. Check "
+            f"\"units\" ({spec.units!r}) against the unit beside your "
+            f"formula.")
+    if abs(spec.offset_eur_kwh) > INJECTION_OFFSET_MAX_EUR_KWH:
+        return (
+            f"{spec.option}.offset is {spec.offset:g} {spec.units}, which is "
+            f"{spec.offset_eur_kwh:+.5f} EUR/kWh and larger than "
+            f"{INJECTION_OFFSET_MAX_EUR_KWH} EUR/kWh either way. Check its "
+            f"unit.")
+    return None
+
+
+def stale_card(spec: FormulaSpec, today=None):
+    """A warning when the card is older than ~6 months, or None. NEVER a
+    refusal: ENGIE freezes a contract's coefficients for its duration, so an
+    old card can be exactly right and refusing one would stop the add-on on a
+    correctly configured site."""
+    dated = _month_date(spec.card_month)
+    now = today or datetime.now(timezone.utc).date()
+    if dated is None or (now - dated).days <= CARD_STALE_DAYS:
+        return None
+    return (
+        f"{spec.option}'s card is dated {spec.card_month}, "
+        f"{(now - dated).days} days ago. The add-on still starts, but if your "
+        f"contract changed since, copy the new figures from your supplier.")
+
+
+# --------------------------------------------------------------------------- #
+# Resolution
+# --------------------------------------------------------------------------- #
+
+def to_resolution(pairs, resolution: str) -> list:
+    """`[(instant, index EUR/MWh)]` -> the series the CONTRACT is written on.
+
+    `quarter_hourly` hands the feed's own points back, ascending.
+    `hourly` averages each hour's members into one point AT THE TOP OF THE
+    HOUR.
+
+    ⚠️ THE BUCKET IS A UTC HOUR AND THAT IS EXACT FOR BELGIUM, not an
+    approximation: CET and CEST are both WHOLE-hour offsets, so a Brussels hour
+    and a UTC hour start at the same instant on every day of the year including
+    both transition days. Keying by a naive local hour is what collides the two
+    02:00s in October; keying by the UTC instant cannot.
+
+    ⚠️ AND THIS IS NOT `_Series.at()`'s HOURLY ASSUMPTION COMING BACK
+    (TARIFF-14). It decides how many points are EMITTED, not how long one
+    covers - the coverage window is still derived from the neighbours in
+    `_cover_table()`. A feed that already publishes hourly points averages one
+    member per hour, i.e. the identity, so this cannot silently assume the
+    granularity it was handed.
+
+    ⚠️ AN INCOMPLETE HOUR IS AVERAGED OVER WHAT IS THERE rather than dropped or
+    zero-filled. A horizon that starts at 09:20 has two quarters in its first
+    hour; their mean is the best statement available about that hour, and
+    dropping it would leave a hole `at()` answers with `Absence` for an hour
+    the feed did publish.
+    """
+    ordered = sorted(pairs, key=lambda r: r[0].astimezone(timezone.utc))
+    if resolution == "quarter_hourly":
+        return list(ordered)
+    if resolution != "hourly":
+        raise FormulaInvalid(f"unknown resolution {resolution!r}")
+    buckets: dict = {}
+    for start, value in ordered:
+        key = start.astimezone(timezone.utc).replace(
+            minute=0, second=0, microsecond=0)
+        buckets.setdefault(key, []).append(value)
+    return [(k, sum(v) / len(v)) for k, v in sorted(buckets.items())]
+
+
+# --------------------------------------------------------------------------- #
+# The startup preview
+# --------------------------------------------------------------------------- #
+
+PREVIEW_HOURS = 24
+PREVIEW_MAX_ROWS = 24
+
+
+def preview_lines(spec: FormulaSpec, rows) -> list:
+    """`[(instant, index EUR/MWh, all-in EUR/kWh)]` -> lines for the log.
+
+    THE DEFECT THIS EXISTS TO MAKE VISIBLE: every error this module refuses is
+    one the operator cannot see from the status page, and the two numbers that
+    would have shown it - the index that went IN and the price that came OUT -
+    are never printed beside each other anywhere else. A factor of 1000 is
+    obvious in one line of `61.96 -> 0.13522` and invisible in a plan.
+
+    ⚠️ IT PRINTS A BOUNDED NUMBER OF ROWS AND SAYS SO. At `quarter_hourly` the
+    next 24 h is 96 points; the cap is a row COUNT rather than "every fourth
+    point", because sampling every fourth point would assume the granularity
+    TARIFF-14 spent a card removing the assumption of.
+    """
+    if not rows:
+        return []
+    shown = rows[:PREVIEW_MAX_ROWS]
+    prices = sorted(r[2] for r in rows)
+    mid = len(prices) // 2
+    median = (prices[mid] if len(prices) % 2
+              else (prices[mid - 1] + prices[mid]) / 2.0)
+    out = [
+        f"custom_formula preview - the next {PREVIEW_HOURS} h of YOUR tariff, "
+        f"index EUR/MWh -> all-in EUR/kWh, computed as "
+        f"({spec.factor:g} x index + {spec.offset:g}) x "
+        f"(1 + {spec.vat_pct:g}/100) {spec.units}, converted to EUR/kWh and "
+        f"with price_taxes_eur_kwh added by the framework:"]
+    for start, index, all_in in shown:
+        out.append(f"    {start.isoformat()}  {index:9.3f} -> {all_in:9.5f}")
+    if len(rows) > len(shown):
+        out.append(f"    ... {len(rows) - len(shown)} further point(s) not "
+                   f"listed; the figures below cover ALL {len(rows)}")
+    out.append(
+        f"  min {prices[0]:.5f} / median {median:.5f} / max {prices[-1]:.5f} "
+        f"EUR/kWh, spread {prices[-1] - prices[0]:.5f} EUR/kWh over "
+        f"{len(rows)} point(s). ⚠️ If those are a thousand times what your "
+        f"bill says, `units` is wrong; if the spread is 0, `factor` is.")
+    return out
@@ -0,0 +1,262 @@
+"""OPT-11 P4: the day plan. Will the sun fill each battery before the
+expensive hours? If not, how much should it take from the grid?
+
+Pure: the forecast (`solarfc`), the house profile, the price runs and the
+batteries in; a level per battery (`Plan.targets`) out. `modetrade.charge_to()`
+turns the level into permission to charge from the grid; main.py rebuilds the
+plan with the price runs (at most every 15 minutes) and keeps a level unless
+it moves by `HYST_KWH` or `HYST_FRAC` (`hold()`).
+
+The sums (OPT-11-design section 1, "Excess solar", with the owner's answers):
+* `sun`: trust x the solar the house will not use, between now and the
+  expensive run the cheap run is for, x the charge efficiency:
+  `trust x sum_h max(0, forecast_h - house_h) x EFF`.
+* Solar first batteries take it first, up to the ceiling. What is left is
+  shared by the Leftover solar batteries by their room.
+* Cheap hours only ignores the plan and fills to the ceiling, as in P3 and
+  the design (section 1). Skipping the sun's share cost money in the replay
+  (PR #156 review: 29.72 against 29.41 EUR on real 2026 prices).
+* A Leftover solar battery charges only up to what the house will draw from
+  it in the expensive runs before the next cheap run, less its share:
+  `min(ceiling, floor + house use / EFF) - share`. So it buys only the
+  shortfall, not up to the ceiling.
+* Solar first never charges from the grid (owner, 2026-09-29).
+
+The house profile is the add-on's own measurement, grid + battery power, per
+local hour, over the last `PROFILE_DAYS` days; the estimate for an hour is the
+median of that hour. It is net of the solar the house used itself, so for
+the solar sum it is never taken below the night-time median (`base()`).
+The site's own solar readings are not used: TEL-11 keeps them out of every
+control decision.
+"""
+
+import statistics
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+
+from .packmode import LEFTOVER_SOLAR, SOLAR_FIRST
+from .tariff import BILLING_TZ
+
+EFF = 0.95                  # charge (and discharge) efficiency
+HYST_KWH = 1.0              # a kept level moves only by this much...
+HYST_FRAC = 0.10            # ...or this share of the battery's shortfall
+PROFILE_DAYS = 7
+MIN_HOURS = 20              # hours of a day recorded before it counts
+NIGHT_HOURS = (0, 1, 2, 3, 4, 5, 22, 23)
+DEFAULT_TRUST_PCT = 70
+
+# Site verdicts (the page's forecast line).
+SUNNY, PARTLY, DARK = "sunny", "partly", "dark"
+
+
+# --------------------------------------------------------------------------- #
+# The house profile
+# --------------------------------------------------------------------------- #
+def _local(t: datetime):
+    return t.astimezone(BILLING_TZ)
+
+
+class HouseProfile:
+    """Hourly means of the house's net use (grid + battery power), kept per
+    local day and hour: `{"YYYY-MM-DD": {hour: [mean_w, samples]}}`. The
+    store holds `dump()`; `load()` takes it back and drops what is bad."""
+
+    def __init__(self, data=None):
+        self.days = {}
+        self._cur = None            # (day, hour, sum, n)
+        if isinstance(data, dict):
+            self.load(data)
+
+    def load(self, data):
+        for day, hours in data.items():
+            try:
+                datetime.strptime(str(day), "%Y-%m-%d")
+            except ValueError:
+                continue
+            if not isinstance(hours, dict):
+                continue
+            row = {}
+            for h, v in hours.items():
+                try:
+                    hi, w = int(h), float(v)
+                except (TypeError, ValueError):
+                    continue
+                if 0 <= hi < 24 and abs(w) < 1e6:
+                    row[hi] = w
+            if row:
+                self.days[str(day)] = row
+
+    def dump(self) -> dict:
+        return {d: {str(h): round(w, 1) for h, w in sorted(r.items())}
+                for d, r in sorted(self.days.items())}
+
+    def add(self, now: datetime, house_w) -> bool:
+        """One reading. Returns True when an hour closed (then store it)."""
+        lt = _local(now)
+        key = (lt.strftime("%Y-%m-%d"), lt.hour)
+        closed = False
+        if self._cur is not None and self._cur[:2] != key:
+            day, hour, s, n = self._cur
+            if n >= 60:                 # about 5 minutes of readings
+                self.days.setdefault(day, {})[hour] = s / n
+                closed = True
+            self._cur = None
+            self._prune(lt)
+        if house_w is None:
+            return closed
+        if self._cur is None:
+            self._cur = (key[0], key[1], 0.0, 0)
+        d, h, s, n = self._cur
+        self._cur = (d, h, s + float(house_w), n + 1)
+        return closed
+
+    def _prune(self, lt):
+        """Keep the last `PROFILE_DAYS` days; a day after today (the clock
+        was wrong once) would never age out, so it goes too."""
+        keep = (lt.date() - timedelta(days=PROFILE_DAYS)).isoformat()
+        today = lt.date().isoformat()
+        for d in [d for d in self.days if d < keep or d > today]:
+            del self.days[d]
+
+    def ready(self) -> bool:
+        """At least one day with `MIN_HOURS` hours recorded."""
+        return any(len(r) >= MIN_HOURS for r in self.days.values())
+
+    def hour_w(self, hour: int):
+        vals = [r[hour] for r in self.days.values() if hour in r]
+        return statistics.median(vals) if vals else None
+
+    def base(self):
+        vals = [w for h in NIGHT_HOURS if (w := self.hour_w(h)) is not None]
+        return statistics.median(vals) if vals else None
+
+    def estimator(self):
+        """`f(hour) -> W`, or None when not ready. Fixed at call time."""
+        if not self.ready():
+            return None
+        base = self.base() or 0.0
+        table = {}
+        for h in range(24):
+            w = self.hour_w(h)
+            table[h] = base if w is None else w
+        return lambda h: table[h], max(0.0, base)
+
+
+# --------------------------------------------------------------------------- #
+# The plan
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class Plan:
+    verdict: str                # SUNNY / PARTLY / DARK
+    sun_kwh: float              # solar the batteries can count on
+    fc_kwh: float               # the forecast over the same span
+    until: datetime             # the expensive run the plan is for
+    targets: dict               # name -> level % (Leftover solar only)
+    need_kwh: dict              # name -> kWh from the grid (0: none)
+    share_kwh: dict             # name -> kWh of solar counted for it
+
+
+def _hour_slices(t0, t1):
+    """Local-hour slices of [t0, t1): (start, end, local hour)."""
+    out, t = [], t0
+    while t < t1:
+        lt = _local(t)
+        nxt = (lt.replace(minute=0, second=0, microsecond=0)
+               + timedelta(hours=1)).astimezone(timezone.utc)
+        e = min(nxt, t1)
+        out.append((t, e, lt.hour))
+        t = e
+    return out
+
+
+def _room(p, to_pct):
+    if p.capacity_kwh is None or p.soc is None:
+        return 0.0
+    return max(0.0, float(to_pct) - float(p.soc)) / 100.0 * float(
+        p.capacity_kwh)
+
+
+def plan(forecast, house, runs, now, packs, *, trust_pct, floor_pct,
+         ceiling_pct):
+    """The day plan, or None when there is none to make: no forecast, no
+    house profile yet, no price plan, or no expensive run after the cheap
+    run. `house` is `HouseProfile.estimator()`'s answer. `packs` are
+    `modetrade.Pack`s."""
+    if forecast is None or house is None or runs is None or not runs.on \
+            or runs.cheap is None:
+        return None
+    house_w, base_w = house
+    until = next((g for g in runs.give if g.start >= runs.cheap.end), None)
+    if until is None:
+        return None
+    trust = max(0.0, min(1.0, float(trust_pct) / 100.0))
+    sun = fc_sum = 0.0
+    for s, e, h in _hour_slices(now, until.start):
+        pv = forecast.between(s, e)
+        if pv is None:
+            return None             # the span reaches a day with no forecast
+        hrs = (e - s).total_seconds() / 3600.0
+        use = max(house_w(h), base_w) * hrs / 1000.0
+        sun += max(0.0, pv - use)
+        fc_sum += pv
+    sun *= trust * EFF
+
+    usable = [p for p in packs if p.use and p.live and p.idle
+              and p.soc is not None and p.capacity_kwh]
+    sf = [p for p in usable if p.mode == SOLAR_FIRST]
+    price = [p for p in usable if p.mode == LEFTOVER_SOLAR]
+    sf_room = sum(_room(p, ceiling_pct) for p in sf)
+    excess = max(0.0, sun - sf_room)
+    rooms = {p.name: _room(p, ceiling_pct) for p in price}
+    total_room = sum(rooms.values())
+
+    # What the house draws in the expensive runs from the one this plan is
+    # for until the next cheap run (or a day), from the profile.
+    horizon = until.start + timedelta(hours=24)
+    use_kwh = 0.0
+    for g in runs.give:
+        if g.start < until.start or g.start >= horizon:
+            continue
+        for s, e, h in _hour_slices(g.start, g.end):
+            use_kwh += max(0.0, house_w(h)) * (
+                e - s).total_seconds() / 3600.0 / 1000.0
+    caps = {p.name: float(p.capacity_kwh) for p in price}
+    cap_sum = sum(caps.values()) or 1.0
+
+    targets, need, share = {}, {}, {}
+    for p in price:
+        sh = excess * rooms[p.name] / total_room if total_room > 0 else 0.0
+        sh_pct = sh / caps[p.name] * 100.0
+        want = use_kwh * caps[p.name] / cap_sum / EFF
+        top = min(float(ceiling_pct),
+                  float(floor_pct) + want / caps[p.name] * 100.0)
+        level = max(0.0, top - sh_pct)
+        targets[p.name] = round(level, 2)
+        need[p.name] = round(_room(p, level), 3)
+        share[p.name] = round(sh, 3)
+    if sun < sf_room:
+        verdict = DARK
+    elif any(v > 0.05 for v in need.values()):
+        verdict = PARTLY
+    else:
+        verdict = SUNNY
+    return Plan(verdict, round(sun, 3), round(fc_sum, 3), until.start,
+                targets, need, share)
+
+
+def hold(old: dict | None, new: dict, capacity: dict) -> dict:
+    """Hysteresis: a battery keeps its old level unless the new one differs
+    by at least `HYST_KWH`, or by `HYST_FRAC` of the larger level's energy
+    (whichever is less). A battery new to the plan takes its level at once;
+    one that left the plan is dropped at once."""
+    out = {}
+    for name, level in new.items():
+        was = (old or {}).get(name)
+        cap = float(capacity.get(name) or 0.0)
+        if was is None or cap <= 0:
+            out[name] = level
+            continue
+        moved = abs(level - was) / 100.0 * cap
+        step = min(HYST_KWH, HYST_FRAC * max(was, level) / 100.0 * cap)
+        out[name] = level if moved >= step else was
+    return out
@@ -424,15 +424,17 @@ class FreezeWatchdog:
        # page was telling, printed into the log and the HA notification where
        # it would outlive the page.
        ceiling = rail_ceiling_w(max_w, dev_min=dev_min, dev_max=dev_max)
+        # UX-10: plain sentences, every figure kept (test_messages.py part 6).
        capped = ("" if ceiling >= abs(float(max_w))
                  else f", capped from max_w {float(max_w):.0f} W by the "
-                       f"setpoint device's own rating")
+                       f"inverter's own rating")
        self.reason = (
-            f"METER_FROZEN: the meter has answered {float(unchanged_s):.0f} s "
-            f"without its measurement changing while the command stands at "
-            f"{float(commanded_w):+.0f} W, at the {ceiling:.0f} W rail{capped} "
-            f"(limits: unchanged over {self.cfg.hold_s:.0f} s, command over "
-            f"{rail_w(max_w, dev_min=dev_min, dev_max=dev_max):.0f} W)")
+            f"METER_FROZEN: the meter has not changed for "
+            f"{float(unchanged_s):.0f} s while the command is "
+            f"{float(commanded_w):+.0f} W, at the {ceiling:.0f} W limit"
+            f"{capped}. Limits: unchanged over {self.cfg.hold_s:.0f} s, "
+            f"command over "
+            f"{rail_w(max_w, dev_min=dev_min, dev_max=dev_max):.0f} W")
        if self.active:
            return False
        self.active = True
@@ -87,6 +87,10 @@ when it has not moved THROUGH A CHANGE IT WAS OBLIGED TO FOLLOW:
                AND |standing command now - standing command when the reading
                     last changed| >= MOVE_W

+SAFETY-94: "unchanged for" counts only the reads at which both command terms
+held, so a register that rested is not judged before it could answer.
+DECISIONS/SAFETY-94-lagging-battery.md.
+
 0x0518 is the inverter reporting ITSELF and it tracks its own command: r = 0.998
 with battery power against r = 0.09 with the real meter (goodwe/NOTES.md §3.3),
 command and actual agreeing within 4 W once settled (§5.10, 2026-08-22), and the
@@ -175,6 +179,126 @@ 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.
+SAFETY-94: many were the gate judging a rested register on its first read
+(SAFETY-58). Counted from the ask, the same days give 59 trips.
+
+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 +335,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 +356,7 @@ class Bound:
    signal: str
    unchanged_s: float
    move_w: float
+    release_s: float
    wired: bool
    derivation: str

@@ -233,13 +371,21 @@ 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. SAFETY-94: the "
+                   "35 s counts only reads at which the command asks the "
+                   "register to move"),
    "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 +409,31 @@ 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. SAFETY-94: the 35 s counts only while the command asks the
+    register to move, so a site that rests after a release is not re-tripped
+    on its first ask.
+
+    ⚠️ 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 +448,25 @@ 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
+        # SAFETY-94. Seconds of this window during which the register was
+        # obliged to move (the command at least `move_w` and `move_w` away
+        # from `standing_at_grade`), and the instant of the last read.
+        self.obliged_acc = 0.0
+        self.last_read = 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,21 +493,103 @@ 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._oblige(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))
+        # The read that opens a window is never an ask (no travel yet).
+        self.obliged_acc = 0.0
+
+    def _obliged(self, standing_w) -> bool:
+        """Is the register asked to move: the command is at least `move_w` and
+        has travelled `move_w` since the window opened?"""
+        if standing_w is None or self.standing_at_grade is None:
+            return False
+        standing_w = float(standing_w)
+        return (abs(standing_w) >= self.bound.move_w
+                and abs(standing_w - self.standing_at_grade)
+                >= self.bound.move_w)
+
+    def _oblige(self, standing_w, now_mono) -> None:
+        """SAFETY-94. Count only the time the register was asked to move.
+
+        A register that held still while nothing asked it to move has not
+        failed, so time before the command moved is not evidence. The time
+        since the previous read counts when the obligation stands at this
+        read; a command flapping in and out of the obligation still adds up.
+        """
+        now_mono = float(now_mono)
+        if self.last_read is not None and self._obliged(standing_w):
+            self.obliged_acc += max(0.0, now_mono - self.last_read)
+        self.last_read = now_mono
+
+    def obliged_s(self) -> float:
+        """Seconds of the current window the register was obliged to move."""
+        return self.obliged_acc
+
+    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)
-        if held_s < self.bound.unchanged_s:
+        held_s = self.graded_s(now_mono)
+        # SAFETY-94 (closes SAFETY-58): the bound counts only the time the
+        # command asked the register to move, not the time since it last
+        # changed. A register that rested for minutes was otherwise judged on
+        # the first read after a new command, before it could answer (live,
+        # 2026-10-03: 1 s after the command).
+        if self.obliged_s() < self.bound.unchanged_s:
            return
        # ⚠️ BOTH None GUARDS ARE FOR A CALLER THAT DOES NOT KNOW ITS OWN
        # OBLIGATION YET, WHICH IS NOT `_read_unit`. `Inverter.standing_w()`
@@ -333,30 +597,93 @@ 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.
+        # UX-10: two plain sentences (test_messages.py part 6). SAFETY-56's
+        # two explanations stay, in this order, and so does the admission
+        # that this check cannot tell them apart. The reading is treated as
+        # missing either way, which the log line around this says. The
+        # limits (`self.bound`) are on main.py's DEBUG line beside it, so the
+        # logged line stays within 3 sentences.
+        # ⚠️ SAFETY-57, AND THE THREE DURATIONS ARE THREE DIFFERENT FACTS, each
+        # in its own slot: the register's unchanged time, the WINDOW this
+        # verdict actually rests on after a release (`regraded`), and 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.
+        regraded = (f", checked {self.releases + 1} times over a {held_s:.0f} s "
+                    f"window since the last stop was withdrawn"
+                    if self.releases else "")
        self.reason = (
-            f"STALE_READING: {self.held:+.0f} unchanged for {held_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"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)")
+            f"STALE_READING: {self.held:+.0f} W unchanged for {shown_s:.0f} s "
+            f"while the command moved {moved_w:.0f} W to {standing_w:+.0f} W"
+            f"{regraded}. The reading may have stopped, or the battery may be "
+            f"unable to follow the command, and this check cannot tell which")

    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 +693,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 +707,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.
@@ -0,0 +1,115 @@
+"""UX-13: Home Assistant's entities, for the settings page's entity picker.
+
+A read of `GET /api/states` through the add-on's own session (hass.states()),
+cached for 30 s and trimmed to what a picker shows. Nothing here writes, so
+UX-02 §6 holds. When Home Assistant does not answer, the last good list is
+served with its age, or an empty one that says why: the route never fails.
+"""
+
+import asyncio
+import time
+
+CACHE_S = 30.0
+DOWN_TEXT = "Home Assistant is not answering, so the entity list is empty."
+STALE_TEXT = "Home Assistant is not answering, so this list may be old."
+_POWER_UNITS = ("mW", "W", "kW", "MW", "GW", "TW")
+_TO_W = {"mW": 0.001, "W": 1.0, "kW": 1000.0, "MW": 1e6}
+_ENERGY_UNITS = ("Wh", "kWh", "MWh", "GWh")
+
+
+def row(state: dict) -> dict | None:
+    """One state object -> {entity_id, name, state, unit, device_class}."""
+    if not isinstance(state, dict) or not isinstance(state.get("entity_id"), str):
+        return None
+    attrs = state.get("attributes") if isinstance(state.get("attributes"), dict) else {}
+    return {"entity_id": state["entity_id"],
+            "name": str(attrs.get("friendly_name") or state["entity_id"]),
+            "state": state.get("state"),
+            "unit": attrs.get("unit_of_measurement"),
+            "device_class": attrs.get("device_class")}
+
+
+def watts(r: dict | None):
+    """A power entity's reading in W, or None when it is not a number in a
+    power unit (the setup wizard's kettle test)."""
+    if not r or r.get("unit") not in _TO_W:
+        return None
+    try:
+        value = float(r.get("state"))
+    except (TypeError, ValueError):
+        return None
+    return value * _TO_W[r["unit"]] if value == value else None
+
+
+def matches(r: dict, kind: str) -> bool:
+    """Is `r` what a picker of this kind offers first? `kind` is one of
+    uilayout.ENTITY_KINDS; "" or "any" offers everything."""
+    unit, cls = r.get("unit"), r.get("device_class")
+    if kind in ("power", "power_w"):
+        return cls == "power" or unit in _POWER_UNITS
+    if kind == "energy":
+        return cls == "energy" or unit in _ENERGY_UNITS
+    if kind == "pct":
+        return unit == "%"
+    if kind == "number":
+        return r["entity_id"].startswith(("number.", "input_number."))
+    return True
+
+
+class EntityCache:
+    """The last entity list read from Home Assistant, at most CACHE_S old."""
+
+    def __init__(self, hass, clock=time.monotonic):
+        self.hass = hass
+        self.clock = clock
+        self.rows: dict | None = None
+        self.read_at: float | None = None
+        self.tried_at: float | None = None
+        self._lock = asyncio.Lock()
+
+    async def get(self, max_age: float = CACHE_S
+                  ) -> tuple[dict | None, float | None]:
+        """(rows by entity id, age in s), or (None, None) if never read.
+        `max_age` is how old a try may be before HA is asked again: the setup
+        wizard's last step asks for a list at most a few seconds old."""
+        async with self._lock:      # one HA read however many pickers ask
+            now = self.clock()
+            # A failed read also waits CACHE_S, so polls while HA is down do
+            # not queue one 10 s read each behind this lock.
+            if self.tried_at is None or now - self.tried_at >= max_age:
+                self.tried_at = now
+                states = await self.hass.states()
+                if states is not None:
+                    rows = (row(s) for s in states)
+                    self.rows = {r["entity_id"]: r for r in rows if r}
+                    self.read_at = now
+            if self.read_at is None:
+                return None, None
+            return self.rows, now - self.read_at
+
+    async def reading(self, entity_id: str) -> dict:
+        """One entity read now, not from the list: the kettle test compares
+        two readings seconds apart, which a 30 s list cannot. A read only."""
+        r = row(await self.hass.state(entity_id)) if entity_id else None
+        return {"entity_id": entity_id, "found": r is not None,
+                "state": r and r["state"], "unit": r and r["unit"],
+                "watts": watts(r)}
+
+    def peek(self) -> dict | None:
+        """The cached rows if they are fresh, without asking Home Assistant."""
+        if self.read_at is None or self.clock() - self.read_at >= CACHE_S:
+            return None
+        return self.rows
+
+    async def payload(self, kind: str = "") -> dict:
+        """The route's JSON: matching entities first, then the rest."""
+        rows, age = await self.get()
+        if rows is None:
+            return {"available": False, "text": DOWN_TEXT, "entities": []}
+        ordered = sorted(rows.values(), key=lambda r: r["entity_id"])
+        first = [dict(r, match=True) for r in ordered if matches(r, kind)]
+        rest = [dict(r, match=False) for r in ordered if not matches(r, kind)]
+        out = {"available": True, "age_s": round(age, 1), "entities": first + rest}
+        if age >= CACHE_S:
+            out["text"] = STALE_TEXT
+        return out
@@ -16,12 +16,53 @@ _LOG = logging.getLogger("goodwe.hass")
 CORE_API = "http://supervisor/core/api"
 SUPERVISOR_API = "http://supervisor"
 BAD_STATES = ("unknown", "unavailable", "none", "")
+# What the Supervisor's proxy answers while Home Assistant restarts.
+UNAVAILABLE = (502, 503, 504)
+STATES_TIMEOUT_S = 10       # UX-13's entity list, like every other read here
+
+
+class Outage:
+    """UX-10: Home Assistant not answering, said in one plain line per outage.
+
+    A restart takes the REST API and the meter websocket down together, and
+    each used to log the library's own text for every entity and service
+    ("502, message='Bad Gateway', url=URL(...)", "Received message 8:1000 is
+    not str"). Now the first channel to fail says it once at WARNING, the raw
+    text goes to DEBUG, and the last channel to recover says so at INFO.
+    """
+
+    def __init__(self):
+        self.down_on = set()
+
+    def down(self, channel: str, what: str, detail) -> None:
+        if not self.down_on:
+            _LOG.warning("Home Assistant is not answering (%s), perhaps it is "
+                         "restarting. The add-on keeps trying.", what)
+        self.down_on.add(channel)
+        _LOG.debug("Home Assistant not answering on %s: %s", channel, detail)
+
+    def up(self, channel: str) -> None:
+        if channel in self.down_on:
+            self.down_on.discard(channel)
+            if not self.down_on:
+                _LOG.info("Home Assistant answers again.")
+
+
+OUTAGE = Outage()
+
+
+class ReadOnly(RuntimeError):
+    """A service call on a read-only HomeAssistant (UX-15 setup-only mode)."""


 class HomeAssistant:
-    def __init__(self, session: aiohttp.ClientSession, token: str | None = None):
+    def __init__(self, session: aiohttp.ClientSession, token: str | None = None,
+                 *, read_only: bool = False):
        self.session = session
        self.token = token or os.environ.get("SUPERVISOR_TOKEN", "")
+        # UX-15: setup-only mode reads Home Assistant and calls no service.
+        # Fixed at construction; `call()` refuses before it sends anything.
+        self._read_only = bool(read_only)
        self._last_moan: dict[str, float] = {}
        if not self.token:
            _LOG.error("SUPERVISOR_TOKEN missing - is this running as an add-on?")
@@ -58,13 +99,61 @@ class HomeAssistant:
            async with self.session.get(
                f"{CORE_API}/states/{entity_id}", headers=self._headers, timeout=10
            ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"read {entity_id}: {resp.status}")
+                    return None
+                OUTAGE.up("api")
                if resp.status == 404:
                    return None
                resp.raise_for_status()
-                return await resp.json()
-        except (aiohttp.ClientError, TimeoutError) as err:
+                obj = await resp.json()
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection", f"read {entity_id}: {err}")
+            return None
+        # SAFETY-61: an undecodable body is an absence like any other failed
+        # read, never an exception into the control loop.
+        except (aiohttp.ClientError, TimeoutError, ValueError) as err:
            self._moan(f"read:{entity_id}", "read %s failed: %s", entity_id, err)
            return None
+        if not isinstance(obj, dict):
+            self._moan(f"shape:{entity_id}", "read %s: not a state object: %.80r",
+                       entity_id, obj)
+            return None
+        return obj
+
+    async def states(self) -> list | None:
+        """Every entity's state object (`GET /api/states`), or None when Home
+        Assistant does not answer. A read only (UX-13 entity picker)."""
+        try:
+            async with self.session.get(
+                f"{CORE_API}/states", headers=self._headers,
+                timeout=STATES_TIMEOUT_S
+            ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"read all states: {resp.status}")
+                    return None
+                OUTAGE.up("api")
+                resp.raise_for_status()
+                obj = await resp.json()
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection", f"read all states: {err}")
+            return None
+        # A timeout's own text is empty, so the line names the wait instead
+        # (UX-13 P1 test, c).
+        except TimeoutError:
+            self._moan("read:*", "Reading the entity list failed: no answer "
+                       "within %s seconds.", STATES_TIMEOUT_S)
+            return None
+        except (aiohttp.ClientError, ValueError) as err:
+            self._moan("read:*", "Reading the entity list failed: %s",
+                       str(err) or type(err).__name__)
+            return None
+        if not isinstance(obj, list):
+            self._moan("shape:*", "The entity list is not a list: %.80r", obj)
+            return None
+        return obj

    async def number(self, entity_id: str, invert: bool = False) -> float | None:
        """Numeric state, or None. Never substitutes a default."""
@@ -100,24 +189,55 @@ class HomeAssistant:
                return None
        return (_f("min"), _f("max"), _f("step"))

+    @property
+    def read_only(self) -> bool:
+        return self._read_only
+
    async def call(self, domain: str, service: str, data: dict) -> bool:
+        if self._read_only:
+            # Every service call, `number.set_value` included, goes through
+            # here, so setup-only mode has no way to command (DECISIONS UX-15).
+            _LOG.error("Setup-only mode called no service, because it may not "
+                       "command anything.")
+            raise ReadOnly(f"{domain}.{service} refused: setup-only mode")
        try:
            async with self.session.post(
                f"{CORE_API}/services/{domain}/{service}",
                headers=self._headers, json=data, timeout=10,
            ) as resp:
+                if resp.status in UNAVAILABLE:
+                    OUTAGE.down("api", f"error {resp.status}",
+                                f"service {domain}.{service}: {resp.status}")
+                    return False
+                OUTAGE.up("api")
                if resp.status >= 400:
                    body = await resp.text()
                    # 400 here usually means out-of-range for the entity - the
                    # value is rejected outright, not clamped. Always log it:
                    # silently dropped commands are how a controller ends up
                    # believing something the hardware never did.
+                    # UX-10: plain words. While Home Assistant loads its
+                    # entities it answers 400 with only "400: Bad Request",
+                    # which says nothing, so only a body with more is quoted.
+                    said = body.strip()[:200]
+                    if said.lower() in (f"{resp.status}: {resp.reason}".lower(),
+                                        ""):
+                        said = "no details"
+                    entity = (data.get("entity_id", "no entity")
+                              if isinstance(data, dict) else "no entity")
                    self._moan(f"svc:{domain}.{service}",
-                               "service %s.%s rejected (%s): %s",
-                               domain, service, resp.status, body[:200])
+                               "Home Assistant refused %s.%s for %s (error %s, "
+                               "%s). The entity may still be loading, or the "
+                               "value is out of range.", domain, service,
+                               entity, resp.status, said)
                    return False
                return True
-        except (aiohttp.ClientError, TimeoutError) as err:
+        except aiohttp.ClientConnectionError as err:
+            OUTAGE.down("api", "no connection",
+                        f"service {domain}.{service}: {err}")
+            return False
+        # ValueError: an undecodable error body (SAFETY-61) is a failed write.
+        except (aiohttp.ClientError, TimeoutError, ValueError) as err:
            self._moan(f"svcerr:{domain}.{service}", "service %s.%s failed: %s",
                       domain, service, err)
            return False
@@ -0,0 +1,87 @@
+"""SAFETY-97: what a battery's power reading shows while it gives nothing.
+
+B's reading (0x0518) shows -95 to -118 W at idle (standby draw, live
+2026-10-03); A's shows -2 to -4 W. "The battery gives nothing" is graded
+against this idle reading, not against 0 W, or a refusing B never latches.
+DECISIONS/SAFETY-97-idle-offset.md.
+
+Learned per unit, never configured:
+- only while control runs, the unit is not refused, stale or tripped, and
+  its command has been within IDLE_ASK_W for IDLE_QUIET_S (a refusing battery
+  is asked more than that, so it cannot teach its refusal as idle);
+- a reading beyond IDLE_SAMPLE_W is not a sample;
+- first value: the mean of IDLE_FIRST_S of samples; then a slow follow
+  (IDLE_TAU_S);
+- persisted per unit and restored, clamped to IDLE_SAMPLE_W, at start.
+The band is centred on it clamped to IDLE_MAX_W (owner, 2026-10-04). Until
+learned the idle reading is 0 W, the rule as it was.
+"""
+
+import math
+
+IDLE_MAX_W = 75.0       # |idle| used: under the 100 W band, so it keeps 0 W +-25 W
+IDLE_SAMPLE_W = 250.0   # a reading beyond this is not a sample
+IDLE_ASK_W = 50.0       # a command this small counts as "asked ~0"
+IDLE_QUIET_S = 120.0    # 6 lags of 20 s: a 2500 W step has decayed to 6 W
+IDLE_FIRST_S = 120.0    # seconds of samples averaged for the first value
+IDLE_TAU_S = 1800.0     # then follow drift this slowly
+IDLE_SAVE_W = 5.0       # persist when the value moved this far
+IDLE_GAP_S = 10.0       # a longer gap between reads counts as this
+
+
+def _num(v):
+    try:
+        v = float(v)
+    except (TypeError, ValueError):
+        return None
+    return v if math.isfinite(v) else None
+
+
+class IdleReading:
+    """One unit's idle reading. `w` is what "gives nothing" is centred on."""
+
+    def __init__(self, saved=None):
+        v = _num(saved)
+        self.value = (None if v is None
+                      else max(-IDLE_SAMPLE_W, min(IDLE_SAMPLE_W, v)))
+        self.saved = self.value
+        self.quiet_since = None
+        self.last = None
+        self.acc_w = 0.0
+        self.acc_s = 0.0
+
+    @property
+    def w(self) -> float:
+        """The centre used: the learned value clamped to IDLE_MAX_W."""
+        if self.value is None:
+            return 0.0
+        return max(-IDLE_MAX_W, min(IDLE_MAX_W, self.value))
+
+    def observe(self, reading, standing_w, now_mono, may_learn) -> bool:
+        """One read. Returns True when the value should be persisted."""
+        now = float(now_mono)
+        dt = (0.0 if self.last is None
+              else max(0.0, min(IDLE_GAP_S, now - self.last)))
+        self.last = now
+        standing = _num(standing_w)
+        if not may_learn or standing is None or abs(standing) > IDLE_ASK_W:
+            self.quiet_since = None
+            return False
+        if self.quiet_since is None:
+            self.quiet_since = now
+        b = _num(reading)
+        if (now - self.quiet_since < IDLE_QUIET_S or b is None
+                or abs(b) > IDLE_SAMPLE_W or dt <= 0.0):
+            return False
+        if self.value is None:
+            self.acc_w += b * dt
+            self.acc_s += dt
+            if self.acc_s < IDLE_FIRST_S:
+                return False
+            self.value = self.acc_w / self.acc_s
+        else:
+            self.value += (b - self.value) * min(1.0, dt / IDLE_TAU_S)
+        if self.saved is None or abs(self.value - self.saved) >= IDLE_SAVE_W:
+            self.saved = self.value
+            return True
+        return False
--- a/Show More
+++ b/Show More