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

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

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

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

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

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

.gitea/workflows/checks.yml

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

goodwe_controller/CHANGELOG.md

@@ -1,29 +1,297 @@
 # Changelog
 
-## Unreleased
+## 0.10.0
 
-⚠️ **THIS HAS NO VERSION AND CANNOT REACH AN INSTALL UNTIL IT GETS ONE.**
-PKG-06's and PKG-07's rule: the Supervisor keys the built image by `version:`,
-so `ha apps update` is a silent no-op on an unbumped change. This branch
-deliberately does **not** pick the number, because the right one depends on a
-fact the branch cannot observe - whether 0.9.0's image has already been built
-and pulled. If it has not, this belongs inside 0.9.0's section before it ships;
-if it has, it needs 0.10.0. Whoever deploys decides.
+⚠️ **A CONFIG THAT IS LEGAL ON 0.9.0 IS REFUSED ON 0.10.0, AND THAT - NOT THE
+NUMBER OF TICKETS - IS WHY THIS IS A MINOR BUMP RATHER THAN A PATCH.** Same
+shape as 0.8.0's `slew_w` rule and the same test: is there a stored options
+blob the previous version started on and this one will not? There is. A refusal
+is `SystemExit(78)` (`EX_CONFIG`) - the add-on does not start, ⚠️ **and the
+ingress panel goes with it**, because the add-on serving it is not running, so
+recovery means the Supervisor UI.
+
+Measured on the reference install's own exported blob (70 keys), merged over
+this version's 75 defaults the way the Supervisor merges it, inside the CI
+image. The three below are what a reader who checks only one thing should
+check.
+
+* ⚠️ **[[TARIFF-07]] - THREE `price_provider` IDS ARE RETIRED, AND A SITE SET
+  TO ONE OF THEM IS REFUSED BY NAME AT STARTUP.** `engie_dynamic`,
+  `totalenergies_dynamic` and `eneco_eddy` are gone from `PROVIDERS`. Each was
+  accepted, silently, at every startup on 0.9.0 and earlier; on 0.10.0 each is
+  a refusal that names the id, the endpoint, what that endpoint actually
+  answers - a 404 from a gateway with no route, a TLS handshake against a
+  hostname the certificate does not cover, a 404 with an empty body - which
+  tariff the site has really been running since the id was entered, and what to
+  set instead. **The refusal IS the migration.** Every fetch any of the three
+  ever made ended in `SourceUnavailable`, and §11.4 turns that into a SILENT
+  fall back to the static profile, so there is no working behaviour to preserve
+  and nothing on the status page ever differed from a provider that simply
+  never found a cheap hour. ⚠️ **All three ids stay in `config.yaml`'s
+  `price_provider` enum on purpose**: drop one and the Supervisor rejects the
+  options file *before the add-on runs*, the operator gets an opaque `expected
+  one of ...`, and `validate.py`'s message is never seen - on exactly the sites
+  that need it. `PROVIDERS` is three; the enum is seven.
+  ⚠️ **The reference install is on `price_provider: off` and is unaffected.**
+
+* **[[TARIFF-18]] - `price_taxes_eur_kwh` moves from `0.06` to `0.11736`, and
+  the non-obvious half is the refusal that deliberately does NOT happen.** A
+  site that *stored* `0.06` is unaffected in both directions. It keeps `0.06`,
+  because `App.options` is `deepmerge(config.yaml defaults, stored options)`
+  and a moved default reaches only keys the blob does not carry - so the new
+  figure arrives at a **fresh** install, and at an existing one only when its
+  options are re-saved. ⚠️ **AND IT DOES NOT BECOME A STARTUP REFUSAL EITHER,
+  WHICH TOOK A MECHANISM.** [[TARIFF-17]] made a `price_taxes_profile` period
+  table beside a **non-default** `price_taxes_eur_kwh` a refusal, comparing
+  against the shipped default precisely because the Supervisor writes the key
+  whether the operator typed it or not. Moving the default turns every stored
+  `0.06` into "non-default" **with nobody editing anything**, so a working
+  Walloon or Brussels site with a period table would have stopped starting on
+  this upgrade, over an inert number the table overrides anyway.
+  `price.py` carries `SUPERSEDED_TAXES_DEFAULTS_EUR_KWH = (0.06,)` and
+  `validate.py` reads a superseded default as *untouched*. **The rung is not
+  weakened**: the same table beside a figure that is neither the shipped nor a
+  superseded default - ORES's `0.1198` - is still refused, by name, and the
+  refusal now says which two figures it will accept.
+
+* **[[SAFETY-10]] - a new `shadow_mode` option, shipped `auto`, and BOTH halves
+  of what that does matter.** ⚠️ **AN EXISTING INSTALL THAT IS CONTROLLING DOES
+  NOT CHANGE BY ONE WATT.** `auto` is not a constant the Supervisor merges; it
+  is a value the add-on **resolves**, and it resolves to `not control_started`
+  - `shadow.engaged()` reads `Controller.auto`, the persisted start/stop state.
+  An install with `auto_start: true`, or whose operator has pressed *Start /
+  stop control*, is started, so `auto` resolves to live. An install that is
+  **stopped** keeps its actuator at 0 W exactly as before, from the same writer
+  on the same heartbeat; what changes is what the status page says and that the
+  decision path now runs and is recorded. ⚠️ **A FRESH INSTALL COMES UP
+  OBSERVING**: it ships `auto_start: false`, has no stored `auto` key, and
+  therefore runs its whole decision path in shadow before it is ever allowed to
+  command anything. That is the "default-on" the card asked for, delivered
+  where it is safe and withheld where it is not - there is no mechanism in the
+  add-on options system by which one key can default differently for a new
+  install and an existing one, so a literal `shadow_mode: true` default would
+  have stopped the battery at the reference site on the next update.
+  **Measured cross-revision** - the same stimulus through the shipped
+  `Controller.cycle()` on `8f82dd4` (the merge before SAFETY-10) and on
+  `e6da478` (SAFETY-10 itself), start button ON: the write streams are
+  **byte-identical**, 13 / 13 / 25 writes on a 6000 W import, a 4000 W export
+  and a 300 W trickle, same values in the same order. An install that is
+  **stopped** is byte-identical across the same pair too, at one 0 W write.
+  ⚠️ The positive control is what makes that readable: the same driver with
+  `shadow_mode: on` and the button ON gets 13 writes up to 5000 W on the older
+  tree and **one 0 W write** on the newer, so the driver does reach shadow mode
+  and an identical pair is a result rather than a silence. The shadow case is
+  also graded in `test_clamp.py` part 8 on what reached `set_number()`, against
+  a precondition run that puts 30 non-zero writes on the wire. ⚠️ An
+  unrecognised `shadow_mode` fails toward inaction
+  **and** is refused by name (rule 11), so the reinterpretation is never
+  silent; no blob written before 0.10.0 can carry one.
+
+⚠️ **AND IF YOU ARE UPGRADING FROM 0.7.0 - WHICH THE REFERENCE INSTALL IS -
+THE REFUSAL THAT CAN STOP YOU IS IN 0.8.0'S SECTION, NOT IN THIS ONE.** `ha
+addons update` does not walk the versions; it installs 0.10.0 in one step, so
+**every validator rule added in 0.8.0 and 0.9.0 lands at the same moment as
+0.10.0's own**, and a config that has not been looked at since 0.7.0 meets all
+of them at once. Of those, exactly one can refuse a config nobody has edited:
+
+> [[SAFETY-39]]'s **rule 10**, added in 0.8.0, refuses an explicit `slew_w`
+> above `SLEW_RAIL_FRAC x` the site rail, where `SLEW_RAIL_FRAC` is
+> `LOOP_TICK_S / PLANT_SETTLE_S` = 2/18. On a 5000 W rail that ceiling is
+> **555.6 W** - and ⚠️ **0.7.0's own shipped default was `slew_w: 1000`**, so
+> an install that never touched the key and simply took the default does not
+> start on 0.10.0 until the value is lowered.
+
+Measured on this tree: the reference blob with `slew_w: 1000` is refused, by
+name, and the same blob at its actual `slew_w: 400` is accepted. 0.9.0's own
+additions cannot reach a pre-0.9.0 config at all - [[OPT-09]]'s two refusals
+fire only on a roster entry that USES `capacity_kwh`, a key that did not exist
+- so 0.8.0's is the whole of the crossing. **Read the live options and check
+`slew_w` against the ceiling and `price_provider` against the withdrawn list
+BEFORE `ha addons update`**, with `tools/predeploy_check.py`, which does both.
+
+✅ **RUN AGAINST THIS RELEASE: CLEARED, exit 0.**
+
+    docker run --rm -v <repo>:/w:ro -v <dir>:/opt:ro goodwe-addon-checks:1 \
+      python3 /w/goodwe_controller/tools/predeploy_check.py \
+      --deployed-version 0.7.0 --options /opt/live-options.json
+
+      deployed on the box : 0.7.0
+      shipped in this tree: 0.10.0
+      live options pass this version's validator
+      CLEARED for deploy.
+
+**The option surface: 71 keys -> 75, `options:` and `schema:` in step.** Four
+new keys, and none of them can refuse a blob written before it existed:
+`price_formula`, `price_export_formula` and `price_taxes_profile` are `str?` -
+**note the trailing `?`, they are OPTIONAL** - defaulting to `""`;
+`shadow_mode` is `list(auto|on|off)` with no `?`, which is the shape that
+becomes exit 78, and it is safe for the same reason 0.9.0's `delivery_hold_s`
+was: it carries an `options:` default, so the Supervisor's merge supplies it to
+every stored blob that lacks it. Nothing was removed. One default moved
+(`price_taxes_eur_kwh`, above) and one enum widened (`price_provider` gains
+`custom_formula`).
+
+⚠️ **WHY 0.10.0 AND NOT 0.9.0, SINCE 0.9.0'S IMAGE NEVER REACHED THE BOX.**
+The block this section closes used to say the choice depended on whether
+0.9.0 had been built and pulled, and that if it had not, this work belonged
+*inside* 0.9.0's section. That was written before 0.9.0's section was cut. It
+has been cut since `86bdf49`, on 2026-09-07, and **28 runtime commits** have
+landed behind it; folding them in would make the string `0.9.0` name two
+different trees, and the Supervisor keys the built image on exactly that
+string. Reusing it is the PKG-06/PKG-07 no-op in its worst form - a cached
+image the Supervisor is entitled to serve while reporting success. The version
+a tree has already shipped under is not available to be re-cut.
+
+⚠️ **AND THIS SECTION IS NOT THE WHOLE OF WHAT 0.10.0 SHIPS. THREE TICKETS
+WITH RUNTIME CHANGES LANDED AFTER `86bdf49` AND ARE NOT IN THE TABLE BELOW.**
+Saying so is cheaper than moving them, and moving them is [[PKG-08]]'s card,
+not this one:
+
+| ticket | runtime files | where it is written down |
+|---|---|---|
+| [[SAFETY-43]] | `app/delivery.py`, `app/packshare.py`, `config.yaml` | the `## Unreleased` block **below `## 0.9.0`**, which is misfiled |
+| [[TEST-21]] | `app/delivery.py`, `config.yaml`, `translations/` | the same block |
+| [[SAFETY-44]] | `app/main.py`, `app/store.py` | ⚠️ **nowhere in this file** |
+
+Five more landed that touch no runtime file and so cannot change what the
+image does - PKG-13, UX-04, SAFETY-31, ARCH-02, INSTR-01. The count that
+matters for the no-op check is `tools/predeploy_check.py`'s own: **28 runtime
+commits since `86bdf49`**, of which the table below accounts for 21.
+
+Contents of this release, in merge order since 0.9.0 (`86bdf49`):
 
 | | |
 |---|---|
-| _this branch_ | FCST-04 - the carry-forward fill reaches the plan, and the day it carries survives a restart |
-| _this branch_ | FCST-05 - one byte stops stopping the add-on, and the write path gets the read path's standard |
-| _this branch_ | FCST-06 - "cannot persist" stops meaning "has no /data" and starts meaning what it says |
-| _this branch_ | TARIFF-08 - the day-ahead feed is read in the shape it actually publishes, and the fixtures stop agreeing with the parser |
-| _this branch_ | TARIFF-09 - the day-ahead feed is asked for the horizon it was given, so tomorrow arrives firm instead of carried |
-| _this branch_ | TARIFF-10 - configuring a price provider is what fetches prices; trading stays its own switch |
-| _this branch_ | TARIFF-12 - a supplier outage stops deleting the plan on its first failed fetch, and TARIFF_MAX_AGE_S starts governing |
-| _this branch_ | TARIFF-14 - the price a trade is decided against is the price of the interval being traded |
-| _this branch_ | TARIFF-07 - three plugins that never fetched a price are withdrawn, and a site configured on one is told so **⚠️ BACKWARD-INCOMPATIBLE** |
-| _this branch_ | TARIFF-15 - `custom_formula`: your own tariff card's two coefficients, graded against the card's own printed price |
-| _this branch_ | TARIFF-13 - the capacity-tariff row's "quarter(s) banked" stops resetting to 0 at every restart, and a tied peak's quarter stops moving |
-| _this branch_ | TARIFF-11 - the add-on's account of the tariff plan stops flattering it, and the status page is graded as a surface |
+| `c2787da` | FCST-04 - the carry-forward fill reaches the plan, and the day it carries survives a restart |
+| `5059e28` | FCST-05 - one byte stops stopping the add-on, and the write path gets the read path's standard |
+| `958f5cd` | FCST-06 - "cannot persist" stops meaning "has no /data" and starts meaning what it says |
+| `4257e38` | TARIFF-08 - the day-ahead feed is read in the shape it actually publishes, and the fixtures stop agreeing with the parser |
+| `88c59a9` | TARIFF-09 - the day-ahead feed is asked for the horizon it was given, so tomorrow arrives firm instead of carried |
+| `559f0eb` | TARIFF-10 - configuring a price provider is what fetches prices; trading stays its own switch |
+| `a6e64fb` | TARIFF-12 - a supplier outage stops deleting the plan on its first failed fetch, and TARIFF_MAX_AGE_S starts governing |
+| `8d09b30` | TARIFF-14 - the price a trade is decided against is the price of the interval being traded |
+| `aade2c7` | TARIFF-07 - three plugins that never fetched a price are withdrawn, and a site configured on one is told so **⚠️ BACKWARD-INCOMPATIBLE** |
+| `068b83f` | TARIFF-15 - `custom_formula`: your own tariff card's two coefficients, graded against the card's own printed price |
+| `b4a3801` | TARIFF-13 - the capacity-tariff row's "quarter(s) banked" stops resetting to 0 at every restart, and a tied peak's quarter stops moving |
+| `c518007` | TARIFF-11 - the add-on's account of the tariff plan stops flattering it, and the status page is graded as a surface |
+| `7796f16` | TARIFF-17 - a price component that varies by hour has somewhere to live, so a Walloon day/night network tariff can change which hour is cheapest |
+| `4dcd9b0` | TARIFF-18 - `price_taxes_eur_kwh` stops shipping at half the real Flemish figure **⚠️ CHANGED DEFAULT** |
+| `478ba93` | TARIFF-16 - the injection leg stops being one number: an injection formula with its own coefficients, its own VAT and no floor under zero |
+| `8f82dd4` | SAFETY-45 - a price-driven charge is SIZED by the capacity-tariff guard instead of being switched on and off by it **⚠️ CONTROL STABILITY** |
+| `e6da478` | SAFETY-10 - shadow mode: the whole decision path runs and nothing reaches the inverter **⚠️ NEW OPTION, DEFAULT-ON FOR A NEW INSTALL** |
+| `587495e` | SAFETY-47 - what a shadow run can show you, and the watts on its status row **⚠️ CORRECTS THREE CLAIMS SAFETY-10 SHIPPED** |
+
+### SAFETY-47 — what a shadow run can show you, and the watts on its status row
+
+⚠️ **Nothing about the write path changed, and nothing needed to.** Shadow
+mode still holds every inverter at 0 W through the one writer. What was wrong
+is what three merged documents **said** a shadow run can show you, and a number
+on the status page that could be **6.61×** what a live controller would
+command.
+
+**A shadow run cannot show you a closed-loop defect. Not partially — not at
+all.** The battery is held at 0 W, so every measured input — the meter, the
+billed-quarter accumulator behind it, the battery power, the state of charge —
+describes a plant that did not respond, and a closed-loop defect is one whose
+stimulus *is* the plant's response. That is the same property that makes shadow
+mode safe, so it is not a gap to be closed later: **the closed-loop answer
+comes from the closed-loop rig or from a live run.**
+
+SAFETY-10 promised otherwise, because of a sentence that was true when it was
+written and false one commit later:
+
+> the **strategies** are unaffected — they ask for a fixed power from inputs
+> that do not depend on what the battery did — so a shadow run does show you
+> the trades, the peak-guard engagements and the SoC-limit behaviour.
+
+SAFETY-45 (above) sizes the buy leg to the billed quarter's charging headroom,
+and that headroom is `(900 / seconds remaining) × (ceiling − projected)` with
+the projection read off the **open quarter's meter**. The strategy became
+closed-loop the day that landed. Measured on the rig, one hour at `peak_cap_w`
+1500 under a 1200 W house:
+
+| | live | shadow |
+|---|---|---|
+| charge onsets | 28 | **1** |
+| grid | −455.5 … +3200.0 W | **1200.0 W flat — the house** |
+| capacity guard engaged | 410 / 720 cycles | **0 / 720** |
+| state of charge | 50.000019 → 51.856789 % | **50.000000 → 50.000000 %** |
+
+**What the documents now say.** The exemption narrows to exactly what is still
+true — **which** hour a strategy picks and **why** are unaffected, because the
+clock and the price series are not functions of the battery; **how hard** it
+trades is not. Of the three defects shadow mode was written for, one —
+TARIFF-14's wrong quarter-hour — is genuinely visible from a shadow run, and it
+is graded that way: identical live and shadow on 720 of 720 charging cycles at
+a binding cap.
+
+**What you will see on the status page.** The `Shadow mode` row and the action
+log now introduce the watts as what the controller would have commanded **on
+this cycle** — in every state, because no number a shadow run records is a
+forecast of a live run. And when a **measured** billed quarter sized those
+watts, both surfaces carry:
+
+> ⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE HOUSE
+> IN IT WHILE THE BATTERY IS HELD AT 0 W. A live run sizes the same trade
+> against a meter the battery is moving, so this is an UPPER BOUND and not a
+> prediction; how far under it a live run lands is a closed-loop question and a
+> shadow run cannot answer it.
+
+⚠️ **The number is caveated, not re-computed, and that was the decision.**
+Re-computing it to "look right" would mean the recorded decision was no longer
+the decision the shipped path reached — while the arbiter, the clamp, the
+write-authorisation gate, the action log and MQTT all ran on the real one. A
+shadow run's whole worth is that what it records is what the controller
+actually decided. `DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md` §3
+records the three alternatives that were rejected and why.
+
+⚠️ **On a site whose cap does not bind, nothing changes by one watt.** At
+`peak_cap_w` 15000 against a 350 W house the recorded figure is the live one
+exactly, and no caveat is a lie there either — the row still says the size came
+off a meter with no battery in it, which is true and is the point.
+
+**And SAFETY-10's own committed evidence could never have failed.** Its
+comparison table ran at a cap the guard never reaches, *and* read only the
+first charging sample — the one instant at which the two runs agree even at a
+cap that does bind. Both had to be closed; closing either alone closes nothing.
+The table is re-taken across the whole run at a binding cap, and
+`test_arbitrage.py` part 3d is the CI-side grader so this class cannot recur.
+14 mutations, no survivors; all 29 check files green.
+
+### SAFETY-10 — shadow mode, and what its default does to YOUR install
+
+A new option, `shadow_mode`, with three values and a shipped default of
+`auto`. In shadow mode the add-on runs its entire decision path — strategies,
+arbiter, clamps, guards — and **sends nothing to the inverter**: every inverter
+is held at **0 W**, refreshed on the ordinary heartbeat by the ordinary single
+writer, and the status page says plainly that the battery is not being
+controlled. What it *would* have commanded, and why, is on the status page and
+in the action log.
+
+⚠️ **WHAT HAPPENS TO AN EXISTING INSTALL: NOTHING.** `auto` resolves to shadow
+mode only while control is **stopped**. An install that is controlling —
+`auto_start: true`, or *Start / stop control* pressed — is started, so `auto`
+resolves to ordinary control and not one watt changes. An install that is
+**stopped** keeps its actuator at 0 W exactly as it did before, from the same
+writer on the same heartbeat; what changes for it is what the status page and
+the action log **say**, and that the decision path now runs and is recorded.
+
+⚠️ **AND THAT IS WHY IT IS NOT A BOOLEAN.** The card is titled "default-on".
+Taken literally — `shadow_mode: true` in `config.yaml` — it would be the worst
+change in this repository's history: 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,
+including the one regulating a real battery at the reference site. It would
+have silently stopped it, and the only symptom would have been a battery that
+stopped doing anything. There is no mechanism in the add-on options system that
+lets one key default differently for a new install and an existing one, so
+"default-on for new" is expressed as a value the add-on **resolves** rather
+than a constant the Supervisor merges.
+
+A **new** install ships `auto_start: false`, so it comes up in shadow mode and
+observes a day of decisions before it is allowed to command anything. That is
+the default-on the card asked for, delivered where it is safe and withheld
+where it is not.
 
 ⚠️ **A CONFIG THAT STARTS ON THE CURRENT VERSION CAN BE REFUSED ON THE NEXT
 ONE.** TARIFF-07 withdraws `engie_dynamic`, `totalenergies_dynamic` and
@@ -59,6 +327,358 @@ separate card. *(Annotated 2026-09-13: that card is **TARIFF-15**, below, and it
 shipped on this branch as `custom_formula`. It is still not an alias — the
 operator types their own coefficients; nothing is invented on their behalf.)*
 
+### SAFETY-45 - the trade is sized by the capacity guard, not switched by it
+
+**A price-driven charge now asks the peak guard HOW HARD it may pull, instead of
+only whether it may pull at all.** On any site where `load + max_w` reaches
+`peak_cap_w` - at the shipped `peak_cap_w: 3500` and `max_w: 2000`, any house
+drawing over 1500 W in the cheapest quarter - arbitrage and the capacity-tariff
+guard were driving each other in a sustained limit cycle. Measured on TEST-23
+stage 3's closed rig at `peak_cap_w: 1500` against a 1200 W house: **28 charge
+onsets in one hour, mean period 131 s, the grid swinging −456 to +3200 W**, and
+every billed quarter in the three affected configurations finishing **over** the
+cap it was oscillating about. §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."*
+
+**What was happening.** The guard computes `wanted = batt_w + excess` - the
+battery discharge that would land the quarter exactly on the ceiling - and files
+a claim only while that number is positive. While a trade charges at `max_w`
+the number is negative for the first minute or so of every cycle, so the guard
+files **nothing** and the trade is not constrained at all. `wanted` then crosses
+zero, the guard engages on a floor of a few watts, and that flips
+`arbitrage.guard_state()` - which cancels **the whole trade**. The
+grid-following loop takes the actuator, drives the meter to zero and past it,
+the projection collapses, the guard releases, and the trade comes back at
+`max_w`. 115 s later, again.
+
+**The fix, and it is a shape this add-on already had.**
+`control.maintenance_charge_floor()` has always capped a MAINTENANCE charge at
+"the headroom left under the site's cap", because *"a maintenance charge is the
+only thing this system does that is big enough and long enough to set that
+peak"*. ⚠️ That stopped being true when OPT-04 landed: a trade commands `max_w`
+for a whole tariff interval, deliberately, against the meter.
+`peakguard.charge_headroom_w()` publishes the same quantity off the **measured**
+guard rather than off the optional `peak_forecast_entity`, and
+`arbitrage.decide()` sizes the buy leg to it.
+
+**No new arithmetic and no new constant.** The number is `wanted_w` read in the
+other direction: a negative `wanted` is not "nothing to say", it is a permitted
+charge of `−wanted`. `peakguard.decide()` is **unchanged** - byte-identical to
+`release/1.0`, `sha256 = 200090d0835a3a55` - so 2026-08-20's anti-bang-bang rung
+is exactly where it was, and `tools/replay_ac3.py` reproduces the same 190/190
+guarded quarters, 110 engaged cycles and 878 Wh on this branch as on the tip.
+
+**After, on the same rig, same command:**
+
+| `peak_cap_w` / house | onsets per hour | grid swing | energy bought | billed quarters |
+|---|---|---|---|---|
+| 1500 / 1200 W | 28 → **1** | 3656 → **282 W** | 180 → **285 Wh** | 1490/1497/**1509** → **1500/1500/1500** |
+| 3500 / 1800 W | 8 → **1** | 3673 → 1688 W | 1653 → 1616 Wh | **3511/3536/3559** → **3500/3500/3500** |
+| 3500 / 3000 W | 32 → **1** | 3798 → **475 W** | 483 → 475 Wh | **3519/3542/3557** → **3500/3500/3500** |
+| 5000 / 1200 W | 1 → 1 | *identical* | *identical* | *identical* |
+
+One onset means the trade starts once and runs for the whole window - the
+battery is now trading 100 % of the cheap hour where it traded 43 %, 92 % and
+54 %. **Every billed quarter now lands on the cap and none over it.** At the
+aggressive cap the site buys 58 % MORE energy, because a continuous 300 W trade
+beats a 2000 W trade that is cancelled for well over half the hour; at the two
+shipped-default rows it buys about 2 % less and the worst quarter drops from
+59 W over the cap to zero. The last row is the negative control - `load + max_w`
+never reaches the cap there, and the two runs are bit-identical. **This costs
+nothing on the installs it is not about.**
+
+⚠️ **NOT A CONFIG CHANGE.** No option is added, removed or re-defaulted, and
+arbitrage remains off in the shipped configuration. A site that has not armed
+`arbitrage_enabled` is unaffected in every respect.
+
+⚠️ **WHAT IS NOT FIXED, AND IT IS NAMED RATHER THAN IMPLIED.** TEST-23 finding 1
+- the export overshoot at the END of any trade, 356-938 W, about 0.37 × `max_w`
+- is untouched and is a different card. A house whose load ALONE exceeds
+`peak_cap_w` still has the guard engage and the trade refused outright, which is
+correct, and the grid-following loop then drives to grid = 0 rather than to the
+ceiling. See `DECISIONS/SAFETY-45-sizing-the-trade.md` §5, and §2 there for the
+negative-`lo` design that was rejected because it creates a new `lo > hi`
+contradiction against the maintenance charge shaping.
+
+### TARIFF-16 - the injection leg stops being one number
+
+**`price_export_formula`: what a site is PAID for export, as `factor × index +
+offset` with its own coefficients, alongside the flat `export_price_eur_kwh`.**
+
+⚠️ **THIS IS NOT A WRONG-TRADE FIX, AND SAYING SO IS PART OF SHIPPING IT.**
+`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
+this add-on takes today is decided by an injection price, and nothing here
+changes one. What it changes is what an operator is told, and what any future
+export-aware strategy rests on: OPT-06 and any export logic would otherwise
+inherit a scalar that cannot represent the market, and the 6% VAT asymmetry
+between the two legs would be invisible in the arithmetic. `test_price.py` 17h
+parses every module under `app/` and goes red the day something calls an
+injection reader, so that claim is graded rather than attested.
+
+**The market publishes a line, not a number.** Verbatim off the cards: Eneco
+Zon & Wind Dynamisch `0,1 x BELPEX-H - 1,188` c€/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`; Aspiravi `0,07 x Belpex - 2`.
+Four properties a scalar cannot hold:
+
+1. **Its own factor.** Eneco `0,102` on consumption against `0,100` on
+   injection; Aspiravi `0,07` against about `0,10` on its consumption leg. Not
+   the consumption `B` with a sign flip.
+2. **A negative offset** — `− 1,188`, `− 2`. `price_markup_eur_kwh: float(0,1)`
+   cannot express a negative markup at all, so it has no home on the
+   consumption side either.
+3. **VAT-exempt** — *"Injectietarieven zijn vrijgesteld van btw"* — while
+   consumption is at 6%. `vat_pct` is now **per leg**, so the six-point
+   asymmetry is expressible; a scalar carries no VAT field at all.
+4. **It goes negative with no floor**, below `11,88 EUR/MWh` of BELPEX-H — the
+   midday hours a PV household exports in. You can be charged to export.
+
+⚠️ **A NEGATIVE INJECTION PRICE IS ACCEPTED, NOT REFUSED**, and that needed a
+different band rather than a lower floor. `implausible_all_in()` floors the
+consumption leg at `+0.02 EUR/kWh` of energy, which is right there and fatal
+here — measured, not assumed: `test_price.py` 17c puts one spec through **both**
+bands and prints that the consumption band refuses `−0.03008 EUR/kWh` while the
+injection band accepts it. The floor was not decoration, though: it is what
+catches a 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. So the bound moves **off the price and onto the coefficients**, where it
+is index-free and sign-free — a **pass-through** band (`factor` as a share of
+the wholesale price; Eneco's injection leg is 1.00×, Aspiravi's 0.70×, the band
+is 0.10–10×) and an **offset magnitude** bound (0.20 EUR/kWh against published
+values of 0.01188 and 0.02). Two rungs that can both answer a hundredfold
+error, so each is graded on its **reason**, each gets a stimulus the other
+cannot reach, and they are mutated **together** (TEST-16).
+
+⚠️ **THE CARD SELF-CHECK APPLIES WHERE THERE IS A CARD, AND WHERE THERE IS NOT
+THAT IS STATED RATHER THAN WORKED AROUND.** `price_formula` can require a `card`
+block because a Belgian card prints the consumption formula, the reference index
+*and* the resulting price. **Eneco's injection formula is printed with no price
+beside it.** Requiring a block would make the market's own published line
+inexpressible; inventing the estimate would grade the coefficients against
+arithmetic done with the same coefficients. So the block is **optional on this
+leg and unchanged on the other**, the self-check runs at the same tolerance
+wherever a printed estimate exists, and validate.py says at startup —
+*"its coefficients are UNGRADED"* — when it does not, naming the two bounds that
+ran instead. This is TARIFF-15 demonstrating two tariffs end to end rather than
+three, one card later.
+
+**ONE PARSER, NOT TWO.** `custom_formula.py` already shipped the units table,
+the NaN rule, the closed enumerations, the unknown-key refusal, the card
+comparison and `to_resolution()`'s DST handling, so `parse_export_formula()` is
+that parser with its **option name as an argument** — TARIFF-17's move on
+`parse_static_profile()`, exactly. Everything that differs between the two legs
+is a string in one `_LEGS` table. `test_price.py` 17b pins it two ways: by
+parsing every module under `app/` and asserting all 32 grammar names are defined
+in exactly **one** of them, and by deriving twelve refusal sentences for the new
+option from the old option's own sentence rather than transcribing them. The
+three sentences that deliberately **differ** are named, with what differs, and
+asserted to differ.
+
+**NOTHING CHANGES FOR A SITE THAT DOES NOT SET IT.** The option ships `""`, and
+`export_price_eur_kwh()`'s body is byte-identical — pinned on the AST, not on
+the source text — with `export_price_at()` falling through to it for every index
+value. `test_price.py` 17f compares seven option dicts × five index values
+against the pre-TARIFF-16 expression with `==`.
+
+`export_price_eur_kwh` and the new key are both in `FRAMEWORK_KEYS`;
+`BANNED_IN_PLUGIN_CODE` is derived from that set, so `code_leaks()` refuses a
+plugin that names either with nothing else edited.
+
+**Also corrected here:** `config.yaml`'s comment beside `export_price_eur_kwh`
+still read *"no shipped supplier publishes a dynamic injection curve"*.
+TARIFF-07 struck that claim from `app/price.py` and `DOCS.md` and did not reach
+`config.yaml`, where it has been shipping since.
+
+**20 mutations, every one red on a named check**, ledger in `test_price.py`
+below section 17 with byte deltas — including a **zero-byte** one (the two legs
+transposed in the VAT-asymmetry banner, which changes no decision and only
+moves the sentence) and a **one-byte** one (`card_required=True` on the
+injection leg). Three were run over all 29 files and are red on `test_price.py`
+alone; the rest over the five suites that can reach this card. Each row gets a
+fresh copy of the tree under a `mktemp` path, mounted `:ro` — no revert to fail
+and no shared backup path, which is MUTATION.md habit 18 closed structurally.
+29/29 green.
+
+### TARIFF-17 - a price component that varies by hour has somewhere to live
+
+**`price_taxes_profile`: the taxes component as a period table, alongside the
+flat `price_taxes_eur_kwh`.** ⚠️ **The flat scalar was not a wrong number, and
+this is not a correction of one.** The optimiser reads exactly two things off a
+series — the spread `max − min` over the firm points, and which hour is
+cheapest — and an additive constant identical in every hour cancels out of the
+first and leaves the second where it was. It is *provably* inert. What was
+missing was anywhere for an **hour-varying** non-energy component to live.
+
+Belgium has one. Fluvius distribution is a single rate, and its row on the
+tariff card reads `Normaal | Uitsl. nacht` — *exclusive night* being a separate
+physical circuit, not a night register — so for the reference site in Flanders
+nothing here changes. The Walloon DSOs and Sibelga are on the same card with
+four columns, `Enkelvoudig | Dag | Nacht | Uitsl. nacht`, and the gap is real
+money (c€/kWh): ORES `13,27 / 7,39`, AIESH `15,17 / 8,21`, Tecteo RESA
+`12,20 / 7,01`, Sibelga `9,39 / 7,10`, ORES IMPACT 2026 `16,578 / 5,090`.
+
+⚠️ **AND THE BANDS ARE ANTI-CORRELATED WITH WHAT THE BATTERY WANTS TO DO.** The
+cheap network hours *are* the cheap spot hours, so flattening them does not
+shift the curve — it **understates the spread** and declines cycles that would
+have paid. Measured on one ordinary Belgian winter weekday, same feed, same
+markup, the only difference being the taxes argument:
+
+```
+flat 0.0000 / 0.0739 / 0.1198 / 0.1327 / 1.0000  -> cheapest hour 13, spread 0.1500
+ORES dag 0.1327 / nacht 0.0739                   -> cheapest hour 03, spread 0.1788
+```
+
+Five different flat figures spanning and exceeding the table's own range give
+**the same hour and the same spread to the last digit**; the table moves the
+hour a battery would buy in from 13:00 to 03:00. That is the regression
+`test_price.py` section 16 grades, and it grades **the hour**, not the spread:
+an implementation that reads the table once and adds one number to every point
+produces the right magnitude and the wrong shape, and a spread assertion passes
+on it. `DOCS.md` now names the three buckets — LEVEL, SPREAD, ORDER — so the
+next person adding a component knows which one it is in.
+
+**The change is contained.** `static_tariff.py` already shipped the grammar —
+periods tiling the day, gaps and overlaps refused, day types, DST — so it is
+**the same parser**, taking the option name and the "what this number means"
+clause as arguments. There is no second tiling rule, because a second one would
+be a second set of 23- and 25-hour-day bugs; `test_static_tariff.py` section 10
+pins that by parsing every module under `app/` and asserting the grammar is
+defined in exactly one of them, and by deriving each of thirteen refusal
+sentences for the new option from the old option's own sentence.
+`Component.TAXES` semantics, `code_leaks()` and the double-counting guarantee
+are untouched: the new key joins `FRAMEWORK_KEYS`, `BANNED_IN_PLUGIN_CODE` is
+derived from that set, and a plugin naming it is refused at `register()`.
+
+⚠️ **A MALFORMED TABLE IS REFUSED AT STARTUP, NOT AT THE NEXT FETCH.** It is
+read on the ~30 s planning path through `assemble()`, and a table that first
+fails at 03:00 is a site that stops pricing at 03:00 — which §11.4 turns into a
+quiet fallback indistinguishable from a healthy fixed-tariff day. `validate.py`
+parses it at startup, and refuses three things: a table that does not tile the
+day (the same sentence `static_profile` gives, naming this key); a table set
+*beside* a non-default `price_taxes_eur_kwh`, because the table wins and the
+scalar would then be a number the operator typed that decides nothing; and a
+whole card typed **in cents**, which is how these figures are printed. That
+last rung is not a restatement of the parser's ±10 EUR/kWh bound — ORES's
+`13,27` trips the parser, but Sibelga's entire card, `9,39` and `7,10`, is
+under it, and would otherwise have started as a 9.39 EUR/kWh levy.
+
+**Nothing changes for a site that does not set it.** The option ships `""`, the
+scalar path is unchanged arithmetically — `test_price.py` 16f reproduces the
+pre-TARIFF-17 expression and compares 12 capability/scalar combinations point
+for point with `==` — and the reference site is in Flanders, where the flat
+figure is correct. This is a product concern rather than a site one: the add-on
+is sold to clients, and a Walloon or Brussels client could not express their
+own tariff.
+
+### TARIFF-18 - `price_taxes_eur_kwh` stops shipping at half the real figure
+
+⚠️ **A SHIPPED DEFAULT CHANGED: `price_taxes_eur_kwh` 0.06 -> 0.11736 EUR/kWh.**
+Same shape as 0.8.0's `slew_w` rule, and the same instruction follows — **read
+the live options before `ha addons update`**, this time to see whether
+`price_taxes_profile` is set, which is the one shape the move could have
+refused. The "who is affected" section below is the part that matters, and it
+is shorter on consequences than a changed default usually is.
+
+The old `0.06` had **no recorded provenance anywhere**: not a card, not a date,
+not a component list. It is roughly **half** the Flemish figure. The new default
+is the Eneco residential card for Flanders, September 2026, incl. 6 % VAT, and
+its rows are now **in the code** (`app/price.py`'s
+`FLEMISH_TAXES_COMPONENTS_EUR_KWH`, re-added by `test_price.py` section 1b):
+
+| component | c€/kWh |
+|---|---|
+| Fluvius distribution (**Antwerpen**) | 5,35 |
+| Bijzondere accijns, *"Alle verbruik"* — no volume bands | 4,876 |
+| Bijdrage groene stroom en WKK Vlaanderen | 1,51 |
+| Energiebijdrage — **0 EUR/MWh since 2026-08-01**, merged into the accijns | 0 |
+| **total** | **11,736 c€/kWh = 0.11736** |
+
+⚠️ **IT IS PER-DSO, AND THE DEFAULT IS NOT AN AVERAGE.** Only the distribution
+row moves: across the eight Fluvius DSOs it runs 5,28 c€/kWh
+(Midden-Vlaanderen) to 6,70 (West), so the Flemish total runs about **0.117 to
+0.131**. The default is a real DSO's real row, near the **low** end, and DOCS
+tells an operator to look up their own. A **Walloon or Brussels** site should
+not use this scalar at all — its distribution tariff has a day and a night band
+and belongs in TARIFF-17's `price_taxes_profile`.
+
+⚠️ **THIS IS A DISPLAY AND GUARD FIX. IT DOES NOT IMPROVE ARBITRAGE AND CANNOT.**
+This scalar is a **LEVEL** component: an additive constant cancels exactly in
+`max − min` and leaves the argmin where it was. TARIFF-17 shipped the machinery
+and the proof — six flat scalars spanning and exceeding the whole per-DSO range
+give the **identical** cheapest hour and the **identical** spread to the last
+digit (`test_price.py` 16b, printed on every run), and none of that changes
+here. No trade happens that did not happen before *because of the level*. What
+does change is two things, and nothing else:
+
+* **every number an operator reads** — the all-in prices on the status page,
+  `custom_formula`'s startup preview and the recorded price history. At half
+  the true non-energy component they made the add-on look considerably better
+  than it is; and
+* **§17's negative-price guard** (`arbitrage.py`), the one rung that tests an
+  **absolute** all-in price rather than a difference. It fires when
+  `spot < −(markup + taxes)`, so its boundary moves **−0.09000 -> −0.14736
+  EUR/kWh of spot**. A −0.11868 EUR/kWh spot hour used to read **−0.02868**
+  all-in and the discharge was refused as paid-for disposal; at the real tax
+  level it reads **+0.02868** and discharges, because that hour genuinely
+  paid.
+  `test_arbitrage.py` section 2c drives both sides through the shipped
+  `decide()`, and pins the boundary from below as well.
+
+⚠️ **AND THAT ASYMMETRY IS WHY THE DEFAULT SITS AT THE BOTTOM OF THE BAND.** Set
+too **high**, the figure carries a genuinely negative hour above zero and the
+add-on exports into paid-for disposal — §17's own case. Set too **low**, it only
+declines a discharge that would have paid. One default standing in for eight
+DSOs belongs at the bottom.
+
+#### Who is affected
+
+* **A site that set `price_taxes_eur_kwh` itself: nothing changes.** Its value
+  is kept and is never silently replaced.
+* **A site whose stored options blob already carries the key: nothing changes
+  either, and this is most existing installs.** The Supervisor sets
+  `App.options = deepmerge(config.yaml defaults, stored options)`
+  (`tools/supervisor_selfapi_probe.py` §D), so a moved default reaches only
+  keys the blob does **not** carry — and the reference install's export carries
+  **70 of the 71**, the one absentee being a key added after its last save.
+  Such a site goes on running at `0.06` and reading numbers that are about half
+  its real all-in price until somebody opens the Configuration tab. ⚠️ **That
+  is a real limit of this card and it is not fixed here**: the change reaches a
+  **fresh install**, and an existing one only when its options are re-saved.
+  ⚠️ **NOT re-measured on this branch** — the 70-of-71 figure is 0.9.0's, and
+  PKG-09's `tools/predeploy_check.py --options <live blob>` against the live
+  options is what would confirm it before deploying.
+* ⚠️ **A site with `price_taxes_profile` SET would have been refused at startup,
+  and is deliberately not.** TARIFF-17 made a taxes period table beside a
+  **non-default** `price_taxes_eur_kwh` a `SystemExit(78)` refusal, comparing
+  against the shipped default precisely because the Supervisor writes the key
+  whether it was typed or not. Moving the default turns every stored `0.06`
+  into "non-default" **without anybody editing anything**, so a working Walloon
+  or Brussels site would have stopped starting on the upgrade over an inert
+  number the table overrides anyway. `price.py` now carries
+  `SUPERSEDED_TAXES_DEFAULTS_EUR_KWH = (0.06,)` and `validate.py` treats a
+  superseded default as *untouched* as well. **The rung is not weakened**: a
+  figure that is neither the shipped nor a superseded default — ORES's 0.1198,
+  say — is still refused, by name, and the refusal now says which of the two
+  figures it will accept (`test_validate.py`, four new checks plus the
+  difference precondition).
+
+Nothing hardcoded `0.06` in that rung — it read `PRICE_OPTION_DEFAULTS` — which
+is why the interaction is a *behaviour* change rather than a drift, and why it
+had to be decided rather than noticed.
+
+`config.yaml` and `PRICE_OPTION_DEFAULTS` moved together and CFG-03's tripwire
+(`test_price.py` section 1, `test_defaults_pin.py`) stayed green by agreeing,
+not by being widened. ⚠️ One check did have to be **rewritten rather than
+re-pointed**: `test_price.py` section 0 used to justify its own grading
+constants by observing that the shipped pair was degenerate — `0.06` is exactly
+twice `0.03`. TARIFF-18 ends that coincidence, so the sentence is no longer true
+and is not kept; the file now asserts per-figure that neither shipped default is
+what it grades with, which is the property that was actually load-bearing.
+
 ### TARIFF-13 - the coverage figure beside the peak, and which quarter gets it
 
 **The capacity-tariff status row's `N quarter(s) banked` is read from the
@@ -1165,12 +1785,30 @@ and pulled. If it has not, this belongs inside 0.8.0's section before it ships;
 if it has, it needs 0.8.1. Whoever deploys decides, and PKG-07 is the record of
 what happens when nobody does.
 
+⚠️ **ANNOTATED BY PKG-14, 2026-09-16 - EVERY ROW BELOW HAS SHIPPED, AND THE
+PARAGRAPH ABOVE IS NO LONGER TRUE OF ANY OF THEM.** It is annotated rather
+than rewritten, and nothing is moved out of it, because re-filing this file's
+misplaced entries is [[PKG-08]]'s card and guessing a boundary is what that
+card exists to stop. What is measurable, and what PKG-14 measured:
+
+* **UX-02 shipped in 0.9.0.** Its merge `3d29993` is an ancestor of the 0.9.0
+  bump `86bdf49` and it is already listed in `## 0.9.0`'s own contents table,
+  so this row is a duplicate of a released one.
+* **UX-04, TEST-21 and SAFETY-43 shipped in 0.10.0.** All three merged after
+  `86bdf49`. TEST-21 (`app/delivery.py`, `config.yaml`, `translations/`) and
+  SAFETY-43 (`app/delivery.py`, `app/packshare.py`, `config.yaml`) are runtime
+  changes and are named in `## 0.10.0`'s preamble as shipping there and being
+  written down here; UX-04 touches no runtime file.
+* ⚠️ **[[SAFETY-44]] also shipped in 0.10.0 and is nowhere in this file** -
+  `app/main.py` and `app/store.py`, three commits. It is named in
+  `## 0.10.0`'s preamble for the same reason.
+
 | | |
 |---|---|
-| _this branch_ | UX-02 - a configuration page in the ingress panel, where the validator's refusals can be seen |
-| _this branch_ | UX-04 - UX-01's three unmet acceptance criteria: one withdrawn, one built, one re-attributed |
-| _this branch_ | TEST-21 - `delivery_hold_s`'s floor re-derived from a harness that is now committed, and the recorded 30.0 s did not reproduce |
-| _this branch_ | SAFETY-43 - delinquency measured against the ask as well as against a flat 500 W, closing OPT-09's disclosed detection regression |
+| `3d29993` | UX-02 - a configuration page in the ingress panel, where the validator's refusals can be seen **⚠️ SHIPPED IN 0.9.0, see that section** |
+| `bb46916` | UX-04 - UX-01's three unmet acceptance criteria: one withdrawn, one built, one re-attributed **⚠️ SHIPPED IN 0.10.0** |
+| `6719bd8` | TEST-21 - `delivery_hold_s`'s floor re-derived from a harness that is now committed, and the recorded 30.0 s did not reproduce **⚠️ SHIPPED IN 0.10.0** |
+| `37dd0f0` | SAFETY-43 - delinquency measured against the ask as well as against a flat 500 W, closing OPT-09's disclosed detection regression **⚠️ SHIPPED IN 0.10.0** |
 
 ⚠️ **SAFETY-43 CLOSES THE DETECTION REGRESSION OPT-09 DISCLOSED, AND IT IS A
 TWO-INVERTER FIX. N=1 IS BYTE-IDENTICAL.** `delivery.delinquent()` named a unit

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

@@ -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.

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

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

goodwe_controller/DECISIONS/SAFETY-45-sizing-the-trade.md

@@ -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.

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

@@ -0,0 +1,319 @@
+# SAFETY-47 — what a shadow run can show, and what it cannot
+
+**Status:** decided and implemented on branch `SAFETY-47`.
+**Card:** SAFETY-47 — *"shadow mode's claims, and the number on the status
+row"*.
+**Nothing here reached the inverter.** No deployment, no `ha addons update`, no
+contact with 192.168.2.158 or 192.168.2.221. Everything below was measured in
+the CI image and on TEST-23 stage 3's closed-loop rig.
+
+⚠️ **This is not a write-path defect and nothing in the write path was
+touched.** SAFETY-10's substitution, re-seed, authorisation gate and clamp are
+unchanged. What was wrong is what three merged documents **say** a shadow run
+can show you, and a number on the status row that can be **6.61×** what a live
+controller would command.
+
+---
+
+## 0. The four things a reader should take away
+
+1. **Shadow mode cannot surface a closed-loop defect. Not partially — not at
+   all**, and by the same construction that makes it safe. §1.
+2. **The "strategies are unaffected" exemption was true until SAFETY-45 merged,
+   one commit before SAFETY-10.** Sizing the buy leg to the billed-quarter
+   headroom made the strategy closed-loop. §2.
+3. **The recorded watts are the right answer to a question nobody asked, and
+   they are CAVEATED rather than re-computed.** Re-computing would mean the
+   recorded decision was no longer the decision the shipped path reached, which
+   is the one thing shadow mode has to be able to say. §3 records what was
+   rejected.
+4. **SAFETY-10 §6's committed evidence could never have failed, for two
+   independent reasons, and closing either one alone closes nothing.** §4.
+
+---
+
+## 1. Why the answer is "not at all", and not "not very well"
+
+Shadow mode holds every actuator at `shadow.WIRE_W` and re-seeds the carried
+command to it at the end of each cycle. So every **measured** input — the
+meter, the billed-quarter accumulator behind it, the battery power, the state
+of charge — describes a plant that **did not respond**.
+
+A closed-loop defect is, by definition, one whose stimulus **is** the plant's
+response to the controller. No response, no stimulus, nothing to see. This is
+not an implementation gap:
+
+* feeding the guards a **simulated** plant instead is exactly what SAFETY-10 §4
+  refuses for the sign watchdogs, and the reason generalises — a controller
+  reacting to a plant that does not exist drifts further from reality every
+  tick, and three cycles in its numbers describe nothing;
+* and SAFETY-10 §5 already conceded the same fact for the grid-following loop
+  ("one slew step, not a trajectory"). That was never a property of the loop.
+  **It is the general case**, and the loop leg was simply where it had already
+  been noticed.
+
+**So the closed-loop answer comes from a closed-loop rig (TEST-23 stage 3) or
+from a live run. There is no third place, and saying that plainly is worth more
+than the three sentences it replaces.**
+
+### Measured, on the rig, at a cap that binds
+
+`peak_cap_w` 1500 / house 1200 / `max_w` 2000, one hour at a 5 s cycle. Of the
+three defects SAFETY-10 was written for:
+
+| | visible? | measured |
+|---|---|---|
+| SAFETY-45's limit cycle | **no** | 28 charge onsets live, **1** in shadow. Grid −455.5 … +3200.0 W live, **flat at the 1200 W house** in shadow. Guard engaged 410/720 cycles live, **0/720** in shadow. (Taken with SAFETY-45 reverted — that is the defect being looked for.) |
+| SAFETY-46's SoC churn | **no** | the SoC moves **0.000000000 pp** in a shadow run. The SoC is the pack's integral of what the pack was commanded, and it was commanded 0 W. No SoC limit can be *reached* in a shadow run at all |
+| TARIFF-14's wrong quarter-hour | **yes**, and it is the only one | the price lookup's inputs are the clock and the price series, neither a function of the battery. Which hour, at what price, clearing what spread: **identical live and shadow on 720 of 720 charging cycles, at a binding cap** |
+
+### What a shadow run genuinely is for
+
+*Which* strategy wins, on *which* hour, at *which* price, for *which* reason,
+against which limits — the wrong-quarter-hour class, a trade armed on a day it
+should not be, a refusal whose sentence names the wrong subsystem, a clamp that
+would have engaged, a standing failsafe latch. That is a real and useful set,
+and it is the set the documents now claim.
+
+---
+
+## 2. The exemption, and exactly how much of it survives
+
+All three documents carried a version of:
+
+> The **strategies** are unaffected — price arbitrage, the capacity guard and
+> maintenance all ask for a fixed power **from inputs that do not depend on
+> what the battery did**.
+
+**True before SAFETY-45, false after it.** SAFETY-45 makes the buy leg
+`min(asked, headroom)`, and
+
+```
+headroom = (900 / remaining) x (ceiling - projected)
+```
+
+where `projected` reads the **open quarter's accumulator** — the meter — which
+is a function of what the battery did earlier in that same quarter. SAFETY-45
+merged one commit before SAFETY-10, so the exemption was stale on the day it
+was written.
+
+**What survives, and it is now graded rather than asserted:**
+
+> **Which** hour a strategy picks, and **why**, are unaffected — the clock and
+> the price series are not functions of the battery.
+> **How hard** it trades is not.
+
+⚠️ **The peak guard is not in the surviving half either.** Every term of
+`wanted = batt_w + excess` is measured, so in a shadow run the guard engages
+only if the *house alone* would put the quarter over the ceiling. Its
+**ceiling** and its **reasons** are worth reading from a shadow run; its
+**engagements** are not evidence of anything.
+
+---
+
+## 3. The number on the status row — decided, and what was rejected
+
+At `peak_cap_w` 1500 under a 1200 W house the status row read **"WOULD HAVE
+COMMANDED −2 000 W"**. A live controller commands **−302.4 W**. Measured on the
+shipped build:
+
+| cap / house | live commanded | shadow recorded | over by |
+|---|---|---|---|
+| 1500 / 1200 | −302.4 W | **−2000.0 W** | **6.61×** |
+| 3500 / 3000 | −502.6 W | −2000.0 W | 3.98× |
+| 3500 / 2000 *(shipped cap)* | −1502.6 W | −2000.0 W | 1.33× |
+| 3500 / 1800 | −1702.6 W | −2000.0 W | 1.17× |
+| 15000 / 350 | −2000.0 W | −2000.0 W | 1.00× |
+
+⚠️ **The arithmetic is not wrong.** `900/remaining` is correct for a meter that
+is genuinely under the ceiling, and in a shadow run the meter genuinely *is*
+under it, because the battery is not charging. **The recorded number is the
+right answer to a question nobody asked** — and the last row of that table is
+the fixture SAFETY-10's own evidence was taken on, which is why nothing
+reported it.
+
+### What shipped
+
+1. **Unconditionally**, the row and the log line stop forecasting: the watts
+   are introduced as what would have been commanded **ON THIS CYCLE**. No
+   number a shadow run records is a prediction of a live run, so no state
+   should read like one.
+2. **Conditionally**, whenever a **measured** billed quarter sized the number
+   being recorded, both surfaces carry `shadow.SIZED_FROM_METER`:
+
+   > ⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE
+   > HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W. A live run sizes the same
+   > trade against a meter the battery is moving, so this is an UPPER BOUND and
+   > not a prediction; how far under it a live run lands is a closed-loop
+   > question and a shadow run cannot answer it.
+
+⚠️ **"Upper bound", and not "smaller", and the difference was measured.**
+Charging only *adds* offtake, so a live `projected` is never below a shadow one
+and the headroom never above it — with **equality at the start of every
+quarter**, where `900/remaining` is 1.0 and neither plant has moved. Measured
+pairwise over 3600 charging cycles in five configurations: **0 cycles below,
+730 exactly equal.** A sentence reading "smaller" would have been false on
+every one of those 730, and the first draft of this card said "smaller".
+
+⚠️ **And it names no factor.** How far under the bound a live run lands is a
+property of the site. A number invented for the row would be a second helping
+of the defect the sentence exists to disclose.
+
+⚠️ **The predicate is NOT keyed on whether the trade was capped, and that is
+the trap this card nearly walked into.** `arbitrage`'s own sentence says *"SIZED
+BY THE CAPACITY-TARIFF GUARD"* only when the headroom came out **below** the
+ask — which in a shadow run is the **start** of the quarter, where the two runs
+still agree to the float. By the end, `900/remaining` has multiplied the
+headroom **past** the ask, the trade is **not** capped, the sentence is silent,
+and the recorded number is at its **most** wrong. A caveat keyed on it would be
+quietest exactly where it is needed loudest. `arbitrage.sized_from_meter()` is
+keyed on the headroom having been **measured**, so it fires on both.
+`test_arbitrage.py` part 3d-8 drives the inversion.
+
+### Rejected, and why
+
+* **Re-compute the number so it does not amplify** — e.g. record
+  `ceiling − projected` (gain 1.0) instead of the sized figure. It matches the
+  live answer almost exactly at this cap, and it is the **worst** of the
+  options. It would be a **shadow-only sizing**: the recorded decision would no
+  longer be the decision the shipped path reached, while the arbiter, the
+  clamp, SAFETY-28's gate, the action log and MQTT all ran on the real one. A
+  second copy of the sizing arithmetic living in the display layer is
+  MUTATION.md's transcribed-predicate defect on an operator-facing surface, and
+  it generalises to no other strategy. SAFETY-10's whole safety argument is
+  that shadow mode is a **substitution at the wire**, not a second controller;
+  this would have made it a second controller everywhere except the wire.
+* **Record nothing where the sizing depends on measured state.** Tempting —
+  "no number beats a number 6.61× out". Rejected on three counts: it blanks the
+  row exactly when arbitrage is trading, which is when a commissioning engineer
+  most wants it; the action log's edge key is the rounded watts, so blanking
+  them either floods or silences the log; and a surface that flickers between a
+  number and a dash is harder to read than a number with a standing caveat.
+  The narrow version of this — dropping the watts only — was the closest
+  runner-up.
+* **Record the unsized ask alongside the sized one.** It adds a number without
+  adding a warning. The unsized ask is `max_w`, a constant the operator
+  configured; on the shipped 3500/2000 row both figures are 2000 W, so the pair
+  is exactly as misleading as the single figure was.
+* **A caveat on every cycle in every state.** Rejected as the *whole* answer,
+  accepted as half of it: the unconditional part is a two-word narrowing of the
+  verb ("on this cycle"), not a warning, and the warning proper is conditional
+  so that it still means something when it appears.
+
+---
+
+## 4. SAFETY-10 §6's evidence, and why it could not fail
+
+§6 tabulated `arb_power_w` −2000 W *"identical"*, `arb_reason` *"identical,
+verbatim"*, arbiter winner *"identical"*. Two independent reasons it could
+never have gone red:
+
+1. **the fixture is `peak_cap_w: 15000` against a 350 W house**, so the guard
+   never engages and SAFETY-45's sizing is in the run and inert. ⚠️ **The
+   harness's own comment says so** — *"at this scenario's `peak_cap_w: 15000`
+   it is not binding anyway"* — which is MUTATION.md habit 4 written down
+   beside the check it disables;
+2. **every identity row reads the FIRST charging sample.** At `elapsed = 0` the
+   projection *is* the held level, so the two runs agree to the float there
+   **even at a cap that does bind**.
+
+⚠️ **AND THAT SECOND REASON IS THE ONE A REVIEWER CANNOT SEE FROM A DIFF.**
+Widening the fixture alone — the obvious fix — leaves the `[0]` comparison
+passing. Measured, not reasoned: at 1500/1200 the first charging cycle is
+−300.0000 W in **both** runs while 716 of the 720 cycles differ. Part 3d-2
+grades that agreement **as an expectation**, so nobody rebuilds a check on
+`[0]` believing it covers something.
+
+This is habit 4's **twelfth** instance in this repository, its **second**
+inside a committed evidence artifact, and — like the seventh and the eleventh —
+it was in a **measuring instrument** rather than in a check.
+
+§6 is re-taken at `peak_cap_w` 1500 / house 1200 / `max_w` 2000, across the
+whole run. Harness `/home/homelab/s47-mut/shadowloop47.py`.
+
+---
+
+## 5. The grader, so this class cannot recur
+
+`test_arbitrage.py` part **3d** — placed beside part 3c, which is SAFETY-45's
+own closed-loop regression, and built on the **same** `s45_loop()` harness so
+the two runs share every line of shipped code and differ in **one argument**:
+
+```
+s45_loop(sized=True)                  the live hour
+s45_loop(sized=True,  shadow=True)    the same hour, battery held at WIRE_W
+s45_loop(sized=False, shadow=True)    SAFETY-45's own defect, watched from
+                                      inside shadow mode
+```
+
+Three lines of `s45_loop()` stand in for `Controller._write_unit()`'s
+substitution and `_shadow_settle()`'s record and re-seed. They are marked as a
+**transcription**; `test_clamp.py` part 8 is the check on the shipped
+placement, and it drives the real `Controller`. Everything that produces a
+number — the averager, the projection, the guard, the headroom, the strategy,
+the arbiter, the row and the log sentence — is the shipped one.
+
+What 3d grades, in order: that the cap **binds** (the precondition the old
+evidence lacked); that the first charging cycle agrees **anyway**; that the
+whole run diverges, and by how much; that the record is an **upper bound**, and
+the two-point arithmetic that makes it one; what survives of the exemption;
+that SAFETY-45's limit cycle and the guard's engagements are **not** visible;
+the four rungs of `sized_from_meter()`, each reached with the other three clear
+(TEST-16); both operator surfaces; the `capped`-keying trap; and main.py's
+three call sites, pinned on the AST.
+
+⚠️ **The section carries its own precondition into every check.** A mutation
+that stops either run trading left the lists empty, the first `min()` raised,
+the file died before part 4 and the run reported **zero reds — which reads
+exactly like a survivor**. That is FCST-06's shape and it was **driven**, not
+imagined. `s47check()` now fails every check in the section when the stimulus
+was not produced, and the one division in it answers `nan` rather than raising.
+
+---
+
+## 6. The mutation battery — 14 mutations, no survivors
+
+Harness `/home/homelab/s47-mut/run.py`, backups inside it. Each run restores
+from backup, purges `__pycache__` **on the host**, and grades through the CI
+image with the tree bind-mounted `:ro`, so the interpreter cannot write a cache
+into the tree under test (TEST-15). Fingerprints are printed before the first
+run and re-checked after the last restore.
+
+| # | mutation | file | Δ | reds |
+|---|---|---|---|---|
+| M1 | the row drops the caveat branch | `shadow.py` | −63 B | 2 |
+| M2 | **the trap**: `sized_from_meter()` keyed on the trade being CAPPED — silent where the record is multiples out | `arbitrage.py` | +33 B | 5 |
+| M3 | the CHARGE rung dropped — a sell carries a caveat §9.1 makes false | `arbitrage.py` | −30 B | 1 |
+| M4 | the measured-headroom rung dropped | `arbitrage.py` | −18 B | 1 |
+| M5 | the arbiter-winner rung dropped — a caveat on somebody else's number | `arbitrage.py` | −33 B | 1 |
+| M6 | `main.py` renders the row with `sized_from_meter=False` | `main.py` | −23 B | 1 |
+| M7 | `main.py` drops `winner=` — the rung exists and is never reached | `main.py` | −1 B | 1 |
+| M8 | `main.py` sizes the trade from a literal — SAFETY-45 out of the shipped path, which the hoist put at risk | `main.py` | −41 B | 2 |
+| M9 | the headroom assignment moves out of `cycle()` | `main.py` | −39 B | 1 |
+| M10 | `sized_from_meter` gains a `False` default (TEST-14) | `shadow.py` | +8 B | 1 |
+| M11 | `ON THIS CYCLE` deleted — the row forecasts again | `shadow.py` | −14 B | 1 |
+| M12 | `log_line()` drops the caveat — the page discloses, the record does not | `shadow.py` | −63 B | 2 |
+| M13 ⚠️ | `main.py` re-assembles the log sentence at the call site | `main.py` | **+0 B** | 1 |
+| M14 ⚠️ | `wanted = batt_w − excess` — the headroom stops being monotone in the battery and the row's UPPER BOUND sentence becomes false | `peakguard.py` | **+0 B** | 38 |
+
+**Survivors: none.**
+
+⚠️ **M13 and M14 are `+0 B`, which MUTATION.md names as the risky delta.** Both
+were confirmed on disk by `sha256` before the run started — the harness prints
+the fingerprint of every graded file and the hash moved for each — and every
+run is purged, so neither is at risk of the stale-`.pyc` failure.
+
+⚠️ **Two findings from driving it, both reported rather than tidied away.**
+
+* **M14's first form was aimed at the wrong direction and correctly survived.**
+  `min` → `max` in the buy leg's sizing makes the shadow record *larger*, which
+  is still an upper bound, so 3d-3b was right not to fail. The mutation that
+  actually inverts the bound is the sign of the excess term in `wanted`. A
+  survivor that is right is worth more than a red aimed at the wrong claim.
+* **M12 was a survivor before the fix it forced.** Deleting the caveat from the
+  action-log line left **all 29 files green**: the only check that could see
+  that line drives a fixture with `meter_source: off`, where no arbitrage
+  decision — and therefore no caveat — is reachable. The sentence was an
+  f-string inside `Controller._shadow_settle()`, i.e. a surface no check could
+  grade. It is `shadow.log_line()` now, for the reason `words()` is a function,
+  and M13 is the mutation that puts it back at the call site.

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

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

goodwe_controller/DECISIONS/TARIFF-15-the-card-is-the-grader.md

@@ -85,11 +85,14 @@ 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` is 0.06 — three times the floor — so a card read a
+`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.
+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
 
@@ -155,4 +158,9 @@ granularity it was handed. Graded.
 * **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.
+  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.)*

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

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

goodwe_controller/DOCS.md

@@ -287,8 +287,10 @@ it always has.
 published — `Setpoint`, `Grid power`, `Battery power`, `Battery SoC`,
 `Circulating power`, `Maintenance phase`, `Controller status`, `P1 sample age` —
 keep their device, their `unique_id`s and therefore their **entity ids and their
-whole recorded history**. At a roster of one, nothing new is announced at all:
-no second device, no renamed entity, not one added topic.
+whole recorded history**. At a roster of one, nothing new is announced by the
+per-unit machinery at all: no second device, no renamed entity, not one added
+topic. (TEL-10's three loop rows, below, are site rows and are added at every
+roster length, including one.)
 
 Declare a second inverter and **four rows per unit** appear beside them:
 
@@ -321,7 +323,90 @@ arrives, and it fails silently and looks correct.
 There is one P1 meter and one grid connection; a per-inverter copy would invent
 two of a thing there is one of, and `P1 sample age` is a safety input. Same for
 `Circulating power` (it is a property of the *set* of inverters), the controller
-status, the maintenance phase and the capacity-tariff peak.
+status, the maintenance phase, the capacity-tariff peak and the three loop rows
+below.
+
+### Reading the grid-following loop: `Loop integrator`, `Loop integrator lead`, `Loop reason`
+
+The control law is a bounded integrator: an accumulator that is **not** the
+command. Each cycle it moves by `gain × error`; the command is then derived
+from it and passed through the output clamp, the slew limit and a 10 W
+quantisation before anything is written. Three entities publish what the
+accumulator is doing:
+
+| entity | unit | what it is |
+|---|---|---|
+| `Loop integrator` | W | the accumulator **after** this cycle — the value *before* the clamp, the slew limit and quantisation |
+| `Loop integrator lead` | W | that value minus **the command it was computed against**, i.e. the command the previous cycle left standing |
+| `Loop reason` | — | the law's own word for this cycle |
+
+`Loop reason` takes one of eight values:
+
+| value | what happened |
+|---|---|
+| `tracking` | ordinary regulation |
+| `deadband` | the error is inside `deadband_w`; the loop is holding |
+| `i-clamped` | the integrator hit `integrator_max_w` (which follows `max_w` by default) |
+| `clamped` | the *command* came out over `max_w` — only reachable if `integrator_max_w` is deliberately set above the rail |
+| `slew-limited` | the command could not move as far as the integrator asked for; `slew_w` is what stopped it |
+| `saturated-freeze` | the inverter is not following, so the command's magnitude may fall but not rise |
+| `freeze-released` | the freeze had run out of plant-shaped explanations and the command was let move again |
+| `not-running` | control is stopped **and** shadow mode is off, so the loop did not run |
+
+⚠️ **`Loop reason` is not the `Why` row on the status page, and the two will
+often disagree.** `Why` is the *arbiter's* sentence — `loop -> -1200 W` — which
+names the strategy that won and the watts it won with. It has never carried the
+strategy's own reason, so a loop that is slew-limited or frozen says so **only**
+here.
+
+⚠️ **`Loop integrator` is not `Setpoint`, even though it usually looks like
+it.** With nothing binding, the command *is* the integrator rounded to 10 W, so
+on a quiet day the two rows track each other and the difference is a rounding
+step. They separate exactly when something is wrong: a large disturbance sends
+the integrator to its bound in one or two cycles while the command may only
+travel `slew_w` per cycle, and `Loop integrator lead` is the gap. A standing,
+large lead means the loop has wound up further than the command can follow, and
+the number of cycles needed to unwind it is that lead divided by `slew_w`.
+
+Both numbers are `state_class: measurement`, so Home Assistant's recorder keeps
+long-term statistics for them.
+
+⚠️ **`Loop integrator lead` is BOUNDED, and the bound is two slew steps.** While
+the slew limit is what is holding the command back, the integrator may not stand
+more than **one** `slew_w` ahead of the command it emits — so the command always
+covers the gap in one cycle, and a reversal costs one cycle of unwind rather
+than `integrator_max_w / slew_w` (12.5 at `max_w: 5000`, `slew_w: 400`).
+Measured against the *previous* cycle's command, which is what this row
+publishes, that is two steps: 800 W at the live shape. **A published lead
+persistently above two slew steps means something is wrong** — either the
+saturation freeze is holding the command (`Loop reason` says
+`saturated-freeze`), or the bound is not doing its job.
+
+Before this bound existed, the same 6 kW export drove the lead to 4600 W and the
+integrator to its 5000 W rail, and the command then needed twelve cycles — about
+a minute at this install's meter rate — to walk back down once the disturbance
+cleared.
+
+⚠️ **What the bound buys — and how much of it is a model rather than a meter
+reading.** Sixteen days of the reference install's own recorded disturbances
+were replayed through both laws (`tools/replay_recorded_loop.py`). The result
+that survives every plant and tuning tried is the **export reduction: about an
+eighth of the modelled export** — 5.5 kWh of 39.6 at the plant lag the replay
+fits, 3.8 kWh of 28.9 at the shorter lag that best reproduces what this install
+actually exported — with wasted battery throughput falling alongside it, 4.67 to
+3.19 kWh at the fitted plant. ⚠️ **Those are simulated watt-hours.** The
+replay's fitted inverter carries a ~375 W RMS residual and prints `+35 %
+PESSIMISTIC` beside its own export figure on every run; the *direction* is what
+it establishes, not the absolute kWh.
+
+⚠️ **And it does NOT promise you a lower capacity-tariff peak.** The worst
+quarter-hour average offtake — the billed quantity — improves from 3739 W to
+3434 W **only at the longest plant lag the replay fits**. At every shorter lag,
+including the one that best reproduces the recorded export, release/1.0 already
+sits at 3434 W and this bound changes it by exactly zero. The plant lag is not
+identified by the recording, so treat the peak as unchanged and the export as
+the reason this exists. `DECISIONS/SAFETY-48-bounding-the-integrator-lead.md`
+§3a has the table.
 
 ⚠️ **Two roster names that differ only in punctuation or case** — `inverter-b`
 and `Inverter B` — are two names to the validator and one id once slugged. The
@@ -601,6 +686,168 @@ behind it would trip the firmware watchdog on a system that is working fine.
 | `site_sign_disagree_w` | 300 | **Two or more inverters only.** Threshold for the site-wide check - the sum of the commands against the meter. The same 300 W as `sign_disagree_w`, for the same reason: near zero the sign is noise |
 | `site_sign_disagree_s` | 325 | **Two or more inverters only.** How long the site's total command and the meter must stay opposed before every inverter is parked. Longer than `sign_disagree_s` because the command has to cross zero over a rail that is the sum of the roster, at a `slew_w` that is not - measured at 110 s with one inverter and 215 s with two |
 | `delivery_hold_s` | 185 | **Two or more inverters only.** How long one inverter may stand at a discharge share it is not producing - short by more than `saturation_w`, with no reason this add-on can read - while at least one sibling is **not** in that state, before it is named. **It reports; it does not act.** Nothing is commanded differently and the site goes on running short by that unit's share |
+| `shadow_mode` | `auto` | **Run every decision and command nothing.** `auto` = shadow mode while control is stopped, ordinary control once you press Start; `on` = shadow mode always; `off` = ordinary control. See *Shadow mode* below |
+
+#### Shadow mode (`shadow_mode`, SAFETY-10)
+
+Shadow mode runs the **whole** decision path — the price strategy, the capacity
+guard, the maintenance shaping, the grid-following loop, the arbiter that ranks
+them, SAFETY-28's authorisation gate and SAFETY-03's clamp — and **sends nothing
+to the inverter**. It is how you find out what this add-on *would* do on a site
+before you let it do it.
+
+Every defect in the optimiser that this project has found was invisible from
+outside while it was happening: a price lookup answering for the wrong
+quarter-hour, a trade against a binding capacity cap that ran 28 charge onsets
+in an hour, an SoC ceiling churning 598 Wh to gain 310 Wh. Each one was paid for
+at the meter first and noticed afterwards. Shadow mode is the surface that
+would have shown all three on the day.
+
+**What "commands nothing" means, exactly.** Every inverter is held at **0 W**,
+written by the ordinary single writer and refreshed on the ordinary heartbeat.
+It is not silence. ⚠️ **The inverter holds its last command forever** — it has
+no meter timeout — so a mode that simply stopped writing would leave whatever
+was standing when you switched it on standing for as long as you left it on,
+under a page saying nothing was being commanded. Refreshing 0 W is also what
+the ESP32's 30 s stale-input watchdog requires of us: going quiet would put
+that board into a *tripped watchdog* state for the whole run, which is an alarm
+being used as a mode.
+
+**The three values.**
+
+| value | what happens |
+|---|---|
+| `auto` | **the shipped default.** Shadow mode while control is **stopped**; ordinary control once control is **started**. A new install ships `auto_start: false`, so it comes up in shadow mode and observes before it ever commands anything. An install that is already controlling is started, so nothing about it changes |
+| `on` | shadow mode **always**, whatever the *Start / stop control* button says. This is the one to pick to watch an armed site for a day — the loop runs, arbitrage decides, the peak guard files its claims, and the battery does not move |
+| `off` | ordinary control |
+
+⚠️ **Existing installs are not changed.** The default is `auto` rather than a
+boolean `true` precisely because a boolean would have changed them: the
+Supervisor composes an add-on's options as *its defaults, overlaid with your
+stored options*, so a new key with a new default reaches every install on the
+next update. `shadow_mode: true` would have silently stopped a battery that is
+regulating today, and the only symptom would be a battery that stopped doing
+anything.
+
+⚠️ **Under `auto`, pressing *Start* leaves shadow mode.** That is the point of
+`auto` — the button means "control the battery". Set `on` if you want the
+decisions recorded while the loop runs.
+
+**What you get out of it.** The status page carries a red-amber banner saying
+the battery is not being controlled, a `Shadow mode` row saying which rung
+decided, what it **would have commanded on that cycle** and why — with the
+caveat below, where the number was sized from a meter the battery never
+moved — and the `Why` row with the arbiter's own sentence. The action log gets one line each time the decision
+changes — the winner or the watts — rather than one per cycle, so a 40-row log
+still contains the context of what it found. MQTT reports `status: shadow`.
+
+**The failsafes.** The sign watchdogs (SAFETY-02/30) are **inert**: they grade
+what this controller has standing on the wire, and that is 0 W, so they cannot
+arm. That is deliberate and it is the single most important decision in this
+feature — 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**. The clamp (SAFETY-03), the write-authorisation gate (SAFETY-28), the
+frozen-meter alarm (SAFETY-18) and the capacity guard all **observe**: they run
+on the number the decision path produced, so a shadow run can tell you the
+clamp would have engaged. ⚠️ **The capacity guard observes a meter with no
+battery in it.** Every term of the quantity it thresholds is measured, so it
+engages in a shadow run only if the *house alone* would have put the quarter
+over the ceiling — 410 engaged cycles live against 0 in shadow, on the hour
+tabulated below. Its *ceiling* and its *reasons* are worth reading from a
+shadow run; its *engagements* are not evidence of anything. The circulation (SAFETY-31) and delivery (SAFETY-42)
+watchdogs observe and may legitimately latch, because their evidence is
+*measured* power, not a command. The operator stop is enforced at the wire
+instead of as a claim, so that the recorded decision is the real one.
+
+⚠️ **A latch that was already up stays up.** Shadow mode does not clear
+anything. The 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 unchanged.** The maintenance state machines are ticked on
+every cycle whether control is started or not, so they already run against a
+battery that does not move on a stopped install. Shadow mode inherits that
+exactly; it neither improves it nor makes it worse.
+
+⚠️ **What a shadow run will NOT tell you — and it is a whole category, not a
+footnote.** The controller's carried command is re-seeded to the 0 W standing
+on the wire at the end of every shadow cycle — that is what makes turning
+shadow mode off safe, because the loop then resumes from where the battery
+actually is. Everything below follows from the same fact.
+
+**A shadow run cannot show you a closed-loop defect. Not partially — not at
+all.** The battery is held at 0 W, so every *measured* input — the meter, the
+billed-quarter accumulator behind it, the battery power, the state of charge —
+describes a plant that did not respond. A closed-loop defect is one whose
+stimulus **is** the plant's response, and there is no response to be the
+stimulus. This is not a gap waiting to be closed: feeding the guards a
+simulated plant instead is exactly what the sign-watchdog decision below
+refuses, and for the same reason — a controller reacting to a plant that does
+not exist drifts further from reality every tick. **The closed-loop answer
+comes from the closed-loop rig or from a live run, and there is no third
+place.**
+
+Concretely, measured on the rig at `peak_cap_w` 1500 under a 1200 W house,
+`max_w` 2000, one hour at a 5 s cycle — the same hour run twice, live and in
+shadow, on the same code:
+
+| | live | shadow |
+|---|---|---|
+| charge onsets in the hour | **28** | **1** |
+| grid | **−455.5 … +3200.0 W** | **1200.0 W flat — the house** |
+| capacity guard engaged | **410 / 720 cycles** | **0 / 720** |
+| state of charge | 50.000019 → 51.856789 % | **50.000000 → 50.000000 %** |
+
+(The onset and engagement figures are taken with the trade-sizing fix reverted,
+because that is the defect being looked for; the SoC and grid figures are the
+shipped build.)
+
+⚠️ **The "strategies are unaffected" exemption that used to stand here was true
+until the trade-sizing fix landed, and is now false by hours.** That fix makes
+the buy leg `min(asked, headroom)`, where the headroom is
+`(900 / seconds remaining) × (ceiling − projected quarter average)` — and the
+projection reads the **open quarter's accumulator**, i.e. the meter, i.e. a
+function of what the battery did earlier in that same quarter. What survives
+of the exemption is exactly this much:
+
+> **Which** hour a strategy picks, and **why**, are unaffected — the clock and
+> the price series are not functions of the battery. Measured: identical live
+> and shadow on 720 of 720 charging cycles at a binding cap. **How hard** it
+> trades is not.
+
+⚠️ **So the watts on the `Shadow mode` row are the right answer to a question
+nobody asked, and the row now says so.** In a shadow run the billed quarter
+really *is* under its ceiling, because the battery really *is* not charging, so
+`900 / remaining` multiplies a gap a live run would have closed. On the same
+rig, shipped code:
+
+| cap / house | live commanded | shadow recorded | over by |
+|---|---|---|---|
+| 1500 / 1200 | −302.4 W | **−2000.0 W** | **6.61×** |
+| 3500 / 3000 | −502.6 W | −2000.0 W | 3.98× |
+| 3500 / 2000 *(shipped cap)* | −1502.6 W | −2000.0 W | 1.33× |
+| 3500 / 1800 | −1702.6 W | −2000.0 W | 1.17× |
+| 15000 / 350 | −2000.0 W | −2000.0 W | 1.00× |
+
+Whenever a measured billed quarter sized the number, the row and the action log
+carry **⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE
+HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W** — and the watts are introduced
+as what it would have commanded **on this cycle**, in every state, because no
+number a shadow run records is a forecast of a live one. The figure is **not**
+re-computed to look right: a shadow-only sizing would mean the recorded
+decision was no longer the decision the shipped path reached, which is the one
+thing this feature has to be able to say.
+
+The **grid-following loop** is the same story told first: its recorded decision
+is **one slew step** and stays there, because a trajectory depends on a battery
+responding and none did.
+
+**What a shadow run genuinely is for**, then: *which* strategy wins, on *which*
+hour, at *which* price, for *which* reason, against which limits — the
+wrong-quarter-hour class of defect, a trade armed on a day it should not be, a
+refusal whose sentence names the wrong subsystem, a clamp that would have
+engaged, a standing failsafe latch. That is a real and useful set, and it is
+the set this feature covers.
 
 #### The sign-disagreement failsafe
 
@@ -979,6 +1226,7 @@ What exists today, and what does not:
 |---|---|
 | `max_w` bounds the magnitude | ✅ — but the exposure IS the magnitude |
 | Maintenance charging capped under `peak_cap_w` | ✅ |
+| **Arbitrage charging capped under `peak_cap_w`** | ✅ — SAFETY-45, sized to the guard's own MEASURED headroom rather than to `peak_forecast_entity` |
 | **Loop capped under `peak_cap_w`** | ✅ — SAFETY-07, on every `meter_source` but `off` |
 | Frozen meter detected | ✅ on `homewizard_local` only, **alarm only** |
 | Frozen meter *stopped* | ✅ — SAFETY-07 forbids importing while the meter is frozen |
@@ -1041,6 +1289,19 @@ projected over — raises one notification (`goodwe_peak_saturated`), because th
 is the one state where the money will be spent and shedding load is the only
 thing left that changes the bill.
 
+**And it sizes a price-driven charge, not only a forced discharge (SAFETY-45).**
+The same arithmetic read the other way answers *"how hard may this site charge
+without putting the quarter over"* — `peakguard.charge_headroom_w()` — and
+`arbitrage.decide()` sizes its buy leg to it. Before that, a trade commanded
+`max_w` until the projection rose far enough to engage the guard, at which point
+the interlock cancelled the trade outright, the loop took the actuator, the
+projection collapsed and the trade came back at `max_w`: **28 charge onsets in
+one hour** on TEST-23 stage 3's closed rig, with the grid swinging −456 to
++3200 W and every billed quarter finishing over the cap. It is one onset now,
+the trade runs continuously at the affordable rate, and the billed quarters land
+**on** the cap. ⚠️ The guard is what changed *around* arbitrage; `decide()`
+itself is untouched, so nothing above this line is different.
+
 **No new option for the CEILING.** It is `peak_cap_w`, which already shipped. The
 coverage threshold is `meter_max_age_s`, the freeze predicate is
 `meter_freeze_s`, and the achievable discharge comes from `max_w` and the device
@@ -1371,8 +1632,9 @@ does, and only after you have read why.
 |---|---|
 | `price_provider` | `off` (default) or one of the three plugins below |
 | `price_markup_eur_kwh` | Your supplier's margin, EUR/kWh. **Added only when the chosen plugin's feed does not already contain it** |
-| `price_taxes_eur_kwh` | Levies and VAT, EUR/kWh. Same rule |
-| `export_price_eur_kwh` | The **injection** price. A separate scalar, not a series — see below |
+| `price_taxes_eur_kwh` | Distribution, levies and VAT, EUR/kWh. Same rule. Defaults to **0.11736** — a real Flemish figure, and **yours is probably different**: see *What `price_taxes_eur_kwh` is made of* below |
+| `export_price_eur_kwh` | The **flat injection** price, EUR/kWh. May be negative — see below |
+| `price_export_formula` | The **injection formula**, if your contract has one. Same shape as `price_formula`, its own coefficients, its own `vat_pct` — see below |
 | `price_csv_path` | Where `manual_csv` reads its file |
 | `price_feed_url` | Override the plugin's default feed. Used **exactly as written** — the add-on appends nothing to it, including the date range, so an override gets whatever horizon that URL returns. Only a host the plugin itself declares is accepted |
 | `price_horizon_h` | How far ahead to ask for, hours |
@@ -1691,10 +1953,13 @@ the default markup and taxes, not an illustration.)
 
 ##### What it does not do
 
-The **injection** leg is a separate card. Eneco uses `0,102` on consumption and
+The **injection** leg is a separate card, and it has its own option:
+`price_export_formula` (TARIFF-16). Eneco uses `0,102` on consumption and
 `0,100` on injection, and injection is VAT-exempt where consumption is at 6 %,
-so it is a second per-contract formula rather than a second copy of this one.
-`export_price_eur_kwh` is still the scalar you enter by hand.
+so it is a second per-contract formula rather than a second copy of this one —
+the same parser, its own coefficients. `export_price_eur_kwh` remains the flat
+injection price for a site that is paid one, and **no strategy reads either**;
+see *Injection is priced separately* above.
 
 #### `manual_csv` — the offline fallback
 
@@ -1845,31 +2110,335 @@ logged and reported on the status row, never raised. A cache that cannot answer
 is not allowed to be a controller that cannot regulate, and that applies to the
 volume being full exactly as it applies to the volume being absent.
 
-**Injection is priced separately** (`export_price_eur_kwh`). In Belgium it is
-often near zero, which by itself strongly favours self-consumption over export.
-Negative values are accepted — you can be paid to *not* export at midday in
-summer.
+### Injection is priced separately
 
-⚠️ It is a single number rather than a curve, and the reason given here until
-TARIFF-07 — *"no supported supplier publishes a dynamic injection tariff"* — was
-**false**. Suppliers do. Eneco publishes `0,1 x BELPEX-H − 1,188` on the same
-tariff card as its consumption formula (identical on the January and the
-September 2026 cards), and ENGIE publishes one in the same shape,
-`(B x eSpot_15) − A`. What is true is narrower: an injection curve is the **same
-two-coefficient formula** as the consumption curve but with **its own**
-coefficients and **its own VAT treatment** — injection is VAT-exempt where
-consumption is at 6% — so it is a second per-contract formula rather than a copy
-of the first, and the add-on cannot evaluate either one yet. Until the formula
-provider ships, **this scalar is a simplification you enter by hand — an average
-of what you are actually paid — and not a reflection of the market.**
+There are two ways to say what you are paid for an exported kWh, and which one
+you want depends on your contract:
 
-**The old Home Assistant price sensors.** `price_now_entity` and
+| your contract | what to set |
+|---|---|
+| a flat injection price | `export_price_eur_kwh` — one number, EUR/kWh. This is the default and what every existing install uses |
+| a price that moves with the market | `price_export_formula` — your card's injection line as `factor × index + offset`, in exactly the shape `price_formula` uses for consumption |
+
+Negative values are accepted on both — you can be charged to export at midday in
+summer, and the add-on says so rather than flooring it.
+
+#### ⚠️ What the add-on does *not* do with an injection price
+
+**No strategy in this add-on reads one.** Not the scalar, not the formula.
+`arbitrage.py` prices the sell side as **displaced import** — both hours it
+compares are all-in *consumption* prices — and its own comment gives the reason:
+§9.3's near-zero Belgian injection price is exactly why the economically sound
+trade on this market is *charge cheap to displace expensive import*, not *charge
+cheap to export dear*. So setting `price_export_formula` changes **no decision
+the add-on takes today**. It changes what you are shown at startup, and it is
+the shape any future export-aware strategy would read.
+
+That is the argument for doing it now rather than later: OPT-06 and any export
+logic would otherwise inherit a scalar that cannot represent the market, and the
+6% VAT asymmetry between the two legs would be invisible in the arithmetic.
+`test_price.py` 17h parses every module under `app/` and goes red the day
+something calls an injection reader, so this paragraph is graded rather than
+attested.
+
+#### Why a scalar was not enough
+
+Belgian suppliers publish the injection leg as a formula, on the same card as
+the consumption one. The reason given here until TARIFF-07 — *"no supported
+supplier publishes a dynamic injection tariff"* — was **false**, and what they
+publish has four properties one number cannot hold:
+
+```
+Eneco Zon & Wind Dynamisch   0,1 x BELPEX-H - 1,188   c/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
+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 about `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%. `vat_pct` is **per leg**, so that six-point asymmetry
+   is expressible; a single scalar carries no VAT field at all.
+4. **It goes negative, with no floor.** Eneco's injection price is below zero
+   for any BELPEX-H under **11,88 EUR/MWh** — and a PV household exports
+   precisely in the hours most likely to be negative. **You can be charged to
+   export.**
+
+#### `price_export_formula`, field by field
+
+Same grammar as `price_formula` — literally the same parser, with its option
+name as an argument, so there is no second unit table and no second card rule to
+diverge from the first. Eneco's published injection line, typed out:
+
+```json
+{"index":"epex_be","resolution":"hourly","factor":0.1,"offset":-1.188,
+ "units":"c_eur_per_kwh","vat_pct":0}
+```
+
+⚠️ **`vat_pct` is 0 here and 6 on the consumption leg.** That is the one field
+people copy across from the other formula and get wrong.
+
+⚠️ **The `card` block is optional on this leg and required on the other**, and
+that is a statement about the cards rather than a relaxed rule. `price_formula`
+can demand one because a Belgian card prints the consumption formula, the
+reference index it assumed *and* the resulting price — so the add-on can
+recompute that price and refuse to start unless your numbers reproduce it.
+**Eneco's injection formula is printed with no price beside it.** There is
+nothing to grade against on that card. Requiring a block would make the market's
+own published line inexpressible; inventing the estimate would grade your
+coefficients against arithmetic done with your coefficients, which is not a
+check. So:
+
+* if **your** card prints an injection estimate, fill the block in and it is
+  graded at the same tolerance as the consumption leg — the add-on refuses to
+  start if your numbers do not reproduce it;
+* if it does not, the add-on **says so at startup** — *"its coefficients are
+  UNGRADED"* — and names what it checked instead.
+
+What it checks instead, always, on both paths:
+
+* **pass-through**: `factor`, converted to a share of the wholesale price, must
+  be between 0.10× and 10×. Eneco's injection leg is `1.00×` and Aspiravi's
+  `0.70×`; a coefficient typed a hundred times out reads `0.01×` or `100×`.
+* **offset magnitude**: `|offset|` must be at most 0.20 EUR/kWh. The published
+  ones are `−0.01188` and `−0.02`.
+
+Both bounds are on the **coefficients**, not on the price, which is why they can
+bound a leg whose price legitimately goes below zero. `price_formula`'s
+plausibility band is deliberately **not** reused here: its floor is `+0.02
+EUR/kWh` of energy, and applying that to injection would refuse the real market
+in exactly the hours where knowing the number matters most.
+
+⚠️ **And the gap those bounds leave, with its size.** They bound the *shape* of
+the coefficients, never their truth. With no printed estimate, a `factor` of
+`0.070` where your contract says `0.100` — 30% of every export payment — passes
+both, because `0.70×` is a pass-through somebody really publishes. Only a
+printed estimate can catch a wrong-contract pair, and on Eneco's card there is
+not one. That is why the startup line says the leg is ungraded instead of
+implying it was checked.
+
+### The old Home Assistant price sensors
+
+`price_now_entity` and
 `price_avg_entity` still work and are unchanged: the add-on compares them and
 uses the result as a cheap-window hint for the maintenance charge. They are
 **not compatible with `price_provider`, and not with `static_profile` either**
 — configure two of them and the add-on refuses to start, naming the conflict,
 because the add-on reads exactly one and the loser is silent. Use one.
 
+### The three buckets — which price components can move a decision (TARIFF-17)
+
+**Read this before adding a price component of any kind.** The optimiser reads
+exactly two quantities off a price series, and nothing else:
+
+- the **spread**, `max − min` over the *firm* points, weighed against
+  `cycle_cost_threshold_eur`; and
+- **which hour is cheapest**, `min(firm, key=…)` — the hour a battery would
+  buy in.
+
+Every component of a Belgian bill reaches those two through one of three
+buckets, and which bucket it is in is a property of its *shape*, not of its
+size:
+
+| bucket | what it looks like | reaches the decision? |
+|---|---|---|
+| **LEVEL** | additive, **identical every hour** | **No — provably.** An additive constant cancels exactly in `max − min`, and adding it to every point leaves the argmin where it was |
+| **SPREAD** | **multiplicative** on the spot index | **Yes.** It scales the spread against a fixed `cycle_cost_threshold_eur` |
+| **ORDER** | **varies** by hour, block or day-type | **Yes, and worst.** It changes *which hour is cheapest* |
+
+Measured on the real arithmetic (`test_price.py` section 16b, printed on every
+run): with a flat taxes figure of 0.00, 0.0739, 0.11736 (the shipped default),
+0.1198, 0.1327 or 1.00 EUR/kWh, the same 24-hour feed is cheapest at **13:00 in
+all six cases** and its spread is **0.1500 EUR/kWh in all six cases**. That is
+the LEVEL bucket doing nothing, and it is not a rounding artefact — it is
+arithmetic.
+
+Three consequences worth having in mind:
+
+1. **`price_taxes_eur_kwh` is not a wrong number and never was.** It sits in
+   the LEVEL bucket and *cannot* distort either quantity. What it also cannot
+   do is express a component that varies by hour — which is why
+   `price_taxes_profile` exists. The defect TARIFF-17 closed was a **missing
+   capability**, not a bad constant.
+2. **`custom_formula`'s `factor` is a SPREAD component, and its `offset` is
+   LEVEL.** The contract price is `(factor × index + offset) × (1 + VAT)`, so
+   the spread over a feed is `factor × (1 + VAT) × (max index − min index)` —
+   the offset drops out entirely, and the spread is *proportional* to `factor`.
+   Moving `factor` from 0.100 to 0.10812 therefore moves the spread by exactly
+   **+8.1 %** on any feed whatever. A coefficient typed one digit wrong is not
+   a small pricing error; it is a different trading threshold. The VAT rate is
+   multiplicative on the whole expression, so it is SPREAD too.
+3. **A check that grades the spread is grading the wrong bucket.** An
+   implementation that reads an hour-varying table *once* and adds the same
+   number to every point produces a series of the right magnitude and the wrong
+   shape — the LEVEL bucket wearing a period table. The spread would look
+   plausible; the buy hour would be wrong. So the regression check for an
+   ORDER-bucket component asserts **which hour is cheapest**, not how big the
+   spread is (`test_price.py` 16c and 16d).
+
+⚠️ **Where the buckets are today.** `price_markup_eur_kwh`,
+`price_taxes_eur_kwh` and `custom_formula`'s `offset` are LEVEL.
+`custom_formula`'s `factor` and its VAT rate are SPREAD. `price_taxes_profile`
+is the only ORDER component the add-on has. Anything added next belongs in one
+of the three, and saying which is part of adding it.
+
+### What `price_taxes_eur_kwh` is made of, and why yours is different (TARIFF-18)
+
+**It ships at `0.11736` EUR/kWh.** That is the all-in non-energy part of a
+Flemish residential bill — everything on your invoice that is *not* the energy
+itself — read off the Eneco residential card for Flanders, **September 2026**,
+**including 6 % VAT**:
+
+| component | c€/kWh |
+|---|---|
+| Fluvius distribution (**Antwerpen**) | 5,35 |
+| Bijzondere accijns, *"Alle verbruik"* — no volume bands | 4,876 |
+| Bijdrage groene stroom en WKK Vlaanderen | 1,51 |
+| Energiebijdrage | **0** |
+| **total** | **11,736 c€/kWh = 0.11736 €/kWh** |
+
+The rows are in the code, in `app/price.py`'s
+`FLEMISH_TAXES_COMPONENTS_EUR_KWH`, and `test_price.py` section 1b re-adds them
+and refuses a default that is not their sum. It replaces a shipped `0.06`,
+which was roughly **half** the true figure and had no recorded provenance at
+all.
+
+⚠️ **`energiebijdrage` is zero and that is not a mistake.** *"Vanaf 1 augustus
+2026 bedraagt de energiebijdrage 0 EUR/MWh"* — it was merged into the
+bijzondere accijns. If you are re-deriving this total from a guide written
+before that date you will find a separate energiebijdrage line; adding it would
+count it twice. It is carried as a **zero row** rather than left out for
+exactly that reason.
+
+⚠️ **THIS IS A PER-DSO FIGURE AND YOURS IS PROBABLY NOT 0.11736.** Only the
+distribution row moves. Across the eight Fluvius DSOs it runs **5,28 c€/kWh**
+(Midden-Vlaanderen) to **6,70** (West), so the Flemish all-in total runs about
+**0.117 to 0.131 €/kWh** — a 1,42 c€/kWh spread, which on 4 000 kWh a year is
+about €57. The other two rows are Flanders-wide and do not move. **Look up your
+own distribution row, add the same accijns and groenestroombijdrage, and type
+the total.**
+
+⚠️ **A WALLOON OR BRUSSELS SITE SHOULD NOT USE THIS SCALAR AT ALL.** Their
+distribution tariff has a **day and a night band** — `Enkelvoudig | Dag |
+Nacht | Uitsl. nacht` on the same card, where Fluvius prints a single rate —
+and a flat figure flattens exactly the component that is anti-correlated with
+what the battery wants to do. Use **`price_taxes_profile`** (the next section);
+it is the only ORDER-bucket component the add-on has.
+
+⚠️ **THIS IS A DISPLAY AND GUARD FIX. IT DOES NOT IMPROVE ARBITRAGE, AND IT
+CANNOT.** `price_taxes_eur_kwh` is a **LEVEL** component — added identically to
+every hour — so it **cancels exactly** in `max − min` and leaves the argmin
+where it was. It does not change which hour is cheapest, it does not change the
+spread, and it does not make any trade happen that did not happen before. See
+*The three buckets* above, where six flat scalars spanning and exceeding the
+whole per-DSO range give the identical cheapest hour and the identical spread
+to the last digit. What raising it **does** change is exactly two things:
+
+* **every figure an operator reads** — the all-in prices on the status page,
+  `custom_formula`'s startup preview and the recorded price history. At half
+  the true non-energy component they made the add-on look considerably better
+  than it is.
+* **§17's negative-price guard** (`arbitrage.py`), which is the one rung that
+  tests an **absolute** all-in price rather than a difference. The guard fires
+  when `spot < −(markup + taxes)`, so its boundary moved from **−0.09000** to
+  **−0.14736 €/kWh** of spot. A spot hour at −0.11868 €/kWh used to read
+  **−0.02868 €/kWh** all-in and the discharge was refused as paid-for disposal;
+  at the real tax level it reads **+0.02868** and the discharge is allowed,
+  because the operator really does pay those levies and that hour really was
+  profitable (`test_arbitrage.py` section 2c drives both, and pins the boundary
+  from below as well).
+
+⚠️ **Which is why the default sits near the LOW end of the per-DSO band rather
+than in the middle of it.** The two error directions are not symmetric. Set too
+**high**, the figure carries a genuinely negative hour up above zero and the
+add-on exports into paid-for disposal — §17's own regression case. Set too
+**low**, it only declines a discharge that would have paid. Where one default
+has to stand in for eight DSOs, it belongs at the bottom.
+
+**If you set this yourself, nothing above affects you.** A site with its own
+`price_taxes_eur_kwh` keeps it; the default only answers where the option is
+absent from the stored options blob.
+
+### Levies and VAT by time of day (`price_taxes_profile`)
+
+**Leave this empty unless your network tariff really does have a day and a
+night rate**, which in Flanders it does not. Fluvius distribution is a single
+rate: its row on the tariff card reads `Normaal | Uitsl. nacht`, and
+*exclusive night* is a **separate physical circuit** (a night-storage heater on
+its own meter), not the night register of a dual-rate meter. For a Flemish site
+the flat `price_taxes_eur_kwh` is correct, and this option changes nothing.
+
+**Wallonia and Brussels are different, and the same card proves it.** The
+Walloon DSOs and Sibelga get four columns — `Enkelvoudig | Dag | Nacht |
+Uitsl. nacht` — and the day/night gap is real money (c€/kWh):
+
+| DSO | enkelvoudig | dag | nacht | gap |
+|---|---|---|---|---|
+| ORES | 11,98 | 13,27 | 7,39 | **5,88** |
+| AIESH | 13,64 | 15,17 | 8,21 | **6,96** |
+| Tecteo RESA | 11,06 | 12,20 | 7,01 | 5,19 |
+| Sibelga (Brussels) | 9,39 | 9,39 | 7,10 | 2,29 |
+| ORES IMPACT (2026) | — | 16,578 | 5,090 | **11,49** |
+
+⚠️ **The bands are anti-correlated with what the battery wants to do.** The
+cheap network hours are the cheap spot hours. So flattening them does not
+merely shift the curve — it **systematically understates the true spread**, and
+the add-on declines cycles that are genuinely profitable. On ORES's bands over
+one ordinary winter weekday the measured effect is: cheapest hour **13:00 →
+03:00**, spread **0.1500 → 0.1788 EUR/kWh**.
+
+It is written in **exactly the same grammar as `static_profile`** — the same
+periods, the same day selectors, the same rule that every day type is covered
+once with no gap and no overlap, the same DST handling. It is literally the
+same parser; there is no second tiling rule, because a second one would be a
+second set of 23- and 25-hour-day bugs.
+
+```json
+{"periods": [
+  {"name":"dag",  "from":"07:00","to":"22:00","days":"mon-fri","eur_per_kwh":0.1327},
+  {"name":"nacht","from":"22:00","to":"07:00","days":"mon-fri","eur_per_kwh":0.0739},
+  {"name":"nacht","from":"00:00","to":"24:00","days":"sat,sun", "eur_per_kwh":0.0739}]}
+```
+
+- ⚠️ **`eur_per_kwh` here is the LEVIES ALONE, not an all-in price.** It is the
+  non-energy part of the bill for that band, and the add-on adds it to whatever
+  your price source publishes — exactly as it adds the flat figure. This is the
+  one place the two options differ in meaning while sharing a grammar, and the
+  refusal you get for leaving the number out says which one is wanted.
+- ⚠️ **The card prints cents. This option takes EUR.** ORES prints `13,27`;
+  type `0.1327`. A whole card typed in cents is refused at startup, naming both
+  bands and the factor — including the cards (Sibelga's 9,39 / 7,10) whose
+  figures are small enough to slip past the ±10 EUR/kWh bound the parser holds
+  every price to.
+- ⚠️ **Set this *or* `price_taxes_eur_kwh`, not both.** The table wins when it
+  is set, so a scalar left at a non-default value beside it would be a number
+  you typed that decides nothing. That is refused at startup rather than
+  silently resolved; leave `price_taxes_eur_kwh` at its shipped `0.11736` when
+  you fill this in. ⚠️ **A scalar still sitting on the superseded `0.06` is
+  also accepted**, and deliberately so — TARIFF-18 moved that default, and your
+  stored options blob carries the old number whether you typed it or not, so
+  refusing it would have stopped working Walloon and Brussels sites on an
+  upgrade over a figure the table overrides anyway.
+- A **malformed table is refused at startup**, not at the next fetch. It is
+  read on the ~30 s planning path, and a table that first fails at 03:00 is a
+  site that stops pricing at 03:00 — which §11.4 turns into a quiet fallback
+  that looks exactly like a healthy fixed-tariff day.
+- It applies to the components the framework **adds**: `generic_dayahead`
+  (which declares `{ENERGY}`) and `custom_formula` (which declares
+  `{ENERGY, MARKUP}`) both get it. `manual_csv` publishes an all-in figure and
+  is untouched — the table is routed through the same `capabilities().adds`
+  rule as the scalar, not bolted on.
+- It does **not** apply to `static_profile`, whose prices are already all-in,
+  nor to `export_price_eur_kwh` or `price_export_formula`. Those are the
+  injection leg, and nothing is added to what you are *paid* for export:
+  `price_taxes_eur_kwh` is a consumption component.
+
 ### Static day/night and fully-fixed tariffs (`static_profile`)
 
 Most Belgian households are **not** on a dynamic contract, and an EMS that only

goodwe_controller/MUTATION.md

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

goodwe_controller/app/arbitrage.py

@@ -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 "
@@ -303,7 +314,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 +325,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 +353,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 +428,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.
 

goodwe_controller/app/control.py

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

goodwe_controller/app/custom_formula.py

@@ -125,6 +125,49 @@ 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
@@ -183,6 +226,150 @@ _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 price_provider is 'custom_formula'.",
+        zero_factor=("every spread is exactly 0, and arbitrage can never "
+                     "clear any threshold - a strategy that silently never "
+                     "fires rather than one that is off"),
+        flat=("that is `static_profile` with a single period covering "
+              "00:00-24:00 on all days and price_provider 'off'; the add-on "
+              "then says so at startup instead of leaving you to find out "
+              "from a year of unchanged bills"),
+        neg_factor=("No consumption tariff is indexed negatively; if your "
+                    "card shows a minus sign it is on the OFFSET (`A`), "
+                    "which is allowed here and common on injection"),
+        card_required=True,
+        card_note=("It is the only thing that can tell a correct pair of "
+                   "coefficients from a plausible-looking wrong one"),
+        card_causes=(
+            "or - the expensive one - network charges, levies or excise "
+            "folded into `offset`. ⚠️ THEY DO NOT BELONG THERE: a Belgian "
+            "card's Tariefformule line is the ENERGY component alone (Eneco "
+            "tabulates network tariffs and levies separately; ENGIE says in "
+            "so many words that the formula excludes network, distribution, "
+            "transport, levies and excise), the add-on adds "
+            "price_taxes_eur_kwh on top of it, and folding ~12 c EUR/kWh of "
+            "network charge into `offset` bills you for it twice. That is "
+            "the error this check exists to catch, and it is why it cannot "
+            "be switched off."),
+    ),
+    EXPORT_FORMULA_OPTION: _Leg(
+        option=EXPORT_FORMULA_OPTION,
+        what="injection",
+        # ⚠️ NO `card` BLOCK IN THE EXAMPLE, because Eneco's injection line has
+        # none to copy - the formula is printed with no price beside it. An
+        # example carrying one would invite an operator to compute the figure
+        # themselves, which is the one thing this leg must not encourage.
+        example=('{"index":"epex_be","resolution":"hourly","factor":0.1,'
+                 '"offset":-1.188,"units":"c_eur_per_kwh","vat_pct":0}'),
+        when=("Leave it empty unless your supplier pays you an injection "
+              "price that moves with the market; a flat one is "
+              "export_price_eur_kwh. ⚠️ This option is read whatever "
+              "price_provider is set to - it is the leg you are PAID on, not "
+              "the one you buy on."),
+        zero_factor=("every hour pays the same, which is a FLAT injection "
+                     "price written as a formula. ⚠️ Note this is NOT the "
+                     "arbitrage argument the consumption leg gives: no "
+                     "strategy in this add-on reads an injection price at "
+                     "all, so a flat one here fires nothing and declines "
+                     "nothing - it is simply the wrong option"),
+        flat=("that is `export_price_eur_kwh`, the flat injection scalar, "
+              "which is what every site used before this option existed and "
+              "which still answers when this one is empty"),
+        neg_factor=("No Belgian injection tariff is indexed negatively - you "
+                    "are paid MORE when the market is dearer, not less. The "
+                    "minus sign on an injection card is on the OFFSET (`A`): "
+                    "Eneco prints `0,1 x BELPEX-H - 1,188` and Aspiravi "
+                    "`0,07 x Belpex - 2`, and a negative offset is accepted "
+                    "here"),
+        card_required=False,
+        card_note=(
+            "⚠️ IT IS OPTIONAL ON THIS LEG, AND THAT IS A STATED GAP RATHER "
+            "THAN A RELAXED RULE. A Belgian card prints the CONSUMPTION "
+            "formula with the reference index and the resulting price beside "
+            "it, which is what makes `price_formula`'s self-check possible. "
+            "Eneco's injection line has NO printed price beside it, so on "
+            "that card there is nothing to grade against and requiring a "
+            "`card` block would make the market's own published formula "
+            "inexpressible - or, worse, invite an operator to compute the "
+            "estimate themselves, at which point the check grades the "
+            "coefficients against arithmetic done with the same coefficients. "
+            "Supply it if YOUR card prints one; when it is absent the add-on "
+            "says at startup that this leg is UNGRADED and the two "
+            "coefficient bounds below are all there is"),
+        card_causes=(
+            "or VAT added where there is none. ⚠️ INJECTION IS VAT-EXEMPT IN "
+            "BELGIUM - \"Injectietarieven zijn vrijgesteld van btw\" - while "
+            "consumption is at 6%, so `vat_pct` on THIS option is 0 on every "
+            "Belgian card the research found, and a 6 typed here because it "
+            "is 6 on the consumption leg is a ratio of exactly 1.06. Nothing "
+            "is added to this leg by the framework: price_taxes_eur_kwh is a "
+            "CONSUMPTION component and is not applied to what you are paid "
+            "for export, so an offset carrying network charges is a "
+            "different error here than it is on price_formula and this "
+            "check cannot tell you which one you made."),
+    ),
+}
+
+
 
 @dataclass(frozen=True)
 class FormulaSpec:
@@ -199,14 +386,44 @@ class FormulaSpec:
     offset: float
     units: str
     vat_pct: float
-    card_month: str                 # "YYYY-MM", as the card is dated
-    card_index_eur_per_mwh: float
-    card_expect_incl_vat: float     # in `units`, as the card prints it
+    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.
@@ -241,7 +458,18 @@ def card_discrepancy(spec: FormulaSpec) -> float:
     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
 
@@ -250,7 +478,7 @@ def card_discrepancy(spec: FormulaSpec) -> float:
 # Reading the option
 # --------------------------------------------------------------------------- #
 
-def _finite(value, field: str) -> float:
+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
@@ -260,26 +488,37 @@ def _finite(value, field: str) -> float:
     """
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         raise FormulaInvalid(
-            f"price_formula.{field} is {value!r}, which is not a number. "
+            f"{option}.{field} is {value!r}, which is not a number. "
             f"Write the coefficient as a bare JSON number - 0.102, not "
             f"\"0.102\" and not an expression: this provider takes FIXED "
             f"coefficients and evaluates nothing.")
     if not math.isfinite(float(value)):
         raise FormulaInvalid(
-            f"price_formula.{field} is {value!r}, which is not finite. A NaN "
+            f"{option}.{field} is {value!r}, which is not finite. A NaN "
             f"or an infinity here makes every price NaN, every price "
             f"comparison False, and an arbitrage strategy that never fires "
             f"while reporting that it is armed.")
     return float(value)
 
 
-def _card(raw) -> tuple:
-    """The `card` block: the estimate the coefficients are graded against."""
+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(
-            "price_formula has no \"card\" block, and it is REQUIRED. It is "
-            "the only thing that can tell a correct pair of coefficients from "
-            "a plausible-looking wrong one: the add-on recomputes your "
+            f"{leg.option} has no \"card\" block, and it is REQUIRED. "
+            f"{leg.card_note}: the add-on recomputes your "
             "supplier's own printed example from the numbers you typed and "
             "refuses to start if it does not come out. Copy the three figures "
             "off the same tariff card as the coefficients: "
@@ -287,24 +526,26 @@ def _card(raw) -> tuple:
             "\"expect_incl_vat\": 15.55}.")
     if not isinstance(raw, dict):
         raise FormulaInvalid(
-            f"price_formula.card is {type(raw).__name__}, not an object with "
+            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"price_formula.card has no field(s) {unknown}. The fields it "
+            f"{leg.option}.card has no field(s) {unknown}. The fields it "
             f"takes are {list(_CARD_KEYS)}; a key that is merely ignored is a "
             f"number the operator believes took effect.")
     month = str(raw.get("month", "") or "").strip()
     if not _month_date(month):
         raise FormulaInvalid(
-            f"price_formula.card.month is {raw.get('month')!r}; write the "
+            f"{leg.option}.card.month is {raw.get('month')!r}; write the "
             f"month the card is dated as \"YYYY-MM\", e.g. \"2026-09\". It is "
             f"not used in any price - it is what lets the add-on tell you "
             f"your card has gone stale.")
     return (month,
-            _finite(raw.get("index_eur_per_mwh"), "card.index_eur_per_mwh"),
-            _finite(raw.get("expect_incl_vat"), "card.expect_incl_vat"))
+            _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):
@@ -316,9 +557,16 @@ def _month_date(month: str):
         return None
 
 
-def parse_price_formula(value):
+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:
 
@@ -335,6 +583,7 @@ def parse_price_formula(value):
     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):
@@ -345,16 +594,13 @@ def parse_price_formula(value):
             value = json.loads(text)
         except ValueError as e:
             raise FormulaInvalid(
-                f"price_formula is not valid JSON ({e}). It is a JSON object "
+                f"{option} is not valid JSON ({e}). It is a JSON object "
                 f"on one line, e.g.\n"
-                f'  {{"index":"epex_be","resolution":"hourly","factor":0.102,'
-                f'"offset":1.00,"units":"c_eur_per_kwh","vat_pct":6,'
-                f'"card":{{"month":"2026-09","index_eur_per_mwh":133.9905,'
-                f'"expect_incl_vat":15.55}}}}\n'
-                f"Leave it empty unless price_provider is 'custom_formula'.")
+                f"  {leg.example}\n"
+                f"{leg.when}")
     if not isinstance(value, dict):
         raise FormulaInvalid(
-            f"price_formula is {type(value).__name__}, not a JSON object with "
+            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
@@ -366,7 +612,7 @@ def parse_price_formula(value):
     unknown = sorted(set(value) - set(_TOP_KEYS))
     if unknown:
         raise FormulaInvalid(
-            f"price_formula has no field(s) {unknown}. The fields it takes "
+            f"{option} has no field(s) {unknown}. The fields it takes "
             f"are {list(_TOP_KEYS)}. ⚠️ There is deliberately NO field that "
             f"takes an expression: this provider multiplies and adds two "
             f"FIXED coefficients and evaluates nothing, because two "
@@ -378,7 +624,7 @@ def parse_price_formula(value):
     index = str(value.get("index", "") or "").strip()
     if index not in INDEXES:
         raise FormulaInvalid(
-            f"price_formula.index is {value.get('index')!r}. The reference "
+            f"{option}.index is {value.get('index')!r}. The reference "
             f"series this add-on can fetch are "
             f"{', '.join(f'{k!r} ({v})' for k, v in sorted(INDEXES.items()))}. "
             f"If your card names a different index, the add-on cannot get it "
@@ -388,7 +634,7 @@ def parse_price_formula(value):
     resolution = str(value.get("resolution", "") or "").strip()
     if resolution not in RESOLUTIONS:
         raise FormulaInvalid(
-            f"price_formula.resolution is {value.get('resolution')!r}; it "
+            f"{option}.resolution is {value.get('resolution')!r}; it "
             f"must be one of {list(RESOLUTIONS)}. Belgium has been on a "
             f"15-minute MTU since 2025-10-01 and the feed publishes 96 points "
             f"a day; a contract written against the HOURLY series is priced "
@@ -402,16 +648,16 @@ def parse_price_formula(value):
     units = str(value.get("units", "") or "").strip()
     if units not in UNITS:
         raise FormulaInvalid(
-            f"price_formula.units is {value.get('units')!r} and is REQUIRED - "
+            f"{option}.units is {value.get('units')!r} and is REQUIRED - "
             f"there is no default, on purpose. It must be one of "
             f"{sorted(UNITS)}. Your card prints the formula in ONE of these "
             f"and two suppliers use two different conventions for the same "
             f"shape, so assuming one would be a factor of 100 or 1000 on "
             f"every hour with nothing able to notice.")
 
-    factor = _finite(value.get("factor"), "factor")
-    offset = _finite(value.get("offset"), "offset")
-    vat_pct = _finite(value.get("vat_pct"), "vat_pct")
+    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
@@ -421,15 +667,10 @@ def parse_price_formula(value):
     # the operator at it rather than let them build it by accident.
     if factor == 0.0:
         raise FormulaInvalid(
-            "price_formula.factor is 0, so the index would not enter the "
+            f"{option}.factor is 0, so the index would not enter the "
             "price at all: every hour of every day comes out at "
-            f"{offset:g} x (1 + {vat_pct:g}/100), every spread is exactly 0, "
-            "and arbitrage can never clear any threshold - a strategy that "
-            "silently never fires rather than one that is off. If your tariff "
-            "really is one flat price, that is `static_profile` with a single "
-            "period covering 00:00-24:00 on all days and price_provider "
-            "'off'; the add-on then says so at startup instead of leaving you "
-            "to find out from a year of unchanged bills.")
+            f"{offset:g} x (1 + {vat_pct:g}/100), {leg.zero_factor}. If "
+            f"your {leg.what} tariff really is 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
@@ -437,37 +678,96 @@ def parse_price_formula(value):
     # mispriced site, it is a site actively trading against itself.
     if factor < 0.0:
         raise FormulaInvalid(
-            f"price_formula.factor is {factor:g}, which is NEGATIVE. That "
+            f"{option}.factor is {factor:g}, which is NEGATIVE. That "
             f"inverts the market: the dearest hour of the day comes out as "
             f"the cheapest one, so the battery would charge at the evening "
             f"peak and discharge at 03:00 - trading against itself on every "
-            f"cycle. No consumption tariff is indexed negatively; if your "
-            f"card shows a minus sign it is on the OFFSET (`A`), which is "
-            f"allowed here and common on injection.")
+            f"cycle. {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"price_formula.vat_pct is {vat_pct:g} and must be between 0 and "
+            f"{option}.vat_pct is {vat_pct:g} and must be between 0 and "
             f"30. It is a PERCENTAGE, so Belgian residential electricity is "
             f"6, not 0.06 and not 106. Zero is legitimate and is not refused: "
             f"injection is VAT-exempt, and a card that already quotes "
             f"VAT-inclusive coefficients needs no second multiplication.")
 
-    month, card_index, card_expect = _card(value.get("card"))
+    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)
+                       card_expect_incl_vat=card_expect, option=option)
 
-    delta = card_discrepancy(spec)
-    if abs(delta) > CARD_TOLERANCE:
-        raise FormulaInvalid(card_refusal(spec, delta))
+    # ⚠️ 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.
 
@@ -479,8 +779,9 @@ def card_refusal(spec: FormulaSpec, delta: float) -> str:
     got = in_card_units(spec, spec.card_index_eur_per_mwh)
     ratio = (got / spec.card_expect_incl_vat
              if spec.card_expect_incl_vat else float("inf"))
+    leg = _LEGS[spec.option]
     return (
-        f"price_formula does not reproduce its own card, so the add-on will "
+        f"{spec.option} does not reproduce its own card, so the add-on will "
         f"NOT start on it. Your contract's arithmetic is "
         f"price = (factor x index_eur_per_mwh + offset) x (1 + vat_pct/100); "
         f"on the card's own index that is "
@@ -496,15 +797,7 @@ def card_refusal(spec: FormulaSpec, delta: float) -> str:
         f"1000 - `units` must be the one the formula line is printed in); VAT "
         f"left out or applied twice (ratio 1.06 or 1/1.06); a transposed "
         f"digit; the two sides copied off DIFFERENT cards or different "
-        f"months; or - the expensive one - network charges, levies or excise "
-        f"folded into `offset`. ⚠️ THEY DO NOT BELONG THERE: a Belgian card's "
-        f"Tariefformule line is the ENERGY component alone (Eneco tabulates "
-        f"network tariffs and levies separately; ENGIE says in so many words "
-        f"that the formula excludes network, distribution, transport, levies "
-        f"and excise), the add-on adds price_taxes_eur_kwh on top of it, and "
-        f"folding ~12 c EUR/kWh of network charge into `offset` bills you for "
-        f"it twice. That is the error this check exists to catch, and it is "
-        f"why it cannot be switched off.")
+        f"months; {leg.card_causes}")
 
 
 # --------------------------------------------------------------------------- #
@@ -520,13 +813,16 @@ def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
 
     ⚠️ 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.06, which is three 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. 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.
+    `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
@@ -536,13 +832,27 @@ def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
     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"price_formula's own card works out at {energy:.5f} EUR/kWh of "
+        f"{spec.option}'s own card works out at {energy:.5f} EUR/kWh of "
         f"energy ({spec.card_expect_incl_vat:g} {spec.units} as the card "
         f"prints it) and {all_in:.5f} EUR/kWh all-in once "
         f"price_taxes_eur_kwh is added, which is outside the plausible band "
@@ -558,6 +868,85 @@ def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
         f"the best charging opportunity of the year - is never refused.")
 
 
+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 is {spec.factor:g} {spec.units} per "
+            f"EUR/MWh, which passes through {spec.passthrough:.4g}x the "
+            f"wholesale price - outside the plausible "
+            f"{PASSTHROUGH_LO}-{PASSTHROUGH_HI}x for an injection tariff. A "
+            f"Belgian injection formula pays a share of the market price a "
+            f"little under or about equal to it: Eneco's "
+            f"`0,1 x BELPEX-H - 1,188` c EUR/kWh is 1.00x and Aspiravi's "
+            f"`0,07 x Belpex - 2` is 0.70x. {spec.passthrough:.4g}x is what a "
+            f"factor typed in the wrong units looks like - check `units` "
+            f"({spec.units!r}) against the unit printed beside your formula, "
+            f"because the card self-check cannot see a factor of 10, 100 or "
+            f"1000 applied to BOTH sides at once. ⚠️ This bounds the "
+            f"COEFFICIENT and not the price: an injection price below zero is "
+            f"accepted and is the real market - Eneco's goes negative under "
+            f"11.88 EUR/MWh of BELPEX-H, which is the middle of a sunny day.")
+    if abs(spec.offset_eur_kwh) > INJECTION_OFFSET_MAX_EUR_KWH:
+        return (
+            f"{spec.option}.offset is {spec.offset:g} {spec.units} = "
+            f"{spec.offset_eur_kwh:+.5f} EUR/kWh, and |offset| above "
+            f"{INJECTION_OFFSET_MAX_EUR_KWH} EUR/kWh is not a Belgian "
+            f"injection tariff in either direction. The published ones are "
+            f"small and NEGATIVE - Eneco -1,188 c EUR/kWh (-0.01188), "
+            f"Aspiravi -2 c (-0.02) - so a minus sign here is expected and is "
+            f"not what this refuses; a MAGNITUDE two orders out is. The usual "
+            f"cause is the offset typed in a different unit from `units` "
+            f"({spec.units!r}), or a consumption offset copied onto the "
+            f"injection leg: they are different numbers on the same card. "
+            f"⚠️ Network charges and levies do not belong here either - "
+            f"nothing is added to what you are PAID for export, so an offset "
+            f"carrying them is simply wrong rather than double-counted.")
+    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
@@ -568,7 +957,7 @@ def stale_card(spec: FormulaSpec, today=None):
     if dated is None or (now - dated).days <= CARD_STALE_DAYS:
         return None
     return (
-        f"price_formula's card is dated {spec.card_month}, which is "
+        f"{spec.option}'s card is dated {spec.card_month}, which is "
         f"{(now - dated).days} days ago. Suppliers reprice: if your contract "
         f"has been renewed or rolled over since then, the coefficients here "
         f"are last year's and every price this add-on computes is wrong by "

goodwe_controller/app/main.py

@@ -66,6 +66,7 @@ from .mqtt import (MqttPublisher, announced_units, unit_slugs,
                    unit_state_key)
 from . import peakguard
 from . import packshare
+from . import shadow
 from .p1 import P1Ingest, build_source, is_enabled
 from .price import Uncertainty, price_option, provider_configured
 from .price_history import PriceHistory
@@ -830,9 +831,46 @@ class Controller:
 
         # live state
         self.auto = bool(store.data.get("auto", opts.get("auto_start", False)))
+        # --- SAFETY-10 -------------------------------------------------------
+        # What the decision path reached on the last shadow cycle, in W, or
+        # None before the first one. ⚠️ IT IS KEPT SEPARATELY FROM
+        # `self.target` BECAUSE THEY ARE DIFFERENT FACTS: `self.target` is what
+        # is STANDING ON THE WIRE - held at `shadow.WIRE_W` for the whole of a
+        # shadow run, and re-seeded to it at the end of every shadow cycle so
+        # the loop and the sign watchdogs track reality - and this is what a
+        # live controller WOULD have put there. Folding them into one field is
+        # how a shadow run starts telling an operator a number nothing is
+        # doing.
+        self.shadow_would_w = None
+        # SAFETY-47. Was the number above SIZED FROM THE BILLED-QUARTER METER
+        # on the cycle it was recorded? ⚠️ IT IS RECORDED WHERE THE DECISION
+        # WAS TAKEN, NOT RE-DERIVED WHERE THE PAGE IS RENDERED. The status page
+        # runs on its own task and `self.peak_guard` has moved on by then, so a
+        # page that asked the question again would be answering it about a
+        # different cycle from the one whose watts it is displaying - which is
+        # the same two-facts-one-field defect the comment above this one is
+        # about. ⚠️ False AND NOT None BEFORE THE FIRST SHADOW CYCLE, unlike
+        # the field above: this one is a claim ABOUT a number, and there is no
+        # number yet, so the honest value is "nothing to disclose". The row's
+        # `would_w is None` branch renders no watts at all there.
+        self.shadow_sized_from_meter = False
+        # Edge state for the action log, both of them. `_shadow_was` is None
+        # until the first cycle, so an install that comes up IN shadow mode
+        # says so in the log it will be read from rather than leaving the
+        # operator to infer it from a page nobody is looking at yet. Coming up
+        # LIVE is silent - see `_shadow_settle()`, which says why.
+        self._shadow_was = None
+        self._shadow_winner = None
         self.target = 0.0
         self.sat_count = 0
         self.i_w = 0.0        # the loop's integrator, carried between cycles
+        # TEL-10. What the last cycle's loop did, kept for publication. Seeded
+        # to the SAME values the "stopped or blind" branch of `cycle()` writes,
+        # because before the first cycle the loop has not run - which is the
+        # thing that branch is for.
+        self.loop_i_w = 0.0
+        self.loop_i_lead = 0.0
+        self.loop_reason = "not-running"
         self.loop_w = None    # what the loop asked for last cycle, or None
         # Did the grid-following loop actually win the LAST arbitration? That is
         # the question SAFETY-02 has to ask about the command standing on the
@@ -904,6 +942,12 @@ class Controller:
         # None (startup) or the PREVIOUS cycle's decision (an input hold), and
         # the status row rendered all three identically.
         self.arb_at = None
+        # SAFETY-45/47. The billed-quarter charging headroom the arbitrage step
+        # was handed on the cycle above, or None when nothing measured it. It
+        # is CARRIED rather than recomputed for `arbitrage.sized_from_meter()`,
+        # because `self.peak_guard` is a different cycle's decision by the time
+        # the status page renders.
+        self.arb_headroom_w = None
         # TARIFF-11. When the most recent cycle() STARTED. `arb_at < cycle_at`
         # is the exact, derived statement of "the latest cycle did not get as
         # far as the arbitrage step", which is the fact the *Arbitrage* row
@@ -1739,6 +1783,42 @@ class Controller:
                        "reports a different value.",
                        inv.name, inv.batt_fresh.reason)
 
+    @property
+    def shadow(self) -> bool:
+        """SAFETY-10. Is the battery being left alone right now?
+
+        ⚠️ A PROPERTY, NOT A FIELD, AND FOR THE REASON `self.units` IS ONE.
+        Three surfaces ask this question at three different moments - the
+        cycle, the write, and the status page rendered between two cycles - and
+        a cached flag is a fourth answer that can disagree with the option and
+        the button it is derived from. Derived, they cannot.
+
+        ⚠️ AND THE WRITE GATE ASKS THIS, NOT A PARAMETER PASSED DOWN TO IT. A
+        suppression that had to be threaded through `write_setpoint()` would be
+        absent from every call site that forgot it - the heartbeat, the stop
+        button, `shutdown()` - which is exactly the shape of hole this add-on's
+        single choke point exists to close.
+        """
+        return shadow.engaged(self.o, control_started=self.auto)
+
+    def shadow_latches(self) -> tuple:
+        """The failsafe latches that are UP, named, for the shadow banner.
+
+        A latch that is standing while the controller is inert is standing when
+        it stops being inert. `shadow.banner()` carries them so an operator who
+        turns shadow mode off is not handed a battery that will not move and a
+        page that never mentioned why.
+        """
+        out = []
+        if self.circ_wd.tripped:
+            out.append("circulating power")
+        if self.site_sign_wd.tripped and len(self.inverters) > 1:
+            out.append("site sign watchdog")
+        for inv in self.inverters:
+            if inv.sign_wd.tripped:
+                out.append(f"{inv.name} sign watchdog")
+        return tuple(out)
+
     def write_refusal(self, value: float, inv=None) -> str | None:
         """Why `value` may NOT be written to `inv` right now, or None if it may.
 
@@ -1930,6 +2010,40 @@ class Controller:
             self.log_event(f"{inv.name}: {result.describe()}")
         value = result.applied_w
 
+        # --- SAFETY-10: AND THIS IS THE LAST THING BEFORE THE WIRE -----------
+        # Shadow mode runs the whole decision path and commands nothing. The
+        # suppression is HERE, in the one method every write in this add-on
+        # reaches - the cycle, the heartbeat, the stop button, shutdown() and
+        # maint_abort() alike - so there is no call site that can route round
+        # it. app/shadow.py carries the whole argument; three things about the
+        # placement belong here:
+        #
+        # ⚠️ IT IS A SUBSTITUTION, NOT A RETURN, exactly like the two refusals
+        # above it. Returning would leave the inverter LATCHED ON ITS LAST
+        # COMMAND with the ESP32's heartbeat still being fed - a battery held
+        # at whatever it was doing when shadow mode was switched on, under a
+        # status page saying nothing is being commanded. That is the failure
+        # this add-on keeps finding, and shadow mode must not be a new way to
+        # reach it. `shadow.WIRE_W` is 0.0 W and it is REFRESHED on the
+        # ordinary heartbeat, which is also what firmware/goodwe-master.yaml's
+        # 30 s stale-input watchdog requires of us.
+        #
+        # ⚠️ IT IS BELOW SAFETY-28's GATE AND BELOW SAFETY-03's CLAMP, so both
+        # still grade the number the decision path actually produced. A shadow
+        # run that could not say "it would have hit the rating here" would be
+        # answering a different question from the one it is for.
+        #
+        # ⚠️ IT IS NOT A SECOND WRITER. No claim is filed, no transport is
+        # opened and no arithmetic of its own reaches the wire: one actuator,
+        # one writer, and this is that writer emitting the value it emits for
+        # every other refusal.
+        if self.shadow and value != shadow.WIRE_W:
+            _LOG.info("SHADOW MODE: not commanding %+.0f W to %s - holding "
+                      "%+.0f W. The decision was reached and recorded; "
+                      "nothing was sent to the inverter.",
+                      value, inv.name, shadow.WIRE_W)
+            value = shadow.WIRE_W
+
         changed = (inv.last_write is None or value != inv.last_write)
         if not (changed or force):
             return
@@ -2549,7 +2663,16 @@ class Controller:
         # operator switching control off for the whole site; "inputs missing" is
         # the SITE's own telemetry gone - the meter this controller regulates
         # against. Neither is about a pack, and both must stop every inverter.
-        if not self.auto:
+        # ⚠️ SAFETY-10: `and not self.shadow`, AND IT IS THE ONE FAILSAFE THIS
+        # CARD CHANGES. `P_SAFETY` out-ranks every other claim, so leaving the
+        # stop claim in while shadow mode is engaged would make the recorded
+        # decision "stopped" on every cycle - a shadow run that answers the
+        # wrong question, which is the same as no shadow run. The actuator ends
+        # at the same number either way, and the substitution in `_write_unit()`
+        # that replaces it is STRICTLY STRONGER than this claim: a claim can be
+        # out-ranked by a higher priority, and the wire gate cannot be
+        # out-ranked by anything.
+        if not self.auto and not self.shadow:
             claims.append(Claim.set("safety", P_SAFETY, 0.0, "stopped",
                                     actuator=self.actuator_of("safety")))
         elif not self.inputs_ok:
@@ -2720,12 +2843,35 @@ class Controller:
         # `arb_at` is then the age the status row reports rather than a
         # decision presented as current.
         self.arb, self.arb_at = None, now
+        self.arb_headroom_w = None
         if arbitrage.enabled(self.o):
             floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
             charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
+            # SAFETY-47. HOISTED OUT OF THE CALL, NOT COPIED. One evaluation of
+            # the shipped expression feeds both the sizing below and
+            # `arbitrage.sized_from_meter()` in `_shadow_settle()`, so the
+            # caveat on the recorded watts can never be answered from a
+            # different cycle's guard than the watts were.
+            self.arb_headroom_w = peakguard.charge_headroom_w(self.peak_guard)
             self.arb = arbitrage.decide(
                 self.fresh_tariff_plan(now), now,
                 peak_guard_active=arbitrage.guard_state(self.peak_guard),
+                # SAFETY-45. THE SAME GUARD'S SECOND ANSWER, AND THE CONTINUOUS
+                # ONE. `guard_state()` is a switch and it was the whole loop:
+                # the guard engaged on a 5 W floor, the trade was refused
+                # outright, the loop took the actuator, the meter fell, the
+                # guard released and the trade came back AT max_w. Measured on
+                # TEST-23 stage 3 at the shipped peak_cap_w/max_w: 28 charge
+                # onsets an hour, grid -456 <-> +3200 W. This is the watts the
+                # billed quarter can still afford, so the buy leg is CLAMPED
+                # instead - the shape control.maintenance_charge_floor() has
+                # always given a maintenance charge, off the MEASURED guard
+                # rather than off the optional peak_forecast_entity.
+                # ⚠️ SAME ORDERING ARGUMENT AS THE LINE ABOVE: this reads the
+                # peak block's conclusion, ~50 lines up, so it must stay after
+                # it. Evaluated earlier it would size this quarter's trade from
+                # the previous cycle's quarter.
+                charge_headroom_w=self.arb_headroom_w,
                 # The emptiest pack again, and for the sell side that is the
                 # right reduction. ⚠️ THE BUY SIDE WANTS THE FULLEST, and there
                 # is one `soc` argument - `pack_floor_soc` names that residual
@@ -2877,7 +3023,14 @@ class Controller:
                                                                         inv)))
 
         # --- the grid-following loop -----------------------------------------
-        if self.auto and self.inputs_ok:
+        # ⚠️ SAFETY-10: `or self.shadow`. The loop is the leg a shadow run most
+        # needs and the one that is switched off by `auto_start: false`, so
+        # without this an install in `auto` shadow mode would record every
+        # strategy's decision and a permanent silence where the grid-following
+        # loop should be. It is safe because the loop's `prev_w` is
+        # `self.target`, which the end of this method re-seeds to what is
+        # actually standing on the wire.
+        if (self.auto or self.shadow) and self.inputs_ok:
             # ⚠️ prev is the ARBITER's last output, not the loop's own last
             # wish. If something outranked the loop, that is what the hardware
             # actually did, and the controller must track reality or it jumps
@@ -2908,8 +3061,15 @@ class Controller:
             # level: the two halves of §6.2's identity break in opposite
             # directions. See `site_batt_w` and test_alloc.py part 8.
             site_batt = self.site_batt_w
+            # TEL-10. ⚠️ ONE NAME FOR THE COMMAND THE LOOP WAS MEASURED
+            # AGAINST. `self.target` is reassigned further down this method, so
+            # a `decision.i_w - self.target` written at publish time would
+            # subtract a DIFFERENT cycle's command and call the answer a lead.
+            # The published lead is built from the value `compute()` was
+            # actually handed, on the line that hands it over.
+            loop_prev = self.target
             decision = compute(
-                prev_w=self.target,
+                prev_w=loop_prev,
                 grid_w=self.grid,
                 actual_w=site_batt,
                 tuning=self.tuning,
@@ -2922,6 +3082,41 @@ class Controller:
             self.sat_count = decision.sat_count
             self.i_w = decision.i_w
             self.loop_w = decision.target_w
+            # --- TEL-10 ------------------------------------------------------
+            # ⚠️ THE INTEGRATOR HAS NEVER LEFT THIS PROCESS, AND THAT IS WHAT
+            # THE CARD IS. `self.i_w` is carried between cycles and published
+            # nowhere - no entity, no attribute, no log line - so the only way
+            # anyone has ever asked what it was doing is to RECONSTRUCT it from
+            # the grid trace and a replay. That reconstruction reproduced about
+            # a third of the engagements it was checked against and was thrown
+            # away; a card that has to be argued from a discarded reconstruction
+            # is a card that cannot be argued.
+            #
+            # Three rows, and the third is not derivable from the first two by
+            # anyone reading the dashboard afterwards:
+            #
+            #   `loop_i`      the integrator AFTER this cycle - `Decision.i_w`,
+            #                 which its own docstring says is the value BEFORE
+            #                 the output clamp, the slew limit and quantisation.
+            #                 It is therefore NOT `setpoint` and must never be
+            #                 published from it.
+            #   `loop_lead`   how far the integrator stands AHEAD of the command
+            #                 it was computed against. This is the quantity
+            #                 SAFETY-48 bounds, and `integrator_max_w / slew_w`
+            #                 is the number of cycles it takes to unwind.
+            #   `loop_reason` `compute()`'s OWN reason string - `deadband`,
+            #                 `i-clamped`, `clamped`, `slew-limited`,
+            #                 `saturated-freeze`, `freeze-released`, `tracking`.
+            #
+            # ⚠️ AND `loop_reason` IS NOT `self.reason`. `self.reason` is the
+            # ARBITER's sentence (`resolution.explain()`, e.g. "loop -> 1200 W")
+            # and it does not carry the loop's own word at all: the Claim filed
+            # below takes `decision.reason` and `Resolution.explain()` prints the
+            # winner's NAME, not the winner's reason. The status page's "Why"
+            # row is the arbiter's sentence and stays that way.
+            self.loop_i_w = decision.i_w
+            self.loop_i_lead = decision.i_w - loop_prev
+            self.loop_reason = decision.reason
             # --- SAFETY-03 ---------------------------------------------------
             # ⚠️ READ THE BOOLEANS, NOT `decision.reason`. On a default install
             # the integrator bound is what bites and the output clamp is
@@ -2946,6 +3141,15 @@ class Controller:
             # Stopped or blind: no accumulation may survive the outage.
             self.i_w = 0.0
             self.loop_w = None
+            # TEL-10, and it is the same zero the line above writes rather than
+            # a second opinion about it. ⚠️ `not-running` rather than a stale
+            # `tracking`: a reason row that keeps repeating the last word the
+            # loop said while the loop is not running is a row that reads as
+            # health, which is the failure `publish()`'s own None-dropping note
+            # is about one field over.
+            self.loop_i_w = 0.0
+            self.loop_i_lead = 0.0
+            self.loop_reason = "not-running"
             # A loop that is not running cannot be winding. Clearing this here
             # rather than letting the last value stand is what makes the alarm
             # de-assert when control is stopped.
@@ -3211,6 +3415,133 @@ class Controller:
         # reads only `self.p1`, which no line in this method writes.
         self.peak.sync(self.p1)
 
+        # --- SAFETY-10, AND IT IS LAST FOR A REASON THAT IS NOT TIDINESS -----
+        # Every guard above has now read `self.target` - the resolved intent -
+        # and SAFETY-18 in particular grades exactly that. Re-seeding before
+        # them would hand each one a 0 W that no decision produced. Re-seeding
+        # AFTER them hands the NEXT cycle, and the sign watchdogs, what is
+        # actually standing on the wire. See `_shadow_settle()`.
+        self._shadow_settle(resolution)
+
+    def _shadow_settle(self, resolution) -> None:
+        """SAFETY-10. Record the decision, then re-seed the carried command.
+
+        TWO JOBS, AND THEY ARE IN THIS ORDER BECAUSE THE SECOND DESTROYS THE
+        FIRST'S EVIDENCE.
+
+        1. THE RECORD. A shadow run is only worth running if it answers "what
+           would it have done, and why". `self.shadow_would_w` and
+           `Resolution.explain()` are that answer, and the action log gets one
+           line per CHANGE OF DECISION rather than one per cycle - the log
+           holds 40 rows, and a level-logged shadow run would flush the context
+           of its own findings inside four minutes at a 15 s cycle floor. The
+           same edge rule the peak guard and the arbitrage strategy already
+           use, for the same reason.
+
+        2. THE RE-SEED. `self.target` and each `inv.target` are set back to
+           `shadow.WIRE_W` - what the write gate actually put on the wire.
+
+        ⚠️ WHY THE RE-SEED IS A SAFETY PROPERTY AND NOT BOOKKEEPING. Three
+        machines read the carried command as a statement about the HARDWARE:
+
+          * `compute(prev_w=self.target, ...)` - the loop's slew limiter and
+            its integrator. Left holding a shadow decision, the first cycle
+            after shadow mode is turned off would slew from a base that never
+            existed: up to a full `slew_w` step onto a battery sitting at 0 W.
+            Re-seeded, the exit is safe BY CONSTRUCTION and needs no separate
+            transition code - the carried command already equals the standing
+            one.
+          * `Inverter.standing_w()`, which is what SAFETY-02/30's sign
+            watchdogs grade. Fed a shadow decision they would compare a number
+            against a meter that never saw it, disagree for as long as the
+            decision asked for power, and LATCH A TRIP THAT SURVIVES INTO LIVE
+            OPERATION AND A RESTART. Shadow mode would manufacture the failsafe
+            it exists to help debug. ⚠️ THIS ONE IS ALREADY HELD BY THE WIRE
+            GATE - `standing_w()` prefers `last_write`, and that is the 0.0 W
+            the gate accepted - so the re-seed is the SECOND rung, covering
+            the fallback before any write has been accepted. Two rungs
+            answering one question is MUTATION.md's masking shape, and the
+            mutation that reproduces the hazard has to defeat BOTH: driven
+            singly, dropping this line leaves the detector inert and names
+            nothing about the latch. Measured.
+          * SAFETY-42's delivery watchdog compares `inv.target` against what
+            the pack is producing. A share nothing was told to produce is a
+            delinquency report on every cycle of every shadow run.
+
+        ⚠️ AND EVERY CYCLE'S DECISION IS THEREFORE COMPUTED FROM WHERE THE
+        PLANT REALLY IS, not from a counterfactual plant that drifts further
+        from reality every tick. "What would this controller command NOW,
+        given this meter and a battery at 0 W" is a true statement about the
+        present; "what would the eleventh cycle of a run that never happened
+        have commanded" is not a statement about anything.
+        """
+        engaged = self.shadow
+        if engaged != self._shadow_was:
+            # ⚠️ `first` EXISTS SO A LIVE INSTALL'S FIRST CYCLE IS SILENT. The
+            # edge is against `None` on cycle one, and an install that comes up
+            # CONTROLLING has nothing to report - a "shadow mode off" line at
+            # every start is one more row of boilerplate in a 40-row log, and
+            # it was measured pushing a real clamp episode's context out of
+            # test_clamp.py part 2's ring. Coming up IN shadow mode is the
+            # other direction and it is always worth a line: it is the log an
+            # operator reads to find out why nothing is being commanded.
+            first = self._shadow_was is None
+            self._shadow_was = engaged
+            if engaged:
+                self.log_event(
+                    "SHADOW MODE ON - " + shadow.why(
+                        self.o, control_started=self.auto)
+                    + f"; inverter held at {shadow.WIRE_W:.0f} W")
+                _LOG.warning(
+                    "SAFETY-10 SHADOW MODE IS ON. The full decision path runs "
+                    "and NOTHING is commanded: every inverter is held at "
+                    "%+.0f W on the ordinary heartbeat. %s", shadow.WIRE_W,
+                    shadow.why(self.o, control_started=self.auto))
+            elif not first:
+                self.log_event(
+                    "SHADOW MODE OFF - the battery is being controlled again, "
+                    f"resuming from {shadow.WIRE_W:.0f} W")
+                _LOG.warning(
+                    "SAFETY-10 shadow mode is OFF. This controller is "
+                    "commanding the battery again, starting from the "
+                    "%+.0f W that was standing on the wire.", shadow.WIRE_W)
+        if not engaged:
+            self.shadow_would_w = None
+            self.shadow_sized_from_meter = False
+            self._shadow_winner = None
+            return
+        self.shadow_would_w = float(resolution.target_w)
+        # SAFETY-47. ⚠️ NO LOGIC HERE, DELIBERATELY. All three rungs - the
+        # arbiter's winner, the leg being a CHARGE, and the headroom having
+        # been MEASURED - live inside `arbitrage.sized_from_meter()`, which
+        # says why, including why it is NOT keyed on whether the trade was
+        # capped. A rung written at a call site is a rung no check can reach
+        # with the other two clear, which is TEST-16's rule.
+        self.shadow_sized_from_meter = arbitrage.sized_from_meter(
+            self.arb, self.arb_headroom_w, winner=resolution.winner)
+        # ⚠️ THE WINNER AND THE ROUNDED WATTS, NOT THE WATTS ALONE. A decision
+        # that moves from the loop to the peak guard at the same number is a
+        # different decision and the operator needs the line; a loop target
+        # that wanders by a watt is not, and 15 s of those would be the whole
+        # log.
+        # ⚠️ SAFETY-47 ADDS THE CAVEAT FLAG TO THE EDGE. The same winner at the
+        # same watts with and without the caveat are two different claims about
+        # the same number, and an edge key blind to that would print the first
+        # one and silently keep it standing. It cannot flood: the flag only
+        # moves when arbitrage starts or stops owning the resolution, or when
+        # the guard starts or stops measuring the quarter, and both of those
+        # move the winner or the watts as well on every cycle measured.
+        edge = (resolution.winner, round(float(resolution.target_w)),
+                self.shadow_sized_from_meter)
+        if edge != self._shadow_winner:
+            self._shadow_winner = edge
+            self.log_event(shadow.log_line(
+                would_w=resolution.target_w, reason=resolution.explain(),
+                sized_from_meter=self.shadow_sized_from_meter))
+        self.target = shadow.WIRE_W
+        for inv in self.inverters:
+            inv.target = shadow.WIRE_W
+
     async def check_output_clamp(self) -> None:
         """SAFETY-03. Alarm whenever a clamp actually engaged this cycle.
 
@@ -4000,6 +4331,14 @@ class Controller:
                        or (self.site_sign_wd.tripped
                            and len(self.inverters) > 1)
                        or self.circ_wd.tripped
+                       # SAFETY-10: "shadow" is its own value and not a
+                       # flavour of "stopped". A fleet dashboard reporting a
+                       # shadow install as `running` would be calling a
+                       # battery nobody is controlling healthy; one reporting
+                       # it as `stopped` would lose the fact that the decision
+                       # path is live and being recorded. ⚠️ BELOW `failsafe`:
+                       # a latch that is up is up, and shadow does not clear it.
+                       else "shadow" if self.shadow
                        else "running" if self.auto else "stopped"),
             # SAFETY-31. ⚠️ MEASURED, not the allocation record - see
             # `site_circulating_w`. `publish()` drops None values, so a cycle
@@ -4007,6 +4346,14 @@ class Controller:
             # rather than publishing a zero that would read as health.
             "circulation": (None if self.site_circulating_w is None
                             else round(self.site_circulating_w)),
+            # TEL-10. The loop's own three, written from the fields `cycle()`
+            # recorded and not re-derived here - the page and the publisher run
+            # on their own tasks and `self.target` has moved on by the time
+            # either of them looks (SAFETY-47's note on `sized_from_meter`, one
+            # field up, is the same hazard).
+            "loop_i": round(self.loop_i_w, 1),
+            "loop_lead": round(self.loop_i_lead, 1),
+            "loop_reason": self.loop_reason,
         }
         # ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input
         # watchdog subscribes to sensor.goodwe_p1_sample_age - see the entity-id
@@ -4500,7 +4847,24 @@ class Controller:
     def status_payload(self) -> dict:
         checks = self.checks()
         bad = [c for c in checks if not c["ok"] and not c["warn"]]
-        if self.circ_wd.tripped:
+        # --- SAFETY-10, AND IT IS FIRST IN THE CASCADE -----------------------
+        # "The battery is NOT being controlled" is the one sentence on this
+        # page that may never be displaced by another condition. A banner that
+        # can be out-ranked does not STATE a thing plainly; it states it
+        # whenever nothing else is happening, which is the half of the time
+        # nobody needs telling.
+        #
+        # ⚠️ AND IT CARRIES A STANDING LATCH RATHER THAN HIDING ONE. The three
+        # `bad` branches below all say some version of "held at 0 W", which is
+        # still true in shadow mode - but an operator who turns shadow mode off
+        # with a latch up gets a battery that will not move and a page that
+        # never mentioned it. `shadow.banner()` names the latch and goes red
+        # for it, so nothing this cascade would have said is lost.
+        _shadow = shadow.banner(self.o, control_started=self.auto,
+                                latched=self.shadow_latches())
+        if _shadow is not None:
+            level, banner = _shadow
+        elif self.circ_wd.tripped:
             # ⚠️ ABOVE THE SIGN FAILSAFE, and the order is a decision. Both are
             # latched P_SAFETY stops, so the site is at 0 W either way and the
             # banner can only carry one sentence. This one goes first because it
@@ -4600,6 +4964,21 @@ class Controller:
             ("State of charge", "—" if self.pack_floor_soc is None
              else f"{self.pack_floor_soc:g} %"),
             ("Commanded", w(self.target)),
+            # SAFETY-10, and it sits BETWEEN the two rows it reconciles.
+            # "Commanded 0 W" above and a "Why" below that explains a trade is
+            # the exact pair an operator would otherwise have to guess at; this
+            # row is what makes the two of them consistent, and it is rendered
+            # in EVERY state - including `off`, where it says the battery IS
+            # being controlled - because a surface whose ABSENCE is how you
+            # learn something is a surface you have to already know about.
+            ("Shadow mode", shadow.words(
+                self.o, control_started=self.auto,
+                would_w=self.shadow_would_w,
+                # SAFETY-47. THE FLAG THE CYCLE RECORDED, NOT ONE DERIVED HERE
+                # - the page runs on its own task and `self.peak_guard` has
+                # moved on. See `Controller.__init__`.
+                sized_from_meter=self.shadow_sized_from_meter,
+                reason=self.reason)),
             ("Why", self.reason),
             ("Maintenance phase", self.maint.phase if len(self.inverters) <= 1
              else f"{self.maint.phase} ({self.maint_unit.name})"),

goodwe_controller/app/mqtt.py

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

goodwe_controller/app/peakguard.py

@@ -822,6 +822,145 @@ def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
                f"only give {ceil_top:.0f} W" if saturated else "")))
 
 
+def charge_headroom_w(decision) -> float | None:
+    """SAFETY-45. The hardest this SITE may charge without putting the billed
+    quarter over the ceiling, in W, positive - or None when nothing measured it.
+
+    THE ONE PLACE THIS QUESTION IS ANSWERED, and it is public for the reason
+    `discharge_permitted()`, `shaping_suspended()`, `guard_state()` and
+    `looks_frozen()` are: the check that grades it has to assert on THE SHIPPED
+    EXPRESSION, and a predicate transcribed into its own test is one copy plus a
+    future disagreement about what the check means.
+
+    ------------------------------------------------------------------------
+    THE DEFECT IT PREVENTS, AND IT IS NOT A NEW IDEA IN THIS REPOSITORY
+
+    `control.maintenance_charge_floor()` already caps MAINTENANCE charging at
+    "the headroom left under the site's cap", and its docstring says why in
+    words this card only has to widen:
+
+        "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. Measured on TEST-23 stage 3's closed rig at the shipped
+    `peak_cap_w: 3500` / `max_w: 2000`: 28 charge onsets in one hour, mean period
+    131 s, grid swinging -456 <-> +3200 W, on any house drawing over 1500 W in
+    the cheapest quarter. §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."
+
+    ⚠️ AND IT IS THE **MEASURED** GUARD, NOT `peak_forecast_entity`.
+    `maintenance_charge_floor()` sizes itself from the forecast sensor, which is
+    OPTIONAL and empty on a default install - the exact hole SAFETY-25 had to
+    close in `shaping_suspended()`, where a suspension gated on the forecast
+    alone could not fire on the very site that needed it. This number comes off
+    `decide()`, which runs wherever P1 does.
+
+    ------------------------------------------------------------------------
+    WHERE THE NUMBER COMES FROM: IT IS `wanted_w`, READ IN THE OTHER DIRECTION
+
+    `decide()` already computes
+
+        wanted = batt_w + excess = (the offtake there would be with the battery
+                 at zero) - (the level this quarter can still afford)
+
+    as the battery DISCHARGE that would land the quarter exactly on the ceiling.
+    A negative `wanted` is not "nothing to say" - it is a permitted CHARGE of
+    `-wanted` watts, and throwing it away is SAFETY-45's whole defect. So this
+    function invents no arithmetic; it reads the sign the guard already had.
+
+    ⚠️ AND THE QUANTITY IS INVARIANT IN THE BATTERY, WHICH IS WHY SIZING A TRADE
+    TO IT CANNOT OSCILLATE. 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. It is a FEED-FORWARD number - a function of the house, the ceiling and
+    the seconds already banked - so consuming it adds no feedback path around the
+    plant. The fixed point is `charge = ceiling - load`, with the meter sitting
+    ON the ceiling and `wanted` parked at `load - ceiling`, a whole `ceiling -
+    load` clear of the engagement boundary rather than chattering across it.
+
+    ⚠️ AND A QUARTER BOUNDARY DOES NOT HAND IT BACK AT FULL POWER, WHICH IS THE
+    OTHER HALF OF SAFETY-45 AND IS NOT THE SAME CLAIM AS "IT DOES NOT CHANGE".
+    It DOES change - it is `(900 / remaining) * (ceiling - projected)`, so it is
+    largest in the last seconds of a block and collapses at the boundary. What
+    matters is WHAT IT COLLAPSES TO: at `elapsed = 0` the projection IS the held
+    level, so the answer is `ceiling - (load - pv)` - the house and the cap, and
+    nothing else. A trade refused at 14:59 therefore resumes at 15:00 at the rate
+    the new quarter can afford, not at `max_w`, and §10.1's answer survives the
+    boundary because the arithmetic does: no timer, no backoff constant, no state
+    carried between calls.
+
+    ⚠️ AND THE AMPLIFICATION IS BOUNDED IN ITS EFFECT, NOT MERELY LARGE. Hold a
+    charge of exactly this size for the rest of the block and the block's average
+    lands on `ceiling` EXACTLY, wherever in the block it started:
+
+        (acc + (held + headroom) * remaining) / 900
+            = projected + (900/remaining) * (ceiling - projected) * remaining/900
+            = ceiling
+
+    so 162 kW of headroom with 5 s left and 900 W of it with the whole quarter to
+    go are the same statement about the bill. `test_peakguard.py` part 13 sweeps
+    that identity across the block rather than arguing it here.
+
+    ------------------------------------------------------------------------
+    THE THREE ANSWERS
+
+    `None`  nothing measured it: the guard never ran (`meter_source: off`), or
+            it ran with no battery reading to size a floor from, or the block
+            had no seconds left to influence. ⚠️ None IS NOT UNLIMITED. A caller
+            that treats it as "charge away" is `arbitrage.guard_state()`'s
+            collapse of None into False, one layer down - a strategy creating
+            the billed quantity while nothing measures the quarter it lands in.
+    `0.0`   measured, and the answer is no charging: the guard is BLIND (its
+            claim already says so at `floor 0 W` and this agrees with it rather
+            than restating it), or it is holding and `wanted >= 0`.
+    `> 0`   the watts a charge may pull this cycle.
+
+    ⚠️ HOLDING IMPLIES ZERO, BY CONSTRUCTION AND NOT BY COINCIDENCE. Every state
+    that files a claim with `engaged=True` has `wanted > 0`, `wanted is None` or
+    `blind`, so this answers 0.0 or None there and can never hand a strategy
+    permission the guard's own `lo` is at that instant refusing.
+
+    ------------------------------------------------------------------------
+    ⚠️ WHY THIS IS A SIZING AND NOT A CLAIM, AND DO NOT "SIMPLIFY" IT INTO ONE
+
+    The obvious tidier answer is to delete `decide()`'s `wanted <= 0` gate and
+    let it file `lo = wanted` unconditionally - a NEGATIVE floor, meaning "you
+    may charge, but no harder than this". The arithmetic is identical, it is
+    continuous, and it would bind every claimant rather than only arbitrage. It
+    was measured, considered and REJECTED, and the reason is not style:
+
+      * `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`: a CONTRADICTION, which resolves to 0 W - the battery PARKED,
+        in the one quarter of the month that sets the bill. That is the exact
+        failure `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 suspends the maintenance charge-only
+        shaping PERMANENTLY.
+      * and it would change what `engaged` MEANS 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 reads it as "the guard is HOLDING".
+
+    `control.maintenance_charge_floor()` is a sizing and not a limit for the same
+    reason, which is why this is the shape that already fits.
+    DECISIONS/SAFETY-45-sizing-the-trade.md §2b carries the full argument.
+    """
+    if decision is None:
+        return None
+    if decision.blind:
+        return 0.0
+    if decision.wanted_w is None:
+        return None
+    return max(0.0, -float(decision.wanted_w))
+
+
 def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
     """Must the maintenance charge-only shaping stand down this cycle?
 

goodwe_controller/app/price.py

@@ -151,8 +151,8 @@ from textwrap import dedent
 from urllib.parse import urlencode
 
 from .custom_formula import (
-    FormulaInvalid, PREVIEW_HOURS, parse_price_formula, preview_lines,
-    price_eur_kwh, to_resolution)
+    EXPORT_FORMULA_OPTION, FormulaInvalid, PREVIEW_HOURS, parse_export_formula,
+    parse_price_formula, preview_lines, price_eur_kwh, to_resolution)
 
 _LOG = logging.getLogger("goodwe.price")
 
@@ -818,6 +818,69 @@ def plan_is_provisional(read: PriceRead) -> bool:
 # Options: what a plugin may see, and what it may not
 # --------------------------------------------------------------------------- #
 
+# --------------------------------------------------------------------------- #
+# TARIFF-18: what `price_taxes_eur_kwh` IS MADE OF
+# --------------------------------------------------------------------------- #
+
+# ⚠️ THE DEFECT THIS TABLE PREVENTS IS THE ONE THE SHIPPED 0.06 WAS: A NUMBER
+# NOBODY COULD SOURCE. 0.06 EUR/kWh is roughly HALF the real Flemish non-energy
+# figure, and because no reader could see what it was made of there was nothing
+# to argue with. Every row below is one line of the Eneco residential card for
+# Flanders, September 2026, INCLUDING 6 % VAT, converted from the c EUR/kWh the
+# card prints to the EUR/kWh this option takes. `price_taxes_eur_kwh`'s default
+# is their sum, and test_price.py section 1b re-adds them and refuses a default
+# that is not exactly that.
+#
+# ⚠️ THIS IS A PER-DSO FIGURE, AND IT IS THE DISTRIBUTION ROW THAT MOVES. Across
+# the eight Fluvius DSOs that row runs 5,28 c EUR/kWh (Midden-Vlaanderen) to
+# 6,70 (West), so the all-in Flemish total runs about 0.117 to 0.131 EUR/kWh.
+# A site outside Antwerpen should type its own total; the other two rows are
+# Flanders-wide and do not move with the DSO.
+#
+# ⚠️ AND THE DEFAULT SITS NEAR THE LOW END OF THAT BAND ON PURPOSE, BECAUSE THE
+# TWO ERROR DIRECTIONS ARE NOT SYMMETRIC. This scalar is a LEVEL component: it
+# cancels exactly in `max - min` and cannot move which hour is cheapest
+# (test_price.py 16b measures that as a family). The one DECISION it reaches is
+# §17's negative-price guard in arbitrage.py, which tests the ABSOLUTE all-in
+# price of the sell hour. A figure set too HIGH carries a genuinely negative
+# hour up above zero, and the add-on exports into paid-for disposal - the exact
+# case §17 exists to refuse. A figure set too LOW only declines a trade that
+# would have paid. So where a default must stand in for eight different DSOs,
+# it belongs at the bottom of the band and not in the middle of it.
+#
+# ⚠️ `energiebijdrage` IS ZERO, AND IT IS A ROW HERE RATHER THAN AN ABSENCE.
+# "Vanaf 1 augustus 2026 bedraagt de energiebijdrage 0 EUR/MWh" - it was merged
+# into the bijzondere accijns. Anyone re-deriving this total from a guide
+# written before that date will find a separate energiebijdrage line and add it
+# on top of an accijns that already contains it. The zero row is here so that
+# the double-count is visible as a decision rather than as an omission.
+FLEMISH_TAXES_COMPONENTS_EUR_KWH = (
+    ("Fluvius distribution, Antwerpen", 0.0535),
+    ("Bijzondere accijns, 'Alle verbruik' - no volume bands", 0.04876),
+    ("Bijdrage groene stroom en WKK Vlaanderen", 0.0151),
+    ("Energiebijdrage - 0 EUR/MWh since 2026-08-01, inside the accijns", 0.0),
+)
+
+# ⚠️ TARIFF-18, AND IT IS NOT HOUSEKEEPING - IT DECIDES WHICH CONFIGS START.
+# TARIFF-17's rung in validate.py refuses a site that sets `price_taxes_profile`
+# AND leaves `price_taxes_eur_kwh` at something other than the shipped default,
+# because the table wins and the scalar would decide nothing. It compares
+# against the DEFAULT rather than against presence, because the Supervisor sets
+# `App.options = deepmerge(config.yaml defaults, stored options)` and a saved
+# blob therefore carries every schema key whether the operator typed it or not
+# (measured: the reference install's export is 70 of 71 keys - CHANGELOG 0.9.0,
+# `tools/supervisor_selfapi_probe.py` §D).
+#
+# So moving the default turns a previously ACCEPTED configuration into
+# `SystemExit(78)`. A site that stored 0.06 - which is every install that has
+# ever saved its configuration - and that also carries a taxes table would stop
+# starting on the upgrade, over a number it never typed and that decides
+# nothing. That refusal would be TRUE and USELESS: the rung's subject is a
+# number the OPERATOR typed, and a superseded shipped default is not one. It
+# still reads as "untouched" here, and the rung's sentence names both figures.
+SUPERSEDED_TAXES_DEFAULTS_EUR_KWH = (0.06,)     # TARIFF-02 .. TARIFF-17
+
+
 # ⚠️ CFG-03, AND HOW THIS TICKET AVOIDS WIDENING IT. Option defaults in this
 # add-on already live in three places - config.yaml, main.py's `o.get(k, X)`
 # fallbacks, and a dataclass default - held apart only by a tripwire in
@@ -836,7 +899,9 @@ def plan_is_provisional(read: PriceRead) -> bool:
 PRICE_OPTION_DEFAULTS = {
     "price_provider": "off",
     "price_markup_eur_kwh": 0.03,      # §14 tariffs.energy_price.markup_eur_kwh
-    "price_taxes_eur_kwh": 0.06,       # §14 tariffs.energy_price.taxes_eur_kwh
+    # TARIFF-18: the sum of FLEMISH_TAXES_COMPONENTS_EUR_KWH above, to the
+    # card's own last digit. §14 tariffs.energy_price.taxes_eur_kwh.
+    "price_taxes_eur_kwh": 0.11736,
     "export_price_eur_kwh": 0.04,      # §14 tariffs.export_price_eur_kwh (AC4)
     "price_csv_path": "/share/goodwe_prices.csv",
     "price_feed_url": "",
@@ -851,6 +916,18 @@ PRICE_OPTION_DEFAULTS = {
     # test_price.py section 1. A second defaults dict in the new module would be
     # a fourth place option defaults live, which is exactly the open ticket.
     "static_profile": "",
+    # TARIFF-17. A JSON object in `static_profile`'s OWN period grammar whose
+    # per-period `eur_per_kwh` is the TAXES COMPONENT for that band, not an
+    # all-in price; "" is unset and the scalar above decides. Parsed and
+    # validated by app/static_tariff.py (`parse_taxes_profile`), refused at
+    # startup by validate.py - the `static_profile` precedent exactly, and here
+    # for the same CFG-03 reason: this dict is the ONE in-code mirror of
+    # config.yaml.
+    #
+    # ⚠️ IT IS IN FRAMEWORK_KEYS. A plugin that could read this could add the
+    # taxes a second time, per hour, which is the double-counting defect trap 1
+    # exists to refuse - wearing a period table instead of a scalar.
+    "price_taxes_profile": "",
     # TARIFF-15. A JSON object carrying ONE contract's two coefficients, the
     # units they are printed in, its VAT rate and the card figures the add-on
     # grades them against; "" is unset. Parsed and validated by
@@ -858,6 +935,20 @@ PRICE_OPTION_DEFAULTS = {
     # `static_profile` precedent exactly, and here for the same CFG-03 reason:
     # this dict is the ONE in-code mirror of config.yaml.
     "price_formula": "",
+    # TARIFF-16. The INJECTION leg, in `price_formula`'s OWN grammar and read
+    # by `custom_formula.parse_export_formula()` - the same parser with its
+    # option name as an argument, so a second unit table and a second unknown-
+    # key rule do not exist to diverge. "" is unset and the scalar
+    # `export_price_eur_kwh` above decides, which is every site today.
+    #
+    # ⚠️ IT IS IN FRAMEWORK_KEYS, for the reason the scalar is: a CONSUMPTION
+    # plugin that could read an injection curve could fold it into a
+    # consumption price, and nothing downstream could tell.
+    #
+    # ⚠️ AND IT LIVES HERE RATHER THAN IN custom_formula.py FOR CFG-03's SAKE,
+    # exactly as `price_formula` and `price_taxes_profile` do: this dict is the
+    # ONE in-code mirror of config.yaml.
+    "price_export_formula": "",
     # OPT-04. §10.1 priority 3, and §14's `optimizer.cycle_cost_threshold_eur`.
     #
     # ⚠️ THEY LIVE HERE FOR CFG-03's SAKE, exactly as `static_profile` does, and
@@ -884,6 +975,19 @@ PRICE_OPTION_DEFAULTS = {
 # that can double-count, so `PluginOptions` refuses them by name. Trap 1.
 FRAMEWORK_KEYS = frozenset({
     "price_markup_eur_kwh", "price_taxes_eur_kwh", "export_price_eur_kwh",
+    # TARIFF-17. The hour-varying spelling of `price_taxes_eur_kwh`, and it
+    # belongs here for the same reason the scalar does: it is a component the
+    # FRAMEWORK adds exactly once, by `caps.adds`. `BANNED_IN_PLUGIN_CODE` is
+    # derived from this set, so `code_leaks()` refuses a plugin that names it
+    # without anything else being edited.
+    "price_taxes_profile",
+    # TARIFF-16. The hour-varying spelling of `export_price_eur_kwh`, and it
+    # belongs here for the same reason the scalar does: a plugin that could
+    # read an INJECTION curve could fold it into the CONSUMPTION series it
+    # emits, and `assemble()` has no way to notice a component that arrived
+    # inside a RawPoint. `BANNED_IN_PLUGIN_CODE` is derived from this set, so
+    # `code_leaks()` refuses a plugin that names it with nothing else edited.
+    EXPORT_FORMULA_OPTION,
 })
 
 
@@ -997,28 +1101,103 @@ def export_price_eur_kwh(opts: dict) -> float:
     consumption is at 6% - so it is a second per-contract formula, not a second
     copy of the first.
 
-    ⚠️ TARIFF-15 LANDED THE EVALUATOR AND DID NOT LAND THIS CURVE, and the
-    difference is the point rather than an omission. `custom_formula` can now
-    express `B x index + A` exactly - it is what it exists for - but it is a
-    CONSUMPTION provider: it declares {ENERGY, MARKUP}, the framework adds the
-    consumption taxes, and an injection leg carries its OWN coefficients
-    (Eneco: 0,102 consumption against 0,100 injection) and its own VAT
-    treatment (injection is exempt; consumption is at 6%). Pointing this
-    scalar at that machinery would mean pricing an injection curve with a
-    consumption card, which is the wrong-card defect the card self-check
-    exists to refuse. So until the injection card lands this scalar remains a
-    SIMPLIFICATION an operator enters by hand - an average of what they are
-    actually paid - and not a reflection of the market. 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.
+    ⚠️ TARIFF-16 LANDED THE INJECTION LEG, AND THIS FUNCTION IS UNCHANGED. The
+    curve lives in `price_export_formula` and is read by `export_formula()`
+    below; this reader still answers the FLAT injection price, still from one
+    option, still with no formula anywhere in its arithmetic. That is the
+    arrangement this docstring predicted before either existed - "an injection
+    curve gets a `PriceProvider` of its own and this scalar becomes its
+    FIXED-product default" - and it is why a site with a flat injection price
+    sees nothing change: `price_export_formula` ships "", `export_price_at()`
+    falls through to this function, and this function's body is byte-identical
+    to the one TARIFF-02 shipped.
 
     ⚠️ It is NOT reachable from a plugin: `export_price_eur_kwh` is in
     FRAMEWORK_KEYS, so a consumption plugin cannot quietly fold an injection
-    price into a consumption price.
+    price into a consumption price. `price_export_formula` is in the same set
+    for the same reason.
+
+    ⚠️ AND NOTHING IN THIS ADD-ON READS EITHER ONE TO TAKE A DECISION.
+    `arbitrage.py` prices the sell side as DISPLACED IMPORT and says so in its
+    own comment; both hours it compares are all-in consumption prices. This
+    reader has no caller under `app/` and neither does `export_price_at()`.
+    They are what an operator is shown and what a future export-aware strategy
+    would call - not a number any trade turns on today.
     """
     return float(price_option(opts, "export_price_eur_kwh"))
 
 
+def export_formula(opts: dict):
+    """The configured `price_export_formula` as a `FormulaSpec`, or None.
+
+    TARIFF-16. Raises `custom_formula.FormulaInvalid` on a malformed leg - and
+    ⚠️ THAT EXCEPTION IS NOT MEANT TO REACH A RUNNING SITE, by the rule
+    `taxes_profile()` states above and `static_profile` established:
+    validate.py parses the same option at STARTUP and refuses to start on it,
+    because a formula that only fails when something reads it is a defect
+    discovered at the worst possible moment and §11.4 makes every price
+    defect quiet.
+
+    ⚠️ THE PARSE IS THE SAME ONE THE CONSUMPTION LEG GETS. There is no second
+    parser, no second unit table and no second resolution rule -
+    `parse_export_formula()` is `parse_price_formula()` with its `option`
+    argument moved, so every refusal an operator can hit on this leg is a
+    refusal that already had checks over it.
+    """
+    return parse_export_formula(price_option(opts, EXPORT_FORMULA_OPTION))
+
+
+def export_price_at(opts: dict, index_eur_per_mwh: float) -> float:
+    """What the site is PAID for one exported kWh at one index value, EUR/kWh.
+
+    THE SEAM, AND ITS HONEST SCOPE. This is the one function a future
+    export-aware strategy calls, and it has NO CALLER UNDER `app/` today -
+    stated here rather than implied, because the add-on takes no decision on an
+    injection price (see `export_price_eur_kwh()` above and `arbitrage.py`'s
+    accounting-basis comment). What it buys now is that OPT-06 and anything
+    after it inherit a shape the market fits, instead of a scalar that cannot
+    hold its own factor, a negative offset, or a VAT rate different from the
+    consumption leg's.
+
+    ⚠️ THE FLAT PATH IS THE FALLTHROUGH AND IT IGNORES THE INDEX, which is
+    CORRECT rather than a simplification: a site with a flat injection price is
+    paid the same for every kWh whatever the market did, and that is what the
+    scalar means. With `price_export_formula` empty - every site today - this
+    returns exactly `export_price_eur_kwh(opts)` for every index.
+
+    ⚠️ A NEGATIVE ANSWER IS A REAL ANSWER. Eneco's `0,1 x BELPEX-H - 1,188` is
+    below zero for any BELPEX-H under 11,88 EUR/MWh, which is the middle of a
+    sunny day and precisely when a PV household exports. Nothing here floors
+    it: a caller that silently clamped it to zero would hide the hours in which
+    exporting COSTS money, which is the one thing an injection price is for.
+    """
+    spec = export_formula(opts)
+    if spec is None:
+        return export_price_eur_kwh(opts)
+    return price_eur_kwh(spec, index_eur_per_mwh)
+
+
+def taxes_profile(opts: dict):
+    """The configured `price_taxes_profile` as a period table, or None.
+
+    TARIFF-17. Raises `static_tariff.ProfileInvalid` on a malformed table - and
+    ⚠️ THAT EXCEPTION IS NOT MEANT TO REACH A RUNNING SITE. validate.py parses
+    the same option at STARTUP and refuses to start on it, for the reason
+    `static_profile` is refused there: a table that only fails when a fetch
+    happens is a site that stops pricing at 03:00, and §11.4 turns that into a
+    quiet fallback nothing on the status page distinguishes from a healthy
+    fixed-tariff day. `load_prices()` still handles it, loudly, because a guard
+    whose only proof is "the other guard ran first" is not a guard.
+
+    ⚠️ THE IMPORT IS LAZY AND THE CYCLE IS THE REASON. `static_tariff.py`
+    imports this module at module scope; importing it back at module scope here
+    would make which file is imported first decide whether the add-on starts.
+    `sys.modules` makes the repeat cost a dict lookup.
+    """
+    from .static_tariff import parse_taxes_profile
+    return parse_taxes_profile(price_option(opts, "price_taxes_profile"))
+
+
 # --------------------------------------------------------------------------- #
 # The plugin interface
 # --------------------------------------------------------------------------- #
@@ -1286,23 +1465,68 @@ def _validate_raw(points, caps):
         seen = u
 
 
+def taxes_at(taxes, instant: datetime) -> float:
+    """The TAXES component at ONE instant. A scalar, or a period table.
+
+    TARIFF-17. THE DEFECT THIS EXISTS TO CLOSE, and it is a MISSING CAPABILITY
+    rather than a wrong constant: `price_taxes_eur_kwh` is additive and
+    identical every hour, so it cancels exactly out of `max - min` and cannot
+    move `min(firm, key=...)`. It is not a distortion - it is provably inert on
+    both quantities the optimiser reads. What was missing is anywhere for an
+    HOUR-VARYING non-energy component to live, and the Walloon and Brussels
+    DSOs bill one: ORES `dag 13,27 / nacht 7,39` c EUR/kWh, a 5,88 c gap whose
+    cheap band coincides with the cheap spot hours. Flattening it does not
+    shift the curve, it UNDERSTATES the spread and declines profitable cycles.
+    See DOCS.md "The three buckets".
+
+    ⚠️ DUCK-TYPED ON `price_at`, NOT ON `isinstance`. price.py must not import
+    static_tariff.py - static_tariff.py imports THIS module, and a module-level
+    cycle would make the import order load-bearing. `taxes_profile()` below is
+    the one place the real parser is reached, and it imports it lazily.
+
+    ⚠️ THE LOOKUP IS ON THE ~30 s PLANNING PATH through `assemble()`, so it
+    stays a linear scan over the two-to-four periods a Belgian tariff has
+    (`StaticProfile.at()`), with no parsing, no allocation and no I/O. A
+    malformed table never reaches here: validate.py refuses it at STARTUP.
+    """
+    at = getattr(taxes, "price_at", None)
+    if at is None:
+        return float(taxes)
+    return float(at(instant))
+
+
 def assemble(caps: ProviderCapabilities, raw, markup: float,
-             taxes: float) -> list:
+             taxes) -> list:
     """RawPoints -> canonical all-in PricePoints. THE ONLY PLACE MARKUP IS ADDED.
 
     Adds exactly `caps.adds` - the complement of what the plugin declared its
     source already contains. A plugin that publishes an all-in figure gets
     nothing added; a raw EPEX figure gets both.
+
+    ⚠️ `taxes` IS A SCALAR *OR* A PERIOD TABLE (TARIFF-17), AND IT IS EVALUATED
+    AT EACH POINT'S OWN INSTANT. Hoisting the lookup out of the loop - reading
+    it once and adding the same number to every point - is the mutation that
+    collapses the whole feature back into the LEVEL bucket: the assembled
+    series would still differ from the untaxed one by the right MAGNITUDE, and
+    the cheapest hour would be wrong. `test_price.py` section 24 is the check
+    that goes red for it, and it grades WHICH HOUR IS CHEAPEST rather than the
+    spread, because a spread-magnitude assertion passes on the hoisted version.
+
+    ⚠️ THE SCALAR PATH IS UNCHANGED, ARITHMETICALLY AND NOT ONLY IN INTENT.
+    `taxes_at()` on a float returns that float at every instant, and
+    `0.0 + markup` is exactly `markup` in IEEE 754 for every finite markup, so
+    a site on a scalar gets the identical bytes it got before this landed.
     """
-    add = 0.0
-    if Component.MARKUP in caps.adds:
-        add += float(markup)
-    if Component.TAXES in caps.adds:
-        add += float(taxes)
-    return [PricePoint(start=brussels(p.start),
-                       eur_per_kwh=round(p.eur_per_kwh + add, 6),
-                       provisional=bool(p.provisional))
-            for p in raw]
+    add_markup = float(markup) if Component.MARKUP in caps.adds else 0.0
+    wants_taxes = Component.TAXES in caps.adds
+    out = []
+    for p in raw:
+        local = brussels(p.start)
+        add = add_markup + (taxes_at(taxes, local) if wants_taxes else 0.0)
+        out.append(PricePoint(start=local,
+                              eur_per_kwh=round(p.eur_per_kwh + add, 6),
+                              provisional=bool(p.provisional)))
+    return out
 
 
 # --------------------------------------------------------------------------- #
@@ -1902,13 +2126,38 @@ async def load_prices(opts: dict, since: datetime, until: datetime,
 
     caps = cls.capabilities()
     markup = float(price_option(opts, "price_markup_eur_kwh"))
-    taxes = float(price_option(opts, "price_taxes_eur_kwh"))
+
+    # ⚠️ TARIFF-17: THE TABLE WINS OVER THE SCALAR, AND validate.py REFUSES THE
+    # CASE WHERE BOTH SAY SOMETHING. Two writers of one quantity, one of which
+    # silently loses, is the shape validate.py exists to refuse - so the
+    # precedence here is only ever exercised on a configuration that has
+    # already been accepted, and it is spelled out rather than left implicit.
+    taxes_key = "price_taxes_eur_kwh"
+    try:
+        table = taxes_profile(opts)
+    except Exception as e:                                    # noqa: BLE001
+        # Not silent, and not a traceback into the 30 s tick. validate.py
+        # should have refused this at startup; if the add-on is running with it
+        # anyway, the operator is told which key and what is wrong with it.
+        _LOG.error("price_taxes_profile cannot be used (%s: %s), so this fetch "
+                   "has NO tax component to add - it is not falling back to "
+                   "price_taxes_eur_kwh, because a silently different tax "
+                   "basis is the defect this option exists to remove. Fix the "
+                   "table or clear it; validate.py refuses it at startup",
+                   type(e).__name__, e)
+        return PriceRead.no_data(
+            f"price_taxes_profile cannot be used: {e}")
+    if table is not None:
+        taxes = table
+        taxes_key = "price_taxes_profile"
+    else:
+        taxes = float(price_option(opts, "price_taxes_eur_kwh"))
 
     # ⚠️ Not a refusal, but not silent either. A plugin whose feed is already
     # all-in ignores these two numbers, and an operator who typed them has every
     # reason to believe they took effect.
     ignored = [n for c, n, v in ((Component.MARKUP, "price_markup_eur_kwh", markup),
-                                 (Component.TAXES, "price_taxes_eur_kwh", taxes))
+                                 (Component.TAXES, taxes_key, taxes))
                if c not in caps.adds and v]
     if ignored:
         _LOG.warning("%s publishes a figure that already contains %s, so the "

goodwe_controller/app/shadow.py

@@ -0,0 +1,518 @@
+"""SAFETY-10 - shadow mode: the whole decision path, and no command.
+
+WHAT DEFECT THIS PREVENTS
+=========================
+Not one defect - the CLASS of them. Every optimiser fault this repository has
+found was invisible from outside while it was happening, and each one was paid
+for at the meter before anybody could see it:
+
+  * SAFETY-45  arbitrage against a binding `peak_cap_w` ran 28 charge onsets an
+               hour, the grid swinging -455 .. +3200 W, and put a billed
+               quarter 59 W over the cap;
+  * TARIFF-14  the price lookup answered for the wrong quarter-hour 45 minutes
+               in every 60, and traded on it;
+  * SAFETY-46  the SoC ceiling churns 598 Wh to gain 310 Wh, no hysteresis.
+
+There was no way to WATCH what the optimiser would do without letting it do it.
+A commissioning engineer could arm arbitrage and find out, or not arm it and
+learn nothing. Shadow mode is the third option: strategies, arbiter, clamps and
+guards all run, the decision is recorded with its reason, and NOTHING THE
+CONTROLLER DECIDES REACHES THE INVERTER.
+
+⚠️ AND OF THOSE THREE, A SHADOW RUN CAN SHOW YOU EXACTLY ONE - SEE THE NEXT
+   SECTION. This header used to name SAFETY-45's limit cycle as the example
+   of what shadow mode surfaces. That was false, and SAFETY-47 measured it.
+
+⚠️ WHAT A SHADOW RUN CAN AND CANNOT SHOW  (SAFETY-47)
+=====================================================
+SHADOW MODE CANNOT SURFACE A CLOSED-LOOP DEFECT. Not badly, not partially -
+NOT AT ALL, and by the same construction that makes it safe. The actuator is
+held at WIRE_W and the carried command is re-seeded to WIRE_W, so every
+MEASURED input - the meter, the quarter accumulator behind it, the battery
+power, the state of charge - describes a plant that DID NOT RESPOND. A
+closed-loop defect is by definition one whose stimulus is the plant's response
+to the controller. No response, no stimulus, no defect to see.
+
+That is not a gap to be closed later. Feeding the guards a simulated plant
+instead is what SAFETY-10 §4 refuses for the sign watchdogs, for a reason that
+applies to all of this: a controller reacting to a plant that does not exist
+drifts further from reality every tick, and three cycles in its numbers
+describe nothing. THE CLOSED-LOOP ANSWER COMES FROM A CLOSED-LOOP RIG
+(TEST-23 stage 3) OR FROM A LIVE RUN. There is no third place.
+
+So, of the three defects above, measured on that rig at `peak_cap_w` 1500 /
+house 1200 / `max_w` 2000, one hour at a 5 s cycle:
+
+  * SAFETY-45's limit cycle    NOT VISIBLE. Live: 28 charge onsets, the grid
+                               swinging -455.5 .. +3200.0 W, the guard engaged
+                               on 410 of 720 cycles. Shadow, same hour, same
+                               code: 1 onset, the grid flat at the 1200 W
+                               house, the guard engaged on 0 of 720. Every
+                               term of `wanted = batt_w + excess` is measured.
+  * SAFETY-46's SoC churn      NOT VISIBLE. The SoC moves 0.000000000 pp in a
+                               shadow run, because it is the pack's integral of
+                               what the pack was commanded and the pack was
+                               commanded 0 W. No SoC limit can be REACHED in a
+                               shadow run; the ones already crossed when it
+                               started are reported, and that is all.
+  * TARIFF-14's wrong quarter  VISIBLE, and it is the one. The price lookup's
+                               inputs are the CLOCK and the PRICE SERIES, and
+                               neither is a function of what the battery did.
+                               Measured: which hour the strategy picked, its
+                               price and the spread it cleared are identical
+                               live and shadow on 720 of 720 charging cycles,
+                               AT A BINDING CAP.
+
+⚠️ THE EXEMPTION THAT USED TO BE HERE WAS TRUE UNTIL SAFETY-45 MERGED. This
+module, DOCS.md and DECISIONS/SAFETY-10-shadow-mode.md all said "the strategies
+are unaffected - they ask for a fixed power from inputs that do not depend on
+what the battery did". SAFETY-45 made the buy leg `min(asked, headroom)` with
+
+    headroom = (900 / remaining) x (ceiling - projected)
+
+and `projected` reads the OPEN QUARTER'S ACCUMULATOR - the meter - which is a
+function of what the battery did earlier in that same quarter. The strategy
+became closed-loop the day that landed. What survives of the exemption, and
+only this:
+
+    WHICH hour a strategy picks, and WHY, are unaffected.
+    HOW HARD it trades is not.
+
+⚠️ AND THE SIZE A SHADOW RUN RECORDS IS THE RIGHT ANSWER TO A QUESTION NOBODY
+   ASKED. `900/remaining` is correct arithmetic for a meter that is genuinely
+under the ceiling - and in shadow the meter genuinely IS under it, because the
+battery is not charging. So the number is not a bug; it is an answer computed
+for a plant that did not exist. Measured on the same rig, shipped code:
+
+    cap / house      live commanded      shadow recorded      over
+    1500 / 1200         -302.4 W            -2000.0 W         6.61x
+    3500 / 3000         -502.6 W            -2000.0 W         3.98x
+    3500 / 2000        -1502.6 W            -2000.0 W         1.33x
+    3500 / 1800        -1702.6 W            -2000.0 W         1.17x
+   15000 /  350        -2000.0 W            -2000.0 W         1.00x
+
+The last row is the fixture SAFETY-10's own evidence was taken on, which is why
+nothing reported this. `words()` carries the caveat rather than a re-computed
+number, and `DECISIONS/SAFETY-47-what-a-shadow-run-can-show.md` §3 records the
+three alternatives that were rejected and why.
+
+⚠️ "REACHES NOTHING" IS NOT "WRITES NOTHING", AND THE DIFFERENCE IS THE WHOLE
+   SAFETY ARGUMENT
+=======================================================================
+The inverter holds its last command FOREVER - it has no meter timeout
+(HANDOVER.md §6), and firmware/goodwe-master.yaml's header records what that
+cost when a controller stopped refreshing: Illusmart went silent mid-command
+and the inverter held +5000 W for 113 s. main.py's own header carries the same
+measurement. So a shadow mode that
+simply stopped writing would leave whatever was standing when it was switched
+on standing for as long as it was left on. That is the exact failure this
+repository keeps finding - LOOKS HEALTHY BUT IS INERT - with the status page
+calmly reporting that nothing is being commanded.
+
+So shadow mode does write, and it writes ONE number:
+
+    the actuator is held at WIRE_W (0.0 W), refreshed on the ordinary
+    heartbeat, by the ordinary single writer.
+
+That is a DEFINED, SAFE actuator state, it is the same state the operator's
+stop button reaches, and it honours the contract firmware/goodwe-master.yaml
+§"CONTRACT CHANGE" imposes on us - HA must rewrite the setpoint every ~10 s or
+the ESP32's 30 s stale-input watchdog cannot tell "steady" from "dead". Going
+silent would put that board into a tripped-watchdog state for the whole shadow
+run, which is an ALARM being used as a MODE: the operator who learns that
+`wd_tripped` is normal during shadow runs is the operator who ignores it when
+the add-on has actually died.
+
+⚠️ AND IT IS NOT A SECOND WRITE PATH. 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 goes through - in exactly the
+form the three substitutions above it take (non-finite -> 0 W, unauthorised ->
+0 W, clamped -> the rating). It is the LAST of them, so SAFETY-28's
+authorisation gate and SAFETY-03's clamp still grade the number the decision
+path actually produced, and a shadow run therefore records that the clamp WOULD
+have engaged.
+
+THE DEFAULT, AND WHY IT IS NOT A PLAIN `true`  (§ the ticket's own warning)
+==========================================================================
+The card is titled "default-on". Taken literally - `shadow_mode: true` in
+`config.yaml`'s `options:` block - it is the worst change in this repository's
+history. Home Assistant's Supervisor composes an add-on's effective options as
+`{**config.yaml defaults, **the stored user options}`, so a NEW key with a new
+default reaches EVERY install on the next update, including the one regulating
+a real battery in the author's house today. Literal default-on silently stops
+an existing install from controlling, and the only symptom is a battery that
+has stopped doing anything.
+
+There is no mechanism in the add-on options system that lets one key default
+differently for a new install and an existing one: `options:` IS the default,
+and there is exactly one of it. So "default-on for new" has to be expressed as
+a value the add-on RESOLVES, not as a constant the Supervisor merges.
+
+Hence three values rather than two, defaulting to `auto`:
+
+    off    never shadow. The controller commands the battery.
+    on     always shadow, whatever the start/stop button says.
+    auto   shadow WHILE CONTROL IS STOPPED; live once it is started.
+
+`auto` is default-on for a new install and a no-op for an existing one, and it
+is that without any persisted marker, any migration, and any guess:
+
+  * a FRESH install ships `auto_start: false` and has no stored `auto` key, so
+    it comes up stopped -> shadow. It observes a day of decisions before it is
+    ever allowed to command anything. That is the card's intent, delivered.
+  * an install that is CONTROLLING - `auto_start: true`, or the operator has
+    pressed *Start / stop control* and the store carries `auto: true` - is
+    started, so `auto` resolves to LIVE and its behaviour does not change by
+    one watt.
+  * 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 - and gains
+    the recording. The only thing that changes for it is what the status page
+    and the action log SAY.
+
+⚠️ AND `auto` MEANS THE START BUTTON LEAVES SHADOW MODE. That is deliberate:
+under `auto` the button reads "Start / stop control" and pressing Start is the
+operator saying "control the battery". An operator who wants the decisions
+recorded WHILE the loop runs sets `shadow_mode: on` explicitly - that is the
+configuration this card exists to make possible, and it is the one that cannot
+be reached by accident.
+
+⚠️ AN UNRECOGNISED VALUE RESOLVES TO SHADOW, NOT TO LIVE. `validate.py` refuses
+it at startup so this is not meant to be reachable, but the fail-safe direction
+for "the operator's intent is unreadable" is the one that does not move energy.
+
+THE FAILSAFES, ONE BY ONE (the card asks for each to be decided and recorded)
+============================================================================
+| failsafe                       | in shadow mode                            |
+|--------------------------------|-------------------------------------------|
+| SAFETY-02/30 sign watchdogs    | INERT, and by construction rather than by |
+| (per-unit and site)            | a special case. They grade                |
+|                                | `Inverter.standing_w()` - what this       |
+|                                | controller has standing on the wire - and |
+|                                | shadow mode holds that at 0 W. A 0 W      |
+|                                | command cannot oppose a meter, so the     |
+|                                | detector never arms. ⚠️ THIS IS THE ONE   |
+|                                | THAT HAD TO BE GOT RIGHT: fed the SHADOW  |
+|                                | decision instead, every shadow run would  |
+|                                | latch a trip within `sign_disagree_s` -   |
+|                                | the decision opposes a meter that never   |
+|                                | saw it - and that latch SURVIVES INTO     |
+|                                | LIVE OPERATION and a restart. Shadow mode |
+|                                | would manufacture the failsafe it is      |
+|                                | meant to help debug.                      |
+| SAFETY-03 clamp                | OBSERVES. It runs on the number the       |
+|                                | decision path produced, `clamp_last` is   |
+|                                | set and every engagement goes to the      |
+|                                | action log, because "it would have hit    |
+|                                | the rating" is part of what a shadow run  |
+|                                | is for. It changes no command: the value  |
+|                                | it narrows is replaced by 0 W below it.   |
+| SAFETY-28 write authorisation  | OBSERVES, for the same reason and in the  |
+|                                | same place - above the substitution, so   |
+|                                | it still asks who chose the number.       |
+| SAFETY-18 meter freeze         | OBSERVES, unchanged. It takes no action   |
+|                                | in live operation either; it grades the   |
+|                                | resolved intent against a meter that has  |
+|                                | stopped moving, and both halves are as    |
+|                                | true in shadow as out of it.              |
+| SAFETY-07/24/25 peak guard     | OBSERVES, AND SEES ONLY THE HOUSE. It is  |
+|                                | level-triggered and unlatched and it files|
+|                                | its claim as usual, so the recorded       |
+|                                | decision is the real one FOR THIS METER - |
+|                                | but every term of `wanted = batt_w +      |
+|                                | excess` is measured, and in shadow mode   |
+|                                | the battery contributes nothing to either.|
+|                                | ⚠️ SAFETY-47: this row used to claim      |
+|                                | SAFETY-45's limit cycle was visible from a|
+|                                | shadow run. It is not - 410/720 engaged   |
+|                                | cycles live against 0/720 in shadow, on   |
+|                                | the same hour and the same code.          |
+| SAFETY-31 circulation          | OBSERVES AND MAY LATCH, legitimately. Its |
+| SAFETY-42 delivery             | evidence is MEASURED power, not a         |
+|                                | command: packs pushing against each other |
+|                                | while every one of them is told 0 W is a  |
+|                                | real fault and a latch is the right       |
+|                                | answer to it.                             |
+| operator stop (`auto` False)   | SUPPRESSED AS A CLAIM, ENFORCED AT THE    |
+|                                | WIRE. It is the one deliberate change.    |
+|                                | Its `P_SAFETY` 0 W claim out-ranks        |
+|                                | everything, so leaving it in would make   |
+|                                | the recorded decision "stopped" on every  |
+|                                | cycle - the shadow run would answer the   |
+|                                | wrong question. The actuator state is     |
+|                                | identical either way, and the wire        |
+|                                | substitution is STRICTLY STRONGER than    |
+|                                | the claim: a claim can be out-ranked, and |
+|                                | this cannot.                              |
+| inputs missing, non-finite,    | UNCHANGED. All of them resolve to 0 W,    |
+| allocator refusal, arbiter     | which is what the wire gets in shadow     |
+| contradiction                  | mode anyway, so they act redundantly and  |
+|                                | are recorded as they always were.         |
+
+⚠️ MAINTENANCE IS NOT IN THAT TABLE BECAUSE SHADOW MODE DOES NOT TOUCH IT. The
+state machines are ticked on every cycle today 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; it is a pre-existing
+property of `auto_start: false` and it is recorded here rather than quietly
+fixed under another card's name.
+
+LEAVING SHADOW MODE
+===================
+`Controller.cycle()` re-seeds its 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. Two things follow, and both are safety properties:
+
+  * the loop's `prev_w` and its integrator track WHAT IS ACTUALLY STANDING ON
+    THE WIRE, so every shadow cycle answers "from where the plant really is,
+    what would this controller do NOW" - a true statement about the present,
+    rather than a simulation of a counterfactual plant that drifts further from
+    reality every tick;
+  * the exit is safe BY CONSTRUCTION. The carried command already equals the
+    standing command, so the first live cycle slews from 0 W like any other
+    cycle. Carrying the shadow decision instead would let the slew limiter
+    depart from a base that never existed - up to a full `slew_w` step onto a
+    battery sitting at zero.
+
+The entry is safe for the ordinary reason: the substitution happens on the very
+first write of the very first shadow cycle, and `last_write` was not 0 W, so
+that write is issued rather than skipped as unchanged.
+"""
+from __future__ import annotations
+
+# ⚠️ CFG-03's mirror. `test_defaults_pin.py` part 2 discovers every
+# module-level name ending in OPTION_DEFAULTS and asserts each value
+# reproduces config.yaml EXACTLY, so this table cannot drift from the shipped
+# default. Nothing in the add-on may carry a literal fallback for a key a
+# mirror answers for - part 3 scans for that - which is why `main.py` asks the
+# functions below and never reads `shadow_mode` itself.
+SHADOW_OPTION_DEFAULTS = {
+    "shadow_mode": "auto",
+}
+
+#: The three values `shadow_mode` may take, in the order config.yaml's schema
+#: lists them. `validate.py` refuses anything else by name.
+MODES = ("auto", "on", "off")
+
+#: What stands on the wire while shadow mode is engaged. ⚠️ A NUMBER, NOT A
+#: SILENCE - see this module's header. It is 0.0 W for the same reason every
+#: other refusal in this add-on is 0.0 W: fail toward inaction, and keep
+#: commanding it so the inverter cannot be left latched on anything else.
+WIRE_W = 0.0
+
+#: SAFETY-47. What the recorded watts mean when a MEASURED billed quarter sized
+#: them.
+#:
+#: ⚠️ "UPPER BOUND" AND NOT "SMALLER", AND THE DIFFERENCE WAS MEASURED RATHER
+#: THAN ARGUED. Charging only ADDS offtake, so a live meter's `projected` is
+#: never below a shadow meter's and the headroom is never above it: the shadow
+#: size is >= the live size, with EQUALITY at the start of every quarter, where
+#: `900/remaining` is 1.0 and neither plant has moved. Measured pairwise over
+#: 3600 charging cycles in five configurations - 0 cycles below, 730 exactly
+#: equal. A sentence reading "smaller" would have been false on every one of
+#: those 730.
+#:
+#: ⚠️ AND IT NAMES NO FACTOR. How far under the bound a live run lands is a
+#: property of the site - 6.61x at a 1500 W cap under a 1200 W house, 1.00x at
+#: a cap that does not bind - and a number invented for the row would be a
+#: second helping of the defect this constant exists to disclose.
+SIZED_FROM_METER = (
+    "⚠️ AND ITS SIZE CAME FROM THE BILLED-QUARTER METER, WHICH HAS ONLY THE "
+    "HOUSE IN IT WHILE THE BATTERY IS HELD AT 0 W. A live run sizes the same "
+    "trade against a meter the battery is moving, so this is an UPPER BOUND "
+    "and not a prediction; how far under it a live run lands is a closed-loop "
+    "question and a shadow run cannot answer it")
+
+
+def mode(opts: dict) -> str:
+    """The configured `shadow_mode`, normalised to one of `MODES`.
+
+    ⚠️ AN UNRECOGNISED VALUE ANSWERS `"on"`, NOT `"auto"` AND NOT `"off"`.
+    `validate.py` refuses such a value at startup, so this branch is not meant
+    to be reachable at all; it exists because the fail-safe direction for "the
+    operator's intent cannot be read" is the one that does not move energy. A
+    typo that silently resolved to `off` would put a battery under a controller
+    whose configuration nobody could parse.
+    """
+    raw = opts.get("shadow_mode", SHADOW_OPTION_DEFAULTS["shadow_mode"])
+    text = str("" if raw is None else raw).strip().lower()
+    if text in MODES:
+        return text
+    return "on"
+
+
+def engaged(opts: dict, *, control_started: bool) -> bool:
+    """Is the battery being left alone right now?
+
+    `control_started` is `Controller.auto` - the persisted start/stop state,
+    which a fresh install gets from `auto_start` and an operator moves with the
+    *Start / stop control* button. See the header on why `auto` reads it.
+    """
+    m = mode(opts)
+    if m == "off":
+        return False
+    if m == "on":
+        return True
+    return not control_started
+
+
+def why(opts: dict, *, control_started: bool) -> str:
+    """Which rung decided, in the words an operator can act on.
+
+    ⚠️ THE REASON, NOT ONLY THE VERDICT - MUTATION.md's masking rule. `on` and
+    `auto`-while-stopped produce the same boolean and want different operator
+    actions: one is turned off by editing an option, the other by pressing a
+    button. A surface that showed only "shadow" would make a mutation that
+    swapped the two rungs invisible.
+    """
+    # ⚠️ THE LIVE SENTENCES SAY "NOT IN SHADOW MODE", NOT "THE BATTERY IS
+    # BEING CONTROLLED". The second is FALSE on a stopped install with
+    # `shadow_mode: off` - nothing is regulating there either - and a row that
+    # is false in one of the four live states is a row an operator learns to
+    # discount. What is true in every live state is that what this add-on
+    # decides reaches the inverter; whether control is RUNNING is the
+    # `Stopped` banner's question and it is answered there.
+    m = mode(opts)
+    if m == "off":
+        return ("off (shadow_mode: off) - NOT in shadow mode: what this "
+                "add-on decides DOES reach the inverter")
+    if m == "on":
+        return ("on (shadow_mode: on) - decisions are recorded and nothing "
+                "is commanded")
+    if control_started:
+        return ("off (shadow_mode: auto, control is started) - NOT in shadow "
+                "mode: what this add-on decides DOES reach the inverter")
+    return ("on (shadow_mode: auto, control is stopped) - decisions are "
+            "recorded and nothing is commanded")
+
+
+def words(opts: dict, *, control_started: bool, would_w: float | None,
+          sized_from_meter: bool, reason: str = "") -> str:
+    """The status page's `Shadow mode` row.
+
+    ⚠️ THE ROW IS RENDERED IN EVERY STATE, INCLUDING `off`. A surface whose
+    ABSENCE is how you learn which mode you are in is a surface an operator
+    has to already know about; TARIFF-11's rule is that the rendered text is
+    what gets graded, so there has to be text in both states.
+
+    `would_w` is the decision the path reached this cycle - what a live
+    controller would have put on the wire GIVEN THIS METER AND A BATTERY AT
+    0 W - and `reason` is `Resolution.explain()`, the same sentence the `Why`
+    row carries. Together they are the whole of "what would it have done, and
+    why"; without them the row would say a shadow run happened and nothing
+    about what it found.
+
+    ⚠️ `sized_from_meter` HAS NO DEFAULT, AND THAT IS SAFETY-47's WHOLE POINT.
+    It is True when a MEASURED billed-quarter headroom sized the number being
+    recorded - `arbitrage.sized_from_meter()` answers it, and it is the one
+    place the question is asked. A default of False here would be a caller
+    that forgot the caveat rendering a row that reads exactly like a caller
+    that decided it did not apply, which is the shape of defect this card is
+    about. TEST-14's rule with a new name on it.
+
+    ⚠️ AND THE PHRASE IS "ON THIS CYCLE", UNCONDITIONALLY, NOT ONLY WHEN THE
+    CAVEAT FIRES. Every number a shadow run records was reached from a plant
+    that did not respond; "WOULD HAVE COMMANDED -2 000 W" reads as a forecast
+    of a live run and no number here is one. The ⚠️ below is the STRONGER,
+    conditional statement about the cycles where the answer can be multiples
+    out - see this module's header for the measured table.
+
+    ⚠️ AND IT IS NOT KEYED ON WHETHER THE TRADE WAS CAPPED. `arbitrage`'s own
+    sentence says "SIZED BY THE CAPACITY-TARIFF GUARD" only when the headroom
+    came out BELOW the ask - which in a shadow run is the START of the
+    quarter, where the two runs still agree. By the end of the quarter
+    `900/remaining` has multiplied the headroom past the ask, the trade is
+    NOT capped, the sentence is silent and the recorded number is at its most
+    wrong. A caveat keyed on that sentence would be quietest exactly where it
+    is needed loudest. `test_arbitrage.py` part 3d-8 drives that.
+    """
+    head = why(opts, control_started=control_started)
+    if not engaged(opts, control_started=control_started):
+        return head
+    if would_w is None:
+        return (f"{head}; no decision has been reached yet - the inverter is "
+                f"held at {WIRE_W:.0f} W")
+    # ⚠️ THE THOUSANDS SEPARATOR IS SWAPPED ON THE NUMBER ALONE. Applied to
+    # the whole sentence it ate the comma out of `head` - and `head` is the
+    # half that says WHICH RUNG decided, which is the claim MUTATION.md's
+    # masking rule says must survive.
+    num = f"{float(would_w):+,.0f}".replace(",", " ")
+    out = (f"{head}; ON THIS CYCLE WOULD HAVE COMMANDED {num} W, inverter "
+           f"held at {WIRE_W:.0f} W")
+    if sized_from_meter:
+        out += f" {SIZED_FROM_METER}"
+    if reason:
+        out += f" - {reason}"
+    return out
+
+
+def log_line(*, would_w: float, reason: str, sized_from_meter: bool) -> str:
+    """The action-log line for one change of shadow decision.
+
+    ⚠️ IT IS A FUNCTION FOR THE REASON `words()` IS ONE, AND SAFETY-47 LEARNED
+    IT THE EXPENSIVE WAY. This sentence used to be an f-string inside
+    `Controller._shadow_settle()`. Deleting the caveat from it there left all
+    29 files GREEN - the only check that could see the line drove a fixture
+    with `meter_source: off`, where no arbitrage decision and therefore no
+    caveat can ever be reached. A sentence assembled at a call site is a
+    sentence no check can grade, and the page would have said one thing while
+    the record a later analysis reads said another.
+
+    ⚠️ AND IT IS THE SAME `SIZED_FROM_METER` CONSTANT THE ROW CARRIES, not a
+    second wording of it. Two sentences meaning one thing is how the two
+    surfaces start disagreeing about which cycles are caveated.
+    """
+    out = (f"SHADOW: would have commanded {float(would_w):+.0f} W ON THIS "
+           f"CYCLE - {reason}")
+    if sized_from_meter:
+        out += f" {SIZED_FROM_METER}"
+    return out
+
+
+def banner(opts: dict, *, control_started: bool, latched: tuple = ()) -> tuple:
+    """`(level, text)` for the top of the status page, or `None` when live.
+
+    ⚠️ IT NAMES A STANDING LATCH AND GOES RED FOR ONE. The shadow banner sits
+    ABOVE every other branch of the cascade, because "the battery is not being
+    controlled" is the one sentence that may never be displaced - but a
+    failsafe latch that is up while the controller is inert is up when it
+    stops being inert, and an operator who turns shadow mode off without
+    clearing it gets a battery that will not move and a green page that
+    never mentioned why. So the latch is carried INTO the shadow banner
+    rather than losing its own.
+    """
+    if not engaged(opts, control_started=control_started):
+        return None
+    text = ("SHADOW MODE - the battery is NOT being controlled. Every "
+            f"inverter is held at {WIRE_W:.0f} W and nothing this add-on "
+            "decides reaches the inverter.")
+    if latched:
+        return ("bad", text + " ⚠️ A FAILSAFE LATCH IS STILL UP ("
+                + ", ".join(latched) + ") and it will still be up when shadow "
+                "mode is turned off.")
+    return ("warn", text)
+
+
+def problems(opts: dict) -> list:
+    """`validate.py`'s rule: `shadow_mode` must be one of the three values.
+
+    ⚠️ THE SENTENCE SPELLS `shadow_mode`. `configui.problems_by_field()` files
+    a refusal under the field whose key its text contains; a rule that never
+    names a key lands in the page's top-level block instead, where the operator
+    cannot see which control is wrong. UX-02's whole point is that the shipped
+    validator is the only rule surface, so the rule has to be readable there.
+
+    ⚠️ AND IT IS A REFUSAL RATHER THAN A COERCION. `mode()` resolves an
+    unreadable value to shadow, which is the safe direction but is also a
+    SILENT reinterpretation of what the operator wrote - and an install left in
+    shadow mode by a typo commands nothing at all, indefinitely.
+    """
+    raw = opts.get("shadow_mode", SHADOW_OPTION_DEFAULTS["shadow_mode"])
+    text = str("" if raw is None else raw).strip().lower()
+    if text in MODES:
+        return []
+    return [f"shadow_mode is {raw!r}, which is not one of "
+            + ", ".join(f"'{m}'" for m in MODES)
+            + ". 'auto' leaves the battery alone while control is stopped and "
+              "commands it once control is started; 'on' records every "
+              "decision and commands nothing at all; 'off' is ordinary "
+              "control."]

goodwe_controller/app/static_tariff.py

@@ -222,6 +222,12 @@ _DAY_ALIASES = {
 
 MINUTES_PER_DAY = 1440
 
+# TARIFF-17. The option key whose value is a period table of the TAXES
+# component. One spelling, here, because price.py, validate.py and config.yaml
+# all name it and `provider_id()`'s note says what three spellings of one
+# decision cost.
+TAXES_PROFILE_OPTION = "price_taxes_profile"
+
 # The mean that `cheap_now()` grades against is taken over this many local days.
 # Seven, so each weekday appears exactly once - see the module docstring. It is
 # a MODULE CONSTANT and not an option on purpose: CFG-03 already tracks three
@@ -320,13 +326,37 @@ def _days(value, field: str) -> frozenset:
     return frozenset(out)
 
 
-def _price(value, field: str) -> float:
-    """The all-in EUR/kWh for a period, bounded exactly as price.py bounds a feed."""
+# What a period's `eur_per_kwh` MEANS, per option. The grammar is one grammar
+# (TARIFF-17); the quantity it carries is not, so the "you left this out"
+# sentence is the one thing the two tables do not share.
+_PERIOD_MEANS = {
+    "static_profile":
+        "an all-in eur_per_kwh (energy + supplier markup + taxes, §9.3) - the "
+        "same basis the dynamic providers are assembled onto, so the two are "
+        "comparable",
+}
+_TAXES_MEANS = (
+    "the TAXES component alone in eur_per_kwh - the non-energy part of the "
+    "bill for that band (distribution, levies, VAT), NOT an all-in price. The "
+    "framework adds it to what the feed publishes, exactly as the scalar "
+    "price_taxes_eur_kwh is added"
+)
+_PERIOD_MEANS[TAXES_PROFILE_OPTION] = _TAXES_MEANS
+
+
+def _price(value, field: str, means: str = None) -> float:
+    """One period's EUR/kWh, bounded exactly as price.py bounds a feed.
+
+    `means` names the quantity for the error sentence only. TARIFF-17: the same
+    grammar carries an ALL-IN price under `static_profile` and a TAXES-ONLY
+    component under `price_taxes_profile`, and an operator who confuses the two
+    is out by an energy price - so the refusal says which one is wanted.
+    """
+    if means is None:
+        means = _PERIOD_MEANS["static_profile"]
     if value is None:
         raise ProfileInvalid(
-            f"{field} is missing. Every period needs an all-in eur_per_kwh "
-            f"(energy + supplier markup + taxes, §9.3) - the same basis the "
-            f"dynamic providers are assembled onto, so the two are comparable.")
+            f"{field} is missing. Every period needs {means}.")
     if isinstance(value, bool) or not isinstance(value, (int, float, str)):
         raise ProfileInvalid(f"{field} is {value!r}, which is not a number")
     try:
@@ -383,14 +413,19 @@ class Period:
 class StaticProfile:
     """A validated two-or-more-period tariff. Immutable, pure, I/O-free."""
 
-    def __init__(self, periods):
+    def __init__(self, periods, *, option: str = "static_profile"):
         self.periods = tuple(periods)
+        # ⚠️ TARIFF-17: the OPTION NAME travels with the profile so that every
+        # refusal names the key the operator actually typed. It is a default
+        # argument on purpose - every pre-existing call site and every
+        # pre-existing sentence is byte-identical without it.
+        self.option = option
         if not self.periods:
             raise ProfileInvalid(
-                "static_profile has no periods. A profile with no periods is "
-                "not a fixed tariff, it is an absent one - leave the option "
-                "empty to say that on purpose (§11.4 then applies).")
-        _check_tiling(self.periods)
+                f"{option} has no periods. A profile with no periods is "
+                f"not a fixed tariff, it is an absent one - leave the option "
+                f"empty to say that on purpose (§11.4 then applies).")
+        _check_tiling(self.periods, option=option)
 
     # -- what kind of tariff this is, DERIVED --------------------------------
     @property
@@ -477,7 +512,7 @@ class StaticProfile:
             u += timedelta(hours=1)
         if not out:
             raise ProfileInvalid(
-                f"static_profile.series({since.isoformat()}, "
+                f"{self.option}.series({since.isoformat()}, "
                 f"{until.isoformat()}) spans no whole hour. An empty series is "
                 f"not constructible downstream on purpose (price.py trap 3).")
         return out
@@ -489,7 +524,7 @@ class StaticProfile:
         return f"{kind}: " + "; ".join(p.words for p in self.periods)
 
 
-def _check_tiling(periods) -> None:
+def _check_tiling(periods, *, option: str = "static_profile") -> None:
     """Every day type must be covered by EXACTLY ONE period, every minute.
 
     ⚠️ REFUSES BOTH DIRECTIONS. A gap means an hour with no price, and the only
@@ -506,22 +541,22 @@ def _check_tiling(periods) -> None:
             if n > 1 and over_from is None:
                 over_from = (minute, n)
             if n != 0 and gap_from is not None:
-                _raise_gap(weekday, gap_from, minute)
+                _raise_gap(weekday, gap_from, minute, option)
             if n <= 1 and over_from is not None:
-                _raise_overlap(weekday, over_from, minute, periods)
+                _raise_overlap(weekday, over_from, minute, periods, option)
         if gap_from is not None:
-            _raise_gap(weekday, gap_from, MINUTES_PER_DAY)
+            _raise_gap(weekday, gap_from, MINUTES_PER_DAY, option)
         if over_from is not None:
-            _raise_overlap(weekday, over_from, MINUTES_PER_DAY, periods)
+            _raise_overlap(weekday, over_from, MINUTES_PER_DAY, periods, option)
 
 
 def _hhmm(m):
     return f"{m // 60:02d}:{m % 60:02d}"
 
 
-def _raise_gap(weekday, start, end):
+def _raise_gap(weekday, start, end, option="static_profile"):
     raise ProfileInvalid(
-        f"static_profile leaves {DAY_NAMES[weekday]} "
+        f"{option} leaves {DAY_NAMES[weekday]} "
         f"{_hhmm(start)}-{_hhmm(end)} with no period, so those hours have no "
         f"price. Refused rather than defaulted: an invented price is one an "
         f"optimiser would trade on, and §11.4 already says what a missing price "
@@ -529,19 +564,28 @@ def _raise_gap(weekday, start, end):
         f"\"22:00-07:00 mon-fri\" does NOT cover Saturday morning.")
 
 
-def _raise_overlap(weekday, over, end, periods):
+def _raise_overlap(weekday, over, end, periods, option="static_profile"):
     start, n = over
     names = [p.name for p in periods if p.covers(weekday, start)]
     raise ProfileInvalid(
-        f"static_profile gives {DAY_NAMES[weekday]} {_hhmm(start)}-"
+        f"{option} gives {DAY_NAMES[weekday]} {_hhmm(start)}-"
         f"{_hhmm(end)} {n} prices at once ({', '.join(names)}). Two prices for "
         f"one hour means one of them silently wins on list order. Narrow one of "
         f"the windows or split the day selector.")
 
 
-def parse_static_profile(value):
+def parse_static_profile(value, *, option: str = "static_profile",
+                         means: str = None):
     """`static_profile` -> a `StaticProfile`, or None when unset.
 
+    ⚠️ TARIFF-17 MADE `option`/`means` PARAMETERS RATHER THAN FORKING THIS
+    FUNCTION, and that is the whole of the reuse. A second period parser would
+    be a second tiling rule, a second day-type rule and a second set of DST
+    bugs, diverging first on the 23- and 25-hour days where nobody looks. The
+    two arguments move only the OPTION NAME and the "what this number is"
+    clause through the refusals; the grammar, the tiling check and the wrapping
+    rule are one implementation with one set of checks over it.
+
     Accepts what the option can actually arrive as:
       * `None` / `""` / `"null"`      - unset. §14 ships `static_profile: null`.
       * a JSON string                 - what config.yaml's flat `str?` option
@@ -555,6 +599,8 @@ def parse_static_profile(value):
     """
     if value is None:
         return None
+    if means is None:
+        means = _PERIOD_MEANS.get(option, _PERIOD_MEANS["static_profile"])
     if isinstance(value, str):
         text = value.strip()
         if not text or text.lower() in ("null", "none", "off"):
@@ -563,7 +609,7 @@ def parse_static_profile(value):
             value = json.loads(text)
         except ValueError as e:
             raise ProfileInvalid(
-                f"static_profile is not valid JSON ({e}). It is a JSON object "
+                f"{option} is not valid JSON ({e}). It is a JSON object "
                 f"with a \"periods\" list, on one line, e.g.\n"
                 f'  {{"periods": [{{"name":"day","from":"07:00","to":"22:00",'
                 f'"days":"mon-fri","eur_per_kwh":0.34}}, ...]}}\n'
@@ -573,7 +619,7 @@ def parse_static_profile(value):
         tz = str(value.get("timezone", "") or "").strip().lower()
         if tz not in SUPPORTED_TZ:
             raise ProfileInvalid(
-                f"static_profile.timezone is {value.get('timezone')!r}. Only "
+                f"{option}.timezone is {value.get('timezone')!r}. Only "
                 f"Europe/Brussels is supported: the shipped image carries no tz "
                 f"database (see app/price.py), so any other zone could not be "
                 f"honoured and would be silently treated as Brussels - which is "
@@ -581,24 +627,24 @@ def parse_static_profile(value):
         rows = value.get("periods")
         if rows is None:
             raise ProfileInvalid(
-                "static_profile has no \"periods\" list. Even a fully-fixed "
-                "tariff is written as one period covering 00:00-24:00 all days "
-                "- one shape for both products, so nothing downstream branches "
-                "on which kind of site this is.")
+                f"{option} has no \"periods\" list. Even a fully-fixed "
+                f"tariff is written as one period covering 00:00-24:00 all days "
+                f"- one shape for both products, so nothing downstream branches "
+                f"on which kind of site this is.")
     else:
         rows = value
 
     if not isinstance(rows, (list, tuple)):
         raise ProfileInvalid(
-            f"static_profile.periods is {type(rows).__name__}, not a list")
+            f"{option}.periods is {type(rows).__name__}, not a list")
 
     periods = []
     for i, row in enumerate(rows, start=1):
         if not isinstance(row, dict):
             raise ProfileInvalid(
-                f"static_profile.periods[{i}] is {type(row).__name__}, not an "
+                f"{option}.periods[{i}] is {type(row).__name__}, not an "
                 f"object with from/to/days/eur_per_kwh")
-        where = f"static_profile.periods[{i}]"
+        where = f"{option}.periods[{i}]"
         name = str(row.get("name", "") or f"period{i}").strip() or f"period{i}"
         start = _minutes(row.get("from", row.get("start")), f"{where}.from")
         end = _minutes(row.get("to", row.get("end")), f"{where}.to")
@@ -617,8 +663,47 @@ def parse_static_profile(value):
                               end_min=end,
                               days=_days(row.get("days"), f"{where}.days"),
                               eur_per_kwh=_price(row.get("eur_per_kwh"),
-                                                 f"{where}.eur_per_kwh")))
-    return StaticProfile(periods)
+                                                 f"{where}.eur_per_kwh",
+                                                 means)))
+    return StaticProfile(periods, option=option)
+
+
+def parse_taxes_profile(value):
+    """`price_taxes_profile` -> a `StaticProfile` of TAX values, or None.
+
+    TARIFF-17. THE DEFECT THIS EXISTS TO CLOSE: `price.py` modelled the whole
+    non-energy part of a Belgian bill as ONE scalar. In Flanders that is
+    correct - Fluvius distribution is a single rate and its tariff card offers
+    only `Normaal | Uitsl. nacht`, where *exclusive night* is a separate
+    physical circuit rather than a night register. The Walloon and Brussels
+    DSOs are on the same card with four columns - `Enkelvoudig | Dag | Nacht |
+    Uitsl. nacht` - and the day/night gap is real money:
+
+        ORES          dag 13,27  nacht  7,39  ->  5,88 c EUR/kWh
+        AIESH         dag 15,17  nacht  8,21  ->  6,96
+        Tecteo RESA   dag 12,20  nacht  7,01  ->  5,19
+        Sibelga (BXL) dag  9,39  nacht  7,10  ->  2,29
+        ORES IMPACT   dag 16,578 nacht  5,090 -> 11,49   (2026)
+
+    ⚠️ AND THE BANDS ARE ANTI-CORRELATED WITH WHAT THE BATTERY WANTS TO DO.
+    The cheap network hours are the cheap spot hours, so flattening them does
+    not merely shift the curve - it SYSTEMATICALLY UNDERSTATES the true spread
+    and makes the add-on decline cycles that are genuinely profitable. See
+    DOCS.md "The three buckets" for why the flat scalar could never have done
+    this: an additive constant, identical every hour, cancels exactly in
+    `max - min` and cannot move `min(firm, key=...)` either.
+
+    ⚠️ THE VALUE IS THE TAXES COMPONENT, NOT AN ALL-IN PRICE. `static_profile`
+    uses the same grammar for an all-in figure; the two are one parser and two
+    meanings, and `_price()`'s refusal names which one it wanted.
+
+    ⚠️ NOT PARSED ON THE FETCH PATH. validate.py refuses a malformed table at
+    STARTUP, by the rule `price.py` trap 3 states for `static_profile`: a table
+    that cannot be parsed at 03:00 is a site that stops pricing at 03:00, and
+    §11.4 makes that quiet.
+    """
+    return parse_static_profile(value, option=TAXES_PROFILE_OPTION,
+                                means=_TAXES_MEANS)
 
 
 # --------------------------------------------------------------------------- #

goodwe_controller/app/validate.py

@@ -325,13 +325,19 @@ import logging
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
 from .custom_formula import (
-    FormulaInvalid, implausible_all_in, parse_price_formula, stale_card)
+    EXPORT_FORMULA_OPTION, FormulaInvalid, implausible_all_in,
+    parse_export_formula, parse_price_formula, stale_card)
 from .inverter import roster_entries
 from .maintenance import MAINT_OPTION_DEFAULTS
 from .p1 import is_enabled, validate_meter_options
 from .peakguard import PEAK_OPTION_DEFAULTS
-from .price import PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS
-from .static_tariff import ProfileInvalid, parse_static_profile
+from .price import (
+    PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS,
+    SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
+from .shadow import problems as shadow_problems
+from .static_tariff import (
+    ProfileInvalid, TAXES_PROFILE_OPTION, parse_static_profile,
+    parse_taxes_profile)
 from .watchdog import SIGN_OPTION_DEFAULTS
 
 _LOG = logging.getLogger("goodwe.config")
@@ -835,6 +841,18 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     # missing rating one line up.
     problems.extend(_roster_problems(opts))
 
+    # --- 11. SAFETY-10's shadow mode, and it is a REFUSAL ---------------------
+    # `shadow_mode` decides whether this controller commands the battery at all,
+    # so an unreadable value is not a detail to log and carry on past.
+    # `shadow.mode()` resolves an unrecognised one to SHADOW - the direction
+    # that does not move energy - and an install silently reinterpreted that way
+    # commands nothing, indefinitely, while its status page calmly explains
+    # that this is intentional. UX-02 made this validator the ONE rule surface
+    # both editors read, so the refusal belongs here rather than in a coercion
+    # nobody can see. The sentence spells `shadow_mode` so
+    # `configui.problems_by_field()` can file it under the field.
+    problems.extend(shadow_problems(opts))
+
     # --- 2. the configured ceiling against the device's own rating -----------
     # ⚠️ THE FLAT `max_w`, AND ONLY THE FLAT ONE. `dev_min`/`dev_max` are ONE
     # device's range - the flat `setpoint_entity`'s - so this rule can only ever
@@ -1420,6 +1438,101 @@ def _price_problems(opts: dict) -> list[str]:
                 "for this product. Peak shaving, reserve management and the "
                 "maintenance cycle are unaffected.", profile.prices[0])
 
+    # ⚠️ TARIFF-17: THE TAXES PERIOD TABLE, PARSED AT STARTUP RATHER THAN AT
+    # 03:00, FOR `static_profile`'s REASON ONE OPTION OVER. This table is read
+    # by `price.assemble()` on the ~30 s planning path; a table that only fails
+    # when a fetch happens is a site that stops pricing mid-afternoon, and
+    # §11.4 turns that into a quiet fallback that looks exactly like a healthy
+    # fixed-tariff day. So the parse happens here, once, where a refusal is a
+    # banner naming the key.
+    raw_taxes_profile = opts.get(TAXES_PROFILE_OPTION, "")
+    taxes_table = None
+    if str(raw_taxes_profile or "").strip() \
+            or isinstance(raw_taxes_profile, (list, dict)):
+        try:
+            taxes_table = parse_taxes_profile(raw_taxes_profile)
+        except ProfileInvalid as e:
+            problems.append(f"{TAXES_PROFILE_OPTION} cannot be used: {e}")
+
+    if taxes_table is not None:
+        # ⚠️ TWO WRITERS OF ONE QUANTITY, ONE OF WHICH SILENTLY LOSES - the
+        # exact case (a) this module exists for, and the same refusal shape as
+        # the price-entity/static_profile pair above. The table decides when it
+        # is set, so a non-default scalar left beside it is a number the
+        # operator typed that changes nothing, on the quantity §11.4 makes
+        # hardest to notice. It is compared against the SHIPPED DEFAULTS rather
+        # than against presence, because the Supervisor writes every schema key
+        # into the options file whether the operator touched it or not - so
+        # "the operator did not type this" has to be read off the VALUE.
+        #
+        # ⚠️ TARIFF-18: "UNTOUCHED" IS A SET, NOT ONE NUMBER, AND THE DEFECT
+        # THAT MAKES IT ONE IS AN UPGRADE THAT STOPS A BATTERY CONTROLLER
+        # STARTING. The Supervisor sets `App.options = deepmerge(config.yaml
+        # defaults, stored options)`, so a saved blob carries every schema key
+        # whether the operator typed it or not - the reference install's export
+        # is 70 of 71. When TARIFF-18 moved this default 0.06 -> 0.11736, every
+        # such blob went from "equal to the shipped default" to "not equal to
+        # it" without anybody editing anything, and a site that also carries a
+        # taxes table would have met `SystemExit(78)` on the upgrade. The
+        # sentence below is about a number the OPERATOR TYPED; a superseded
+        # shipped default is not one, so it still reads as untouched. The set
+        # is in price.py beside the default it supersedes, because the two only
+        # ever move together.
+        scalar = _number(opts, "price_taxes_eur_kwh",
+                         PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"])
+        shipped = PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"]
+        untouched = (shipped,) + tuple(SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
+        superseded = ", ".join(
+            str(u) for u in SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
+        if scalar is not None \
+                and not any(abs(scalar - u) <= 1e-12 for u in untouched):
+            problems.append(
+                f"{TAXES_PROFILE_OPTION} is set AND price_taxes_eur_kwh is "
+                f"{scalar} rather than its shipped {shipped}. THE TABLE WINS: "
+                f"the add-on reads the per-period figures and never looks at "
+                f"the scalar, so the number you typed there would decide "
+                f"nothing and nothing would say so. Set price_taxes_eur_kwh "
+                f"back to {shipped}, or clear {TAXES_PROFILE_OPTION} to keep "
+                f"the flat figure. (A scalar still sitting on a SUPERSEDED "
+                f"default - {superseded} - is accepted and NOT refused: "
+                f"that is a number this add-on wrote into your options "
+                f"blob, not one you typed.)")
+
+        # ⚠️ THE UNITS RUNG, AND IT IS A SECOND QUANTITY RATHER THAN A
+        # RESTATEMENT. Every Belgian DSO prints these bands in c EUR/kWh
+        # (ORES `13,27`), and the whole table is copied off one card - so the
+        # factor-100 error arrives on EVERY row at once and nothing internal to
+        # the table disagrees with itself. The parser's own +-10 EUR/kWh bound
+        # catches a 13,27 typed raw, but NOT ORES IMPACT's night band of 5,090,
+        # which would be a 5.09 EUR/kWh levy sailing through. Belgian
+        # non-energy components run roughly 0.05-0.25 EUR/kWh, so anything at
+        # or above 1.0 is the wrong unit and not a tariff.
+        steep = sorted({p.eur_per_kwh for p in taxes_table.periods
+                        if abs(p.eur_per_kwh) >= 1.0})
+        if steep:
+            problems.append(
+                f"{TAXES_PROFILE_OPTION} carries {steep} EUR/kWh. Belgian "
+                f"levies and distribution run about 0.05-0.25 EUR/kWh, so "
+                f"these are almost certainly the CENT figures off the tariff "
+                f"card (ORES prints `13,27`, which is 0.1327 EUR/kWh) typed "
+                f"without the conversion - a factor of 100 that would make "
+                f"every hour look like an emergency. Divide by 100, or clear "
+                f"the option.")
+        negative = sorted({p.eur_per_kwh for p in taxes_table.periods
+                           if p.eur_per_kwh < 0})
+        if negative:
+            # ⚠️ A WARNING, NOT A REFUSAL. A negative non-energy component is
+            # implausible rather than impossible - a prosumer rebate is
+            # expressible this way - and refusing a site over it would be this
+            # module asserting a fact about Belgian tariff design it cannot
+            # observe. §14's warning box governs CONTRADICTIONS, and this is
+            # not one.
+            _LOG.warning(
+                "%s carries negative levies %s EUR/kWh. That is accepted, but "
+                "a tax component below zero is usually a sign error: the "
+                "add-on will SUBTRACT it from the published price in those "
+                "hours.", TAXES_PROFILE_OPTION, negative)
+
     # ⚠️ TARIFF-15: THE FORMULA, GRADED AGAINST THE OPERATOR'S OWN CARD, AT
     # STARTUP RATHER THAN AT 03:00.
     #
@@ -1448,6 +1561,7 @@ def _price_problems(opts: dict) -> list[str]:
     # CARD AGAINST REALITY. A consistent-but-wrong pair - both numbers off the
     # wrong product - reproduces its own printed price and passes. Nothing can
     # catch that.
+    spec = None                 # TARIFF-16 reads this back, below
     raw_formula = opts.get("price_formula", "")
     has_formula = bool(str(raw_formula or "").strip()) \
         or isinstance(raw_formula, dict)
@@ -1499,6 +1613,99 @@ def _price_problems(opts: dict) -> list[str]:
                 # cannot start.
                 _LOG.warning("%s", aged)
 
+    # ⚠️ TARIFF-16: THE INJECTION LEG, REFUSED AT STARTUP ON THE SAME RULE.
+    #
+    # THE DEFECT THIS EXISTS TO PREVENT: `export_price_eur_kwh` models
+    # injection as ONE scalar, and the published market is a line -
+    # Eneco `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. A scalar cannot hold its own factor (0,100 against
+    # 0,102 on the same supplier's consumption leg), cannot hold a negative
+    # offset, cannot state that injection is VAT-EXEMPT while consumption is
+    # at 6%, and cannot go below zero in the midday hours a PV household
+    # actually exports in.
+    #
+    # ⚠️ AND WHAT IT DOES NOT AFFECT TODAY, said here rather than left to be
+    # inferred: `arbitrage.py` does not read the injection price at all. Both
+    # hours it compares are all-in CONSUMPTION prices, by its own
+    # accounting-basis comment. No trade turns on this option. What it changes
+    # is what the operator is told and what a future export-aware strategy
+    # rests on - which is why it is validated here rather than trusted.
+    raw_export = opts.get(EXPORT_FORMULA_OPTION, "")
+    has_export = bool(str(raw_export or "").strip()) \
+        or isinstance(raw_export, dict)
+    if has_export:
+        try:
+            xspec = parse_export_formula(raw_export)
+        except FormulaInvalid as e:
+            xspec = None
+            problems.append(f"{EXPORT_FORMULA_OPTION} cannot be used: {e}")
+        if xspec is not None:
+            # ⚠️ THE 6% ASYMMETRY, PRINTED RATHER THAN ASSUMED. The two legs
+            # carry INDEPENDENT `vat_pct` values and a Belgian site's are 6 and
+            # 0. Printing both beside each other is the only place an operator
+            # can see that the add-on knows it - a status page shows one price
+            # and no arithmetic.
+            _LOG.info(
+                "%s is set: injection priced as (%g x index %+g) x "
+                "(1 + %g/100) %s, i.e. %.4g x the wholesale price with a "
+                "%+.5f EUR/kWh offset. ⚠️ NO STRATEGY IN THIS ADD-ON READS "
+                "IT: arbitrage.py prices the sell side as displaced IMPORT "
+                "and compares two all-in CONSUMPTION prices, so this option "
+                "changes no decision the add-on takes today. It is what you "
+                "are shown, and the shape a future export-aware strategy "
+                "would read.",
+                EXPORT_FORMULA_OPTION, xspec.factor, xspec.offset,
+                xspec.vat_pct, xspec.units, xspec.passthrough,
+                xspec.offset_eur_kwh)
+            if spec is not None:
+                # ⚠️ THE ASYMMETRY, AS AN ORDERED PAIR RATHER THAN TWO NUMBERS
+                # IN ONE SENTENCE (MUTATION.md habit 14). "6 and 0 appear
+                # somewhere" is satisfied by the two legs transposed, which is
+                # the sentence telling an operator that the add-on has their
+                # VAT treatment exactly backwards.
+                _LOG.info(
+                    "the two legs are priced independently: consumption "
+                    "factor %g at vat_pct %g, injection factor %g at vat_pct "
+                    "%g. In Belgium those differ - \"injectietarieven zijn "
+                    "vrijgesteld van btw\" while consumption is at 6%% - and "
+                    "%s is the option that makes the difference "
+                    "expressible; a single scalar could not state it.",
+                    spec.factor, spec.vat_pct, xspec.factor, xspec.vat_pct,
+                    EXPORT_FORMULA_OPTION)
+            if not xspec.card_graded:
+                # ⚠️ A WARNING AND NEVER A REFUSAL, AND THE GAP IS NAMED
+                # RATHER THAN WORKED AROUND. `price_formula`'s card block is
+                # required because a Belgian card prints the consumption
+                # formula, the reference index AND the resulting price. Eneco's
+                # INJECTION formula is printed with no price beside it, so on
+                # that card there is nothing to reproduce. Requiring a block
+                # here would make the market's own published line
+                # inexpressible; inventing the estimate would grade the
+                # coefficients against arithmetic done with the same
+                # coefficients. So the leg is accepted, the two coefficient
+                # bounds in `implausible_injection()` are applied, and the
+                # operator is told which of the two checks did NOT run.
+                _LOG.warning(
+                    "%s has no \"card\" block, so its coefficients are "
+                    "UNGRADED: nothing recomputed a printed price from them. "
+                    "That is accepted because it is the real market - Eneco "
+                    "prints its injection formula with no price beside it, so "
+                    "there is nothing to grade against on that card - and "
+                    "refusing would make the published line inexpressible. "
+                    "What IS checked is the shape of the coefficients: the "
+                    "pass-through (%.4g x the wholesale price) and the offset "
+                    "(%+.5f EUR/kWh). If YOUR card prints an injection "
+                    "estimate, add {\"month\": ..., \"index_eur_per_mwh\": "
+                    "..., \"expect_incl_vat\": ...} and the add-on will "
+                    "refuse to start unless your numbers reproduce it.",
+                    EXPORT_FORMULA_OPTION, xspec.passthrough,
+                    xspec.offset_eur_kwh)
+            else:
+                xaged = stale_card(xspec)
+                if xaged:
+                    _LOG.warning("%s", xaged)
+
     # ⚠️ A WARNING, NOT A REFUSAL, AND THE ASYMMETRY IS DELIBERATE. §11.4 says a
     # site with no price data falls back to the static profile; a dynamic site
     # with none configured has nothing to fall back to when its feed dies. That

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.9.0"
+version: "0.10.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -291,13 +291,58 @@ options:
   # price_markup_eur_kwh is ignored under it, with a line in the log saying so.
   price_provider: "off"
   price_markup_eur_kwh: 0.03
-  price_taxes_eur_kwh: 0.06
+
+  # TARIFF-18. The all-in Flemish non-energy figure, EUR/kWh, incl. 6 % VAT.
+  # Its components are named in app/price.py's FLEMISH_TAXES_COMPONENTS_EUR_KWH
+  # and test_price.py section 1b re-adds them:
+  #
+  #   Fluvius distribution (Antwerpen)              5,35  c EUR/kWh
+  #   Bijzondere accijns, "Alle verbruik"           4,876
+  #   Bijdrage groene stroom en WKK Vlaanderen      1,51
+  #   Energiebijdrage (0 EUR/MWh since 2026-08-01)  0
+  #                                                ------
+  #                                                11,736 c EUR/kWh = 0.11736
+  #
+  # ⚠️ THIS IS PER-DSO AND YOURS IS PROBABLY DIFFERENT. Only the distribution
+  # row moves: across the eight Fluvius DSOs it runs 5,28 c EUR/kWh
+  # (Midden-Vlaanderen) to 6,70 (West), so the Flemish total runs about 0.117
+  # to 0.131. Antwerpen is near the LOW end, which is the direction this
+  # default should err in - it is inert on which hour is cheapest, but §17's
+  # negative-price guard reads the ABSOLUTE all-in price, and a figure set too
+  # high would carry a genuinely negative hour above zero.
+  #
+  # ⚠️ WALLONIA AND BRUSSELS DO NOT BELONG IN THIS SCALAR AT ALL. Their
+  # distribution tariff has a day and a night band; use price_taxes_profile.
+  price_taxes_eur_kwh: 0.11736
 
   # §9.3: injection is priced SEPARATELY, and in Belgium it is often near zero -
-  # which by itself strongly favours self-consumption over export. A scalar, not
-  # a second series: no shipped supplier publishes a dynamic injection curve.
+  # which by itself strongly favours self-consumption over export. This is the
+  # FLAT injection price, for a site paid the same for every exported kWh.
+  #
+  # ⚠️ THE REASON THIS COMMENT USED TO GIVE - "no shipped supplier publishes a
+  # dynamic injection curve" - WAS FALSE, and TARIFF-07 struck the same
+  # sentence from app/price.py and DOCS.md without reaching this file. Eneco
+  # publishes `0,1 x BELPEX-H - 1,188` c EUR/kWh on the same card as its
+  # consumption formula, ENGIE publishes `(B x eSpot_15) - A`, and Aspiravi
+  # `0,07 x Belpex - 2`. A site on one of those sets price_export_formula
+  # below; this scalar stays the fixed-product default and is what every site
+  # uses today.
   export_price_eur_kwh: 0.04
 
+  # TARIFF-16. The INJECTION leg as a formula, in price_formula's own grammar
+  # and with its OWN coefficients: Eneco uses 0,102 on consumption and 0,100 on
+  # injection, and injection is VAT-EXEMPT where consumption is at 6%, so
+  # `vat_pct` here is normally 0. A negative `offset` is expected - it is what
+  # the published lines carry - and the resulting price legitimately goes below
+  # zero in the midday hours a PV household exports in.
+  #
+  # ⚠️ NO STRATEGY IN THIS ADD-ON READS IT. arbitrage.py prices the sell side
+  # as displaced IMPORT and compares two all-in CONSUMPTION prices; it does not
+  # read the injection price at all. This option is what the operator is shown
+  # and the shape a future export-aware strategy would rest on. Empty by
+  # default, which leaves every existing site on the scalar above.
+  price_export_formula: ""
+
   # §14's `tariffs.static_profile`, and "" is its `null`. §9.2: "a large share
   # of the installed base is on [a static profile]" - this is what makes those
   # sites first-class rather than "price_provider: off, good luck".
@@ -328,6 +373,43 @@ options:
   # validate.py warns about exactly that.
   static_profile: ""
 
+  # TARIFF-17. THE TAXES COMPONENT AS A DAY/NIGHT TABLE, for the sites whose
+  # network tariff actually has one. "" means the flat price_taxes_eur_kwh
+  # above decides, which is what every install has had until now and is CORRECT
+  # IN FLANDERS: Fluvius distribution is a single rate, and its row on the
+  # tariff card offers only `Normaal | Uitsl. nacht` - exclusive night being a
+  # separate physical circuit, not the night register of a dual-rate meter.
+  #
+  # The Walloon and Brussels DSOs are on the same card with FOUR columns -
+  # `Enkelvoudig | Dag | Nacht | Uitsl. nacht` - and the gap is real money
+  # (c EUR/kWh): ORES dag 13,27 / nacht 7,39; AIESH 15,17 / 8,21; Tecteo RESA
+  # 12,20 / 7,01; Sibelga 9,39 / 7,10; ORES IMPACT 2026 16,578 / 5,090.
+  #
+  # ⚠️ WHY THIS IS NOT COSMETIC. The optimiser reads the SPREAD (max - min) and
+  # which hour is cheapest. A flat number is additive and identical every hour,
+  # so it cancels out of both - it cannot distort anything, and it also cannot
+  # express this. These bands are ANTI-CORRELATED with what the battery wants
+  # to do (cheap network hours are cheap spot hours), so flattening them
+  # UNDERSTATES the true spread and declines cycles that would have paid. See
+  # DOCS.md, "The three buckets".
+  #
+  # Same JSON grammar as static_profile above - the same tiling rule, the same
+  # day selectors, the same DST handling, because it is literally the same
+  # parser. ⚠️ THE VALUE IS THE TAXES COMPONENT ALONE, NOT AN ALL-IN PRICE:
+  #
+  #   {"periods": [
+  #      {"name":"dag",  "from":"07:00","to":"22:00","days":"mon-fri","eur_per_kwh":0.1327},
+  #      {"name":"nacht","from":"22:00","to":"07:00","days":"mon-fri","eur_per_kwh":0.0739},
+  #      {"name":"nacht","from":"00:00","to":"24:00","days":"sat,sun", "eur_per_kwh":0.0739}]}
+  #
+  # ⚠️ SET THIS *OR* price_taxes_eur_kwh, NOT BOTH. Two writers of one quantity,
+  # one of which silently wins, is refused at startup: leave the scalar at its
+  # shipped default when you fill this in. A scalar still sitting on the
+  # SUPERSEDED 0.06 is accepted too (TARIFF-18 moved that default, and your
+  # stored options carry the old number whether you typed it or not) - the
+  # refusal is about a figure you chose, not about one this add-on wrote.
+  price_taxes_profile: ""
+
   # TARIFF-15. YOUR OWN TARIFF CARD, as two fixed coefficients. Used only when
   # `price_provider: custom_formula`; "" is unset.
   #
@@ -664,6 +746,38 @@ options:
   # and not 150 or 200. 37 control cycles.
   delivery_hold_s: 185
 
+  # SAFETY-10. Run the whole decision path and command NOTHING - strategies,
+  # arbiter, clamps and guards all run, the decision and its reason are
+  # recorded, and every inverter is held at 0 W. `app/shadow.py` carries the
+  # argument; the three things to know before changing this line are:
+  #
+  #   auto  shadow WHILE CONTROL IS STOPPED, live once it is started. This is
+  #         the shipped value and it is what "default-on" means here.
+  #   on    always shadow, whatever the Start / stop button says. This is the
+  #         one an operator picks to watch a day of decisions on an armed site
+  #         before letting it trade.
+  #   off   ordinary control.
+  #
+  # ⚠️ IT IS NOT A BOOLEAN DEFAULTING TO `true`, AND THAT IS THE WHOLE CARD.
+  # The Supervisor composes an add-on's options as `{**these defaults, **the
+  # stored user options}`, so a NEW key with a new default reaches every
+  # EXISTING install on the next update - including one regulating a real
+  # battery. `shadow_mode: true` would silently stop it, and the only symptom
+  # would be a battery that has stopped doing anything. There is no mechanism
+  # in this options system that lets one key default differently for a new
+  # install and an existing one, so "default-on for new" has to be a value the
+  # add-on RESOLVES. `auto` is that value: a fresh install ships
+  # `auto_start: false` and therefore comes up in shadow mode; an install that
+  # is controlling is started, so `auto` resolves to live and NOTHING about it
+  # changes.
+  #
+  # ⚠️ AND UNDER `auto` THE START BUTTON LEAVES SHADOW MODE. Pressing *Start /
+  # stop control* is the operator saying "control the battery". Somebody who
+  # wants the decisions recorded WHILE the loop runs sets `on` explicitly -
+  # which is the configuration this option exists for, and the one that cannot
+  # be reached by accident.
+  shadow_mode: "auto"
+
   # ==========================================================================
   # ADVANCED - the control law and diagnostics
   # ==========================================================================
@@ -842,11 +956,24 @@ schema:
   # bottoms out at 0 would make that site inexpressible.
   export_price_eur_kwh: float(-1,1)
 
+  # TARIFF-16. A JSON string in `price_formula`'s grammar, parsed by
+  # `custom_formula.parse_export_formula()` - the SAME parser with its option
+  # name as an argument, so a second unit table and a second card rule do not
+  # exist to diverge. The `card` block is OPTIONAL on this leg and required on
+  # the other: Eneco prints its injection formula with no price beside it, so
+  # on that card there is nothing to grade against, and the add-on says at
+  # startup that the leg is ungraded rather than inventing an estimate.
+  price_export_formula: str?
+
   # A JSON string rather than a nested schema, deliberately: it is ONE option
   # key (§14 has one), it survives config.yaml's flat options block, and
   # parse_static_profile() accepts an already-parsed dict too, so a future
   # nested schema is a config.yaml change and no code change at all.
   static_profile: str?
+  # TARIFF-17. A JSON string for `static_profile`'s reason, and parsed by
+  # `static_tariff.parse_taxes_profile()` - the SAME period grammar, so a
+  # second tiling rule and a second set of DST bugs do not exist to diverge.
+  price_taxes_profile: str?
   # TARIFF-15. A JSON string for the same reason `static_profile` is one: it is
   # ONE option key, it survives config.yaml's flat options block, and
   # parse_price_formula() accepts an already-parsed dict too, so a future
@@ -970,6 +1097,15 @@ schema:
   # running short of one unit's share must be reported well inside one.
   delivery_hold_s: int(30,900)
 
+  # SAFETY-10. ⚠️ A THREE-VALUED LIST AND NOT A `bool`, for the reason written
+  # against the default in the options block above: a boolean has one default
+  # and the Supervisor gives it to every install, new and existing alike.
+  # `app/shadow.MODES` is this tuple and `validate.py` rule 11 refuses anything
+  # else BY NAME, because `shadow.mode()` resolves an unreadable value to
+  # SHADOW - safe, but a silent reinterpretation that commands nothing for as
+  # long as nobody notices.
+  shadow_mode: list(auto|on|off)
+
   # ==========================================================================
   # ADVANCED - the control law and diagnostics
   # ==========================================================================

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

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

goodwe_controller/test_clamp.py

@@ -74,6 +74,7 @@ Read MUTATION.md before you report a survivor.
 import asyncio
 import io
 import math
+import re
 import sys
 from datetime import datetime, timedelta, timezone
 
@@ -87,6 +88,7 @@ from app.arbiter import P_LOOP, Claim, UnitBounds, allocate, resolve
 from app.control import Tuning, compute
 from app.inverter import Inverter
 from app.main import Controller
+from app import shadow
 
 fails = []
 T0 = datetime(2026, 8, 30, 9, 0, 0, tzinfo=timezone.utc)
@@ -670,8 +672,15 @@ def arm(c, value):
 
 async def _direct():
     hass = _Hass(0.0)
+    # ⚠️ SAFETY-10: `shadow_mode: "off"` EXPLICITLY, BECAUSE THIS FIXTURE
+    # NEVER PRESSES START. The shipped default is `auto`, which is SHADOW
+    # MODE while control is stopped - so without this line the probe below
+    # would be graded against a controller that is correctly refusing to
+    # command anything, and the clamp it is here to exercise would never be
+    # reached. The shipped write path is unaffected: a stopped controller
+    # only ever writes 0 W in production, which shadow mode also writes.
     c = Controller({"setpoint_entity": "number.sp", "max_w": 2000,
-                    "meter_source": "off"},
+                    "meter_source": "off", "shadow_mode": "off"},
                    hass, _Store(), _Pub(), stop=asyncio.Event())
     c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
     # The shape the heartbeat, shutdown() and handle_action() all use - each one
@@ -1121,10 +1130,16 @@ A_UNIT, B_HYPO = "inverter-a", "inverter-b"
 
 
 def fresh(**over):
-    """A Controller with a stub HA, no cycle run, and therefore NO record."""
+    """A Controller with a stub HA, no cycle run, and therefore NO record.
+
+    ⚠️ SAFETY-10: `shadow_mode: "off"` for `_direct()`'s reason - this fixture
+    never presses Start, and the shipped default is shadow mode while control
+    is stopped. Part 7 grades who is allowed to reach the WIRE; a controller
+    that is correctly commanding nothing cannot answer that question.
+    """
     hass = _Hass(0.0)
     c = Controller(dict({"setpoint_entity": "number.sp", "max_w": 2000,
-                         "meter_source": "off"}, **over),
+                         "meter_source": "off", "shadow_mode": "off"}, **over),
                    hass, _Store(), _Pub(), stop=asyncio.Event())
     c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
     return hass, c
@@ -1414,6 +1429,432 @@ check("...and the numbers those cycles put on the wire are the arbiter's own "
       hass_r.writes and all(abs(w) <= LIVE_MAX_W for w in hass_r.writes))
 
 
+# --------------------------------------------------------------------------- #
+# 8. SAFETY-10 - SHADOW MODE: THE DECISION PATH RUNS AND NOTHING REACHES THE
+#    INVERTER
+# --------------------------------------------------------------------------- #
+# This part belongs in THIS file and not in a new one: shadow mode is a
+# substitution inside `_write_unit()`, one line below SAFETY-03's clamp and two
+# below SAFETY-28's gate, and the property it claims - "nothing reaches the
+# inverter" - is the same property parts 5 and 7 already grade from the other
+# side. The fake `set_number()` in this file IS the wire.
+#
+# ⚠️ EVERY CHECK BELOW IS GRADED ON THE WRITES OR ON THE RENDERED SURFACE, NOT
+# ON `Controller.shadow`. A check that asserted the flag would pass on a build
+# in which the flag is set and the substitution is deleted, which is precisely
+# the build this section exists to refuse.
+#
+# ⚠️ AND EVERY ONE OF THEM RUNS THE SAME STIMULUS IN BOTH MODES. MUTATION.md's
+# rule: a per-thing check that has never seen the things DISAGREE is a total.
+# `_s10_live` and `_s10_shadow` are the same 6000 W import through the same
+# `Controller.cycle()`; the only difference is one option.
+print("\n8. SAFETY-10 - shadow mode\n")
+
+
+def _s10(shadow_mode, *, auto=True, cycles=25, grid=6000.0, dev=None, **over):
+    """The same wired run as part 3, with `shadow_mode` and the start button.
+
+    ⚠️ `auto` IS A PARAMETER BECAUSE `shadow_mode: auto` READS IT. The three
+    values and the two button positions are six states and they are not all
+    the same state; the pure-function table over all six is in
+    `test_validate.py`, and 8f says why it is not here.
+    """
+    async def go():
+        hass = _Hass(grid, track=True)
+        c = Controller(dict(
+            {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+             "meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
+             "slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
+             "step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
+             "shadow_mode": shadow_mode},
+            **over), hass, _Store(), _Pub(), stop=asyncio.Event())
+        c.auto = auto
+        # `dev` narrows what the DEVICE says it will accept, which is the
+        # clamp's second stage - the only way to make the clamp engage on a
+        # target the loop has already bounded at `max_w`.
+        c.dev_min, c.dev_max = ((-LIVE_MAX_W, LIVE_MAX_W) if dev is None
+                                else (-dev, dev))
+        # ⚠️ CAPTURED PER CYCLE, BECAUSE THE HEARTBEAT OVERWRITES IT.
+        # `clamp_last` is assigned by every write, and the heartbeat below
+        # writes `inv.target` - 0 W in shadow mode - so the clamp's verdict on
+        # the DECISION is gone by the end of the run. Looking for it afterwards
+        # would grade the refresh instead of the cycle.
+        c.clamp_seen = []
+        for n in range(cycles):
+            await c.read_inputs()
+            await c.cycle()
+            if c.clamp_last is not None:
+                c.clamp_seen.append(c.clamp_last)
+            # ⚠️ THE HEARTBEAT IS DRIVEN HERE AND NOT LEFT OUT, BECAUSE IT IS
+            # THE HALF THAT PROVES SHADOW MODE IS NOT SILENCE. `_write_unit()`
+            # skips an unchanged value unless `force` is set, so a cycles-only
+            # fixture sees exactly ONE 0 W write and could not tell "holds the
+            # inverter at 0 W" from "wrote 0 W once and went quiet" - and the
+            # second of those leaves a real install's ESP32 in a tripped
+            # stale-input watchdog for the whole run. `heartbeat_s=0` makes
+            # every tick due, which is the shipped path with its clock wound
+            # forward rather than a second implementation of it.
+            await c.send_heartbeats(float(n), 0.0)
+        return hass, c
+    return asyncio.run(go())
+
+
+_live_h, _live_c = _s10("off")
+_shad_h, _shad_c = _s10("on")
+
+# --- 8a. THE PRECONDITION, WHICH IS THE HALF THAT MAKES THE REST MEAN ANYTHING
+# MUTATION.md habit 4: a check whose DATA cannot reach the failure it names is
+# decoration. "No non-zero value was written" is trivially true of a stimulus
+# that would not have produced one, so the same stimulus is first shown to
+# produce a large one with the option off.
+check("PRECONDITION: with shadow_mode off this stimulus really does drive the "
+      f"wire - {len(_live_h.writes)} writes, "
+      f"{len([w for w in _live_h.writes if w != 0.0])} of them non-zero, "
+      f"largest {max((abs(w) for w in _live_h.writes), default=0):.0f} W",
+      len([w for w in _live_h.writes if w != 0.0]) >= 10
+      and max((abs(w) for w in _live_h.writes), default=0) > 1000.0
+      and 0.0 not in _live_h.writes)
+
+# --- 8b. NOTHING THE DECISION PATH PRODUCED REACHES THE INVERTER -------------
+check("AC 1: in shadow mode EVERY value that reached set_number() is 0 W. "
+      f"Distinct values written: {sorted(set(_shad_h.writes))}",
+      _shad_h.writes and set(_shad_h.writes) == {0.0})
+
+# ⚠️ AND IT IS NOT SILENCE. The inverter holds its last command forever and the
+# ESP32's stale-input watchdog needs a refresh; a shadow mode that stopped
+# writing would leave a standing command up under a page saying nothing is
+# commanded. A check that only asserted "no non-zero write" would pass on that
+# build too - this is the half that separates them.
+check("...and it WROTE that 0 W rather than going silent, which is what keeps "
+      f"the inverter from holding its last command ({len(_shad_h.writes)} "
+      "writes)",
+      len(_shad_h.writes) >= 2)
+
+# --- 8c. THE DECISION PATH ACTUALLY RAN ------------------------------------
+# "Nothing reached the inverter" is also true of a controller that decided
+# nothing. Both halves, or the feature is an off switch with a long name.
+check("the full decision path still ran: the loop reached a target and the "
+      f"arbiter resolved one ({_shad_c.loop_w!r} W, "
+      f"would have commanded {_shad_c.shadow_would_w!r} W)",
+      _shad_c.loop_w is not None and abs(_shad_c.loop_w) > 500.0
+      and _shad_c.shadow_would_w is not None
+      and abs(_shad_c.shadow_would_w) > 500.0)
+check("...and the decision it recorded is a number a live controller would "
+      "have written - it is inside the rail and it is not the 0 W that went "
+      "on the wire",
+      _shad_c.shadow_would_w != 0.0
+      and abs(_shad_c.shadow_would_w) <= LIVE_MAX_W)
+
+# --- 8d. THE CARRIED COMMAND TRACKS THE WIRE, WHICH IS WHAT MAKES THE EXIT
+#         SAFE
+check("the carried site command is what is STANDING ON THE WIRE, not the "
+      f"decision ({_shad_c.target!r} W standing, "
+      f"{_shad_c.shadow_would_w!r} W decided)",
+      _shad_c.target == 0.0 and _shad_c.shadow_would_w != 0.0)
+check("...and every unit's share is too, so SAFETY-42's delivery watchdog is "
+      "not handed a share nothing was told to produce",
+      all(i.target == 0.0 for i in _shad_c.inverters))
+
+
+def _s10_exit(shadow_first):
+    """Run twelve cycles, force shadow mode off, take ONE more cycle.
+
+    Answers with `inv.last_write` either side of that boundary - WHAT STANDS ON
+    THE WIRE, updated only on an accepted write, which is the number the
+    inverter is actually latched on. Reading `hass.writes` instead would be
+    blind to the converged case, where the controller correctly re-sends
+    nothing at all.
+
+    ⚠️ THE COMPARISON IS AGAINST THE SAME RUN THAT NEVER ENTERED SHADOW MODE,
+    not against a constant. `slew_w` bounds a step from the standing command,
+    so "did it resume from the wire or from a fiction" is a question about a
+    DIFFERENCE, and a hard-coded expectation would be the number the code
+    produces compared with itself.
+    """
+    async def go():
+        hass = _Hass(6000.0, track=True)
+        c = Controller(
+            {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+             "meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
+             "slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
+             "step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
+             "shadow_mode": "on" if shadow_first else "off"},
+            hass, _Store(), _Pub(), stop=asyncio.Event())
+        c.auto = True
+        c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
+        for _ in range(12):
+            await c.read_inputs()
+            await c.cycle()
+        before = c.inverters[0].last_write
+        c.o["shadow_mode"] = "off"
+        await c.read_inputs()
+        await c.cycle()
+        # ⚠️ NOT `float()`. `last_write` is None until something is ACCEPTED,
+        # and a build in which shadow mode writes nothing at all would turn
+        # this fixture into a TypeError - which MUTATION.md's FCST-06 section
+        # is about: a traceback grades none of the checks after it AND reads
+        # like a survivor. It is handed back as None and named below instead.
+        return before, c.inverters[0].last_write, c
+    return asyncio.run(go())
+
+
+_exit_before, _exit_after, _exit_c = _s10_exit(True)
+_never_before, _never_after, _never_c = _s10_exit(False)
+print(f"    shadow run: standing {_exit_before!r} W -> {_exit_after!r} W on "
+      "the first live cycle")
+print(f"    never in shadow: standing {_never_before!r} W -> "
+      f"{_never_after!r} W on the same cycle")
+check("SOMETHING REACHED THE WIRE IN SHADOW MODE. `last_write` is set only on "
+      "an ACCEPTED write, so None here is the build that stops writing "
+      "altogether and leaves the inverter latched on its last command - the "
+      "failure shadow mode must not be a new way to reach",
+      _exit_before is not None and _exit_after is not None
+      and _never_before is not None and _never_after is not None)
+_exit_before = -1.0 if _exit_before is None else float(_exit_before)
+_exit_after = -1.0 if _exit_after is None else float(_exit_after)
+_never_before = 0.0 if _never_before is None else float(_never_before)
+_never_after = 0.0 if _never_after is None else float(_never_after)
+check("PRECONDITION: the two arrangements DISAGREE - the run that was never in "
+      "shadow mode is standing somewhere else entirely at that boundary, so "
+      "the comparison below is not a number against itself",
+      _never_before != _exit_before and abs(_never_before) > 1000.0)
+check("PRECONDITION: and the shadow run really was standing at 0 W, so the "
+      "step below is measured from the wire and not from a coincidence",
+      _exit_before == 0.0)
+check("AC 2, leaving: the first live command after shadow mode is one slew "
+      "step from the 0 W that was actually standing on the wire - NOT one step "
+      "from the decision shadow mode reached, which never existed at the "
+      f"battery. |{_exit_after:.0f}| <= slew 1000 W",
+      abs(_exit_after) <= 1000.0)
+check("...and the run that was never in shadow mode is NOT inside that bound "
+      "at the same cycle, which is what says the bound is a real constraint "
+      "here and not a property of the stimulus",
+      abs(_never_after) > 1000.0)
+
+
+def _s10_enter():
+    """Live first, then shadow mode, on a battery standing somewhere else."""
+    async def go():
+        hass = _Hass(6000.0, track=True)
+        c = Controller(
+            {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+             "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+             "meter_source": "off", "max_w": LIVE_MAX_W, "gain": 0.6,
+             "slew_w": 1000, "deadband_w": 15, "target_grid_w": 0,
+             "step_w": 10, "heartbeat_s": 10, "stale_input_s": 15,
+             "shadow_mode": "off"}, hass, _Store(), _Pub(),
+            stop=asyncio.Event())
+        c.auto = True
+        c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
+        for _ in range(12):
+            await c.read_inputs()
+            await c.cycle()
+        standing = hass.writes[-1]
+        c.o["shadow_mode"] = "on"
+        await c.read_inputs()
+        await c.cycle()
+        # ⚠️ `inverters[0].last_write`, NOT `hass.writes[-1]`. The question is
+        # WHAT THE INVERTER IS LATCHED ON after the first shadow cycle, and a
+        # build that writes NOTHING leaves it latched on the live value while
+        # `hass.writes[-1]` still reads that same number - the two look
+        # identical from the write list and are opposite at the battery.
+        return standing, float(c.inverters[0].last_write), c
+    return asyncio.run(go())
+
+
+_stood, _first_shadow, _enter_c = _s10_enter()
+print(f"    standing when shadow mode came on: {_stood:.0f} W")
+check("PRECONDITION: the battery was standing at a real, non-zero command when "
+      "shadow mode was switched on - otherwise 'it reached 0 W' says nothing",
+      abs(_stood) > 500.0)
+check("AC 2, entering: after ONE shadow cycle the inverter is latched on 0 W, "
+      "not on what it was doing a cycle earlier. The inverter holds its last "
+      "command FOREVER, so a shadow mode that merely stopped writing would "
+      "leave that command standing under a page saying nothing is commanded "
+      f"({_stood:+.0f} W -> {_first_shadow:+.0f} W)",
+      _first_shadow == 0.0)
+
+# --- 8e. THE OTHER GUARDS ON THE WRITE PATH STILL OBSERVE --------------------
+# The substitution is the LAST thing before the wire, below SAFETY-28's gate and
+# below SAFETY-03's clamp, so both still grade the number the decision path
+# produced. A shadow run that could not say "it would have hit the rating here"
+# is answering a different question from the one it is for.
+_cl_h, _cl_c = _s10("on", cycles=12, grid=9000.0, dev=400.0)
+_cl_req = [r.requested_w for r in _cl_c.clamp_seen]
+print(f"    decision {_cl_c.shadow_would_w!r} W; what the clamp was asked "
+      f"about at each cycle boundary: {sorted(set(_cl_req))}")
+check("PRECONDITION: the decision is a real, non-zero number and the wire "
+      "carried only 0 W on this run, so the two are distinguishable",
+      _cl_c.shadow_would_w is not None and _cl_c.shadow_would_w != 0.0
+      and set(_cl_h.writes) == {0.0})
+check("SAFETY-03 still OBSERVES in shadow mode: the clamp was asked about the "
+      "number THE DECISION PATH PRODUCED, not about the 0 W that went on the "
+      "wire. That is what puts the substitution BELOW the clamp, and it is "
+      "what lets a shadow run report that the rating would have been hit",
+      _cl_req and all(r == _cl_c.shadow_would_w for r in _cl_req))
+check("...and the clamp's own alarm still ran on it - the winding-loop "
+      "engagement reached the action log on a run where nothing was commanded",
+      any("clamp" in e.lower() or "CLAMP" in e for e in _cl_c.events))
+check("SAFETY-28's gate still OBSERVES too - it refused nothing on this run, "
+      "which is the same answer it gives live, so shadow mode has not been "
+      "implemented by making every write unauthorised",
+      not [e for e in _cl_c.events if "WRITE REFUSED" in e])
+
+# ⚠️ AND SAFETY-18 IS GRADED ON WHAT IT WAS HANDED, WHICH IS AN ORDERING
+# CLAIM. `check_meter_frozen()` takes `self.target` - the arbiter's RESOLVED
+# INTENT - and `_shadow_settle()` re-seeds that to 0 W at the very end of the
+# cycle, AFTER it. Re-seed one line earlier and the freeze detector grades a
+# 0 W that no decision produced: its conjunction needs a command at the rail,
+# so it goes permanently blind and the whole suite stays green. The detector's
+# own `evaluate` is wrapped here because the arguments are the only place that
+# ordering is observable.
+_fz_seen = []
+_fz_real = _shad_c.freeze_wd.evaluate
+
+
+def _fz_spy(unchanged, target, *a, **k):
+    _fz_seen.append(target)
+    return _fz_real(unchanged, target, *a, **k)
+
+
+_shad_c.freeze_wd.evaluate = _fz_spy
+
+
+async def _one_more():
+    await _shad_c.read_inputs()
+    await _shad_c.cycle()
+
+
+asyncio.run(_one_more())
+_shad_c.freeze_wd.evaluate = _fz_real
+print(f"    SAFETY-18 was handed: {_fz_seen}")
+check("PRECONDITION: the freeze detector was consulted at all on that cycle",
+      len(_fz_seen) == 1)
+check("SAFETY-18 still OBSERVES the DECISION: it is handed the arbiter's "
+      "resolved intent, not the 0 W the wire gate substituted. Re-seeding one "
+      "line earlier would hand it a command no decision produced and its "
+      "conjunction - a command at the rail against a meter that has stopped "
+      "moving - could never be satisfied again",
+      _fz_seen and _fz_seen[0] == _shad_c.shadow_would_w
+      and _fz_seen[0] != shadow.WIRE_W)
+
+# --- 8f. THE MODE TABLE LIVES IN test_validate.py ---------------------------
+# `shadow.engaged()` is a pure function of the option and the start button, and
+# the six states it answers for are graded beside the rule that validates the
+# option - not here, where a defeat of the DEFAULT stops part 3's wired run
+# reaching the wire at all and takes this whole file down before part 8 runs.
+# ⚠️ THAT IS MEASURED, NOT ANTICIPATED: the mutation that makes `auto` resolve
+# to shadow unconditionally aborts part 3 with an IndexError, so its red count
+# here is a LOWER BOUND and none of part 8 is graded (MUTATION.md, FCST-06).
+
+# --- 8g. THE OPERATOR STOP, WHICH IS THE ONE FAILSAFE THIS CARD CHANGES ------
+_stop_live_h, _stop_live_c = _s10("off", auto=False, cycles=6)
+_stop_shad_h, _stop_shad_c = _s10("auto", auto=False, cycles=6)
+print(f"    stopped, shadow off: {_stop_live_c.reason!r}")
+print(f"    stopped, shadow on : {_stop_shad_c.reason!r}")
+check("PRECONDITION: with shadow mode off, a stopped controller files the "
+      "P_SAFETY stop claim and the arbiter resolves to THAT source, at 0 W",
+      _stop_live_c.reason.startswith("safety")
+      and _stop_live_c.target == 0.0)
+check("in shadow mode that claim is NOT filed, so the arbiter resolves to the "
+      "REAL winner and the recorded decision is the real one. A P_SAFETY claim "
+      "out-ranks everything - left in, every shadow run would answer the wrong "
+      f"question ({_stop_shad_c.reason!r})",
+      _stop_shad_c.reason.startswith("loop")
+      and _stop_shad_c.shadow_would_w is not None
+      and abs(_stop_shad_c.shadow_would_w) > 0.0)
+check("...and the actuator ends at exactly the same place either way, because "
+      "the substitution that replaced the claim is STRICTLY STRONGER: a claim "
+      "can be out-ranked and a wire gate cannot",
+      set(_stop_shad_h.writes) == {0.0} == set(_stop_live_h.writes))
+
+# --- 8h. THE RENDERED SURFACE (TARIFF-11's pattern) -------------------------
+# Graded on `status_payload()`, which IS the status page: web.py's `PAGE` is a
+# static shell whose banner and rows are filled from this JSON. Named slots, not
+# substring tests, so a transposition moves a slot.
+_ROW = "Shadow mode"
+_shad_pay = _shad_c.status_payload()
+_live_pay = _live_c.status_payload()
+_shad_rows = dict(_shad_pay["rows"])
+_live_rows = dict(_live_pay["rows"])
+print(f"    banner: {_shad_pay['banner']!r}")
+print(f"    row   : {_shad_rows.get(_ROW)!r}")
+check("the status page has a Shadow mode row in BOTH states, so its ABSENCE is "
+      "never how an operator learns which one they are in",
+      _ROW in _shad_rows and _ROW in _live_rows)
+check("AC 3: the banner states plainly that the battery is not being "
+      "controlled",
+      "SHADOW MODE" in _shad_pay["banner"]
+      and "NOT being controlled" in _shad_pay["banner"])
+check("...and it is not green. A page that reads `ok` while nothing is being "
+      "commanded is the 'looks healthy but is inert' failure itself",
+      _shad_pay["level"] == "warn")
+check("...and it is FIRST in the cascade: the same controller has other "
+      "conditions to report and none of them displaces this sentence",
+      _live_pay["banner"] != _shad_pay["banner"]
+      and "SHADOW MODE" not in _live_pay["banner"])
+_slot = re.search(r"WOULD HAVE COMMANDED ([-+][\d ]+) W, inverter held at "
+                  r"([-\d]+) W", _shad_rows[_ROW])
+check("the row answers 'what would it have done' with a NUMBER in its own "
+      "named slot, and says where the inverter actually is in a second one - "
+      "two slots in one sentence, so a transposition moves them",
+      _slot is not None)
+if _slot is not None:
+    _would = float(_slot.group(1).replace(" ", ""))
+    check("...and that number is the decision the path reached, not the 0 W "
+          f"standing on the wire ({_would:.0f} vs {_shad_c.target:.0f})",
+          _would == round(float(_shad_c.shadow_would_w))
+          and _would != _shad_c.target)
+    check("...and the second slot is the STANDING command, so the two cannot "
+          "be read as one number",
+          float(_slot.group(2)) == 0.0)
+check("the row answers 'and why' by carrying the arbiter's own sentence, "
+      "rather than a re-derivation of it",
+      _shad_c.reason in _shad_rows[_ROW])
+check("with shadow mode off the row says so, and says what follows from it - "
+      "which is the arrangement that makes the one above a claim about this "
+      "controller and not about the string",
+      "NOT in shadow mode" in _live_rows[_ROW]
+      and "DOES reach the inverter" in _live_rows[_ROW]
+      and "WOULD HAVE COMMANDED" not in _live_rows[_ROW])
+
+# ⚠️ A STANDING LATCH IS NAMED RATHER THAN HIDDEN. The shadow banner sits above
+# the three `bad` branches, so it has to carry what they would have said - a
+# latch that is up while the controller is inert is up the moment it stops
+# being inert.
+_shad_c.inverters[0].sign_wd.tripped = True
+_latched = _shad_c.status_payload()
+print(f"    banner with a latch up: {_latched['banner']!r}")
+check("a failsafe latch that is standing is NAMED in the shadow banner and "
+      "turns it red, so nobody turns shadow mode off into a battery that will "
+      "not move and a page that never mentioned why",
+      _latched["level"] == "bad"
+      and "LATCH IS STILL UP" in _latched["banner"]
+      and _shad_c.inverters[0].name in _latched["banner"])
+check("...and it still says the battery is not being controlled, so the latch "
+      "has not displaced the sentence that may never be displaced",
+      "NOT being controlled" in _latched["banner"])
+_shad_c.inverters[0].sign_wd.tripped = False
+
+# --- 8i. THE RECORD A LATER ANALYSIS READS ----------------------------------
+# A shadow run is only worth running if it answers "what would it have done,
+# and why" AFTERWARDS, from the 40-row action log, and not only on a page
+# somebody happened to be looking at.
+_shadow_lines = [e for e in _shad_c.events if "SHADOW" in e]
+print(f"    action log, shadow lines: {len(_shadow_lines)} of "
+      f"{len(_shad_c.events)}")
+check("the action log records that shadow mode came on, in words",
+      any("SHADOW MODE ON" in e for e in _shadow_lines))
+check("...and what it would have commanded, with the arbiter's reason beside "
+      "it",
+      any("would have commanded" in e and "loop" in e for e in _shadow_lines))
+check("...EDGE-logged, not level-logged: 25 cycles did not flush the 40-row "
+      "log that has to carry the context of what the run found",
+      len(_shadow_lines) < 25 and len(_shad_c.events) <= 40)
+
+
 print()
 if fails:
     print(f"{len(fails)} FAILED: {', '.join(fails)}")

goodwe_controller/test_control.py

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

goodwe_controller/test_inverter.py

@@ -224,9 +224,18 @@ A_RATING = 5000.0
 # had become so; validate.py rule 10 refused it the day it existed, which is
 # what a rule about a relationship is for. 0 means "follow the rail"
 # (`control.SLEW_RAIL_FRAC * max_w`) and is what config.yaml ships.
+# ⚠️ SAFETY-10: `shadow_mode="off"` EXPLICITLY, BECAUSE NOTHING HERE PRESSES
+# START. The shipped default is `auto`, which is SHADOW MODE while control is
+# stopped - and in shadow mode every write is substituted with 0 W at the one
+# choke point these parts grade. Without this line the per-unit clamp, the
+# per-unit write budget and the per-unit heartbeat would all be measured on a
+# controller that is correctly refusing to command anything, which is a
+# different (and vacuous) claim. The shipped write path is unaffected: a
+# stopped controller only ever writes 0 W in production anyway.
 BASE_OPTS = dict(A_ENT, meter_source="off", meter_entity="sensor.grid",
                  max_w=A_RATING, gain=0.6, slew_w=0, deadband_w=15,
-                 target_grid_w=0, step_w=10, heartbeat_s=10, stale_input_s=15)
+                 target_grid_w=0, step_w=10, heartbeat_s=10, stale_input_s=15,
+                 shadow_mode="off")
 
 
 def built(opts=None, store=None, hass=None, second=None):

goodwe_controller/test_mqtt.py

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

goodwe_controller/test_packshare.py

@@ -1067,14 +1067,19 @@ class _V:
 
 _here = _Pt(_NOW)
 _other = _Pt(_NOW - timedelta(hours=3))
+# SAFETY-45's `headroom_w` is the last positional. It is set to a value that
+# CANNOT BIND on either call - larger than every sizing below - so this part
+# goes on grading OPT-09's per-pack sizing and not the capacity-tariff cap that
+# now sits beside it. test_arbitrage.py section 3b is where it is made to bind.
+_CLEAR_W = 1e9
 _sell = arbitrage._act(_Plan(_here), _NOW, _V(_other, _here), 60.0,
-                       0.0, 0.0, 20.0, 90.0)
+                       0.0, 0.0, 20.0, 90.0, _CLEAR_W)
 _sell_ok = arbitrage._act(_Plan(_here), _NOW, _V(_other, _here), 60.0,
-                          0.0, 4600.0, 20.0, 90.0)
+                          0.0, 4600.0, 20.0, 90.0, _CLEAR_W)
 _buy = arbitrage._act(_Plan(_here), _NOW, _V(_here, _other), 60.0,
-                      0.0, 0.0, 20.0, 90.0)
+                      0.0, 0.0, 20.0, 90.0, _CLEAR_W)
 _buy_ok = arbitrage._act(_Plan(_here), _NOW, _V(_here, _other), 60.0, 5000.0,
-                         0.0, 20.0, 90.0)
+                         0.0, 20.0, 90.0, _CLEAR_W)
 print(f"    sized at 0 W: sell -> {_sell.action}, buy -> {_buy.action}; "
       f"sized at a rating: sell -> {_sell_ok.action}, buy -> {_buy_ok.action}")
 check("⚠️ A TRADE NOTHING CAN TAKE IS NOT A TRADE. A 0 W sizing IDLES on both "

goodwe_controller/test_peakguard.py

@@ -138,8 +138,8 @@ from app.peakguard import (
     BLIND_COVERAGE, BLIND_FROZEN, BLIND_NO_BLOCK, CEILING_CAP,
     CEILING_MONTH_PEAK, FLOOR_AT_SOC_FLOOR, FLOOR_SOC_UNREADABLE,
     PEAK_OPTION_DEFAULTS, Pack, PeakDecision, binding_soc_floor, blindness,
-    decide, discharge_permitted, excess_w, pack_floor_pct, pack_permissions,
-    quarter_ceiling_w, uncovered_s,
+    charge_headroom_w, decide, discharge_permitted, excess_w, pack_floor_pct,
+    pack_permissions, quarter_ceiling_w, uncovered_s,
 )
 from app.validate import validate_startup_config
 from app.tariff import (
@@ -379,8 +379,17 @@ check("at the engagement boundary the excess is zero, so the floor is exactly "
 released = decide(p_edge, batt_w=BATT_NOW, cap_w=CAP_W, reading=None,
                   achievable_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S, soc=SOC_OK, soc_floor=SOC_FLOOR)
 would_release_on_excess = excess_w(p_edge, CEIL) <= 0.0
+# ⚠️ `floor_w` IS FORMATTED DEFENSIVELY, AND MUTATION.md's OWN LEDGER IS WHY.
+# The mutation this check exists for - reverting the `floor > 0` rung to
+# `excess > 0` - makes `floor_w` None HERE, so a bare `:.0f` raises TypeError
+# and ABORTS THE WHOLE FILE on the line after the check that just went red.
+# Parts 2-13 are then ungraded and the recorded coverage of that mutation is
+# smaller than the truth: exactly what MAINT-05's `delinquent(...)['b']`
+# subscript did to test_delivery.py, and habit 5 ("a check whose failure mode
+# is a hang - or a crash - needs a deadline, or a name") in the other costume.
 print(f"    at the boundary: excess {e_edge:.3f} W (an `excess > 0` test would "
-      f"RELEASE: {would_release_on_excess}), floor {released.floor_w:.0f} W "
+      f"RELEASE: {would_release_on_excess}), floor "
+      f"{'(none)' if released.floor_w is None else f'{released.floor_w:.0f} W'} "
       f"(the shipped `floor > 0` test holds: {released.engaged})")
 check("...and the claim is held there, not released. `excess` falls to zero as "
       "soon as the battery is already taking the watts, so thresholding IT is "
@@ -5947,6 +5956,281 @@ check("...and the row is green and un-warned, which is what makes the "
       "operator scrolls past", _rows38[0]["ok"] and not _rows38[0]["warn"]
       and _S38_CEIL_W - _S38_PROJ.projected_w == 2713.0)
 
+# ==============================================================================
+print()
+print("13. SAFETY-45 - charge_headroom_w(): the number decide() used to throw "
+      "away")
+# ---------------------------------------------------------------------------
+# `decide()` computes `wanted = batt_w + excess` - the DISCHARGE that lands the
+# quarter exactly on the ceiling - and returns `engaged=False, floor_w=None`
+# the moment that number is not positive. A negative `wanted` is not "nothing
+# to say": it is a permitted CHARGE of `-wanted` W, and discarding it is what
+# let an arbitrage charge sit at max_w against a quarter it was blowing.
+#
+# ⚠️ NOTHING IN decide() CHANGES IN THIS CARD, AND THAT IS THE POINT. The
+# `wanted <= 0` branch is 2026-08-20's anti-bang-bang rung and part 6's replay
+# is what proves it still holds; this part grades a PURE READ of the number it
+# already carried. 13g asserts the branch is still there rather than trusting
+# the diff.
+# ---------------------------------------------------------------------------
+
+def _proj_at(net_w, elapsed):
+    return PeakTracker.project(averager_at(net_w, elapsed),
+                               B + timedelta(seconds=elapsed))
+
+
+def _decide_on(projection, *, batt_w, soc=SOC_OK, cap_w=CAP_W,
+               achievable_w=LIVE_MAX_W, reading=None, frozen=False):
+    return decide(projection, batt_w=batt_w, cap_w=cap_w, reading=reading,
+                  achievable_w=achievable_w, soc=soc, soc_floor=SOC_FLOOR,
+                  max_hold_s=MAX_HOLD_S, frozen=frozen)
+
+
+def _decide_at(net_w, elapsed, **kw):
+    return _decide_on(_proj_at(net_w, elapsed), **kw)
+
+
+def _avg_held(base_w, elapsed, held_w, *, start=B, step=5.0):
+    """`elapsed` seconds BANKED at `base_w`, then `held_w` standing at the edge.
+
+    ⚠️ THE HISTORY AND THE HELD VALUE ARE SEPARATE FIXTURE AXES, and 13c is why
+    this helper exists rather than `averager_at(load - batt, ...)`. The averager
+    credits a sample from its own timestamp to the NEXT one, so the last sample
+    contributes ZERO accumulated seconds and only becomes `held`. That is the
+    real shape of a battery whose command changed a moment ago - the quarter's
+    banked seconds do not retroactively change - and a fixture that moved the
+    whole history with it would be grading a different quarter each time.
+    """
+    a = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+    t = 0.0
+    while t < elapsed:
+        a.add(sample(start + timedelta(seconds=t), base_w))
+        t += step
+    a.add(sample(start + timedelta(seconds=elapsed), held_w))
+    return a
+
+
+# --- 13a. the number, and it is DERIVED rather than read back ---------------
+# The house is flat at 2600 W under a 3500 W cap, the battery is idle, and 300 s
+# of the block are banked. 600 s remain, so the block can still absorb
+# 900 W x 900/600 = 1350 W of extra offtake and finish exactly on the ceiling.
+_H45_GAP = 900.0
+_H45_LOAD = CAP_W - _H45_GAP
+_H45_EL, _H45_REM = 300.0, QUARTER_S - 300.0
+_h45_idle = _decide_at(_H45_LOAD, _H45_EL, batt_w=0.0)
+_h45_head = charge_headroom_w(_h45_idle)
+# The CONSEQUENCE, computed from the fixture's own literals and not from the
+# module's arithmetic: hold that charge for the rest of the block and the
+# BILLED AVERAGE is the ceiling. This is the meaning of the number, which is a
+# different statement from the expression that produces it (habit 2).
+_H45_FINAL = (_H45_LOAD * _H45_EL
+              + (_H45_LOAD + _h45_head) * _H45_REM) / QUARTER_S
+print(f"    house {_H45_LOAD:.0f} W under a {CAP_W:.0f} W cap, battery 0 W, "
+      f"{_H45_EL:.0f} s banked: engaged={_h45_idle.engaged}, "
+      f"wanted={_h45_idle.wanted_w:+.0f} W, headroom={_h45_head:.0f} W")
+print(f"    holding that charge for the remaining {_H45_REM:.0f} s bills the "
+      f"block at {_H45_FINAL:.1f} W against a {CAP_W:.0f} W ceiling")
+check("the guard files NOTHING here - this is the shipped `wanted <= 0` branch, "
+      "untouched, and the state SAFETY-45 is about",
+      not _h45_idle.engaged and _h45_idle.floor_w is None
+      and _h45_idle.wanted_w is not None and _h45_idle.wanted_w < 0.0)
+check(f"...and yet the quarter can afford {_h45_head:.0f} W of charging, which "
+      f"is the number that was being discarded. Graded by its CONSEQUENCE - "
+      f"the block lands on the ceiling to the watt - rather than by "
+      f"re-deriving -wanted_w with the module's own formula",
+      near(_H45_FINAL, CAP_W, 0.5))
+check(f"...and it is none of the other numbers this fixture has: not the cap "
+      f"({CAP_W:.0f}), not max_w ({LIVE_MAX_W:.0f}), not the house "
+      f"({_H45_LOAD:.0f}) and not the raw gap under the ceiling "
+      f"({_H45_GAP:.0f}) - the 900/remaining gain is 1.5 here and a check that "
+      f"could not tell those apart would be decoration",
+      not any(near(_h45_head, v, 1.0)
+              for v in (CAP_W, LIVE_MAX_W, _H45_LOAD, _H45_GAP)))
+
+# --- 13a2. AND THE IDENTITY HOLDS ACROSS THE WHOLE BLOCK --------------------
+# ⚠️ THE AMPLIFICATION IS REAL AND IT IS REPORTED WITH ITS SIZE (habit 13).
+# 900/remaining reaches 180 in the last five seconds, so the headroom there is
+# enormous - and it is bounded in EFFECT, not in magnitude: at every elapsed,
+# holding it bills the block at exactly the ceiling.
+H45_ID = []
+for _el in (0.0, 60.0, 300.0, 600.0, 870.0, 895.0):
+    _rem = QUARTER_S - _el
+    _hd = charge_headroom_w(_decide_at(_H45_LOAD, _el, batt_w=0.0))
+    H45_ID.append((_el, _hd,
+                   (_H45_LOAD * _el + (_H45_LOAD + _hd) * _rem) / QUARTER_S))
+print("    headroom across the block (elapsed, headroom W, billed W): "
+      + ", ".join(f"({a:.0f}, {b:.0f}, {c:.1f})" for a, b, c in H45_ID))
+check("at EVERY point in the block, holding the headroom for the rest of it "
+      "bills the block at exactly the ceiling - so the 162 kW answer five "
+      "seconds from the boundary and the 900 W answer at the top of it are the "
+      "same statement about the bill",
+      all(near(c, CAP_W, 0.5) for _, _, c in H45_ID))
+check("...and the fixture SPANS the amplification rather than sitting in one "
+      f"corner of it: the headroom moves by a factor of "
+      f"{max(b for _, b, _ in H45_ID) / min(b for _, b, _ in H45_ID):.0f} "
+      f"across those six points",
+      max(b for _, b, _ in H45_ID) > 100.0 * min(b for _, b, _ in H45_ID))
+
+# --- 13b. HOLDING implies ZERO OR UNKNOWN, swept - the family, not one case -
+# ⚠️ THE PROPERTY THAT MAKES THIS SAFE TO HAND A STRATEGY. Every state that
+# files a claim has `wanted > 0`, `wanted is None` or `blind`, so this function
+# can never hand a caller permission the guard's own `lo` is at that instant
+# refusing. Swept over the same grid part 5's no-negative-floor proof uses,
+# widened with the two ways a cycle can fail to measure at all.
+H45_N = H45_BAD = H45_POS = H45_NONE = H45_ZERO = 0
+for _load in (0.0, CAP_W - 500.0, CAP_W, CAP_W + 300.0, CAP_W + 3000.0,
+              LIVE_MAX_W * 3):
+    for _el in (30.0, 450.0, 870.0):
+        for _bw in (-LIVE_MAX_W, -2000.0, 0.0, 400.0, 4000.0, None):
+            for _sc in (None, BMS_FLOOR, SOC_FLOOR, SOC_FLOOR + 0.5, 100.0):
+                for _fz in (False, True):
+                    _d45 = _decide_at(_load, _el, batt_w=_bw, soc=_sc,
+                                      frozen=_fz)
+                    _hr = charge_headroom_w(_d45)
+                    H45_N += 1
+                    if _hr is None:
+                        H45_NONE += 1
+                    elif _hr > 0.0:
+                        H45_POS += 1
+                    else:
+                        H45_ZERO += 1
+                    if _d45.engaged and _hr not in (None, 0.0):
+                        H45_BAD += 1
+print(f"    swept {H45_N} (load x elapsed x battery x SoC x frozen) "
+      f"combinations: {H45_BAD} ENGAGED decisions answering a positive "
+      f"headroom; {H45_POS} permit charging, {H45_ZERO} answer 0 W, "
+      f"{H45_NONE} unmeasured")
+check(f"NOT ONE of the {H45_N} combinations answers a positive headroom while "
+      f"the guard is ENGAGED. A decision whose `lo` is at that instant "
+      f"forbidding charging can never be read as permission to charge",
+      H45_BAD == 0 and H45_N > 800)
+check("...and the sweep is vacuous in no direction: it reaches decisions that "
+      f"permit charging ({H45_POS}), decisions that permit none ({H45_ZERO}) "
+      f"and decisions nothing measured ({H45_NONE}), so all three answers are "
+      f"exercised", H45_POS > 0 and H45_ZERO > 0 and H45_NONE > 0)
+
+# --- 13c. IT IS INVARIANT IN THE BATTERY, WHICH IS WHY SIZING A TRADE TO IT
+#          CANNOT OSCILLATE -------------------------------------------------
+# 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. The headroom is a
+# FEED-FORWARD number - a function of the house, the ceiling and the seconds
+# already banked - so consuming it adds no feedback path around the plant.
+# Without this property the whole fix would be one loop replacing another.
+H45_INV, H45_EX = [], []
+for _bw in (-LIVE_MAX_W, -2000.0, -500.0, 0.0, 500.0, 2000.0):
+    # ONE banked history, and the battery's change visible only in the HELD
+    # value - which is what a command given a moment ago actually looks like.
+    _d = _decide_on(PeakTracker.project(
+        _avg_held(_H45_LOAD, _H45_EL, _H45_LOAD - _bw),
+        B + timedelta(seconds=_H45_EL)), batt_w=_bw)
+    H45_INV.append(charge_headroom_w(_d))
+    H45_EX.append(round(_d.excess_w, 1))
+print(f"    same house, same banked quarter, battery {-LIVE_MAX_W:+.0f}.."
+      f"{2000.0:+.0f} W: headroom {[round(v, 3) for v in H45_INV]}")
+print(f"    ...while the EXCESS those runs see is {H45_EX}")
+check("the headroom does NOT move when the battery moves across the whole "
+      "range of what it can do - it is a property of the HOUSE and the "
+      "CEILING, not of what the battery happens to be doing, which is what "
+      "makes a trade sized from it feed-forward rather than a second loop "
+      "around the plant",
+      max(H45_INV) - min(H45_INV) < 1.0)
+check(f"...and the fixture SEPARATES it from the two quantities it is built "
+      f"out of: the battery moved {LIVE_MAX_W + 2000.0:.0f} W and the excess "
+      f"with it, over {len(set(H45_EX))} distinct values, so an implementation "
+      f"answering `-batt_w` or `abs(excess)` would give six different answers "
+      f"here (habit 4)",
+      len(set(H45_EX)) == len(H45_EX)
+      and len(set(round(v, 3) for v in H45_INV)) == 1)
+
+# --- 13d. AND A BOUNDARY HANDS IT BACK AT THE AFFORDABLE RATE, NOT AT max_w --
+# ⚠️ SAFETY-45's SECOND HALF, AND THE CLAIM IS NOT "IT DOES NOT CHANGE".
+# `project()` resets to the held level at `elapsed = 0`, and the headroom
+# collapses with it - from 162 kW to 900 W here. What the card is about is WHAT
+# IT COLLAPSES TO: the house and the cap, and nothing else. The behaviour being
+# removed re-armed at `max_w` regardless of either.
+_H45_END = charge_headroom_w(_decide_at(_H45_LOAD, 895.0, batt_w=0.0))
+_H45_TOP = charge_headroom_w(_decide_at(_H45_LOAD, 0.0, batt_w=0.0))
+print(f"    across a boundary, same house: {_H45_END:.0f} W with 5 s of the "
+      f"old quarter left -> {_H45_TOP:.0f} W with the new one 0 s old, against "
+      f"a max_w of {LIVE_MAX_W:.0f} W")
+check(f"at the top of the new quarter the headroom is exactly the ceiling less "
+      f"the house ({CAP_W:.0f} - {_H45_LOAD:.0f} = {_H45_GAP:.0f} W). A trade "
+      f"refused at 14:59 resumes at 15:00 at the rate the new quarter can "
+      f"afford - the projection resets, this does not reset TO max_w",
+      near(_H45_TOP, _H45_GAP, 1.0) and _H45_TOP < LIVE_MAX_W)
+check("...and the check is not passing because nothing moved: the headroom on "
+      "the other side of that boundary is two orders of magnitude larger, and "
+      "the PROJECTION really did reset",
+      _H45_END > 100.0 * _H45_TOP and _proj_at(_H45_LOAD, 0.0).elapsed_s < 1.0)
+
+# --- 13e. the unmeasured answers, and None is NOT unlimited -----------------
+_h45_nobatt = _decide_at(_H45_LOAD, _H45_EL, batt_w=None)
+_h45_blind = _decide_at(_H45_LOAD, _H45_EL, batt_w=0.0, frozen=True)
+print(f"    no battery reading: {charge_headroom_w(_h45_nobatt)}; "
+      f"BLIND: {charge_headroom_w(_h45_blind)}; no decision at all: "
+      f"{charge_headroom_w(None)}")
+check("a guard that never ran answers None, not a number - `meter_source: off` "
+      "reaches this with no decision at all and a caller that read it as a "
+      "large headroom would be guard_state()'s None-is-not-False collapse one "
+      "layer down", charge_headroom_w(None) is None)
+check("...and a cycle with NO BATTERY MEASUREMENT answers None too: there is "
+      "nothing to size a floor from, so there is nothing to size a trade from "
+      "either", charge_headroom_w(_h45_nobatt) is None
+      and _h45_nobatt.wanted_w is None)
+check("...and BLIND answers 0.0 - a NUMBER, and the number is no charging. "
+      "The claim it files already says exactly that at `floor 0 W`, and this "
+      "agrees with it rather than restating it",
+      charge_headroom_w(_h45_blind) == 0.0 and _h45_blind.blind
+      and _h45_blind.floor_w == 0.0)
+check("...and the three are TOLD APART: blind is 0.0 and the two unmeasured "
+      "states are None, so a caller can refuse for the reason that is true "
+      "rather than for whichever fired first",
+      charge_headroom_w(_h45_blind) is not None
+      and charge_headroom_w(_h45_nobatt) is None)
+
+# --- 13f. the SoC floor does not become charging permission -----------------
+# ⚠️ THE ONE ENGAGED STATE WHERE THE GUARD IS DELIBERATELY NOT DISCHARGING.
+# SAFETY-24's floor-limited decision files `lo = 0.0` - "charging stays
+# blocked" - on a quarter that IS over the ceiling. If that read as headroom,
+# an empty pack in a blown quarter would be told to buy.
+_h45_lim = _decide_at(CAP_W + 2000.0, _H45_EL, batt_w=0.0, soc=SOC_FLOOR - 1.0)
+print(f"    floor-limited over a blown quarter: engaged={_h45_lim.engaged}, "
+      f"floor_limited={_h45_lim.floor_limited}, wanted="
+      f"{_h45_lim.wanted_w:+.0f} W, headroom={charge_headroom_w(_h45_lim)}")
+check("a FLOOR-LIMITED decision - the guard wanted a discharge and SoC refused "
+      "to size it - answers 0.0 headroom. The quarter is over the ceiling; the "
+      "pack being empty is not a reason to fill it from the grid in it",
+      _h45_lim.floor_limited and _h45_lim.engaged
+      and charge_headroom_w(_h45_lim) == 0.0)
+
+# --- 13g. decide() ITSELF IS UNCHANGED, PINNED -----------------------------
+# ⚠️ MUTATION.md habit 4, in the direction a diff cannot cover. The whole safety
+# argument of this card is "the 2026-08-20 rung is still there and part 6 still
+# grades it". That is a claim about the SOURCE, so it is pinned on the source -
+# and on the BEHAVIOUR, because a shape pin alone would pass a rung that had
+# been inverted.
+_H45_SRC = (HERE / "app" / "peakguard.py").read_text(encoding="utf-8")
+_H45_TREE = ast.parse(_H45_SRC)
+_h45_fn = next(n for n in ast.walk(_H45_TREE)
+               if isinstance(n, ast.FunctionDef) and n.name == "decide")
+_H45_RUNG = [n for n in ast.walk(_h45_fn) if isinstance(n, ast.If)
+             and ast.unparse(n.test) == "wanted <= 0.0"]
+check("the `wanted <= 0.0` rung is still in decide(), spelled exactly that "
+      "way, on the AST rather than as a substring - it is the rung whose "
+      "removal put 2026-08-20's quarter 49 W over the limit after seventeen "
+      "engage/release cycles in 900 s", len(_H45_RUNG) == 1)
+check("...and it still DISENGAGES rather than merely reporting: the fixture "
+      "13a is built on reaches it and files no claim, so the pin above is not "
+      "grading a rung that has been inverted under it",
+      peakguard.claim(_h45_idle) is None)
+_h45_head_fn = next(n for n in _H45_TREE.body if isinstance(n, ast.FunctionDef)
+                    and n.name == "charge_headroom_w")
+check("...and charge_headroom_w() is a PURE READ of the decision - one "
+      "positional parameter, no projection, no clock and no options - so it "
+      "cannot become a second answer to the question decide() already answers",
+      [a.arg for a in _h45_head_fn.args.args] == ["decision"]
+      and not _h45_head_fn.args.kwonlyargs)
+
 # ==============================================================================
 print()
 shutil.rmtree(TMP, ignore_errors=True)

goodwe_controller/test_price_forecast.py

@@ -1107,21 +1107,59 @@ _OPT04_KEYS = ["arbitrage_enabled", "cycle_cost_threshold_eur",
 # in config.yaml and nowhere else, which is the arrangement `static_profile`
 # already has for the same reason.
 _T15_KEYS = ["price_formula"]
-check(f"the in-code mirror holds exactly TARIFF-02's, TARIFF-03's, OPT-04's "
-      f"and TARIFF-15's keys - FCST-03 still added none of its own "
-      f"{_defaults}",
+# TARIFF-17 added the sixth, and comes here to say so as the comment above
+# instructs. `price_taxes_profile` is the hour-varying spelling of
+# `price_taxes_eur_kwh` - a period table of the TAXES component, for the Walloon
+# and Brussels DSOs whose distribution tariff really does have a day and a night
+# band (ORES 13,27 / 7,39 c EUR/kWh). It is an ADDITION and not a replacement:
+# the scalar is untouched, every site on it is unaffected, and validate.py
+# refuses the configuration that sets both. It lives in this dict and in
+# config.yaml and nowhere else, which is `static_profile`'s arrangement for
+# `static_profile`'s reason.
+_T17_KEYS = ["price_taxes_profile"]
+# TARIFF-16. `price_export_formula` - the INJECTION leg as `factor x index +
+# offset` with its OWN coefficients and its OWN vat_pct, because a Belgian card
+# prices injection on a second formula (Eneco 0,100 against 0,102 on
+# consumption, VAT-exempt against 6%). Like TARIFF-17's key it is an ADDITION:
+# `export_price_eur_kwh` is untouched, every site on the scalar is unaffected,
+# and it lives in this dict and in config.yaml and nowhere else.
+_T16_KEYS = ["price_export_formula"]
+check(f"the in-code mirror holds exactly TARIFF-02's, TARIFF-03's, OPT-04's, "
+      f"TARIFF-15's, TARIFF-17's and TARIFF-16's keys - FCST-03 still added "
+      f"none of its own {_defaults}",
       _defaults == sorted(["price_provider", "price_markup_eur_kwh",
                            "price_taxes_eur_kwh", "export_price_eur_kwh",
                            "price_csv_path", "price_feed_url",
                            "price_horizon_h", "price_timeout_s",
-                           "static_profile"] + _OPT04_KEYS + _T15_KEYS))
+                           "static_profile"]
+                          + _OPT04_KEYS + _T15_KEYS + _T17_KEYS
+                          + _T16_KEYS))
 # ...and the later keys are genuinely NEW, not a rename of something that was
 # already there, or the line above would pass while the mirror silently lost a
 # key.
-check("...and OPT-04's four and TARIFF-15's one are additions rather than "
-      "replacements: the nine TARIFF-02/03 keys are all still present",
+check("...and OPT-04's four, TARIFF-15's one, TARIFF-17's one and TARIFF-16's "
+      "one are additions rather than replacements: the nine TARIFF-02/03 keys "
+      "are all still present",
       isinstance(_defaults, list)
-      and len(set(_defaults) - set(_OPT04_KEYS) - set(_T15_KEYS)) == 9)
+      and len(set(_defaults) - set(_OPT04_KEYS) - set(_T15_KEYS)
+              - set(_T17_KEYS) - set(_T16_KEYS)) == 9)
+# ⚠️ AND THE ONE TARIFF-17 IS THE HOUR-VARYING TWIN OF IS STILL THERE, BY NAME.
+# The line above counts nine, and a rename of `price_taxes_eur_kwh` to
+# `price_taxes_profile` would also count nine. The scalar path being unchanged
+# is this card's first acceptance criterion, and a count cannot grade it.
+# ⚠️ THE LITERAL 0.11736 IS TARIFF-18's, AND IT IS TYPED HERE ON PURPOSE. The
+# claim is "the scalar is still its own key, holding its own real number", and
+# reading that number out of the dict under test would compare it against
+# itself. TARIFF-18 raised it from 0.06; if it moves again this line goes red
+# and whoever moved it comes here and says which card.
+check("...and `price_taxes_eur_kwh` is still its own key beside the table, so "
+      "TARIFF-17 widened the framework rather than renaming the scalar - and "
+      "it still holds TARIFF-18's Flemish figure",
+      isinstance(_defaults, list)
+      and "price_taxes_eur_kwh" in _defaults
+      and "price_taxes_profile" in _defaults
+      and _price.PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"] == 0.11736
+      and _price.PRICE_OPTION_DEFAULTS["price_taxes_profile"] == "")
 check("...and every one of them is still in config.yaml, which stays the "
       "source of truth",
       isinstance(_cfg, str)

goodwe_controller/test_static_tariff.py

@@ -59,6 +59,7 @@ is TEST-15, and it has already turned one live mutation into a false survivor.
 Read MUTATION.md before you report a survivor.
 """
 
+import ast
 import gzip
 import json
 import sys
@@ -71,8 +72,9 @@ from app.price import (
 )
 from app.price_history import NoHistory
 from app.static_tariff import (
-    MEAN_WINDOW_DAYS, ProfileInvalid, StaticProfile, TariffPlan,
-    parse_static_profile, resolve_tariff, static_plan, static_status,
+    MEAN_WINDOW_DAYS, ProfileInvalid, StaticProfile, TAXES_PROFILE_OPTION,
+    TariffPlan, parse_static_profile, parse_taxes_profile, resolve_tariff,
+    static_plan, static_status,
 )
 from app.validate import validate_startup_config
 
@@ -87,6 +89,16 @@ def check(name, cond):
         fails.append(name)
 
 
+def _reason_of(fn):
+    """The message fn() raised, or "" - so a check can assert WHICH rule
+    refused rather than only that something did (MUTATION.md habit 6)."""
+    try:
+        fn()
+    except Exception as e:                                    # noqa: BLE001
+        return str(e)
+    return ""
+
+
 def raises(fn, exc):
     """True only if fn() raises EXACTLY `exc`. A different exception is False -
     'it was refused' and 'it broke on the way to being refused' must not grade
@@ -1130,6 +1142,189 @@ check("...and the table really does exercise both rungs and the allowing path, "
       {want for _n, _p, want in _TABLE9} == {"flat", "firm-pair", "allowed"})
 
 
+
+# --------------------------------------------------------------------------- #
+print()
+print("10. TARIFF-17 - ONE period grammar, not two. A second tiling rule is a "
+      "second set of DST bugs")
+# ⚠️ THE ACCEPTANCE CRITERION THIS GRADES, and why it needs two checks rather
+# than one. `price_taxes_profile` carries the TAXES component as a period table
+# so that a Walloon day/night distribution band can reach the optimiser. The
+# obvious way to build it is a second parser next to this one - and the two
+# would agree on every ordinary day and diverge on the 23- and 25-hour days,
+# where nobody looks and where §11.4 makes the divergence quiet.
+#
+# So the claim is an IDENTITY ("it is this grammar"), and MUTATION.md habit 10
+# says pin an identity structurally and a meaning behaviourally. Both are here:
+#   10a  the grammar family is DEFINED IN EXACTLY ONE MODULE, computed by
+#        parsing every file under app/ rather than by a list somebody typed;
+#   10b  the two options produce the SAME REFUSAL SENTENCES, derived from each
+#        other, which is what a fork would break first.
+
+print()
+print("10a. the grammar is defined in exactly one module under app/, and the "
+      "scope is COMPUTED")
+# ⚠️ A HAND-WRITTEN SCOPE IS THE SAME DEFECT AS A HAND-WRITTEN FIXTURE
+# (habit 12): it passes while the copy sits in the file nobody added to the
+# list. Every `app/*.py` is parsed; the family is taken from THIS module's own
+# top-level names, so it cannot drift from what the grammar actually is.
+#
+# ⚠️ AND THE FAMILY LIST HAS ONE DELIBERATE OMISSION, STATED HERE RATHER THAN
+# ROUNDED OFF (habit 13). `_days` is NOT in it, because `maintenance.py` has a
+# `_days` of its own - a NAMESAKE, not a copy - and the check below would go
+# red on it and be deleted by whoever hit it. The namesake is asserted to BE a
+# namesake, by signature, immediately afterwards, so the omission is graded
+# rather than assumed.
+_T17_FAMILY = ("Period", "StaticProfile", "ProfileInvalid", "_check_tiling",
+               "_raise_gap", "_raise_overlap", "_minutes", "_price",
+               "parse_static_profile", "DAY_NAMES", "MINUTES_PER_DAY",
+               "_DAY_INDEX", "_DAY_ALIASES", "SUPPORTED_TZ")
+
+
+def _t17_defs(path):
+    """Top-level names a module DEFINES - classes, functions and assignments."""
+    tree = ast.parse(path.read_text(encoding="utf-8"))
+    out = set()
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef,
+                             ast.ClassDef)):
+            out.add(node.name)
+        elif isinstance(node, ast.Assign):
+            out |= {t.id for t in node.targets if isinstance(t, ast.Name)}
+    return out
+
+
+_T17_APP = sorted((HERE / "app").glob("*.py"))
+_T17_WHERE = {name: sorted(p.name for p in _T17_APP if name in _t17_defs(p))
+              for name in _T17_FAMILY}
+for _n, _w in sorted(_T17_WHERE.items()):
+    print(f"    {_n:<22} defined in {_w}")
+check(f"every one of the {len(_T17_FAMILY)} grammar names is defined in "
+      f"EXACTLY ONE of the {len(_T17_APP)} modules under app/ - a copy of "
+      f"`_check_tiling` in price.py would take this red",
+      all(len(w) == 1 for w in _T17_WHERE.values()))
+check("...and that module is static_tariff.py in every case, so the grammar "
+      "did not move house either",
+      {w[0] for w in _T17_WHERE.values() if w} == {"static_tariff.py"})
+check("...and the pin is not vacuous: each of those names really is a "
+      "top-level definition, so the scan found something rather than nothing",
+      all(w for w in _T17_WHERE.values()) and len(_T17_APP) > 5)
+
+
+def _t17_sig(module, name):
+    tree = ast.parse((HERE / "app" / module).read_text(encoding="utf-8"))
+    fn = next(n for n in tree.body
+              if isinstance(n, ast.FunctionDef) and n.name == name)
+    return [a.arg for a in fn.args.args]
+
+
+_T17_DAYS = (_t17_sig("static_tariff.py", "_days"),
+                            _t17_sig("maintenance.py", "_days"))
+print(f"    _days: static_tariff{_T17_DAYS[0]} vs maintenance{_T17_DAYS[1]}")
+check(f"...and the ONE name held out of the family is held out honestly: "
+      f"`maintenance._days{tuple(_T17_DAYS[1])}` renders an age in words and "
+      f"is not a second copy of the grammar's "
+      f"`_days{tuple(_T17_DAYS[0])}` day selector",
+      _T17_DAYS[0] != _T17_DAYS[1] and _T17_DAYS[0] == ["value", "field"]
+      and _T17_DAYS[1] == ["n"])
+# ⚠️ WHAT THIS PIN CANNOT SEE, WITH ITS SHAPE (habit 13). It grades WHERE the
+# grammar is defined, never WHAT it means: `_check_tiling` could be rewritten
+# in place to accept a gap and this would still pass. Section 5 and 10b are
+# what grade the meaning. It also covers `app/` only, and a second grammar
+# living under `tools/` or in a check file is outside it.
+
+_T17_BODY = ast.parse(
+    (HERE / "app" / "static_tariff.py").read_text(encoding="utf-8"))
+_T17_WRAP = next(
+    (n for n in _T17_BODY.body
+     if isinstance(n, ast.FunctionDef) and n.name == "parse_taxes_profile"),
+    None)
+_T17_CALLS = ([ast.unparse(n.func) for n in ast.walk(_T17_WRAP)
+               if isinstance(n, ast.Call)] if _T17_WRAP else [])
+check(f"...and `parse_taxes_profile` is a WRAPPER and not a fork: its whole "
+      f"body calls {_T17_CALLS}, pinned on the AST rather than on the source "
+      f"text, because `\"parse_static_profile\" in src` is true of a copy that "
+      f"merely mentions it",
+      _T17_CALLS == ["parse_static_profile"])
+
+
+print()
+print("10b. and the two options give the SAME refusals - derived from each "
+      "other, not typed twice")
+# ⚠️ EVERY EXPECTED SENTENCE HERE IS THE OTHER OPTION'S OWN SENTENCE with the
+# key substituted. Nothing is transcribed, so a fork that reworded one refusal
+# - or that quietly stopped refusing something - is red on the row it broke and
+# not on all of them.
+_T17_BAD = [
+    ("a gap", {"periods": [{"name": "d", "from": "07:00", "to": "22:00",
+                            "days": "all", "eur_per_kwh": 0.13}]}),
+    ("an overlap", {"periods": [
+        {"name": "a", "from": "00:00", "to": "24:00", "days": "all",
+         "eur_per_kwh": 0.13},
+        {"name": "b", "from": "07:00", "to": "22:00", "days": "all",
+         "eur_per_kwh": 0.07}]}),
+    ("a bad HH:MM", {"periods": [{"name": "d", "from": "7.5", "to": "22:00",
+                                  "days": "all", "eur_per_kwh": 0.13}]}),
+    ("a bad day", {"periods": [{"name": "d", "from": "00:00", "to": "24:00",
+                                "days": "funday", "eur_per_kwh": 0.13}]}),
+    ("missing days", {"periods": [{"name": "d", "from": "00:00", "to": "24:00",
+                                   "eur_per_kwh": 0.13}]}),
+    ("a zero-length window", {"periods": [
+        {"name": "d", "from": "07:00", "to": "07:00", "days": "all",
+         "eur_per_kwh": 0.13}]}),
+    ("no periods list", {"timezone": "europe/brussels"}),
+    ("an empty periods list", {"periods": []}),
+    ("a foreign timezone", {"timezone": "utc", "periods": []}),
+    ("periods that are not a list", {"periods": 3}),
+    ("a row that is not an object", {"periods": ["dag"]}),
+    ("invalid JSON", "{not json"),
+    ("a 24:00 start", {"periods": [{"name": "d", "from": "24:00", "to": "07:00",
+                                    "days": "all", "eur_per_kwh": 0.13}]}),
+]
+_T17_ROWS = []
+for _what, _bad in _T17_BAD:
+    _a = _reason_of(lambda: parse_static_profile(_bad))
+    _b = _reason_of(lambda: parse_taxes_profile(_bad))
+    _T17_ROWS.append((_what, _a, _b,
+                      _a.replace("static_profile", TAXES_PROFILE_OPTION) == _b))
+for _what, _a, _b, _same in _T17_ROWS:
+    print(f"    {'ok ' if _same else 'XX '}{_what:<28} {_b[:74]}")
+check(f"all {len(_T17_ROWS)} malformations are refused IDENTICALLY under both "
+      f"options, sentence for sentence, once the key name is substituted - "
+      f"which is what one parser means and a fork could not hold",
+      all(row[3] for row in _T17_ROWS))
+check("...and every one of them really did refuse, or 'the two agree' would be "
+      "two empty strings agreeing",
+      all(row[1] and row[2] for row in _T17_ROWS))
+check("...and the sentences are not all the same sentence, or the row above "
+      "would be one comparison repeated 13 times",
+      len({row[2] for row in _T17_ROWS}) == len(_T17_ROWS))
+
+# ⚠️ THE ONE REFUSAL THAT IS DELIBERATELY DIFFERENT, and it is different
+# because the two options carry different QUANTITIES in the same grammar. A
+# period without `eur_per_kwh` gets a sentence naming what was wanted, and an
+# operator who typed an ALL-IN price into the taxes table is out by an energy
+# price with nothing reporting it.
+_T17_NOPRICE = {"periods": [{"name": "d", "from": "00:00", "to": "24:00",
+                             "days": "all"}]}
+_T17_M_S = _reason_of(lambda: parse_static_profile(_T17_NOPRICE))
+_T17_M_T = _reason_of(lambda: parse_taxes_profile(_T17_NOPRICE))
+print(f"    static_profile : {_T17_M_S[-96:]}")
+print(f"    taxes table    : {_T17_M_T[-96:]}")
+check("the 'you left the number out' refusal is the one sentence the two do "
+      "NOT share, and each names its own quantity: an all-in price for "
+      "static_profile, the taxes component alone for the table",
+      "an all-in eur_per_kwh" in _T17_M_S
+      and "an all-in eur_per_kwh" not in _T17_M_T
+      and "TAXES component alone" in _T17_M_T
+      and "NOT an all-in price" in _T17_M_T
+      and _T17_M_S.replace("static_profile", TAXES_PROFILE_OPTION) != _T17_M_T)
+check("...and both still name the ROW the operator has to go and fix, which is "
+      "the half they do share",
+      "periods[1].eur_per_kwh is missing" in _T17_M_S
+      and "periods[1].eur_per_kwh is missing" in _T17_M_T)
+
+
 # --------------------------------------------------------------------------- #
 print()
 if fails:

goodwe_controller/test_telemetry.py

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

goodwe_controller/test_translations.py

@@ -147,6 +147,16 @@ DERIVED = {
     # where the ratio came from - a citation alone would leave an operator
     # reading "0" on the tab with no idea it is not "off".
     "slew_w": ("SAFETY-39", "DERIVED", "0 MEANS FOLLOW"),
+    # TARIFF-18. `price_taxes_eur_kwh` joins the table for `slew_w`'s reason:
+    # it stopped being a figure somebody picked and became one SUMMED FROM
+    # NAMED CARD ROWS. Three needles, because three different things about it
+    # can go wrong on the Configuration tab and only the first is provenance:
+    # where the number came from, that the operator's own DSO gives a
+    # different one, and that changing it moves no trade - which is the claim
+    # an operator is most likely to assume the opposite of when a number
+    # doubles.
+    "price_taxes_eur_kwh": ("TARIFF-18", "YOUR OWN DSO",
+                            "MOVES NO TRADING DECISION"),
 }
 _uncited = []
 for key, needles in sorted(DERIVED.items()):

goodwe_controller/test_validate.py

@@ -18,7 +18,10 @@ import asyncio
 import sys
 
 from app.maintenance import MAINT_OPTION_DEFAULTS, MaintConfig
+from app.price import (
+    PRICE_OPTION_DEFAULTS, SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
 from app.control import LOOP_TICK_S, PLANT_SETTLE_S, SLEW_RAIL_FRAC
+from app import shadow
 from app.validate import (
     ACTUATOR_WRITE_KEYS, FIRMWARE_INGEST_VETO_S, ConfigRefused,
     actuator_writers, refuse, site_rail_w, validate_startup_config,
@@ -1366,6 +1369,444 @@ check("...and the flat single-inverter config it always refused is refused "
                                   -5000, 5000) == [])
 
 
+
+# --------------------------------------------------------------------------- #
+print()
+print("TARIFF-17 - the taxes period table is refused HERE, at startup, and not "
+      "at 03:00")
+# ⚠️ WHY IT IS REFUSED IN THIS MODULE AND NOT AT FETCH TIME. `price.assemble()`
+# reads this table on the ~30 s planning path. A table that only fails when a
+# fetch happens is a site that stops pricing mid-afternoon, and §11.4 turns
+# that into a quiet fallback indistinguishable on the status page from a
+# healthy fixed-tariff day. That is `static_profile`'s argument, one option
+# over, and this is the same rule.
+_T17_DAG, _T17_NACHT = 0.1327, 0.0739
+_T18_SHIPPED_TAXES = PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"]
+_T18_SUPERSEDED = tuple(SUPERSEDED_TAXES_DEFAULTS_EUR_KWH)
+_T17_OK = ('{"periods":['
+           '{"name":"dag","from":"07:00","to":"22:00","days":"mon-fri",'
+           f'"eur_per_kwh":{_T17_DAG}}},'
+           '{"name":"nacht","from":"22:00","to":"07:00","days":"mon-fri",'
+           f'"eur_per_kwh":{_T17_NACHT}}},'
+           '{"name":"nacht","from":"00:00","to":"24:00","days":"sat,sun",'
+           f'"eur_per_kwh":{_T17_NACHT}}}]}}')
+
+# ⚠️ THE ACCEPTED BASELINE COMES FIRST (MUTATION.md habit 7). Every refusal
+# below varies ONE thing from this line, so a refusal on the next line has
+# nowhere else to have come from.
+check("ORES's real dag/nacht table STARTS - it is a valid configuration, and "
+      "the refusals below are one edit away from this one",
+      validate_startup_config(base(price_taxes_profile=_T17_OK),
+                              -5000, 5000) == [])
+check("...and so does the shipped \"\", which is every install that exists: "
+      "the option is an addition, not a requirement",
+      validate_startup_config(base(price_taxes_profile=""), -5000, 5000) == []
+      and validate_startup_config(base(), -5000, 5000) == [])
+
+_T17_GAP = ('{"periods":[{"name":"dag","from":"07:00","to":"22:00",'
+            f'"days":"all","eur_per_kwh":{_T17_DAG}}}]}}')
+_T17_P_GAP = validate_startup_config(base(price_taxes_profile=_T17_GAP),
+                                     -5000, 5000)
+print(f"    {(_T17_P_GAP or [''])[0][:120]}")
+check("a table that leaves 00:00-07:00 unpriced is REFUSED, by the same tiling "
+      "rule static_profile has - and the refusal names the KEY and the HOURS, "
+      "not merely that something was wrong",
+      why(_T17_P_GAP, "price_taxes_profile cannot be used:")
+      and why(_T17_P_GAP, "leaves mon 00:00-07:00 with no period"))
+check("...and it is refused for THAT reason and not as a side effect of "
+      "something else this fixture happens to break: exactly one problem",
+      len(_T17_P_GAP) == 1)
+
+# ⚠️ TWO WRITERS OF ONE QUANTITY, ONE OF WHICH SILENTLY WINS. The table decides
+# when it is set, so a scalar left at a NON-DEFAULT value beside it is a number
+# the operator typed that changes nothing - on the quantity §11.4 makes hardest
+# to notice.
+_T17_P_BOTH = validate_startup_config(
+    base(price_taxes_profile=_T17_OK, price_taxes_eur_kwh=0.1198), -5000, 5000)
+print(f"    {(_T17_P_BOTH or [''])[0][:120]}")
+check("the table AND a non-default price_taxes_eur_kwh is refused, and the "
+      "refusal says WHICH ONE WINS and what to do - not merely that the two "
+      "are incompatible",
+      why(_T17_P_BOTH, "price_taxes_profile is set AND price_taxes_eur_kwh is "
+                       "0.1198")
+      and why(_T17_P_BOTH, "THE TABLE WINS"))
+check("...and the SHIPPED scalar beside the table is NOT refused, or every "
+      "Walloon site would have to clear a key it never touched. The refusal is "
+      "about a value the operator chose, and the shipped default is the one "
+      "they did not",
+      validate_startup_config(
+          base(price_taxes_profile=_T17_OK,
+               price_taxes_eur_kwh=_T18_SHIPPED_TAXES),
+          -5000, 5000) == []
+      and len(_T17_P_BOTH) == 1)
+
+# ⚠️ TARIFF-18 - "UNTOUCHED" IS A SET, AND THIS IS THE HALF THAT DECIDES
+# WHETHER AN UPGRADE STOPS A RUNNING SITE. The Supervisor sets `App.options =
+# deepmerge(config.yaml defaults, stored options)`, so a saved blob carries
+# every schema key whether the operator typed it or not - the reference
+# install's export is 70 of 71 (CHANGELOG 0.9.0). When TARIFF-18 moved this
+# default 0.06 -> 0.11736, every such blob went from "equal to the shipped
+# default" to "not equal to it" WITHOUT ANYBODY EDITING ANYTHING. A site that
+# also carries a taxes table would have met `SystemExit(78)` on the upgrade,
+# over a number it never typed and that decides nothing. So a SUPERSEDED
+# default still reads as untouched.
+#
+# ⚠️ AND THE PRECONDITION FIRST (MUTATION.md habit 1): if the shipped default
+# and the superseded one were ever the same number, the two checks below would
+# be one check written twice, and dropping the superseded set entirely would
+# leave both green.
+check(f"the shipped taxes default {_T18_SHIPPED_TAXES} and the superseded "
+      f"{_T18_SUPERSEDED} are DIFFERENT numbers, so 'the shipped one is "
+      f"accepted' and 'the superseded one is accepted' are two claims",
+      _T18_SHIPPED_TAXES not in _T18_SUPERSEDED and len(_T18_SUPERSEDED) >= 1)
+check(f"...and the superseded set is non-empty ({_T18_SUPERSEDED}), or the "
+      f"loop below quantifies over nothing and passes on a tree that dropped "
+      f"the set entirely - UX-01 AC 4's vacuous clause, one file over",
+      len(_T18_SUPERSEDED) >= 1)
+for _old in _T18_SUPERSEDED:
+    check(f"...and a blob that still carries the SUPERSEDED default {_old} "
+          f"beside the table STARTS. That value was written into the options "
+          f"file by this add-on, not typed by the operator, so refusing it "
+          f"would stop a working site on an upgrade over an inert number",
+          validate_startup_config(base(price_taxes_profile=_T17_OK,
+                                       price_taxes_eur_kwh=_old),
+                                  -5000, 5000) == [])
+# ⚠️ AND THE RUNG IS STILL A RUNG. A superseded default is not a licence for
+# any value: 0.1198 is ORES's enkelvoudig rate, a number an operator plausibly
+# types, and it is still refused beside the table. Without this line the set
+# above could be widened to "anything" and nothing would report.
+check("...while a value that is NEITHER the shipped default NOR a superseded "
+      "one is still REFUSED beside the table, naming it - the set of "
+      "'untouched' figures widened by exactly the old defaults and by nothing "
+      "else",
+      why(_T17_P_BOTH, "price_taxes_profile is set AND price_taxes_eur_kwh is "
+                       "0.1198")
+      and 0.1198 not in _T18_SUPERSEDED
+      and abs(0.1198 - _T18_SHIPPED_TAXES) > 1e-9)
+# ⚠️ AND THE REFUSAL SAYS SO, so an operator who HAS typed a number is told
+# both which figure to return to and that the old default is not the problem.
+check("...and the refusal names the SHIPPED default to return to AND says the "
+      "superseded default is accepted, so the sentence is actionable on both "
+      "sides of the upgrade",
+      bool(_T18_SUPERSEDED)
+      and why(_T17_P_BOTH, f"back to {_T18_SHIPPED_TAXES}")
+      and why(_T17_P_BOTH, "SUPERSEDED")
+      and all(why(_T17_P_BOTH, str(u)) for u in _T18_SUPERSEDED))
+check("...and the same non-default scalar WITHOUT the table still starts, "
+      "which is what makes the line above about the PAIR rather than about "
+      "0.1198 being disliked",
+      validate_startup_config(base(price_taxes_eur_kwh=0.1198),
+                              -5000, 5000) == [])
+
+# ⚠️ THE UNITS RUNG, A SECOND QUANTITY RATHER THAN A RESTATEMENT. Every Belgian
+# DSO prints these bands in c EUR/kWh, and the whole table is copied off ONE
+# card - so a factor-100 error lands on every row at once and nothing inside
+# the table disagrees with itself.
+#
+# ⚠️ AND THE TWO RUNGS ARE GRADED SEPARATELY, BY THE REASON EACH GIVES, because
+# the parser's own +-10 EUR/kWh bound catches SOME of these cards and not
+# others - and a check that only ever exercised the loud ones would pass with
+# this rung deleted. ORES's 13,27 is refused by the parser; SIBELGA's whole
+# card - 9,39 dag against 7,10 nacht, the Brussels DSO - is under 10 in both
+# bands and reaches this rung alone.
+_T17_ORES_C = ('{"periods":['
+               '{"name":"dag","from":"07:00","to":"22:00","days":"mon-fri",'
+               '"eur_per_kwh":13.27},'
+               '{"name":"nacht","from":"22:00","to":"07:00","days":"mon-fri",'
+               '"eur_per_kwh":7.39},'
+               '{"name":"nacht","from":"00:00","to":"24:00","days":"sat,sun",'
+               '"eur_per_kwh":7.39}]}')
+_T17_SIB_C = ('{"periods":['
+              '{"name":"dag","from":"07:00","to":"22:00","days":"mon-fri",'
+              '"eur_per_kwh":9.39},'
+              '{"name":"nacht","from":"22:00","to":"07:00","days":"mon-fri",'
+              '"eur_per_kwh":7.10},'
+              '{"name":"nacht","from":"00:00","to":"24:00","days":"sat,sun",'
+              '"eur_per_kwh":7.10}]}')
+_T17_P_ORES = validate_startup_config(base(price_taxes_profile=_T17_ORES_C),
+                                      -5000, 5000)
+_T17_P_SIB = validate_startup_config(base(price_taxes_profile=_T17_SIB_C),
+                                     -5000, 5000)
+print(f"    ORES    : {(_T17_P_ORES or [''])[0][:110]}")
+print(f"    Sibelga : {(_T17_P_SIB or [''])[0][:110]}")
+check("ORES's card typed in CENTS is refused by the PARSER's bound, and the "
+      "sentence is the parser's - `beyond +-10.0`, naming the row",
+      why(_T17_P_ORES, "price_taxes_profile cannot be used:")
+      and why(_T17_P_ORES, "beyond +-10.0"))
+check("...and SIBELGA's whole card - 9,39 and 7,10, BOTH under that bound - is "
+      "refused by THIS rung instead, naming both bands and the factor. Without "
+      "it a Brussels site would price a 9.39 EUR/kWh levy and start",
+      why(_T17_P_SIB, "price_taxes_profile carries [7.1, 9.39] EUR/kWh")
+      and why(_T17_P_SIB, "factor of 100"))
+check("...and the two refusals are DIFFERENT sentences, so the rungs cannot "
+      "mask each other: deleting the units rung leaves the Sibelga line red "
+      "while the ORES line goes on passing for the parser's reason",
+      _T17_P_ORES != _T17_P_SIB
+      and not why(_T17_P_ORES, "factor of 100")
+      and not why(_T17_P_SIB, "beyond +-10.0"))
+check("...and BOTH cards divided by 100 start, which is habit 7: the refusals "
+      "above are about the units and not about Brussels or Wallonia",
+      validate_startup_config(
+          base(price_taxes_profile=_T17_ORES_C.replace("13.27", "0.1327")
+               .replace("7.39", "0.0739")), -5000, 5000) == []
+      and validate_startup_config(
+          base(price_taxes_profile=_T17_SIB_C.replace("9.39", "0.0939")
+               .replace("7.10", "0.0710")), -5000, 5000) == [])
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("TARIFF-16 - the INJECTION leg is refused HERE, at startup, and the leg "
+      "the card cannot grade is SAID to be ungraded")
+# ⚠️ WHY IT IS REFUSED IN THIS MODULE. `export_price_at()` is the seam a future
+# export-aware strategy reads, and a formula that first fails when something
+# reads it is a defect discovered at the worst possible moment - which is
+# `static_profile`'s and `price_taxes_profile`'s argument, one option over.
+#
+# ⚠️ AND WHAT THIS OPTION DOES **NOT** DO, said before what it does: no
+# strategy in this add-on reads an injection price. `arbitrage.py` prices the
+# sell side as displaced IMPORT and compares two all-in CONSUMPTION prices.
+# test_price.py 17h grades that by parsing every module under app/; what is
+# graded HERE is that the operator is TOLD it, at startup, in the same breath
+# as the formula being accepted.
+import logging as _t16_logging                # noqa: E402
+
+
+class _T16Log(_t16_logging.Handler):
+    """Every record app.validate emits during one call, rendered."""
+
+    def __init__(self):
+        super().__init__()
+        self.lines = []
+
+    def emit(self, record):
+        self.lines.append((record.levelname, record.getMessage()))
+
+
+def _t16_start(**over):
+    """`validate_startup_config()` -> (problems, rendered log lines).
+
+    ⚠️ THE LEVEL IS FORCED TO INFO FOR THE DURATION AND RESTORED. Without it
+    the capture returns an EMPTY list on a tree that logs correctly, which
+    reads exactly like "the line is not there" - a check whose data cannot
+    reach the failure it names, in the instrument rather than in the check.
+    """
+    log = _t16_logging.getLogger("goodwe.config")
+    h = _T16Log()
+    was, log.level = log.level, _t16_logging.INFO
+    log.addHandler(h)
+    try:
+        return validate_startup_config(base(**over), -5000, 5000), h.lines
+    finally:
+        log.removeHandler(h)
+        log.level = was
+
+
+# The two published injection lines, transcribed from the cards. ⚠️ NEITHER
+# CARRIES A `card` BLOCK, because neither card prints a price beside its
+# injection formula - that is the state this section exists to grade.
+_T16_ENECO = ('{"index":"epex_be","resolution":"hourly","factor":0.1,'
+              '"offset":-1.188,"units":"c_eur_per_kwh","vat_pct":0}')
+_T16_CONS = ('{"index":"epex_be","resolution":"hourly","factor":0.102,'
+             '"offset":1.0,"units":"c_eur_per_kwh","vat_pct":6,'
+             '"card":{"month":"2026-09","index_eur_per_mwh":133.9905,'
+             '"expect_incl_vat":15.55}}')
+
+# ⚠️ THE ACCEPTED BASELINE COMES FIRST (habit 7). Every refusal below varies
+# ONE field from this line, so a refusal has nowhere else to have come from.
+_T16_OK, _T16_OK_LOG = _t16_start(price_export_formula=_T16_ENECO)
+check("Eneco's real published injection line `0,1 x BELPEX-H - 1,188` STARTS - "
+      "including the part that makes its price NEGATIVE below 11,88 EUR/MWh, "
+      "which is the market and not a misconfiguration",
+      _T16_OK == [])
+check("...and so does the shipped \"\", which is every install that exists: "
+      "the option is an addition and the scalar still answers without it",
+      _t16_start(price_export_formula="")[0] == []
+      and _t16_start()[0] == [])
+
+_T16_BAD_PT = _T16_ENECO.replace('"factor":0.1,', '"factor":10.0,')
+_T16_BAD_OFF = _T16_ENECO.replace('"offset":-1.188', '"offset":-118.8')
+_T16_P_PT = _t16_start(price_export_formula=_T16_BAD_PT)[0]
+_T16_P_OFF = _t16_start(price_export_formula=_T16_BAD_OFF)[0]
+print(f"    {(_T16_P_PT or [''])[0][:118]}")
+print(f"    {(_T16_P_OFF or [''])[0][:118]}")
+check("PRECONDITION: each of those two blobs differs from the accepted "
+      "baseline in exactly one coefficient, so the refusals below are about "
+      "the field each names",
+      _T16_BAD_PT != _T16_ENECO and _T16_BAD_OFF != _T16_ENECO
+      and _T16_BAD_PT.replace('"factor":10.0,', '"factor":0.1,') == _T16_ENECO
+      and _T16_BAD_OFF.replace('"offset":-118.8', '"offset":-1.188')
+      == _T16_ENECO)
+check("a factor 100x out is REFUSED at startup, by the pass-through rung, "
+      "naming the option the operator typed",
+      why(_T16_P_PT, "price_export_formula cannot be used:")
+      and why(_T16_P_PT, "passes through")
+      and not why(_T16_P_PT, "|offset| above"))
+check("...and an offset 100x out is refused by the OFFSET rung, so the two "
+      "rungs are graded on their reasons and cannot mask each other",
+      why(_T16_P_OFF, "price_export_formula cannot be used:")
+      and why(_T16_P_OFF, "|offset| above")
+      and not why(_T16_P_OFF, "passes through"))
+check("...and a malformed blob is refused as a malformed blob, naming the "
+      "field rather than 'invalid configuration'",
+      why(_t16_start(price_export_formula='{"index":"belpex_h"}')[0],
+          "price_export_formula.index is 'belpex_h'"))
+
+# ⚠️ THE HONEST HALF, AND IT IS A WARNING RATHER THAN A REFUSAL. Eneco prints
+# its injection formula with NO price beside it, so on that card there is
+# nothing for the self-check to reproduce. Requiring a `card` block would make
+# the published line inexpressible; inventing the estimate would grade the
+# coefficients against arithmetic done with the same coefficients. So the leg
+# starts, and the operator is told WHICH check did not run.
+_T16_UNGRADED = [m for lvl, m in _T16_OK_LOG
+                 if lvl == "WARNING" and "UNGRADED" in m]
+print(f"    {(_T16_UNGRADED or [''])[0][:118]}")
+check("a leg with no card block starts, and says at startup that its "
+      "coefficients are UNGRADED - naming what was checked instead, so the "
+      "gap is stated rather than worked around",
+      len(_T16_UNGRADED) == 1
+      and "no \"card\" block" in _T16_UNGRADED[0]
+      and "pass-through" in _T16_UNGRADED[0])
+_T16_WITH_CARD, _T16_CARD_LOG = _t16_start(
+    price_export_formula=_T16_CONS, price_formula=_T16_CONS,
+    price_provider="custom_formula")
+# ...and a SECOND run with the two legs genuinely different, for the ordered
+# pair below. ⚠️ THE FIRST ONE PUTS THE CONSUMPTION CARD ON BOTH LEGS, so
+# 0.102/6 appears twice and an assertion about arrangement would pass on a
+# TRANSPOSED rendering - MUTATION.md habit 4, in the fixture of a habit-14
+# check. The precondition is asserted below rather than trusted.
+_T16_BOTH_LEGS, _T16_BOTH_LOG = _t16_start(
+    price_export_formula=_T16_ENECO, price_formula=_T16_CONS,
+    price_provider="custom_formula")
+check("...and a leg that DOES carry a card does NOT print it, or the sentence "
+      "would be noise an operator learns to ignore rather than a report of "
+      "which check ran",
+      _T16_WITH_CARD == []
+      and not [m for lvl, m in _T16_CARD_LOG if "UNGRADED" in m])
+# ⚠️ AND A CARD ON THIS LEG IS STILL GRADED, at startup, by the same rung.
+check("...and a card ON THIS LEG that the coefficients do not reproduce is "
+      "REFUSED at startup, so the optional block is optional and not inert",
+      why(_t16_start(price_export_formula=_T16_CONS.replace(
+          '"expect_incl_vat":15.55', '"expect_incl_vat":15.05'))[0],
+          "price_export_formula does not reproduce its own card"))
+
+# ⚠️ THE SENTENCE DOCS.md RESTS ON, AND IT IS THE ONE MOST LIKELY TO ROT.
+_T16_INFO = [m for lvl, m in _T16_OK_LOG if lvl == "INFO"
+             and "NO STRATEGY IN THIS ADD-ON READS IT" in m]
+check("the startup line says, in so many words, that NO STRATEGY IN THIS "
+      "ADD-ON READS IT - the operator is told what the option does not do in "
+      "the same breath as it being accepted",
+      len(_T16_INFO) == 1 and "displaced IMPORT" in _T16_INFO[0])
+# ⚠️ THE ASYMMETRY IS ASSERTED AS AN ORDERED PAIR, NOT AS TWO NUMBERS IN ONE
+# SENTENCE (MUTATION.md habit 14). "6 and 0 appear somewhere" is satisfied by
+# the two legs TRANSPOSED - which is the sentence telling an operator that the
+# add-on has their VAT treatment exactly backwards, on the one line where they
+# could have seen it.
+_T16_PAIR = [m for _l, m in _T16_BOTH_LOG if "priced independently" in m]
+print(f"    {(_T16_PAIR or [''])[0][:118]}")
+check("PRECONDITION: the two legs of that run carry DIFFERENT factors and "
+      "DIFFERENT VAT rates (0.102 at 6 against 0.1 at 0), or the ordered-pair "
+      "assertion below would be satisfied by the transposed rendering it "
+      "exists to refuse",
+      _T16_BOTH_LEGS == [] and '"factor":0.102' in _T16_CONS
+      and '"vat_pct":6' in _T16_CONS and '"factor":0.1,' in _T16_ENECO
+      and '"vat_pct":0' in _T16_ENECO)
+check("and the 6% asymmetry is reported as an ORDERED PAIR: the transposed "
+      "rendering would read `consumption factor 0.1 at vat_pct 0, injection "
+      "factor 0.102 at vat_pct 6`, which is a DIFFERENT string - so an "
+      "argument swap at the call site cannot hide behind `0.102 is in there "
+      "somewhere`",
+      len(_T16_PAIR) == 1
+      and "consumption factor 0.102 at vat_pct 6, injection factor 0.1 at "
+          "vat_pct 0" in _T16_PAIR[0]
+      and "consumption factor 0.1 at vat_pct 0, injection factor 0.102 at "
+          "vat_pct 6" not in _T16_PAIR[0])
+
+
+# --------------------------------------------------------------------------- #
+print("\nSAFETY-10 - shadow_mode is validated like every other option")
+# ⚠️ WHY THIS IS A REFUSAL AND NOT A COERCION. `shadow.mode()` resolves an
+# unrecognised value to SHADOW - the direction that does not move energy - and
+# an install silently reinterpreted that way COMMANDS NOTHING, indefinitely,
+# while its status page calmly explains that this is intentional. A typo is not
+# a decision, and UX-02 made this validator the one rule surface both editors
+# read, so the rule has to be here rather than in a quiet fallback.
+_S10_BAD = ["true", "yes", "1", "shadow", "", "autoo", None, 1]
+for _v in _S10_BAD:
+    _p = validate_startup_config(base(shadow_mode=_v), -5000, 5000)
+    check(f"shadow_mode={_v!r} is REFUSED, and the refusal SPELLS the key so "
+          "configui.problems_by_field() can file it under the right control",
+          why(_p, "shadow_mode is") and why(_p, "'auto'")
+          and why(_p, "'on'") and why(_p, "'off'"))
+for _v in ("auto", "on", "off", "AUTO", " on ", "Auto "):
+    check(f"shadow_mode={_v!r} starts - the three values and the tolerant "
+          "spellings of them are accepted, so the rule above refuses garbage "
+          "and not case",
+          validate_startup_config(base(shadow_mode=_v), -5000, 5000) == [])
+check("PRECONDITION: and the key being ABSENT starts too, which is what every "
+      "install that upgrades into this version has. A rule that refused the "
+      "absent key would refuse every existing install at once",
+      validate_startup_config(base(), -5000, 5000) == []
+      and "shadow_mode" not in base())
+# The two arrangements have to DISAGREE somewhere, or `why()` is grading a
+# sentence that is in the list for another reason entirely.
+check("...and a refused shadow_mode is the ONLY thing wrong with that config, "
+      "so the refusal above is this rule's and not some other rule's",
+      len(validate_startup_config(base(shadow_mode="maybe"), -5000, 5000)) == 1)
+
+
+# --- THE SIX STATES, AND THE ONE THAT PROTECTS THE EXISTING INSTALL ---------
+# ⚠️ GRADED HERE RATHER THAN IN test_clamp.py, WHERE IT STARTED, AND THE REASON
+# IS MEASURED. `shadow.engaged()` is a pure function of the option and the
+# start button; a mutation that defeats the DEFAULT stops test_clamp.py's
+# part 3 reaching the wire at all, which aborts that file with an IndexError
+# before part 8 runs - so the mutation's red count there is a lower bound and
+# the table itself is never graded (MUTATION.md, FCST-06's shape). Nothing in
+# this file drives a Controller, so nothing here can be taken down that way.
+# Six states. The one that matters most is the LAST row: an install that is
+# controlling today must not be changed by this option arriving with a default.
+_TABLE = [
+    ("off", True, False), ("off", False, False),
+    ("on", True, True), ("on", False, True),
+    ("auto", False, True), ("auto", True, False),
+]
+for _m, _started, _want in _TABLE:
+    check(f"shadow_mode {_m!r} with control "
+          f"{'started' if _started else 'stopped'} -> "
+          f"{'SHADOW' if _want else 'LIVE'}",
+          shadow.engaged({"shadow_mode": _m}, control_started=_started)
+          is _want)
+check("THE EXISTING INSTALL: the SHIPPED DEFAULT, on an install that is "
+      "controlling, is LIVE. This is the whole reason the option is not a "
+      "boolean defaulting to true - the Supervisor merges a new default into "
+      "every existing install, and a boolean would have stopped a battery that "
+      "is regulating a real house today",
+      shadow.engaged({}, control_started=True) is False)
+check("...and the SAME shipped default on a FRESH install - `auto_start` is "
+      "false, so nothing has started - is SHADOW. That is what 'default-on' "
+      "means here, delivered where it is safe",
+      shadow.engaged({}, control_started=False) is True)
+# ⚠️ THE REASON, NOT THE VERDICT (MUTATION.md's masking rule). `on` and
+# `auto`-while-stopped are the same boolean and want DIFFERENT operator
+# actions: one is an option, the other is a button. A surface showing only the
+# verdict would be blind to the two rungs being swapped.
+check("the two ways of being in shadow mode are told apart in words, so a "
+      "build that swapped the rungs could not render identically",
+      shadow.why({"shadow_mode": "on"}, control_started=False)
+      != shadow.why({"shadow_mode": "auto"}, control_started=False))
+
+# ⚠️ AND THE FAIL-SAFE DIRECTION OF AN UNREADABLE VALUE IS GRADED, THOUGH THE
+# rule above means a running install can never hold one. It survived the first
+# mutation battery as M9 for exactly that reason: everything else refused the
+# value before `mode()` ever saw it, so the direction it fails in was ungraded
+# and could have been flipped to "live" with the whole suite green.
+check("an UNREADABLE shadow_mode resolves to SHADOW, not to live - the "
+      "direction that does not move energy. It is reachable only if this "
+      "file's rule is ever weakened, which is the case it exists for",
+      shadow.engaged({"shadow_mode": "garbage"}, control_started=True) is True
+      and shadow.engaged({"shadow_mode": ""}, control_started=True) is True
+      and shadow.mode({"shadow_mode": "garbage"}) == "on")
+
 # --------------------------------------------------------------------------- #
 print()
 if fails: