Merge release/1.0 (SAFETY-07) into FCST-03, and close two degenerate stimuli

CHANGELOG.md was the entire collision - SAFETY-07 lands in peakguard.py, main.py
and the arbiter, none of which this branch touches. Both entries kept.

X1. `_firm_or_die` guarding only `cheapest` survived, because the check passed
the SAME provisional point as both cheapest and dearest: a guard on either role
alone raises, so the stimulus could not tell "the buy hour is guarded" from
"both are". Now one call per role with a firm point in the other seat, plus the
positive arm so the two refusals are discriminating.

X6. `firm_points()` returning the carried hours too survived, because its two
consumers - the §11.4 refusal and cheap_now - guard provenance independently and
both keep answering correctly. The accessor is now graded directly: exactly the
published points, by identity and in order.

Both are the degeneracy rule this file states at the top, in a new dress - a
stimulus that cannot distinguish the two things it grades.

⚠️ AND THE REASON THE M9 MUTATION "SURVIVED" IN MY EARLIER REPORT: a stale
__pycache__. Reverting `self.provisional` to `here.provisional` changes neither
the file size nor, at one-second resolution, the mtime, so CPython kept the
MUTATED bytecode and a green run afterwards proved nothing about that line. Every
mutation here now clears __pycache__ first; re-run that way, M9 is caught. The
committed source was always correct - the checks were not being run against it.

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

.gitattributes

@@ -0,0 +1,18 @@
+# This add-on is deployed to a Linux container. core.autocrlf=true on the
+# authoring box gave the checkout CRLF, so a plain copy shipped CRLF files -
+# run.sh with CRLF is a "bad interpreter" failure, and any hash-based drift
+# check between repo and deployment fails for a reason that has nothing to do
+# with the code. Deploy with:
+#     git -c core.autocrlf=false archive release/1.0 goodwe_controller | tar -x
+# which is how 0.3.0 went out, byte-identical to the blobs.
+* text=auto eol=lf
+*.png binary
+*.gz  binary
+
+# `.gitea/workflows/*.yml` steps embed shell heredocs; a `\r` on the terminator
+# line means the heredoc never closes and the job fails on a syntax error that is
+# invisible in the diff. A Windows checkout with core.autocrlf=true would
+# reintroduce it on the next edit. CI-01.
+*.yml  text eol=lf
+*.yaml text eol=lf
+Dockerfile text eol=lf

.gitea/ci/Dockerfile

@@ -0,0 +1,22 @@
+# The image the add-on's tests run in (CI-01). This repo had NO CI at all before
+# that ticket - eight runnable test files, none of them ever run by a machine.
+#
+# ⚠️ THE DEPENDENCIES ARE THE SHIPPED ONES, FROM APK, AND THAT IS THE POINT.
+# goodwe_controller/Dockerfile installs `py3-aiohttp py3-paho-mqtt` from Alpine
+# packages rather than pip, because Alpine ships musl and there are no musl
+# wheels for aiohttp - pip would compile it from source on a client's Raspberry
+# Pi. Testing against pip-installed glibc wheels would be testing a different
+# add-on from the one that ships. Same base, same package manager, same names.
+#
+# ⚠️ NOT `FROM ghcr.io/home-assistant/...-base`. The real Dockerfile takes its
+# base from the Supervisor's `BUILD_FROM` build-arg, which is per-architecture
+# and not resolvable outside a Supervisor build. `alpine:3` is what those images
+# are, minus the s6 supervision the tests do not use - and it is already cached
+# on this runner's host, so the gate does not depend on a registry pull.
+#
+# ⚠️ The runner container itself CANNOT run these tests: it is Alpine with a bare
+# python3, no aiohttp, no pip (`No module named pip`; checked on the box, not
+# assumed). An image is not gold-plating here, it is the only option that does
+# not mutate a shared long-lived runner.
+FROM alpine:3
+RUN apk add --no-cache python3 py3-aiohttp py3-paho-mqtt

.gitea/workflows/checks.yml

@@ -0,0 +1,136 @@
+# CI-01: this repository's FIRST automated check. Before this file, admin/goodwe-addon
+# had no `.gitea/workflows/` directory at all - eight runnable test files, ~100 s
+# 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
+# must; never the workflow.
+#
+# ⚠️ 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
+# rig label without wanting a rig. Nothing below starts, stops, or reads the
+# `goodwe-sim` compose project or takes `sim/riglock.py`; it runs one short
+# container and exits. It does occupy the runner's single slot (`capacity: 1`),
+# so it QUEUES behind a rig campaign - a delayed verdict, never a destroyed one.
+#
+# NO JS ACTIONS: the runner image has no node, so `actions/checkout` cannot run.
+# Checkout is seven lines of git below.
+name: checks
+
+on:
+  pull_request:
+    branches: [release/1.0, master]
+  workflow_dispatch:
+
+concurrency:
+  # ⚠️ PER PULL REQUEST, NOT A BARE NAME. A shared group holds one running and
+  # one pending run, so a bare name lets a second PR supersede a first PR's run
+  # before any runner has picked it up - which is exactly what happened to the
+  # other repo's run 521 (four jobs, `started_at` at the Unix epoch,
+  # `runner_id: 0`, concluded `cancelled`, and the PR merged anyway). Do not
+  # replace this with a constant.
+  group: addon-checks-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  unit:
+    runs-on: [self-hosted, goodwe-rig]
+    timeout-minutes: 70   # ~4 to run; the rest is queueing for the single slot
+    env:
+      # ⚠️ UNDER /home/homelab, NOT $GITHUB_WORKSPACE (ENV-01, and re-measured
+      # during CI-01). act's workspace is `/root/.cache/act/<id>/hostexecutor`, a
+      # path that exists only INSIDE the runner container. Hand it to the host's
+      # snap-confined dockerd and the build fails with "failed to read
+      # dockerfile", or - worse, and this is the documented case - a bind mount
+      # resolves to an EMPTY DIRECTORY with no error at all. /home/homelab is
+      # mirrored 1:1 into the runner and is under $HOME, where snap confinement
+      # accepts it. The same probe under /tmp failed and under $HOME succeeded.
+      WS: /home/homelab/ci/addon-checks-${{ github.run_number }}
+    steps:
+      # ⚠️ THE CHECKOUT IS TWO LEVELS BELOW THE MOUNT ROOT, DELIBERATELY.
+      # test_freeze.py's find_hwsim() reads `HERE.parents[1] / "goodwe" / "sim"`,
+      # looking for the infra repo as a SIBLING of this one. Check out flat -
+      # goodwe_controller directly at the mount root - and `parents[1]` does not
+      # exist, so the test dies on `IndexError: 1` before its first assertion.
+      # Measured during CI-01; the flat layout was tried first and did exactly
+      # that. $WS/goodwe-addon/goodwe_controller gives parents[1] == $WS.
+      - name: checkout into a path the host shares (git; no node for actions/checkout)
+        env:
+          URL: ${{ github.server_url }}/${{ github.repository }}.git
+          TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -eu
+          rm -rf "$WS" && mkdir -p "$WS/goodwe-addon" && cd "$WS/goodwe-addon"
+          git init -q .
+          git remote add origin "$(echo "$URL" | sed "s#://#://x-access-token:${TOKEN}@#")"
+          git fetch -q --depth 1 origin "$GITHUB_REF" || git fetch -q --depth 1 origin "$GITHUB_SHA"
+          git checkout -qf FETCH_HEAD
+          echo "checked out $(git log --oneline -1)"
+
+      - name: build the test image (shipped deps, from apk - see .gitea/ci/Dockerfile)
+        run: |
+          set -eu
+          docker build -q -t goodwe-addon-checks:1 "$WS/goodwe-addon/.gitea/ci" >/dev/null
+          docker run --rm goodwe-addon-checks:1 python3 -c \
+            'import aiohttp, paho.mqtt.client as m, sys; print("python", sys.version.split()[0], "aiohttp", aiohttp.__version__)'
+
+      # ⚠️ THE FILE LIST IS DERIVED FROM THE TREE, NOT TYPED HERE. A hand-written
+      # list is how a new test file joins the repo and is never run - the exact
+      # shape of failure this ticket exists to close. The step globs `test_*.py`,
+      # prints the count, and REFUSES A COUNT OF ZERO: a loop over an empty glob
+      # exits 0 and would report a green gate that examined nothing.
+      #
+      # ⚠️ test_loop.py TAKES ~93 SECONDS OF WALL CLOCK ON PURPOSE (its own
+      # docstring says so, and says why: it drives the real `run_control()`
+      # against a real wall-clock floor, and mocking the clock would leave the
+      # assertion testing the mock). It is not hung. Do not "fix" it with a
+      # shorter timeout - a 60 s limit was tried during CI-01 and reported
+      # exactly the false hang the docstring predicts.
+      #
+      # ⚠️ WHAT THIS RUN DOES NOT COVER, stated because a pass here would
+      # otherwise over-claim. test_freeze.py's third section wants the infra
+      # repo's `sim/hwsim.py` to drive a real HTTP meter through the real
+      # transport. admin/goodwe is PRIVATE (checked via the API) and this
+      # workflow's GITHUB_TOKEN is minted for THIS repository only, so hwsim is
+      # absent here and `find_hwsim()` returns None. The rest of the file runs
+      # and passes. It does so SILENTLY - the file prints nothing to say the
+      # hwsim section was skipped - so "test_freeze.py: PASS" below is a weaker
+      # claim than it looks. That belongs to whoever owns test_freeze.py next;
+      # naming it here is the least this gate can do about it.
+      - name: the add-on's own tests
+        run: |
+          set -eu
+          docker run --rm -v "$WS:/w:ro" goodwe-addon-checks:1 sh -eu -c '
+            cd /w/goodwe-addon/goodwe_controller
+            set -- test_*.py
+            if [ "$1" = "test_*.py" ]; then
+              echo "NO test_*.py FOUND - the mount is empty or the layout moved. NOTHING has been checked."
+              exit 1
+            fi
+            echo "$# test file(s) to run"
+            rc=0
+            for f in "$@"; do
+              start=$(date +%s)
+              if python3 "$f" > /tmp/out 2>&1; then
+                echo "PASS  $f  ($(( $(date +%s) - start ))s)"
+              else
+                echo "FAIL  $f  ($(( $(date +%s) - start ))s)"
+                tail -40 /tmp/out
+                rc=1
+              fi
+            done
+            exit $rc
+          '
+
+      - name: clean up
+        if: always()
+        run: |
+          rm -rf "$WS" || true
+          # Root-owned by this runner inside a directory the `homelab` user owns,
+          # and sudo on that box is interactive-only, so the user cannot clean
+          # this up and the job that made it has to.
+          ls -1dt /home/homelab/ci/addon-checks-*/ 2>/dev/null | tail -n +6 | xargs -r rm -rf || true

HANDOVER.md

@@ -12,7 +12,7 @@ a GoodWe GW5000S-BP.
 
 | | |
 |---|---|
-| running | `local_goodwe_controller` **0.2.0**, `boot: auto`, holding grid at zero |
+| running | `local_goodwe_controller` **0.4.0**, `boot: auto`, holding grid at zero |
 | installed as | a **Local** add-on: `/addons/goodwe_controller` on HA OS at 192.168.2.158 |
 | repo | Gitea `admin/goodwe-addon` (ssh://git@192.168.2.147:2222) — **private** |
 | tuning | gain 0.6, `max_w` 5000, slew 1000, deadband 15, step 10, saturation 500/3, heartbeat 10 s |
@@ -52,9 +52,40 @@ Run the checks before deploying. No framework needed:
 
 ```bash
 cd goodwe_controller
-python3 test_control.py && python3 test_maintenance.py && python3 test_arbiter.py
+python3 test_control.py && python3 test_maintenance.py && python3 test_arbiter.py \
+  && python3 test_validate.py && python3 test_p1.py && python3 test_watchdog.py \
+  && python3 test_loop.py
 ```
 
+`test_watchdog.py` covers SAFETY-02's logic, its arming gate (derived from the
+real arbiter, not passed in), its trip path, and the fact that the latch survives
+an add-on restart. Its headline validation is not here at all: `sim/replay_sign.py`
+in the infra repo drives the same module over the two captured RS485 days and must
+fire on all four of the 2026-08-20 episodes and stay silent on 2026-08-23. That
+needs both checkouts:
+
+```bash
+GOODWE_ADDON_REPO=/path/to/goodwe-addon python3 sim/replay_sign.py
+GOODWE_ADDON_REPO=/path/to/goodwe-addon python3 sim/replay_sign.py --stub
+```
+
+The second run checks the grader still *discriminates* rather than merely still
+passing — a watchdog that never trips and one that always trips must both be
+rejected.
+
+⚠️ **If you are testing the failsafe by hand, note that stopping and starting the
+add-on will not clear a trip.** That is the point of it; use the *Start / stop
+control* button twice, or delete `sign_tripped` from `/data/state.json`.
+
+⚠️ `test_loop.py` takes about **95 seconds** (measured 93 s) and that is not a bug. It
+drives the real control loop, which sleeps 1 s a tick, eight times over, to prove a
+wall-clock property about it (SAFETY-12); mocking the clock there would leave the
+assertion testing the mock. The other six suites together are ~440 checks and finish in
+seconds — `test_watchdog.py` spends ~3 s of that driving a real `Controller` through a
+trip. If you shorten `test_loop.py`'s windows, re-measure and correct this figure —
+an understated runtime is what makes a slow test look like a hung one, and a slow test
+that looks hung gets deleted.
+
 ---
 
 ## 3. Known broken / unfinished

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,991 @@
 # Changelog
 
+## Unreleased
+
+**Provisional prices, and what may not rest on one (FCST-03).**
+Day-ahead prices arrive once a day, around 14–16 h CET. Until they do, §8.3 says
+the unknown hours use yesterday's profile and are flagged `provisional: true` —
+and **no irreversible action may be taken on a provisional price.**
+`app/price_forecast.py` does the fill, and the whole module is shaped by one
+defect: a carried-forward point and a published one are the same three fields
+and a bool, so the natural line `PricePoint(..., provisional=y.provisional)`
+copies yesterday's `False` onto today's guess and produces stale data presented
+as current. That is the meter-side SAFETY-18 failure one layer up — the reading
+arrives on time, looks fresh, and is wrong.
+
+**So the flag is never passed through.** Carried points are built by a
+constructor that has no `provisional` parameter at all (the literal `True` lives
+in one place, and there is nothing for a caller to forget or copy); published
+points are passed through **by identity**, so there is no copy that could lose a
+flag; and an audit re-derives the expected flag for every emitted point from the
+set of hours the feed actually published and *raises* rather than repairing one.
+A published point may itself be provisional — `eneco_eddy`'s current-quarter
+imbalance print is — so the audit's rule for a published hour is "whatever the
+feed said", never "False".
+
+**The fill keys on the Brussels wall clock, not on `t − 24 h`.** A 23-hour day
+has no 02:00 and a 25-hour day has two, so a fixed 24-hour subtraction shifts
+every carried hour by one across a transition and misprices a whole day with
+nothing to show for it. Re-running the fill after a late publication replaces
+the carried hours with the real print: the number and the flag move together
+because the series is rebuilt, never patched.
+
+**Arbitrage now drops provisional hours instead of refusing the whole day.**
+The refusal that read "the plan is provisional" would have switched arbitrage off
+every morning on every dynamic site once carry-forward filling landed — a
+part-firm series is the *normal* state before the print. What §8.3 forbids is
+acting **on** a provisional price, so the provisional hours are dropped and the
+spread, the cheapest hour and the dearest hour are computed over the published
+ones only; fewer than two firm hours is still a refusal, which is where the
+§11.4 fallback (wholly provisional) lands. The permitting variant now refuses to
+be *constructed* around a provisional point at all. The cheap-window flag became
+per-hour for the same reason, so a site's maintenance charge floor does not go
+dark every morning.
+
+**Real-time / imbalance products get measurably wider thresholds.** One widening
+path, driven by a set of active uncertainty sources: the product's own (§9.2 row
+2, derived from the declared `PriceProduct` and never from a plugin id) and
+§11.4's "no weather data" row, which the spec widens by a different trigger and
+which is the same mechanism. The combination rule is `max`, not a product — two
+independent doubts must not compound into a threshold nothing can clear. The
+caller supplies the base round-trip cost threshold, so OPT-04 still owns what
+the number *is*; this owns only how much wider it gets and why, and the allowed
+verdict reports the threshold it cleared.
+
+**An irreversible action is a value, not a judgement call at each call site.**
+`Irreversible` carries the hours an action commits — the maintenance drain's
+window is derived from `maintenance.DRAIN_TIMEOUT_MIN` rather than typed twice —
+and the gate looks at exactly those hours, blocking on a provisional one, on an
+hour the series does not cover, and on no price data at all: three different
+reasons, none of them an answer. ⚠️ It is the entry point for a start being
+*justified by a price*; the calendar path main.py runs today is untouched,
+because a gate that blocked on `no_data` would stop the monthly cycle on every
+default install — §12's opening sentence.
+
+**Zero new options.** No `config.yaml` key, no new defaults dict, no `o.get(k,
+X)` in main.py: the module reads no options at all, so CFG-03 did not widen.
+
+**The grid-following loop is now capped against the month's billed capacity peak
+(SAFETY-07).** New `app/peakguard.py`. TARIFF-01 measured the quarter; this is the
+consumer it was built for. Every cycle the guard projects the open quarter,
+compares it to a ceiling and files ONE arbiter claim: a lower bound on the
+setpoint at `P_PEAK`. That shape is both behaviours §10.1 asks for — a hard clamp
+on charging and pre-emptive discharge — and it cannot cap discharge or export,
+because a floor cannot. `excess = 900 × (projected − ceiling) ÷ remaining`, and
+the floor is the MEASURED battery power plus that: a floor built on the standing
+command winds itself to the rail whenever the inverter fails to follow, and one
+built on delivered power cannot.
+
+**It trips where SAFETY-18 only notifies, and the captures decided that.** On the
+healthy reference day it engages on zero of 95 quarters; the action is
+level-triggered, unlatched and re-derived every cycle, so a false engagement costs
+one cycle of discharge rather than a parked battery. Replayed on 2026-08-20 the
+billed quarter goes from **5029.8 W — above the inverter's own 5000 W rating — to
+3485 W**, under the soft limit and without saturating. Quarters under the limit
+across both committed days: 189/190 → 190/190. Two days is not thirty; AC 3 is
+still TARIFF-01's open item and this does not claim it.
+
+**Blindness forbids importing, and it is checked before the projection is
+graded.** A fresh averager projects a confident 0 W, which is under every ceiling
+there is; a meter gap longer than `meter_max_age_s` makes the projection read LOW;
+and a frozen meter reading export projects 0 W at full coverage. All three become
+a floor of 0 W, which is one-directional and cannot cost pack energy. That is the
+backstop SAFETY-18 could not be — its alarm arrives at 300 s of a 900 s quarter
+and commands nothing. The frozen term is `freeze.looks_frozen()` itself, evaluated
+on this cycle's standing command, not a second copy of the conjunction.
+
+**The ceiling is `peak_cap_w`, raised only by an OBSERVED reading.** `NO_RECORD`
+and `NOT_OBSERVED` both leave it at the cap, so an unreadable peak store makes the
+guard STRICTER. The gate is the reading's STATE, not whether a number happens to
+be attached to it: today a `peak_w is not None` test behaves identically, and
+depending on that coincidence is how a future last-known-peak field would silently
+raise the ceiling off a read that failed. `headroom_w()` is deliberately not
+consumed — `cap − peak` turns a zero peak into FULL freedom.
+
+**Two defects found building it, both in the interaction rather than the
+arithmetic.** A LIMIT does not out-vote another LIMIT — `arbiter.resolve()` applies
+every limit at or above the winner's priority and takes the most restrictive — so
+the peak floor (`lo ≥ 0`) and the maintenance charge-only shaping (`hi ≤ 0`)
+resolved to a CONTRADICTION and 0 W, parking the battery in the exact quarter it
+should shave. Fixed by suppression rather than priority: main.py drops the
+maintenance shaping while the guard is engaged, which is what that branch already
+did for the optional `peak_forecast_entity` — a key that is empty on a default
+install, so until now the suspension could not fire on the site that needed it.
+And thresholding `excess > 0` released the claim the instant it started working,
+producing seventeen engage/release cycles in one 900 s quarter (§10.2's
+oscillation) and leaving that quarter 49 W over; the threshold is now the floor
+itself, which is the same arithmetic read as a level rather than as a switch.
+
+**`PeakTracker.project()` no longer reads a private name with a default.**
+`getattr(averager, "_last_net", 0.0)` failed quiet AND in the disarming direction:
+a rename credits 0 W held, the projection reads low, and the money guard does not
+engage. `QuarterAverager.held_net_w` is now a documented public property, read
+without a default, and `Projection` carries it. TEST-13 item 4.
+
+**No new option, and no fourth defaults site.** The ceiling is `peak_cap_w`, 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 rating.
+`config.yaml` and `validate.py` are untouched; §14's `capacity_peak_limit_kw`
+stays declined as the kW/W mismatch trap it is. On `meter_source: off` there are
+no telegrams, so the guard does not run at all and the status page says NOT
+COVERED — running it there would have blinded it permanently and stopped every
+legacy install from charging, which is what the first cut did until
+`test_clamp.py`'s export case caught it.
+
+**Static day/night and fully-fixed tariffs, first-class (TARIFF-03).**
+§9.2 puts a large share of the Belgian installed base on a static profile, and
+an EMS that only works under dynamic pricing is an EMS for a minority. A new
+`static_profile` option describes a two-period day/night tariff — or a single
+fixed price — as JSON, and `app/static_tariff.py` turns it into the same
+canonical `{start, eur_per_kwh, provisional}` series the fetched providers emit,
+so nothing downstream learns that a tariff can be static.
+
+**It is not a sixth provider plugin, and the reason is mechanical.**
+`PriceProvider.capabilities()` is a classmethod, so a plugin's `PriceProduct` is
+fixed when the class is written — but §9.2 makes STATIC and FIXED two different
+products with two different required behaviours, and which one a site is on is a
+property of the operator's data, not of any class. `StaticProfile.product`
+derives it from the number of distinct prices instead. The second reason: the
+plugin framework exists to stop a *fetched* figure being marked up twice, and a
+number the operator typed as all-in has no publisher to disagree with.
+
+**So the profile sits where §11.4 already says it does — under the providers, as
+the fallback.** The configured-product path and the feed-is-down path are the
+same generator differing in one flag: `provisional`. A static-tariff site runs
+that path every day, so the degradation path for a dynamic site cannot rot
+unused.
+
+**"No arbitrage" is a type, not a boolean somebody has to remember to check.**
+`TariffPlan.arbitrage()` returns a variant: the *allowed* arm carries the
+spread and the cheapest and dearest hours, and the *refused* arm carries a
+reason and nothing else — `.spread_eur_kwh` on a refusal raises rather than
+answering 0.0. An optimiser cannot compute a trade from a refusal because it
+cannot get the inputs out of one. Four refusals, all derived: the peak guard is
+holding, there is no price data, the plan is provisional, or **the series is
+flat**. That last one is AC2 — a fully-fixed tariff disables arbitrage by
+arithmetic rather than by matching on an enum, and a dynamic feed that happens
+to print one price all day is refused for the same true reason.
+
+**Peak shaving outranks arbitrage, expressed so OPT-04 cannot skip it.**
+`arbitrage()` takes `peak_guard_active` as a required keyword argument, so the
+spread is not obtainable without first answering whether §10.1's priority 2 is
+holding. §9.1's capacity tariff is a network cost charged whatever the energy
+product is.
+
+**Time-window shifting reaches the one shiftable load that exists.** main.py's
+cheap-window flag — previously fed only by the `price_now_entity` /
+`price_avg_entity` pair — now falls back to the static profile, and the Web UI
+gained a **Tariff** row naming the window, the price, when it next changes and
+why it is or is not cheap. The rule is *strictly* below the seven-day mean:
+under a flat tariff `<=` would call every hour cheap and a fixed-tariff site
+would top up from the grid at any hour, which is the opposite of
+self-consumption only. Seven days rather than 48 hours because a 48 h mean taken
+on a Friday is two-thirds weekend, and the same Tuesday 09:00 would come out
+cheap or dear depending on when you asked.
+
+**A profile must tile every day type exactly once, checked at startup.** A gap
+is refused with the uncovered range named rather than filled in — an invented
+price is one an optimiser would trade on — and an overlap is refused because
+otherwise one of two prices wins silently on list order. The trap this catches
+in practice: `22:00–07:00 mon-fri` does **not** cover Saturday morning, because
+a window applies on the day the clock reads.
+
+**validate.py rule 7's stated reason expired, exactly as TARIFF-02 predicted.**
+That ticket left a tripwire in `test_price.py` section 12 asserting that nothing
+in `app/` consumed `load_prices()`, with instructions to fix the refusal's
+wording in the same commit when it went red. It went red naming
+`static_tariff.py`. The message now says what is true instead — the series *is*
+consumed, but main.py acts on the static side of it and not on a fetched one —
+and the tripwire is re-aimed rather than removed: the consumer set is pinned, so
+a second consumer (OPT-04) goes red again, and the expired phrase is asserted
+gone so a bad merge cannot restore it. Rule 7 also grew a second refusal:
+`static_profile` alongside the Home Assistant price pair is the same
+silent-loser conflict, and a live one.
+
+**No new place for an option default (CFG-03 is not widened).**
+`static_profile` was added to `app/price.py`'s `PRICE_OPTION_DEFAULTS` — the one
+in-code mirror TARIFF-02 created and pinned to `config.yaml` by a check — rather
+than to a defaults dict in the new module, which has none. main.py grew no
+`o.get("static_profile", …)` fallback. That is TARIFF-02's pattern, stated
+here so a reviewer does not have to infer it.
+
+**Measured, on the data that exists.** `test_static_tariff.py` replays the two
+committed days of this house's real P1 meter (`scenarios/p1-net-2026-08-{20,23}`)
+priced under a Belgian day/night profile. 2026-08-20 is a Thursday: 15.220 kWh
+imported, 9.606 in the day window and 5.614 in the night one, EUR 4.7185 under
+day/night against EUR 4.6725 flat, and shifting the day-window energy into the
+night window saves EUR 0.8069 — which is 9.606 kWh x the 0.0840 spread, derived
+twice and required to agree. 2026-08-23 is a Sunday: 0.728 kWh, **all** of it
+night-priced, which is the weekend row proving itself on real data. §17 names
+six Belgian scenarios and a static-profile case is not among them; this is the
+seventh, and it is two captured days rather than a season — the file says so
+rather than implying an annual figure.
+
+Also worth knowing before OPT-04: on realistic Belgian day/night numbers the
+whole-tariff spread is about 0.08 EUR/kWh, **below** the shipped
+`cycle_cost_threshold_eur` of 0.10. A correct optimiser will decline to cycle
+for the tariff alone on such a site. That is a product finding, not a defect.
+
+**Price provider plugins, and one canonical all-in price format (TARIFF-02).**
+`app/price.py` ships five providers - `generic_dayahead` (wholesale EPEX BE),
+`engie_dynamic`, `totalenergies_dynamic`, `eneco_eddy` and the offline
+`manual_csv` - all emitting exactly `{"prices": [{"start", "eur_per_kwh",
+"provisional"}]}`, tz-aware at the Brussels offset, EUR/kWh, all-in. **Nothing
+consumes it yet**: this is the seam, landed first, so that the arbitrage work
+that follows never learns a supplier's name.
+
+**Double-counting the markup is refused rather than discouraged, given a
+correct declaration.** A plugin does not return a price; it returns the figure
+its source published and declares which of {energy, markup, taxes} that figure
+contains. The framework adds the complement, once. Engie and TotalEnergies
+publish a retail figure with their margin already inside; adding the configured
+3 c/kWh on top would make every future arbitrage decision wrong by that amount
+with nothing reporting it.
+
+Two mechanisms, because one was not enough. `PluginOptions` raises on the
+framework-owned keys - and review of PR #16 then wrote a double-counting plugin
+three more ways, one of them touching nothing but `PRICE_OPTION_DEFAULTS`, a
+public dict in the module every plugin already imports. So `register()` now also
+**refuses at import any plugin whose own code mentions a framework key**
+(`code_leaks()`, docstrings stripped via `ast` so a plugin's mandated
+`SOURCES:` line does not false-positive). Honest wholesale baseline 0.188
+EUR/kWh; every attack landed 0.219.
+
+**The guarantee's precise shape**, stated because an overclaim is worse than no
+claim: the framework adds the complement exactly once *given a correct `sources`
+declaration*. A plugin that declares `{energy}` while its feed is really all-in
+still comes out one markup high while touching no framework name, and no code
+can catch that - the declaration is the plugin's unverifiable claim about
+somebody else's tariff. What is mechanised is reachability; what stays human is
+truthfulness.
+
+**The product type is declared, not inferred from the plugin's name.**
+`eneco_eddy` is a real-time/imbalance product and gets widened arbitrage
+thresholds; that reaches a consumer through `capabilities().product` and
+`volatility_regime()`, never through a name comparison. `test_price.py` asserts
+mechanically that no plugin id appears anywhere in the framework's own code,
+and drives a sixth provider defined inside the test file to the correct regime
+with `price.py` untouched.
+
+**"No price data" is a type, not an empty list.** Following the same rework
+`sim/riglock.py` took, a fetch returns `PriceRead.series(...)` or
+`PriceRead.no_data(reason)`, and only the first carries fields. An empty series
+is not constructible; `no_data` has no `.points` to iterate, no `.at()`, and
+`.get("points", [])` raises rather than returning the default. **A day of free
+electricity and a day with no prices are different instructions** - arbitrage is
+pointless under the first and forbidden under the second - and an implementation
+that returns `[]` on a failed fetch cannot tell them apart. Every site-level
+failure returns `no_data`; nothing raises into the control tick.
+
+**What is not verified, and cannot be by an offline suite:** every fixture is
+synthetic, so the five feed URLs and JSON shapes are checked against a belief
+about what those suppliers publish, not against the feeds. The parse layer is
+exercised; the contract with each supplier is not. Expect the first live fetch
+of each to need a shape fix, and note that a wrong shape degrades to
+no-price-data rather than to a wrong price.
+
+**`manual_csv` is the documented offline fallback** and needs no network, no
+supplier account and no HTTP stack. See DOCS.md for the format. Its `start`
+column must carry a UTC offset - a bare local timestamp is refused, because one
+hour every October names two moments.
+
+**Injection is priced separately** (`export_price_eur_kwh`), a scalar rather
+than a second series, and negative values are accepted. Consumption plugins
+cannot reach it.
+
+**`price_provider` may not be combined with `price_now_entity` /
+`price_avg_entity`** - the add-on refuses to start on that pair. The Home
+Assistant sensors are the existing delegation of pricing to HA and still work
+alone; with both configured they would silently keep deciding while the status
+page named a supplier that decided nothing.
+
+**No timezone database is used.** The shipped Alpine image has no `tzdata`, so
+Brussels offsets are computed from the EU rule and every instant is carried as
+UTC and rendered at the offset that applies to it. The checks drive both 2026
+transitions - the 23-hour and 25-hour days - rather than a normal day, where a
+fixed 24-slot implementation and a correct one agree.
+
+**The capacity-tariff peak is now measured, banked and survives a restart
+(TARIFF-01).** New `app/tariff.py`. The 15-minute block average itself was
+already built and unwired - `p1.QuarterAverager` computes clock-aligned 900 s
+blocks, time-weighted over irregular telegram spacing, offtake-only and
+per-phase - and `P1Ingest.blocks` was a 96-entry list a restart erased. This
+adds the SQLite behind it (`/data/tariff.db`): one row per completed quarter in
+the indefinite 15-min tier, one row per calendar month in the permanent peak
+tier, and no `DELETE` against either anywhere in the module.
+
+**Blocks, not a sliding window.** The card says "rolling"; 9.1 bills "the
+highest 15-minute average offtake", stated per QUARTER. "Rolling" here means
+continuously updated, not a trailing-15-minutes window - a trailing window
+reports a peak the meter never bills, and reports it HIGH, because a burst
+straddling :15 fills it completely while contributing to two block averages at
+partial weight.
+
+**A restart mid-block resumes it, and a restart that outlives the block banks
+it.** `QuarterAverager` grew `snapshot()`/`restore()`; the tracker checkpoints
+the open block every 15 s (worst case 1.7 % of one quarter) and clears the
+checkpoint in the same breath as a block close. The held sample keeps its
+ORIGINAL timestamp across the restart, so the outage is integrated under the
+same `max_hold_s` rule a running process would apply and uncovered seconds drag
+the closed block DOWN rather than being held forward. `quarter_start` is the
+primary key and a re-bank may only ever RAISE a figure, so a replay cannot
+double-count and a partial re-run cannot lower a quarter already measured.
+
+**An unreadable store is not a zero peak.** `peak()` answers `OBSERVED` /
+`NO_RECORD` / `NOT_OBSERVED` and carries `peak_w = None` unless observed - the
+`riglock.holder()` fix applied to something that spends money. A peak read as
+0 W hands SAFETY-07 maximum headroom and silently disarms the guard at the
+moment its own storage breaks, so there is no accessor that defaults it: a
+caller who forgets gets a `TypeError`, and the status page prints a different
+row for "no quarter yet" than for "the database did not answer".
+
+**Calendar months are LOCAL, blocks are UTC.** A quarter starting 22:15 UTC on
+31 August bills in September. Block alignment still needs no timezone.
+
+**No new option, and no second peak entity.** The soft limit is the existing
+`peak_cap_w`; `config.yaml` and `validate.py` are untouched, so CFG-03 is not
+widened. `peak_forecast_entity` stays the input to `maintenance_charge_floor()`
+- repointing that consumer changes what moves energy and belongs to SAFETY-07.
+
+**It measures and nothing else.** No claim, no clamp, no command; graded on the
+parsed syntax in `test_tariff.py`, which also proves the same grader lights up
+on `main.py`. Per SAFETY-20, the quantity is DELIVERED power - `tariff.py` only
+ever sees `P1Sample`, the meter's own reading, never a setpoint.
+
+**AC 3 is not met and the check says so.** It asks for 30 days of replay; two
+days of this house's real meter exist (2026-08-20, 2026-08-23), now committed as
+`scenarios/p1-net-*.jsonl.gz`. `test_tariff.py` part 9 replays them, reports
+the percentage under the shipped limit next to the sample size in days, and
+asserts nothing about the 95 % figure.
+
+**A computed setpoint over the rating now alarms instead of being clipped in
+silence (SAFETY-03).** The clamp was never the missing half - specs.md 10.3
+records an unclamped integrator climbing ~130 W per 4 s past 10 kW and reporting
+**14 768 W** while pinned at the 5 kW rail, and a silent clamp turns exactly that
+into a flat, legal-looking 5000 W hold. `write_setpoint()` - the one path every
+write takes, cycle, heartbeat, operator button and shutdown alike - now clamps to
+the **validated** `max_w` and reports whether the raw value differed, and
+`Controller.check_output_clamp()` raises `OUTPUT_CLAMP`: a persistent
+notification (`goodwe_output_clamp`), an `ERROR`, an event row and a red status
+banner. **Not a trip**: the clamped value is written and the loop keeps running,
+per 11.2's "clamp *and alarm*".
+
+**The bound is `max_w` and nothing is `min()`ed at runtime.** Section 14 requires
+the loop clamp and the driver's `setpoint_limit_w` to agree, validated at startup
+with a refusal on mismatch - which CFG-01 already ships. The device range is
+still applied second, as defence in depth; after a successful validation it
+cannot engage, so if it ever does, that is louder than the first stage and it
+alarms too, naming the bound. No new config key: the guard's limit is the one
+the operator already set, and its cadence is a module constant.
+
+**`Decision` grew `i_clamped` / `clamped` booleans, and that is the load-bearing
+part.** `reason` is one string that later stages overwrite - a cycle that clamps
+the integrator and is then slew limited reports `slew-limited`, and one that
+clamps while saturated reports `saturated-freeze`. Both *are* the winding case,
+so an alarm keyed on the string is silent on exactly the cycles it exists for:
+mutating main.py back onto `"clamp" in decision.reason` drops the 10.3 replay
+from 2 engagements to **0**. The flags are set where the clamp happens and are
+never overwritten. On a default install (`integrator_max_w` following `max_w`)
+the integrator bound is the one that bites and the output clamp is unreachable,
+so the integrator flag is the whole signal.
+
+**Distinct from the saturation freeze, and checked in the negative.** A clamp is
+a *software* bug signal; saturation is the *hardware* failing to follow a legal
+command, and its action is to freeze the integrator, not to alarm. They share no
+reason code, notification id, status row or counter. `test_clamp.py` drives a
+loop that saturates for 10 consecutive cycles at 1.4 % of the rating and asserts
+zero clamp notifications, zero engagements, no log row and no status row - after
+first asserting that the saturation freeze *really did* engage, so the silence is
+an observation rather than a scenario that did nothing.
+
+**The action log is coalesced per episode, and that was a real bug.**
+`log_event()` keeps 40 rows; one row per engagement flushed the entire ring
+within 40 cycles of a winding loop, and the first thing it evicted was
+SAFETY-18's own `METER FROZEN?` row - this guard silencing another guard's log.
+Caught by `test_freeze.py` going red, not by inspection. One row per episode now,
+carrying the exact engagement count read off the counter.
+
+**A non-finite setpoint is refused, and it was worse than passing one through.**
+`nan` is loss of input (11.1 rule 1: command zero, keep commanding), not an
+out-of-range value. Measured: because every comparison against `nan` is False, a
+naive `max(-limit, min(limit, nan))` keeps its *first* argument and turns a `nan`
+into a command **at the full rating**, then reports it as a clamp engagement.
+
+**Review fixes (PR #12).** Three, and the first was a behavioural regression
+this PR introduced: `clamp_to_rating()` **returned early** from the `max_w`
+stage, so the device bound - the "applied second, defence in depth" half - was
+reached only when the rating bound had NOT fired. The bigger the overshoot, the
+less the guard did. At `max_w` 5000 against a +-4000 device, +9999 emitted
+**+5000 W, outside the device range**, while a mere +4500 was correctly held to
++4000. That undid the pre-PR guarantee "never send a value the device will
+reject outright" and undercut this module's own case for clamping to `max_w`
+rather than a runtime `min()`, which rests entirely on that stage catching a
+validation that did not run. Both stages now always run, the result names both
+bounds when both bite (`max_w+device`), and the property is asserted over a
+492-point sweep rather than on witness values - the defect was invisible to any
+single-value check that happened to sit inside one stage. No reachable
+production path was found for it (two validation gates and the arbiter bound sit
+in front), but latent is not harmless.
+
+Two harness defects, both of the kind where a check cannot fail for the value it
+forbids: the hysteresis check issued `range(CLEAR_CYCLES - 1)` clean cycles,
+which at `CLEAR_CYCLES = 1` issues **zero** and passes while printing
+"0 clean cycles do NOT clear it" - green for the chatter setting the constant
+exists to prevent. And the re-assert check stimulated at `REASSERT_S + 9`, green
+for **any** value including 3600, i.e. the hour of silence the module promises
+not to produce. Both are now written in wall-clock terms that do not move when
+the constant does: **one** clean cycle must not clear the alarm, and a loop
+pinned across the 900 s capacity-tariff quarter must speak at least 5 times and
+on no more than 20 % of cycles. `CLEAR_CYCLES = 1`, `REASSERT_S = 3600` and
+`REASSERT_S = 0` each go red.
+
+**`test_clamp.py`** (new, assert-based, no framework) covers the clamp
+arithmetic and its boundaries - exactly +-`max_w` is *not* an engagement - the
+alarm's edge/re-assert/hysteresis cadence, the 10.3 runaway replayed through the
+real `Controller.cycle()` against an unclamped transcription, the saturation
+negative, and the direct-write path. Six author mutations reproduced red,
+including "clamp kept, alarm deleted" (the historical build) and "alarm keyed on
+`reason`". Two of the check's own hypotheses about how the freeze and the clamp
+interact were **refused by the sweep** and rewritten to what it measured: a
+frozen cycle *can* clamp, and does so exactly when the integrator reverses.
+
+`test_freeze.py`'s notification assertions now filter by `notification_id`
+rather than by service - the add-on raises more than one kind of notification,
+and its railing scenarios legitimately raise this one too.
+
+**Cheap-window maintenance charging was unreachable at the shipped defaults, and
+now the config that makes it unreachable is refused (MAINT-04).** `config.yaml`
+shipped `max_w: 2000` against `maintenance_charge_w: 2500`. The cheap-window
+shaping files `Claim.limit(hi = -maintenance_charge_w)` against the supervised
+SAFETY limit's `lo = -max_w`, so `lo > hi` — the arbiter's clause 3, correctly
+resolved to **0 W** and logged as a CONTRADICTION. **Maintenance silently never
+charged in a cheap window on a default install**, and the only evidence read
+like a bug in the arbiter rather than like the two numbers an operator set.
+Measured against the real arbiter, loop asking +500 W:
+
+```
+max_w=2000  hi=-2500  ->     +0 W  contradiction=True
+max_w=2500  hi=-2500  ->  -2500 W  limited by supervised(max_w)
+max_w=3000  hi=-2500  ->  -2500 W  limited by maintenance(cheap-window charge)
+```
+
+`validate_startup_config()` now refuses `maintenance_charge_w > max_w` (rule 6),
+the same shape as CFG-01's `sign_disagree_w >= max_w`: a number the operator set,
+overridden by a layer they cannot see. Equality is reachable (`-max_w` is a
+single valid point) and deliberately not refused. Verified by starting the
+add-on on the pre-fix pair: exit 78, the refusal banner, no traceback.
+
+**`maintenance_discharge_w` was checked, not assumed, and it is NOT the same
+case.** The shaping is not symmetric. The drain phase does not shape the loop,
+it OWNS the actuator — `Claim.set(P_MAINTENANCE, +discharge_w)` — and a SET is
+*clamped* by the limits above it rather than contradicted by them. 2500 against
+a 2000 W ceiling emits **+2000 W**, and the arbiter's own `explain()` prints
+`maintenance -> 2000 W, limited by supervised(max_w)` every cycle. Nothing is
+silent and energy still moves; the cycle completes slower (13.8 kWh usable at
+2000 W is ~6.9 h against the 720 min drain timeout). **Warned about, not
+refused.**
+
+**The shipped defaults changed so the validator does not reject them.**
+`maintenance_charge_w` and `maintenance_discharge_w` are now **2000**, at the
+shipped `max_w`. `max_w` was deliberately NOT raised instead: it is the
+supervised safety ceiling and raising a default upward ships more power to every
+new install. Raising `max_w` (the reference install runs 5000) is what unlocks a
+faster maintenance cycle — raise it first, then these. `test_validate.py` now
+reads `config.yaml` itself and asserts the shipped numbers pass the rule, so a
+default that the validator refuses cannot ship again.
+
+### ⚠️ Upgrading an existing default install: the add-on may refuse to start
+
+An install still carrying `maintenance_charge_w: 2500` against `max_w: 2000`
+now meets rule 6 and **exits 78 with the refusal banner** instead of starting.
+That is the intended behaviour — the configuration was already broken, it was
+just silent about it — but an add-on that will not come back after an update
+needs the fix stated here rather than only in the log.
+
+**The fix, either way: set `maintenance_charge_w` to `2000` or lower, OR raise
+`max_w` to `2500` or higher** (Settings → Add-ons → GoodWe RS485 Controller →
+Configuration), then start it. The banner in the log says the same thing and
+names both numbers.
+
+Whether you hit this at all depends on whether the Supervisor kept the old
+value, and **both cases are covered above because we did not verify which one
+applies here.** The Supervisor merges an add-on's *stored* options over the
+defaults in `config.yaml`, so:
+
+- **A key the operator never edited** re-derives from the new `config.yaml` and
+  becomes 2000 on upgrade. Non-event, nothing to do.
+- **A key the operator did set** persists at 2500 and the add-on refuses to
+  start until it is changed. Note this includes anyone who used the
+  Configuration page's YAML editor, which writes the whole options block back —
+  so "I never touched that field" is not a guarantee the old value is gone.
+
+⚠️ **This is reasoned from the Supervisor's documented merge behaviour, not
+measured on the live install.** The reference install's stored options could not
+be read (`/api/hassio/` refuses a long-lived token) and probing it was out of
+scope — it regulates a real battery. It runs `max_w: 5000` and is unaffected
+either way.
+
+⚠️ **Known, deliberately left, and worth a follow-up:** `main.py` and
+`maintenance.py` still fall back to **2500** when the key is absent from the
+options dict, while `config.yaml` and `validate.py` now say 2000. Unreachable on
+a Supervisor install (every key is always supplied) and reachable only from
+tests/`sim`. The real fix is one source of truth for option defaults, which is
+bigger than this ticket and touches files another ticket is in.
+
+## 0.5.2
+
+**A meter frozen at a wrong-but-fresh value now raises an alarm. It still is not
+stopped.** (SAFETY-18)
+
+A meter that answers `200 OK` with a stale document forever is *arriving* on
+every poll, so every freshness mechanism in the stack reads it as healthy:
+`meter_max_age_s` is reset by each response, the firmware watchdog is fed by the
+heartbeat and by a sample age that never climbs, and the arbiter contributes only
+±`max_w`. The loop integrates a constant error and rails — replaying the real
+`compute()` at 15 s cycles, in 150/60/30 s at `max_w: 2000` for a meter frozen at
+350/1000/≥3000 W, and 360/135/75 s at `max_w: 5000`. **The live install runs
+`max_w: 5000`**, which is both the schema maximum and the device rating.
+
+The new detector (`app/freeze.py`) is a **conjunction**, not the bare
+`unchanged_s` threshold TEL-05 measured and rejected:
+
+    unchanged_s ≥ meter_freeze_s   AND   |command| within 5 % of max_w
+
+Both terms already existed and were already on the status page. They fail for
+independent reasons: at the converged point the command is nowhere near the rail,
+and at the rail against a real load the kWh registers move within seconds. At the
+shipped 300 s there is also a structural relation, not just a margin — the
+slowest a healthy 1 Wh register can tick and still look unchanged is 12 W, which
+is inside the 15 W deadband, so the command there is parked at 0 W and the two
+halves cannot both be true.
+
+**Notification only, deliberately.** An HA persistent notification (fixed
+`notification_id`, so a repeat replaces rather than stacks), an `ERROR` log line,
+a UI event and a red status banner. No claim, no latch, no 0 W: a false trip
+parks the battery and the operator's next move is to switch the guard off; a
+false notification costs an alert. The trip is a separate decision that needs
+data from a real install.
+
+- New option `meter_freeze_s` (default 300, range 60–3600, no "off").
+- **Only `meter_source: homewizard_local` is covered** — it is the only transport
+  that sees the meter's own document. Everywhere else the status page says
+  **NOT COVERED** rather than "armed".
+- `DOCS.md` now states the **capacity-tariff exposure** this does *not* close:
+  `peak_cap_w` caps maintenance charging and nothing caps the loop, so a lying
+  meter can drive a 5 kW unattended import, and ≥15 minutes of that sets the
+  month's billed peak (measured: one 4998 W quarter moved a monthly peak from
+  4832 → 5013 W). That cap is SAFETY-07.
+- `test_freeze.py` grades it in both directions: silent over 40 minutes of the
+  live house's real converged capture (committed as
+  `scenarios/p1-age-2026-08-26.jsonl.gz`), silent over an hour of TEL-05's
+  low-power case where a bare threshold is shown to fire, and alarming on a
+  genuinely frozen meter driven over real HTTP through the real
+  `HomeWizardLocalSource` — against the rig's own `hwsim` `freeze` fault when the
+  infra repo is reachable, an equivalent stub otherwise. Its negative twin is the
+  load-bearing one: the same railed command against a meter that is still moving
+  must stay silent at the same threshold.
+
+## 0.5.1
+
+**SAFETY-02's latch now survives an add-on restart, which is the difference
+between a latch and a pause.** `auto` was persisted and `sign_wd.tripped` was
+not, so reconstructing the `Controller` against the same store — exactly what a
+container restart does — brought it back **armed, into the same fault, with no
+operator involved**: `tripped=False`, banner back to `NOT READY`, and it resumed
+commanding (measured: −1000 W, −2000 W) before re-tripping 180 s later. Under a
+Supervisor that restarts a crashed add-on that is a loop of three-minute
+wrong-direction bursts — and "restart the add-on" is the first thing an operator
+looking at a `FAILSAFE` banner and a 0 W inverter will try.
+
+`sign_tripped` and `sign_reason` are now `Store` keys beside the maintenance
+state, written the moment the trip happens (reason first, flag second, so a crash
+between the two can never persist a latch with no explanation) and restored in
+`Controller.__init__`. Cleared only by the operator's start. `DOCS.md` said "it
+does not clear itself"; that was false across a restart and now is not.
+
+Also in this release, all of it review follow-up rather than new behaviour:
+
+- **The arming gate is tested against the real arbiter.** It was the decision the
+  whole ticket turns on and it was asserted in three comment blocks and verified
+  by nothing — every case passed `following` in as a literal. `test_watchdog.py`
+  now derives it from `resolve()` across twelve claim configurations, including
+  the redirect case `winner == "loop"` alone would have got wrong and the `lo`
+  limit that raises magnitude without flipping sign.
+- **The MQTT `status: "failsafe"` value is tested.** The check that claimed to
+  cover it restated the assertion three lines above it and never touched the
+  payload.
+- **A forward hazard written down where it will be read, and made to bite.**
+  `winner == "loop"` disarms the watchdog under any higher-priority SET claim.
+  Today only maintenance and the safety stops emit one and neither follows the
+  meter; a peak-shaving strategy at `P_PEAK` **does**, and would blind the
+  watchdog for every peak event.
+
+  The gate is now `watchdog.loop_is_following()`, called by both `main.py` and
+  the test, for the same reason `disagrees()` was extracted: the test held a
+  *transcription* of the shipped expression, so editing the shipped gate alone to
+  `winner in ("loop", "peak")` left every suite green while the watchdog went
+  blind. Two copies, and the one that drifts is the one doing the grading.
+
+  ⚠️ Extracting it was not sufficient on its own. The realistic P_PEAK row —
+  peak shaving asking for *more* than the loop — still could not detect the
+  widened gate, because the magnitude term rejects it regardless and masks the
+  winner term. A second row with peak asking for *less* isolates `winner` as the
+  only deciding term, and that is the one that turns red.
+- **The worked example described a configuration that does not ship.** At the
+  defaults `maintenance_charge_w` (2500) exceeds `max_w` (2000), so that claim is
+  an arbiter *contradiction* resolving to 0 W, not a −2500 W charge. The example
+  is now written at 1500 W. (The contradiction is a real pre-existing bug —
+  a default cheap-window maintenance charge silently never happens — filed
+  separately, deliberately not fixed here.)
+- **`disagrees()` is public**, so `sim/replay_sign.py` stops carrying its own copy
+  of the predicate it grades.
+- `held_s` takes the clock instead of reading one, restoring the pure-function
+  property the module advertises.
+- **The `sign_reason`-before-`sign_tripped` write ordering is enforced, not just
+  documented.** Swapping the two lines used to pass every check. A store that
+  fails the second write now proves the property the ordering exists for: what
+  survives a crash mid-trip is a reason with no latch, never a latch with no
+  explanation.
+- Measured figures corrected throughout: 93.4 % / 4212 of 17280 (was 92.9 % /
+  4127 of 16349), per-cluster 0.3 / 0.9 / 10.5 / 0.0 %.
+
+## 0.5.0
+
+**SAFETY-02 — the sign-disagreement watchdog.** The add-on now watches whether
+the setpoint it is emitting and the grid figure it is regulating on point the
+same way. If they oppose each other, both over `sign_disagree_w` (300 W), for
+`sign_disagree_s` (180 s) **continuously**, it files a failsafe claim at
+`P_SAFETY`, commands **0 W**, and latches there until an operator starts control
+again. New module `app/watchdog.py`; new options `sign_disagree_w` and
+`sign_disagree_s`.
+
+This is the gap the existing failsafes leave open. The stale-input watchdog asks
+whether the meter is still talking, the saturation freeze asks whether the
+inverter can follow, the output clamp asks whether the number is too big — a
+loop can pass all three while charging the battery out of the grid, because the
+only thing wrong is the sign. On 2026-08-20 a commercial controller did exactly
+that four times in one day, for up to 77 minutes at a stretch, and reached a
+commanded −14 768 W against a ±5000 W inverter.
+
+Validated against that day. `sim/replay_sign.py` in the infra repo drives this
+module over the committed RS485 captures of both 2026-08-20 (the four episodes)
+and 2026-08-23 (healthy): **18 trips on the fault day, every one inside a window
+`NOTES.md` §4.7 accounts for, and 0 on the healthy day.** The four episodes do
+share one signature rather than merely resembling each other — sign agreement
+runs 0.3 / 0.9 / 10.5 / 0.0 % inside them against 93.4 % on the healthy day.
+
+Three decisions worth knowing about:
+
+- **It is disarmed whenever the grid-following loop is not what is driving.**
+  Sign agreement is a property of a loop that follows the meter. A maintenance
+  grid charge opposes the meter *by design* — 2500 W of charge into a house
+  drawing 500 W is +3000 W on the meter against a −2500 W command, for hours —
+  and armed unconditionally this would trip on every maintenance cycle. The gate
+  tests the emitted number, not the winning claim's name: a limit claim can let
+  the loop "win" and still replace its value with one pointing the other way.
+- **The trip latches.** Commanding 0 W removes the command side of the
+  comparison, so the disagreement always clears the moment the trip works.
+  Un-latched, this would trip, clear, and hand the actuator back to the loop that
+  was driving the wrong way, every three minutes forever.
+- **`sign_disagree_w` at or above `max_w` is refused at startup** (validator rule
+  5). The arbiter never lets a command exceed `max_w`, so such a threshold makes
+  the watchdog incapable of firing while the status page still reports it armed.
+  A disarmed guard that advertises itself as armed is the failure mode this
+  project keeps refusing to ship.
+
+What it does **not** catch, stated so nobody assumes otherwise: an inverter that
+acts opposite to what it was told moves the meter *further* the same way, so
+command and meter agree while everything runs away. That is the saturation
+freeze's job, which compares the command against the battery's actual power.
+
+`test_validate.py`'s "the smallest sane max_w still starts" case now names a
+reachable sign threshold, because a 1 W ceiling genuinely does disarm the 300 W
+default and is now correctly refused.
+
+## 0.4.0
+
+**CFG-01.** The add-on now refuses to start on a configuration it cannot honour,
+instead of logging a line and carrying on. `validate_startup_config()` runs in
+`amain()` before the broker, the web server or any task exists, so a refusal
+cannot leave half a controller running behind a UI.
+
+It refuses only where continuing produces one of two outcomes: **(a)** a stated
+limit is untrue - the operator configured a bound and a lower layer silently
+enforces a different one - or **(b)** the add-on is inert and indistinguishable
+from healthy. (b) is not a special case of (a): with no `setpoint_entity`, layer
+1 pinning the inverter at 0 W is the failsafe *working*. The system does not
+become unsafe, it becomes a convincing impression of a working controller.
+
+Four things qualify:
+
+- **`max_w` above (or below) the setpoint device's own rating.** This is the one
+  that changed behaviour. It used to warn `the device wins` and run anyway, with
+  `write_setpoint()` silently clamping, so the configured ceiling was never the
+  real one and the only evidence had scrolled off the log. The refusal names the
+  configured value, the device's value, and which wins.
+- **No `setpoint_entity`.** A controller with no actuator: every write is a
+  no-op, the device rating is never read, and the ESP32 heartbeat that holds off
+  the layer-1 failsafe never happens. It ran, looked healthy, and moved nothing.
+- **A `meter_source` that can never produce a reading** - missing `p1_host`,
+  missing `p1_net_entity`, a blank MQTT topic, a phase list disagreeing with
+  `meter_phases`, an unknown source name, or a `meter_poll_s` at or past
+  `meter_max_age_s`. These were already caught, but they only *disabled
+  ingestion*, which leaves the grid reading None forever: permanent "inputs
+  missing", 0 W, and a status page indistinguishable from a healthy meter nobody
+  has sent anything to yet.
+- **`meter_max_age_s` above the firmware's ingest veto.** The schema accepts
+  `int(5,300)`; the ESP32's threshold is a compile-time `max_age_s: "30"` and it
+  trips layer 1 at `p1_age_s >= 30`. Set 120 and the add-on treats a 119 s
+  reading as fresh and keeps commanding, while the firmware has already vetoed
+  and is holding the inverter at 0 W - healthy meter, running controller,
+  nothing moving, and no line anywhere saying the number you set was overruled.
+  Structurally the same fault as the `max_w` case. Only *above* the veto is
+  refused: below it the add-on gives up first, which is fail-safe and visible on
+  its own status page. Mirrored as `validate.FIRMWARE_INGEST_VETO_S` - it cannot
+  be imported from a compile-time YAML substitution, so it carries a note about
+  the one direction in which it can go stale.
+
+`max_w` at or below zero is refused too. Schema-blocked on a real install, but
+`validate_startup_config()` is now also the simulation suite's entry point, and
+a non-positive `max_w` inverts the arbiter's `supervised` bounds into a
+contradiction that resolves to 0 W - i.e. it would read as a safety trip rather
+than as the typo it is.
+
+The predicates for the meter group still live in `p1.validate_meter_options()`,
+which `build_source()` also calls - one definition, two callers, not two
+competing validators. Two transports gained a check they never had: `ha_dsmr`
+with only one of its two entities, and `mqtt_p1` with a blank topic, both of
+which previously built a transport that could never read.
+
+Deliberately **not** refused, because it is untidy rather than unsafe:
+`integrator_max_w` above `max_w` (the arbiter still bounds the wire to ±max_w,
+so the cost is unwind latency, not amperage - warned), a missing `soc_entity` /
+`batt_entity` (fail-safe, and already a red NOT READY banner naming it), a
+`setpoint_entity` that has not appeared on the Core API yet (ESPHome is routinely
+late; refusing would make a slow boot need a human - re-checked once the real
+rating arrives), and a thin-but-nonzero `meter_poll_s` margin.
+
+A refusal is legible as a refusal: a banner that says in words that this is a
+configuration problem and nothing is broken, the numbered problems, no traceback,
+and exit status 78 (`EX_CONFIG`).
+
+**SAFETY-12.** The control loop now evaluates on a clock as well as on a change.
+`run_control()` ran `cycle()` only when the meter value differed from the
+previous poll, so a meter that repeated a value ran **no control cycles at
+all** - while the heartbeat went on re-emitting the last command and the
+firmware went on putting it on the wire every 2 s. Layer 1 stayed fed, every
+indicator read healthy, and a command computed from an old reading kept being
+executed through whatever the load did next. Measured on the rig during TEL-05:
+70 s at a literally constant 350.0 W with 14 arrivals and zero cycles.
+
+**It was worse than a latency limit: it was a safety claim that could not
+fire.** `stale_input_s` and the `inputs missing -> 0 W` claim both live *inside*
+`cycle()`. Pre-fix, if the meter value happened to be constant, `cycle()` was
+never called again - so that claim had no way to run. Constant meter, SoC entity
+dying at t=4 s, same binary:
+
+```
+pre-fix    writes: [(0.0, 220.0), (0.0, 220.0), (10.1, 220.0)]
+           final target: 220.0 W   reason: 'loop -> 220 W'
+post-fix   writes: [(0.0, 220.0), (0.0, 220.0), (3.0, 430.0), (9.1, 0.0), (10.1, 0.0)]
+           final target: 0.0 W     reason: 'safety -> 0 W'
+```
+
+The pre-fix controller held 220 W through the entire input outage with its
+status line still reading `loop -> 220 W`, and layer 1 does not cover that case
+on a `meter_source: off` install: no P1 age sensor is published, so the firmware
+has nothing to veto on, while the heartbeat keeps its watchdog fed. So the old
+behaviour was not "holds a stale command safely" - it was a failsafe that a
+repeating meter switched off. `test_loop.py` asserts both halves.
+
+`cycle_floor_s` (default **15 s**) is a deadline on the gap between cycles, not
+a second scheduler: every cycle resets it, whichever trigger fired. On a healthy
+meter it never elapses, so the cycle rate, the write sequence and therefore the
+per-cycle gain the tuning was measured against are unchanged - asserted in
+`test_loop.py` by driving the real loop twice on one binary (a huge
+`cycle_floor_s` reproduces the old behaviour exactly) and comparing the
+commanded values.
+
+The reset is not the only thing holding that up, and the other argument is the
+sturdier one: the combined cycle rate is `max(arrival rate, 1/floor)`, never the
+sum. At 1/15 s the floor is strictly slower than the ~1/5 s arrival rate, so
+even a hypothetical floor racing the arrivals could not exceed the nominal
+healthy rate. The re-tune is unreachable by construction. ⚠️ That holds only
+while `cycle_floor_s` stays above the meter's update interval, and the schema
+minimum is 5 s - which is exactly the reference meter's interval. Nothing
+enforces the relationship; `validate.py` is the obvious home for it and does not
+have it yet.
+
+Observed over six real minutes on the same rig, one binary, meter held at a
+literally constant 350.0 W: **before, 1 cycle** (at startup) and then nothing,
+the command stuck at 220 W against a 350 W import for the rest of the window.
+**After, 24 cycles**, worst gap 15.14 s, and the ordinary PI ramp doing its job -
+220, 430, 650, 860, 1080, 1300, 1510, 1730, 1940, 2000 W, one step per cycle,
+rail at t=136 s and flat after. Three minutes with the meter parked at the
+target instead: **1 cycle before, 12 after, and 19 writes either way - the same
+19**. Three minutes on a normally-changing meter: **36 cycles and 49 writes on
+both sides, the same values in the same order.** The heartbeat write count never
+moves; the only writes the fix adds are the ten the loop was supposed to be
+making all along.
+
+15 s is bracketed, not round.
+
+**Below it, ~11 s, and it arises more routinely than a dropped poll.**
+`HomeWizardLocalSource` polls at 5.0 s against a meter that updates every 4.97 s
+(NOTES.md:640). Two near-equal periods beat, so roughly once every ~14 minutes
+the poller steps over an update entirely - a ~10 s gap between changed values on
+a perfectly healthy meter, plus up to 1 s for the 1 s tick to notice. A failed
+HTTP poll (retried on the next tick, no backoff) adds another 5 s. The floor
+sits above the beat-skip so it does not fire on that alone; what it takes to
+reach 15 s is a beat-skip *and* a failed poll coinciding.
+
+**Above it, 30 s.** `meter_max_age_s` is 30 s, past which there is no reading to
+evaluate, and the firmware's ingest veto is also 30 s - so the loop is
+guaranteed to have re-decided at least twice inside any window in which layer 1
+might otherwise be the only thing deciding. ⚠️ The default is therefore not
+independently justified at 15: if the firmware's veto ever moves, this moves
+with it. Noted beside the constant in `main.py`.
+
+It is also exactly `stale_input_s`, this system's existing answer to "how long
+may we hold without re-deciding".
+
+A floor cycle runs the **full** law on the same inputs, integrator included. In
+P1 mode the freshness question is already answered upstream and answered harder
+- past `meter_max_age_s` the reading is None, which is "inputs missing", which
+is a `P_SAFETY` 0 W claim - so a floor cycle there can only ever run on a reading
+this system already calls fresh. ⚠️ That is transport-conditional: with
+`meter_source: off`, `read_inputs()` takes the grid figure straight from
+`hass.number()` with **no age gate at all**, so a Home Assistant entity that has
+gone quiet reads as current on that path, with or without this change. Running
+the full law is still right there - the alternative is a degraded second law
+reasoning about an age nobody measured - but the floor does not make that path
+fresh. The integrator advances per *cycle*, not per second,
+so bounding the gap bounds the accumulation; `integrator_max_w` bounds it after
+that. A gentler second law for floor cycles would be a second set of dynamics
+nobody can test on this hardware.
+
+⚠️ **This is not a freeze detector**, and TEL-05 established one cannot be built
+here: at the converged -10 W target a 1 Wh register needs ~6 minutes to move
+while the power figure legitimately repeats, so any threshold on `unchanged_s`
+false-trips at the exact operating point we run at. Nothing in this change
+decides whether a repeated reading is *true*. It stops "the number is the same"
+from meaning "do not think". The consequence, stated plainly: against a meter
+genuinely frozen at a wrong value the loop will now correct toward that wrong
+value rather than hold a stale command, bounded by `max_w`, the arbiter and the
+device rating. That was already what happened to a lying meter whose value
+merely jittered; bit-exact repetition was never a safety property.
+
+`DOCS.md`'s "Saturation is counted in cycles, not seconds" section documented
+the old behaviour as an accepted deviation. It is **qualified, not deleted**:
+the deviation survives (the window is still counted in cycles, and 3 x 15 s is
+still not the specification's 10 s) but it is now bounded at 45 s instead of
+open-ended, and the passage's second justification - "nothing accumulates while
+it is stalled" - is called out as having covered integrator windup and not
+staleness, which was the actual hazard. The same wrong argument in
+`control.py`'s saturation comment is corrected too.
+
+**TEL-04.** `meter_source: ha_signed` reads a single *signed* power entity, which
+is the shape a HomeWizard P1 publishes. Both transports 0.3.0 shipped require two
+unsigned registers and refuse negatives, so neither fits the meter installed here.
+
+**TEL-05.** `meter_source: homewizard_local` polls the meter's own local API
+directly. This exists because of something the HA paths cannot do: Home Assistant
+fires no state change for a repeated reading and exposes no arrival signal at
+all, so `sensor.p1_sample_age_s` on those transports measures time since the
+*value changed*, not since the meter *reported*. Real captured data has gaps of
+42 s and 97 s between changes on a perfectly healthy meter - long enough for a
+30 s staleness threshold to command 0 W for no reason. Every HTTP response to the
+local API is a genuine arrival, so the age means what it says.
+
+Verified on the rig against a literally constant 350.0 W for 70 s - the exact
+state where the HA path recorded zero samples in 45 s - with 14 arrivals and the
+age never exceeding the poll cadence.
+
+Set `p1_host` to the meter's address and `meter_poll_s` (default 5 s, matching
+the meter's own ~5 s update). Still defaults to `off`; nothing changes for an
+install that does not opt in.
+
+Freeze detection is separate and deliberately not thresholded: a meter answering
+200 OK with a stale number *is* arriving, so no arrival stamp can flag it. The
+energy registers carry that as `unchanged_s`, surfaced on the status line for a
+human to read rather than alarmed on - at a converged -10 W a 1 Wh register needs
+about six minutes to move, so any threshold would false-trip at the target
+operating point.
+
+## Unreleased
+
+**TEL-05.** A fourth `meter_source`, `homewizard_local`, which polls a
+HomeWizard P1's **own local API** (`GET /api/v1/data`) instead of watching a
+Home Assistant entity. Set `p1_host` to the meter's address; `meter_poll_s`
+(default 5 s, the meter's own update rate) sets the cadence.
+
+✅ **This is the first transport whose `sensor.p1_sample_age_s` measures when
+the meter *reported*, and therefore the first one a firmware watchdog may
+threshold.** Every HTTP response is an arrival: the meter answered, now, with
+its current reading, and whether the *number* moved is not consulted. Home
+Assistant cannot express that at all — a repeated reading emits no
+`state_changed`, advances `last_reported` on neither serialiser, and
+`state_reported` is not subscribable ("Event filter is required"). On
+`ha_signed` that made a healthy meter under a flat load indistinguishable from
+a dead one, and our own capture of this house's meter goes 42.2 s and 97.0 s
+between changes — both past the default `meter_max_age_s` of 30, i.e. a false
+trip to 0 W on a meter that is fine. If you have a HomeWizard P1, move to this
+mode.
+
+Everything TEL-01 established is reused, not re-implemented: ingest
+timestamping, `meter_max_age_s`, the clock-recomputed age, the plausibility
+bounds and the §20 unsigned-decode rejection, and the same `split_signed` sign
+convention `ha_signed` uses. A failed or timed-out poll submits nothing, so it
+is a *missing* reading — never 0 W — and it does not reset the age.
+
+Verified on the ENV-01 rig against `sim/hwsim.py`, steady and with `--fault
+freeze` injected. Still defaults to `off`.
+
+⚠️ **An arrival stamp still cannot see a *frozen* meter**, and no arrival
+detector can: a meter answering `200 OK` forever with a stale number is
+arriving. The local API does expose what the HA path never had — the
+`total_power_*_kwh` registers stop advancing — and the transport tracks it as
+`unchanged_s`, but that is deliberately **not** folded into the age and not
+thresholded: this controller regulates grid power toward ~0 W, and at a
+converged −10 W the export register needs six minutes to move by its 1 Wh
+resolution while the power figure legitimately repeats. Thresholding it at 30 s
+would rebuild the false-trip limit cycle at the exact operating point we aim
+for. Freeze detection needs the low-power case solved first, separately. It is
+shown on the status page's P1 line instead — leaving it unthresholded only
+holds up if a human can read it, so now they can.
+
+**TEL-04.** A third `meter_source`, `ha_signed`, reading **one signed** Home
+Assistant entity: positive = import, negative = export. That is the shape a
+HomeWizard P1 publishes (`sensor.p1_meter_active_power`), and it is the meter
+actually fitted here - which neither TEL-01 transport can read, because
+`ha_dsmr` needs two unsigned registers and refuses a negative one, i.e. every
+exporting telegram. Set `p1_net_entity`, and `p1_phase_net_entities` for the
+per-phase capacity-tariff figures on a three-phase connection.
+
+Everything TEL-01 established is inherited rather than re-implemented - the
+new transport is a subclass of the `ha_dsmr` one overriding only which
+entities it wants and how they become a sample. So ingest timestamping,
+`meter_max_age_s`, `sensor.p1_sample_age_s` recomputed against the clock and
+republished once a second, the plausibility bounds, and `unavailable` /
+`unknown` treated as a *missing reading and never 0 W* all behave identically
+across the three sources.
+
+Still defaults to `off`; an existing install is unaffected until it opts in.
+
+⚠️ **`sensor.p1_sample_age_s` is published on `ha_signed`, but must not yet be
+thresholded by the ESP32 stale-input watchdog.** On the HA WebSocket paths the
+age is stamped from `state_changed`, so it measures time since the value
+*changed*, not since the meter *reported* - and Home Assistant exposes no
+arrival signal for a repeated reading (no `state_changed`, no `last_reported`
+movement on either serialiser, and `state_reported` is not subscribable over
+the WebSocket). Measured on the ENV-01 rig against the real HomeWizard
+integration. `ha_dsmr` mostly escapes it because a telegram moves several
+entities at once; `ha_signed` has one, so a healthy meter under a flat load is
+indistinguishable from a dead one. Our own capture has the house meter going
+42.2 s and 97.0 s between changes. Raising `meter_max_age_s` does not fix that,
+it only chooses which error you get; the fix is an arrival stamp from the meter
+itself and is a separate ticket. Full detail in DOCS.md.
+
 ## 0.3.0
 
 **SAFETY-04.** The control law's integrator is now an explicit accumulator,

goodwe_controller/DOCS.md

@@ -24,9 +24,16 @@ The inverter **holds its last command forever** — it has no meter-timeout. So:
   commanding it.
 - This add-on commands 0 W when its inputs go missing, when you stop control,
   and when it shuts down.
+- This add-on commands 0 W **and latches there** if what it is commanding and
+  what the meter reads point opposite ways for three minutes — see "The
+  sign-disagreement failsafe" below.
 - The **optional RS485 e-stop** is the only thing that covers this machine
   dying. Without it, a failed host leaves the battery latched at its last
   command until someone intervenes.
+- This add-on **raises an alarm — and nothing more —** when the meter keeps
+  answering with a reading that never changes while the command sits at the
+  rail. See "The frozen-meter alarm" and, before you rely on it, "Capacity-tariff
+  exposure of the grid-following loop".
 
 **If anything looks wrong: stop the add-on.** That commands 0 W and the
 hardware holds it there.
@@ -51,21 +58,67 @@ phase having charged nothing.
 ### P1 meter ingestion
 
 `meter_entity` above expects one signed sensor, which usually means a template
-someone wrote by hand. A Belgian P1 meter does not publish one: it publishes two
-**unsigned** registers, consumption and injection. Setting `meter_source` moves
-that subtraction into the add-on, where it is done once and tested, and replaces
-`meter_entity` entirely.
+someone wrote by hand. Setting `meter_source` moves the whole derivation into
+the add-on, where it is done once and tested, and replaces `meter_entity`
+entirely.
+
+Which mode you want depends on what your P1 reader publishes, and there are two
+shapes in the wild:
+
+- **Two unsigned registers**, consumption and injection, which is what a Belgian
+  P1 read over DSMR gives you → `ha_dsmr`, or `mqtt_p1` for a bridge. The add-on
+  subtracts them.
+- **One signed figure**, positive = import and negative = export, which is what
+  a HomeWizard P1 gives you (`sensor.p1_meter_active_power`) → `ha_signed`. The
+  add-on splits it. `ha_dsmr` **cannot** read this: it wants two registers and
+  rejects a negative one outright, which is every exporting telegram.
+
+Either way, do not build the missing shape out of template sensors. The point of
+`meter_source` is that the sign convention is derived in one tested place rather
+than in YAML nobody reviews underneath a safety input.
+
+> ✅ **If your meter is a HomeWizard P1, use `homewizard_local`, not
+> `ha_signed`.** It reads the same meter and produces the same numbers, but it
+> polls the meter directly instead of watching a Home Assistant entity — and
+> that is the difference between an age sensor a watchdog can threshold and one
+> it cannot. See "`sensor.p1_sample_age_s`" below; `ha_signed` remains for
+> installs where the meter is only reachable through Home Assistant.
+
+> ⚠️ **`ha_dsmr` and `mqtt_p1` have never processed a telegram from real
+> hardware.** No meter in this installation uses either one. Both were written
+> to the assumption in `specs.md` §5.2 that a Belgian P1 exposes two unsigned
+> registers, and the meter actually fitted here does not — it is the HomeWizard
+> P1 that `ha_signed` reads. They are covered by the unit checks in `test_p1.py`
+> and by an end-to-end test against a fake Home Assistant, and nothing more.
+>
+> This is recorded because the realistic way it bites is someone debugging a
+> meter problem months from now treating those two paths as proven and looking
+> for the fault elsewhere. If you are the first person to point one at a real
+> meter, expect to find something, and please update this note when you do.
 
 | option | default | meaning |
 |---|---|---|
-| `meter_source` | `off` | `off` keeps `meter_entity`. `ha_dsmr` subscribes to the DSMR integration over the HA WebSocket; `mqtt_p1` reads a topic |
+| `meter_source` | `off` | `off` keeps `meter_entity`. `ha_dsmr` subscribes to the DSMR integration over the HA WebSocket; `mqtt_p1` reads a topic; `ha_signed` subscribes to one signed entity over the HA WebSocket; `homewizard_local` polls a HomeWizard P1's own local API, bypassing Home Assistant |
 | `meter_phases` | 1 | 1 or 3. Must match the telegram, or every telegram is rejected and logged |
 | `meter_max_age_s` | 30 | Beyond this the reading is stale and grid power reads as *missing*. On its own it does **not** command 0 W — see the timing note below. It is also the longest a reading is held forward into the 15-minute average |
+| `meter_poll_s` | 5 | `homewizard_local` only. Seconds between polls. **Must be well under `meter_max_age_s`** — see below |
+| `p1_host` | | `homewizard_local` only. The meter's own address, `host` or `host:port` (e.g. `192.168.2.250`) |
 | `meter_mqtt_topic` | | `mqtt_p1` only |
 | `p1_import_entity` | | The **unsigned** consumption sensor. Do not point this at a signed template |
 | `p1_export_entity` | | The **unsigned** injection sensor |
 | `p1_phase_import_entities` | `[]` | L1..L3, in order. Needed for the capacity-tariff peak on a three-phase connection |
 | `p1_phase_export_entities` | `[]` | L1..L3, in order |
+| `p1_net_entity` | | `ha_signed` only. The **signed** net-power sensor: `+` import, `-` export |
+| `p1_phase_net_entities` | `[]` | `ha_signed` only. L1..L3, in order, each signed the same way. Needed for the capacity-tariff peak on a three-phase connection. **The list length must equal `meter_phases`** |
+
+Both per-phase lists are checked against `meter_phases` **once at startup**: a
+list of the wrong length disables P1 ingestion with an error in the log, rather
+than letting every telegram fail its phase-count check one at a time. Leaving
+the list empty is fine and is not an error — you simply get no per-phase
+figures, and therefore no capacity-tariff peak. On a three-phase connection
+that is a much bigger omission than it looks: on a surveyed reading here the
+phases carried 2769 W of import while the connection netted 187 W, so the
+billed quantity is understated roughly fifteenfold if the phases are missing.
 
 #### How long a dead meter takes to reach 0 W
 
@@ -106,6 +159,55 @@ tested, and guessing a key here means guessing a kilowatt:
 it is present it is used for the age, which is what stops a retained message
 replayed on reconnect from presenting a ten-minute-old reading as current.
 
+#### `homewizard_local` — polling the meter instead of Home Assistant
+
+Set `p1_host` to the meter's address and the add-on does `GET /api/v1/data` on
+it every `meter_poll_s` seconds, reading `active_power_w` (signed, same
+convention as `ha_signed`) and the three `active_power_l{1,2,3}_w` fields. Home
+Assistant is not involved: no entity, no WebSocket, no integration to
+mis-configure. Per-phase figures are used only when the meter serves all
+`meter_phases` of them — a single-phase meter returns `null` for L2/L3, and the
+connection-level reading is still accepted on its own.
+
+**Why this mode exists:** every HTTP response is an *arrival*. The meter
+answered, now, with its current reading — whether or not the number moved. That
+is the signal `sensor.p1_sample_age_s` needs and the one Home Assistant cannot
+give it at all (see the note below). It is also simply fewer moving parts: the
+five-second cadence is the meter's own, rather than an integration's polling of
+it re-published as a state change.
+
+**Cadence.** The age is never fresher than the poll interval, so:
+
+| | |
+|---|---|
+| meter's own update rate | ~5.0 s (measured 4.97 s) |
+| `meter_poll_s` default | 5 s — nothing to gain below the meter's own rate |
+| `meter_max_age_s` default | 30 s, i.e. six polls of headroom |
+| `meter_poll_s >= meter_max_age_s` | **refused at startup** — every reading would be stale before its successor arrived |
+| `meter_poll_s > meter_max_age_s / 2` | warned — one missed poll makes the reading stale |
+
+A failed poll — timeout, connection refused, non-200, unparseable body — is a
+**missing** reading. It submits nothing, so the reading does not become 0 W, the
+last good value and its timestamp are left alone, and the age goes on climbing.
+That is exactly what a dead meter should look like.
+
+**What it still cannot see: a frozen meter.** A meter that answers `200 OK`
+forever with a stale number is arriving, so no arrival detector — this one
+included — can tell it from a healthy one. The local API does expose the raw
+material the HA path never had (the `total_power_*_kwh` registers stop
+advancing), and the transport tracks it as `unchanged_s`, but it is deliberately
+*not* folded into the age and *not* thresholded: this controller regulates grid
+power toward ~0 W, and at a converged −10 W the export register needs six
+minutes to move by its 1 Wh resolution while the power figure legitimately
+repeats. Thresholding that at 30 s would rebuild the false-trip limit cycle at
+the exact operating point the controller aims for. Freeze detection is a
+separate problem and needs the low-power case solved first.
+
+You read it yourself instead: the add-on's status page shows it on the P1 line,
+as `… 4 rejected, measurement unchanged for 312 s`. On a house drawing real
+power that figure stays in the seconds; minutes of it while the load is clearly
+not near zero is the meter to go and look at.
+
 #### `sensor.p1_sample_age_s`
 
 Published over MQTT discovery whenever a broker is available: **seconds since the
@@ -123,13 +225,48 @@ The entity is only created when `meter_source` is not `off`. With P1 ingestion
 disabled there is nothing feeding it, and an age sensor climbing with no ingester
 behind it would trip the firmware watchdog on a system that is working fine.
 
-> **Known limit, `mqtt_p1` only.** The age measures *arrival*, not change. On the
-> `ha_dsmr` path that is exactly right: a frozen meter emits no `state_changed`,
-> so nothing arrives and the age climbs. On the MQTT path a bridge that is stuck
-> republishing its last telegram keeps arriving, so the age stays near zero and a
-> frozen meter still looks fresh. Detecting *that* needs a change-detector rather
-> than an arrival-detector, and it is not in this version. Prefer `ha_dsmr` where
-> both are available.
+> **Known limit, `mqtt_p1`.** The age measures *arrival*. On the MQTT path a
+> bridge that is stuck republishing its last telegram keeps arriving, so the age
+> stays near zero and a frozen meter still looks fresh. Detecting *that* needs a
+> change-detector rather than an arrival-detector, and it is not in this version.
+
+> ⚠️ **Known limit, `ha_signed` — do not drive a watchdog off this age yet.**
+> On the HA WebSocket paths the age is stamped when a `state_changed` arrives,
+> which means it measures *time since the value last changed*, not time since
+> the meter last reported. Home Assistant offers nothing better: a repeated
+> reading produces no `state_changed`, does **not** advance `last_reported` on
+> either the REST or the WebSocket serialiser, and `state_reported` cannot be
+> subscribed to over the WebSocket at all (`Event filter is required for event
+> state_reported`). All three measured on the ENV-01 rig against the real
+> HomeWizard integration with the meter frozen: 0 `state_changed` in 70 s and no
+> timestamp movement anywhere.
+>
+> `ha_dsmr` mostly escapes this because a DSMR telegram updates several entities
+> and something in the set almost always moves. **`ha_signed` has exactly one
+> entity, so a healthy meter under a flat load is indistinguishable from a dead
+> one.** This is not hypothetical: in our own captures
+> (`sim/scenarios/ha-p1_meter_active_power-2026-08-20.json`) the real house meter
+> went **42.2 s and 97.0 s** between changes, and 23 Aug peaks at 29.1 s — all
+> past the default `meter_max_age_s` of 30.
+>
+> So `sensor.p1_sample_age_s` on `ha_signed` is safe to *read*, and it is
+> correct whenever the value is moving, but it must not yet be thresholded by
+> the ESP32 stale-input watchdog: a quiet house would trip the battery to 0 W.
+> Raising `meter_max_age_s` is **not** the fix — the two conditions produce an
+> identical signal, so a bigger number only chooses which of the two errors you
+> get. The real fix is an arrival stamp the meter itself provides — and that now
+> exists: **`meter_source: homewizard_local`**. If you have a HomeWizard P1,
+> switch to it. If your meter is only reachable through Home Assistant, this
+> limit still applies to you and the watchdog threshold still must not be armed.
+
+**Where the age is trustworthy:**
+
+| mode | the age measures | safe to threshold from firmware |
+|---|---|---|
+| `homewizard_local` | time since the meter **answered** | **yes** — every HTTP response is an arrival |
+| `ha_dsmr` | time since one of several entities changed | no — statistically usually fine, which is a masked bug, not an absent one |
+| `ha_signed` | time since the one entity changed | **no** — see above |
+| `mqtt_p1` | time since a message arrived | arrivals yes, but a stuck bridge republishing keeps arriving |
 
 ### Control
 
@@ -142,11 +279,69 @@ behind it would trip the firmware watchdog on a system that is working fine.
 | `target_grid_w` | -10 | What the meter should rest at. Negative = a slight export |
 | `step_w` | 10 | Quantisation |
 | `saturation_w` | 500 | Divergence that counts as "the inverter is at a limit" |
-| `saturation_cycles` | 3 | How many consecutive cycles before freezing. A cycle is one *changed* meter reading, not a fixed period - see the note below. **Do not set to 1** |
+| `saturation_cycles` | 3 | How many consecutive cycles before freezing. A cycle is one meter update or `cycle_floor_s`, whichever comes first - see the note below. **Do not set to 1** |
 | `integrator_max_w` | 0 | Bound on the loop's accumulator, and 0 means "same as `max_w`". Caps how much stale error can be waiting to unwind when the sign flips. **Do not raise it above `max_w`** - the output clamp already bounds what is commanded, so the only thing extra headroom buys is more cycles of wrong-direction power after every saturation event. Lowering it below `max_w` is the useful direction |
 | `heartbeat_s` | 10 | Refresh interval; must stay well under the firmware watchdog |
+| `cycle_floor_s` | 15 | The longest the loop may go without evaluating. A deadline on the gap between cycles, reset by every cycle — on a healthy meter it never elapses and changes nothing. Raise it only if your meter is slower than ~10 s; it must stay under `meter_max_age_s`, past which there is no reading to evaluate anyway |
 | `stale_input_s` | 15 | How long inputs may be missing before commanding 0 W. In P1 mode this clock starts only *after* `meter_max_age_s` has already expired — the two stack, see "How long a dead meter takes to reach 0 W" |
 | `auto_start` | false | Start controlling on boot (only after commissioning) |
+| `sign_disagree_w` | 300 | Both the command and the meter must exceed this before a sign difference counts. Must stay **below `max_w`** or the watchdog can never fire, and the add-on refuses to start |
+| `sign_disagree_s` | 180 | How long they must stay opposed, continuously, before the failsafe trips |
+
+#### The sign-disagreement failsafe
+
+If the setpoint this add-on is emitting and the grid figure it is regulating on
+point **opposite ways** — charging the battery while the house imports, or
+discharging it while the house exports — with both over `sign_disagree_w`, for
+`sign_disagree_s` **continuously**, the add-on commands **0 W** and holds it
+there. The banner reads `FAILSAFE`, the commissioning list says which two
+numbers disagreed and for how long, and the `Controller status` entity reports
+`failsafe`.
+
+**It does not clear itself, and restarting the add-on does not clear it either.**
+Pressing *Start / stop control* twice — stop, then start — is the only thing that
+does. That is deliberate on both counts:
+
+- Commanding 0 W removes the command side of the comparison, so the disagreement
+  always vanishes the instant the trip works. A watchdog that took that as proof
+  the fault was over would hand the inverter straight back to the loop that was
+  driving the wrong way, three minutes later, forever.
+- The trip is written to `/data/state.json` and restored on startup. Restarting
+  the add-on is the first thing most people try when they see a red banner, and
+  a latch that a restart clears would bring the controller back **armed, into the
+  same fault, unattended** — and under a Supervisor that restarts a crashed add-on
+  automatically, would do so in a loop. After a restart the banner, the 0 W and
+  the recorded reason are all still there.
+
+**What it is for.** This is a loop-integrity check: it asks whether the loop's
+output direction still matches the input state it was regulating. It catches a
+polarity error anywhere between the meter and the wire, and an integrator so far
+wound up that unwinding takes minutes. It is the check that would have caught all
+four episodes of 2026-08-20, when a commercial controller charged the battery out
+of the grid, four times, for up to 77 minutes at a time.
+
+**What it is not for.** It does not detect an inverter that acts opposite to what
+it was told — that moves the meter *further* the same way, so command and meter
+agree while everything runs away. That is the saturation freeze's job
+(`saturation_w` / `saturation_cycles`), which compares the command against the
+battery's actual power. The two checks are complementary and neither replaces the
+other.
+
+**Why it will not false-trip on ordinary operation.** A battery that refuses a
+command (empty, full, standby) leaves the meter where it was, so command and
+meter agree. A frozen meter drives the loop into agreeing with it. Around the
+resting point both signals are inside the 300 W gate, so the deadband can never
+produce one. A load step does flip the meter's sign before the loop catches up —
+measured on a full captured day, the longest such crossing is 30 s, against a
+180 s window. And the watchdog is **disarmed whenever the grid-following loop is
+not what is driving**: a maintenance grid charge opposes the meter by design and
+must not be mistaken for a fault.
+
+Both numbers are measured rather than chosen, and are exposed only because the
+ticket requires defaults rather than constants. On the captured healthy day sign
+agreement is 93.4 %; on the four captured fault clusters it is 0.3 %, 0.9 %,
+10.5 % and 0.0 %. There is no reason to move either value without a capture that
+says so.
 
 #### Saturation is counted in cycles, not seconds
 
@@ -154,22 +349,43 @@ The specification states the saturation window as **"> 10 s"**. This add-on coun
 **cycles** instead, and that is a deliberate, accepted deviation rather than an
 oversight - the acceptance criterion is not met as literally written.
 
-A cycle here is one *changed* meter reading: the controller only runs the loop when the
-meter value differs from the previous poll. At the reference P1's ~5 s update rate the
-default of 3 cycles is usually around 15 s, but there is **no guaranteed wall-clock
-window** - a meter that repeats the same value stalls the counter for as long as it
-repeats.
+A cycle here is one meter update **or `cycle_floor_s` elapsing, whichever comes
+first**. At the reference P1's ~5 s update rate the default of 3 cycles is usually
+around 15 s, and the worst case is bounded at `3 x cycle_floor_s` = 45 s. It is still
+not the 10 s the specification asks for, so the deviation stands - but it is now a
+bounded number rather than an open one.
 
-Two reasons that is acceptable:
+⚠️ **This passage used to say something different, and the second half of it was
+wrong.** Until SAFETY-12 the loop ran only when the meter value *changed*, so a meter
+that repeated a value stalled the counter for as long as it repeated, with no upper
+bound at all. That was defended here on the grounds that "a stalled counter is a
+detection-latency limit and not a runaway risk - the condition that stalls it stops the
+whole loop, so nothing accumulates while it is stalled". That argument covers
+**integrator windup and nothing else**. The hazard it misses is **staleness**: while the
+loop was stopped the heartbeat kept re-emitting the last command and the firmware kept
+putting it on the wire every 2 s, so a command computed from an old reading went on
+being executed through a real load change, with every indicator reading healthy.
+Measured on the rig during TEL-05: 70 s at a literally constant 350.0 W, 14 arrivals,
+zero control cycles.
 
-- the control law is a pure function with no clock, which is what makes it testable
-  without hardware, and a seconds-based window would have to live in the controller;
-- a stalled counter is a detection-latency limit and not a runaway risk. The condition
-  that stalls it - an unchanging meter - stops the whole loop, so nothing accumulates
-  while it is stalled.
+The half that survives is the first one: the control law is still a pure function with
+no clock, and the wall-clock window still lives in `Controller`, which has one - see
+`run_control()`. What changed is that the controller now enforces a floor on the gap
+between cycles, so `saturation_cycles` finally means a bounded number of seconds.
 
-If a guaranteed window matters on your site, raise `saturation_cycles` for a fast meter,
-and treat the figure as "N meter updates" rather than "N seconds".
+If a tighter window matters on your site, lower `cycle_floor_s` (not below your meter's
+update interval, or the floor starts firing on a healthy meter) or raise
+`saturation_cycles` for a fast meter.
+
+**This is not a freeze detector, and it deliberately cannot be one.** Nothing here
+decides whether a repeated reading is true — see `unchanged_s` in the meter section for
+why no threshold on that is safe at the converged operating point. The floor only stops
+"the number is the same" from meaning "do not think". The consequence is worth stating
+plainly: against a meter that is genuinely frozen at a wrong value, the loop will now
+correct toward that wrong value instead of holding a stale command. It is bounded by
+`max_w`, the arbiter and the device rating, and it is the same thing that already
+happened to a lying meter whose value merely jittered — bit-exact repetition was never a
+safety property.
 
 #### Why `target_grid_w` is not zero
 
@@ -202,8 +418,8 @@ help - see "Why the tuning is what it is".
 | `maintenance_enabled` | false | Enable the monthly cycle |
 | `maintenance_interval_days` | 28 | Minimum gap between cycles |
 | `maintenance_start_hour` | 10 | Hour of day a due cycle begins |
-| `maintenance_discharge_w` | 2500 | Drain rate (exports the surplus) |
-| `maintenance_charge_w` | 2500 | Charge ceiling, capped again by peak headroom |
+| `maintenance_discharge_w` | 2000 | Drain rate (exports the surplus). Above `max_w` it is **clamped** to `max_w` — the drain phase SETs the setpoint and the arbiter bounds it, saying so on the status page (`limited by supervised(max_w)`). Warned about, not refused: the cycle still completes, just slower |
+| `maintenance_charge_w` | 2000 | Charge ceiling, capped again by peak headroom. Must stay **at or below `max_w`** or the cheap-window shaping (`hi = -maintenance_charge_w`) contradicts the supervised limit (`lo = -max_w`), the arbiter resolves it to **0 W**, and maintenance silently never charges in a cheap window — **the add-on refuses to start** |
 | `maintenance_soc_floor` | 11 | Drain target — stay just above the inverter's own floor |
 | `maintenance_soc_target` | 99 | Charge target |
 | `maintenance_hold_min` | 120 | Hold at full so the BMS can balance |
@@ -221,6 +437,373 @@ under `peak_cap_w`, and if the forecast goes over the cap the charge-only clamp
 is dropped so the battery can shave the peak instead. Money outranks the
 maintenance schedule.
 
+#### Capacity-tariff exposure of the grid-following loop
+
+⚠️ **This section described the exposure BEFORE SAFETY-07. The loop is now
+capped — see "The capacity-peak guard" below — and what follows is kept because it
+is still the clearest statement of WHAT is being guarded and why the number is
+worth what it is.**
+
+⚠️ **`peak_cap_w` caps MAINTENANCE charging. It does not cap the loop.** The
+grid-following loop is bounded by `max_w` and by the device rating, and by
+nothing else. That is deliberate — the loop exists to *reduce* what crosses the
+meter, so under every healthy condition it lowers the peak rather than raising
+it — but it means one thing is true and worth writing down:
+
+**If the meter lies, the loop will happily buy `max_w` from the grid for as long
+as the lie lasts, and no cap in this add-on stops it.** A meter frozen at a large
+export reads as "the house is exporting hard", the loop charges the battery to
+correct it, and the correction is a grid import. At the schema maximum
+`max_w: 5000` — which is what this house runs, and is also the device rating —
+that is a 5 kW unattended import.
+
+The bill is not the energy. In the Belgian capaciteitstarief the month is billed
+on its highest quarter-hour average, so **fifteen minutes of this sets the whole
+month's peak.** A measured case: one 4998 W quarter moved a monthly peak from
+4832 W to 5013 W, and every day of that month was billed at the higher figure.
+
+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` | ✅ |
+| **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 |
+| SoC guard on the loop | ❌ — the BMS is the only energy backstop |
+
+On the legacy `meter_source: off` path there are no P1 telegrams, so there is no
+quarter-hour average to guard, and the status page says **NOT COVERED**. There
+the mitigation is still operational: set `max_w` no higher than the loop actually
+needs (the tuning was measured at 2000 W and a 1.78 kW load step is tracked fine
+there), fit the e-stop, and watch for the alarm.
+
+### The capacity-peak guard
+
+**What it does.** Every cycle the add-on projects the open quarter to its
+end-of-interval average — from P1 telegrams only, never from the command — and
+compares it to a ceiling. Over the ceiling it files one claim: a **lower bound on
+the setpoint**, at `P_PEAK`. That single shape is both behaviours §10.1 asks for:
+a hard clamp on charging while the bound sits above the standing charge, and
+pre-emptive discharge while it sits above zero. It can never cap discharge or
+export, because a floor cannot.
+
+**The number.** `excess = 900 × (projected − ceiling) ÷ seconds remaining`, and
+the floor is the **measured** battery power plus that. The 900/remaining factor
+is the design rather than an accident: it is 1.0 at the top of the quarter and
+grows, so the guard is gentlest when its projection rests on the least evidence
+and becomes aggressive only once the quarter is nearly measured.
+
+**The ceiling** is `peak_cap_w`, raised to the month's banked peak when that
+already stands higher — once a month's bill is set at 5013 W, holding later
+quarters to 3500 W buys nothing and costs real charging. **That relaxation is
+granted only by an OBSERVED reading:** a peak store that cannot be read leaves the
+ceiling at the cap, so a broken instrument makes the guard stricter, never looser.
+
+**When it cannot see, it forbids importing.** Three states are not evidence and
+are checked before the projection is graded: no open quarter (a fresh averager
+projects a confident 0 W, which is under every ceiling there is), a meter gap
+longer than `meter_max_age_s`, and SAFETY-18's frozen-meter conjunction. In all
+three the claim becomes a floor of **0 W**. That is the backstop for the frozen
+meter: the alarm arrives at `meter_freeze_s` (300 s) of a 900 s billing quarter
+and commands nothing, and this stops the import.
+
+**It trips, where the freeze detector only notifies,** and the captures are why.
+On the healthy reference day (2026-08-23) it engages on **zero** of 95 quarters.
+The action is level-triggered and unlatched — re-derived from a fresh projection
+every cycle, released the instant the projection drops back — so a false
+engagement costs one cycle of discharge rather than a parked battery. And it is a
+LIMIT, so every stop in the watchdog table still outranks it.
+
+**Replayed on 2026-08-20**, the day the vendor controller failed: the billed
+quarter measured **5029.8 W**, above the inverter's own 5000 W rating, and the
+guard brings it to **3485 W** — under the soft limit, without ever asking for more
+than the inverter can give. Across both committed days the quarters under the
+limit go from 189/190 to 190/190. Two days is not thirty and does not close AC 3;
+it is the comparison two days can support.
+
+**What it alarms on is saturation, not engagement.** An engagement is an ordinary
+control action and goes to the action log and the status page. A *saturated*
+guard — asking for everything the inverter has while the quarter is still
+projected over — raises one notification (`goodwe_peak_saturated`), because that
+is the one state where the money will be spent and shedding load is the only
+thing left that changes the bill.
+
+**No new option.** The ceiling 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
+rating — every one of them a key that already exists.
+
+### The winding-loop alarm (the output clamp)
+
+Every setpoint this add-on writes is clamped to `max_w` before it leaves the
+process, and **when that clamp actually engages, it alarms.** The clamp on its
+own is not the feature - this project already clipped, and the clipping is what
+hid the defect the guard exists for: with the inverter switched off entirely an
+unclamped integrator climbed ~130 W per 4 s past 10 kW and, pinned at the 5 kW
+rail, reported **14 768 W**. Clipped silently, that is a flat, legal-looking
+5000 W hold on every dashboard, and nothing anywhere says the loop asked for
+three times it.
+
+**What "the rating" is.** The bound is `max_w`, and only `max_w`. It is already
+validated against the setpoint device's own range at startup - the add-on
+*refuses to start* if `max_w` exceeds what the device accepts (and again once
+ESPHome is up and the real rating is known), so by the time the loop runs the two
+numbers agree. The device range is applied a second time inside the write as
+defence in depth; after a successful validation it cannot bite, and if it ever
+does, that engagement alarms too and names the bound.
+
+**Clamping is not saturation, and the two never share a channel.**
+
+| | what it means | what happens |
+|---|---|---|
+| **clamp** | the *computed* value exceeded the rating | a software bug signal - something upstream is winding. **Alarm.** |
+| **saturation** | the inverter is not following a perfectly *legal* command | a hardware condition - freeze the integrator. **No alarm.** |
+
+A loop can be legally saturated all day: a cold pack, a curtailed inverter, an
+export limit. Routing the clamp through a saturation-shaped alarm puts the bug
+signal inside the noise, which is the same silence as clipping quietly. They
+share no reason code, no notification id, no status row and no counter.
+
+**It is an alarm, not a trip.** The clamped value is written and the loop keeps
+running - this is not the sign-disagreement failsafe, which commands 0 W. You
+get a persistent notification (`goodwe_output_clamp`, replaced rather than
+stacked), an `ERROR` in the log with the reason code `OUTPUT_CLAMP`, a row in
+the event list, and a red status banner while it is engaged. Once it clears, a
+warning row keeps the engagement count so the evidence does not vanish with the
+condition. Consecutive engagements share one event row carrying the exact count,
+because the event list keeps only 40 rows and a row per cycle would flush every
+other guard's entries out of it.
+
+**There is nothing to configure**, deliberately. The bound is `max_w`, which you
+already set; giving the guard a limit of its own would be a second number that
+can disagree with the first, which is exactly the failure the startup validation
+exists to prevent. The alarm's cadence - first engagement, then re-asserted every
+30 s while it persists, cleared after 3 clean cycles - is fixed for the same
+reason `RAIL_FRAC` is: it describes the notification bus, not the plant.
+
+WARNING: **on a default install the engagement you will see is the integrator's,
+not the output's.** The control law bounds the integrator to `max_w` and *then*
+derives the command from it, so the command itself can never come out over the
+rating unless `integrator_max_w` has been deliberately raised above `max_w`.
+Both are watched. A guard that watched only the emitted value would be silent on
+every standard configuration.
+
+### The frozen-meter alarm
+
+A meter that has died is easy — it stops answering, the sample age climbs past
+`meter_max_age_s`, the reading becomes missing, and the add-on and the ESP32 both
+command 0 W. A meter that keeps answering `200 OK` with a document that never
+changes is the hard one: **every freshness mechanism in the stack reads it as
+healthy**, because it really is arriving on every poll. The loop then integrates
+a constant error and winds to the rail, in 75–360 s at `max_w: 5000`.
+
+The add-on alarms when **both** of these are true at once:
+
+- the meter's own document (power figure *and* both kWh registers) has not
+  changed for `meter_freeze_s` — 300 s by default; **and**
+- the command standing on the wire is at the rail, within 5 % of `max_w`.
+
+Neither half is usable alone. A bare "unchanged for N seconds" rule false-trips
+at the exact operating point this controller aims for — at a converged −10 W a
+1 Wh register legitimately takes about six minutes to move — and a bare "at the
+rail" rule fires on any genuinely large load. Together they are safe in both
+directions, because a real railed condition means kilowatts still crossing the
+meter, and a kilowatt advances a 1 Wh register every 3.6 s.
+
+**It is an alarm and nothing else.** It does not command 0 W, does not latch, and
+does not claim the actuator. A false trip here parks the battery; a false
+notification costs an alert. Turning it into a trip is a separate decision that
+needs data from a real install — and an answer to "what should the loop do
+instead", given that 0 W is itself an import of whatever the house is drawing.
+
+When it fires you get a Home Assistant persistent notification
+(`goodwe_meter_frozen`, replaced rather than stacked on a repeat), an `ERROR` in
+the add-on log, an entry in the UI's event list, and a red banner on the status
+page. **The loop keeps running.** If the meter really is stuck, stop control from
+the add-on UI.
+
+⚠️ **Only `meter_source: homewizard_local` is covered.** It is the only transport
+that reads the meter's own document; on `ha_dsmr`, `mqtt_p1`, `ha_signed` and
+`off` there is no signal to threshold and the status page says **NOT COVERED**
+rather than pretending the guard is armed.
+
+| option | default | meaning |
+|---|---|---|
+| `meter_freeze_s` | 300 | Seconds of an unchanged measurement, *while the command is at the rail*, before the alarm |
+
+Why 300 s: over 2399 s of this house at the converged operating point (mean grid
+−14.2 W, 1194 polls, 735 of them repeating the previous reading) the largest
+`unchanged_s` any sample sees is **8.0 s**, and the longest interval serving no
+distinct reading at all is **15.4 s**. There is also a structural reason not to
+lower it much: at 300 s the slowest a *healthy* register can tick and still look
+unchanged is 12 W, which is inside the 15 W deadband — so the command there is
+parked at 0 W and the two halves of the rule cannot both be true. At the schema
+floor of 60 s that figure is 60 W and only the margin is left.
+
+### Energy price providers
+
+> **No *fetched* price moves energy in 0.5.x.** This release ships the
+> *plumbing*: the five provider plugins, the canonical all-in format they emit,
+> and the config that selects one. Turning a provider on fetches, validates and
+> publishes prices and changes no charging decision; the arbitrage strategy that
+> would use it is a later ticket.
+>
+> The one exception is `static_profile` below. A static day/night tariff needs
+> no network, so its cheap window is computed on every cycle and does reach the
+> maintenance cycle's grid top-up.
+
+| option | meaning |
+|---|---|
+| `price_provider` | `off` (default) or one of the five 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_csv_path` | Where `manual_csv` reads its file |
+| `price_feed_url` | Override the plugin's default feed. Only a host the plugin itself declares is accepted |
+| `price_horizon_h` | How far ahead to ask for, hours |
+| `price_timeout_s` | Per-request timeout |
+| `static_profile` | A static day/night or fully-fixed tariff. Empty by default — see below |
+
+**Which plugin sources what.** This is the one thing to get right, because
+adding your markup to a price that already contains it makes every future
+arbitrage decision wrong by that amount, in a direction nothing reports.
+
+| plugin | product | the published figure contains | the add-on adds |
+|---|---|---|---|
+| `generic_dayahead` | day-ahead | energy only (wholesale EPEX BE) | markup **and** taxes |
+| `engie_dynamic` | day-ahead | energy + Engie's markup | taxes |
+| `totalenergies_dynamic` | day-ahead | energy + TotalEnergies' markup | taxes |
+| `eneco_eddy` | **real-time / imbalance** | everything, all-in | nothing |
+| `manual_csv` | day-ahead | everything, all-in | nothing |
+
+You cannot get this wrong by editing the markup: each plugin *declares* what its
+feed contains and the add-on adds only the rest. Set a markup under a plugin
+that already carries one and it is **ignored, with a line in the log saying so**
+— never applied twice.
+
+That holds **given a correct declaration**, and it is worth knowing where the
+line is. What the add-on enforces mechanically is that a plugin cannot obtain
+the markup or apply it: the numbers are not reachable from plugin code, and a
+plugin whose code mentions them fails to load at all. What it cannot check is
+whether a plugin described its supplier's feed truthfully — that is a claim
+about somebody else's tariff, and no code can verify it. If you write a plugin,
+the `sources` declaration is the part a reviewer has to read.
+
+`eneco_eddy` is a real-time/imbalance product rather than a day-ahead one. It is
+flagged as high-volatility, which widens arbitrage thresholds once the
+optimiser lands. That comes from the plugin's own declaration, not from its
+name.
+
+**`manual_csv` — the offline fallback.** It needs no internet, no supplier
+account and no HTTP stack at all, and it is the supported way to run this
+add-on price-aware on a site with no outbound connectivity. Write a file and
+point `price_csv_path` at it:
+
+```csv
+start,eur_per_kwh,provisional
+2026-01-15T00:00:00+01:00,0.1834,false
+2026-01-15T01:00:00+01:00,-0.0210,true
+2026-01-15T02:00:00+01:00,0.3115,false
+```
+
+- `start` **must carry its UTC offset** (`+01:00` in winter, `+02:00` in
+  summer). A bare `2026-01-15 00:00` is refused, because for one hour every
+  October a local wall clock names two different moments.
+- `eur_per_kwh` is **all-in** — energy *plus* markup *plus* taxes. This plugin
+  has no way to know what your numbers already include, so it assumes
+  everything and adds nothing.
+- Negative prices are valid and are kept. They are the best charging hours of
+  the year.
+- `provisional` is optional; omit the column and every hour is treated as
+  settled.
+
+**When there are no prices at all** — provider off, feed unreachable, CSV
+missing — the add-on does not guess. It reports *no price data*, which is a
+distinct state from "prices, all of them zero": the plan is marked provisional
+and arbitrage is disabled, per the degradation matrix. It never falls back to a
+price of zero, which would read as free electricity.
+
+**Injection is priced separately** (`export_price_eur_kwh`). In Belgium it is
+often near zero, which by itself strongly favours self-consumption over export.
+It is a single number rather than a curve because no supported supplier
+publishes a dynamic injection tariff; negative values are accepted.
+
+**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.
+
+### Static day/night and fully-fixed tariffs (`static_profile`)
+
+Most Belgian households are **not** on a dynamic contract, and an EMS that only
+works under hourly pricing is an EMS for a minority. `static_profile` is how a
+two-period day/night tariff or a single fixed price becomes a first-class
+configuration rather than "turn the price feature off and hope".
+
+It is one option, holding a JSON object, on one line:
+
+```json
+{"periods": [
+  {"name":"day",   "from":"07:00","to":"22:00","days":"mon-fri","eur_per_kwh":0.34},
+  {"name":"night", "from":"22:00","to":"07:00","days":"mon-fri","eur_per_kwh":0.26},
+  {"name":"night", "from":"00:00","to":"24:00","days":"sat,sun", "eur_per_kwh":0.26}]}
+```
+
+A **fully fixed** tariff is one period covering the whole week:
+
+```json
+{"periods": [
+  {"name":"fixed","from":"00:00","to":"24:00","days":"all","eur_per_kwh":0.31}]}
+```
+
+- `eur_per_kwh` is **all-in** — energy *plus* your supplier's markup *plus*
+  taxes — exactly like `manual_csv`. `price_markup_eur_kwh` and
+  `price_taxes_eur_kwh` are **not** added to it.
+- `days` takes `mon`…`sun`, ranges (`mon-fri`, `fri-mon`), comma lists
+  (`sat,sun`) and the words `weekday`, `weekend`, `all`.
+- Times are **local Belgian time** and windows are half-open: `07:00`–`22:00`
+  includes 07:00 and excludes 22:00. A window may cross midnight.
+- The clock changes twice a year and the add-on handles it. It generates prices
+  against absolute instants, so a spring-forward day is 23 hours and an
+  autumn-back day is 25.
+
+> ⚠️ **A window belongs to the day the clock reads, not the day it started.**
+> `22:00`–`07:00` on `mon-fri` covers Friday 23:00 but **not** Saturday 03:00 —
+> Saturday 03:00 is Saturday's. That is why the example above has a third row
+> for the weekend. Leave it out and the add-on **refuses to start**, naming the
+> uncovered hours.
+
+**Every day type must be covered exactly once.** The periods have to tile all
+seven days with no gap and no overlap, and the add-on checks that at startup. A
+gap is refused rather than filled in, because a made-up price is one the
+optimiser would trade on; an overlap is refused because otherwise one of the two
+prices silently wins on the order you typed them in.
+
+**What it changes today.** The add-on works out which window you are in and
+whether that window is *cheap* — strictly below the tariff's seven-day average.
+The Web UI shows both on a new **Tariff** row, and the maintenance cycle's
+cheap-window grid top-up uses it, which is exactly the "shift load into the
+cheap window" behaviour a day/night tariff asks for. Nothing else moves energy
+on a price yet.
+
+Under a **fully fixed** tariff every hour equals the average, so there is *no*
+cheap window by construction and the add-on runs self-consumption only — which
+is the correct behaviour for that product, not a limitation. Peak shaving, the
+capacity-tariff tracker, the reserve floor and the maintenance schedule are all
+unaffected: the capacity tariff is a network cost charged whatever your energy
+contract is.
+
+**Recommended even on a dynamic contract.** When a price feed is unreachable the
+add-on falls back to your static profile, marks the plan provisional and
+disables arbitrage. With `static_profile` empty there is nothing to fall back
+to, and the site simply has no tariff until the feed returns. It is not required
+— the add-on warns rather than refusing — but filling it in is what makes that
+fallback work.
+
 ### Site
 
 | option | meaning |

goodwe_controller/app/clamp.py

@@ -0,0 +1,284 @@
+"""SAFETY-03 - the output clamp, and the alarm that makes it audible.
+
+WHAT IT CATCHES, in one sentence: a control law that computes a setpoint the
+actuator cannot deliver, which every layer below it will happily clip to
+something legal-looking while the thing that produced it goes on winding.
+
+THE CLAMP IS NOT THE DELIVERABLE. specs.md 10.3 is explicit that this project
+already clipped, and that the clipping is what hid the defect:
+
+    with the inverter switched off entirely, an unclamped integrator climbed
+    ~130 W per 4 s to over 10 kW and, pinned at the 5 kW rail, reported
+    14 768 W
+
+A clamp alone turns that into a silent, perfectly flat 5000 W hold. Every
+dashboard reads "commanded 5000 W", which is a legal number, and nothing
+anywhere says the loop asked for three times it. 11.2's watchdog row says
+"Clamp AND ALARM - the loop is winding"; the second verb is this module.
+
+------------------------------------------------------------------------------
+WHAT "THE RATING" IS HERE, AND WHY IT IS ONE NUMBER AND NOT A MIN()
+
+The card names two bounds and warns against choosing between them:
+
+  - `DriverCapabilities.setpoint_limit_w` (3.2), the inverter's own magnitude
+    rating. In this add-on that arrives as the setpoint entity's `min`/`max`
+    from `hass.limits()` - `Controller.dev_min` / `dev_max`.
+  - `optimizer.loop.clamp_w` (14), the configured loop clamp. In this add-on
+    that is the `max_w` option, which `Tuning.max_w` and the arbiter's
+    `supervised` limit both already use.
+
+14 says these two must AGREE, validated at startup with a refusal on
+mismatch - and that gate already ships: `validate_startup_config()` refuses
+`max_w > dev_max` and `-max_w < dev_min` (validate.py, problem 1), and
+run_control() re-runs it once ESPHome is up and the real rating is known.
+
+So this guard clamps to `max_w`, THE VALIDATED VALUE, and does not `min()` it
+with the device rating at runtime. That is the card's instruction and it is also
+the only reading that keeps `max_w` meaningful: a silent runtime `min()` is
+precisely the "helper bounded to +-500 W under a loop clamped to 1500 W" failure
+the 14 warning box is about.
+
+WARNING - THE DEVICE BOUND IS STILL APPLIED, SECOND, AND IT IS NOT REDUNDANT.
+After a successful validation `+-max_w` lies inside `[dev_min, dev_max]`, so the
+second stage is arithmetically a no-op and can never engage. If it DOES engage,
+the validation did not run or no longer holds - `hass.limits()` returns
+(None, None) whenever ESPHome is not up yet, and the range checks are skipped
+rather than guessed at - and that is a louder fault than the first stage, not a
+quieter one. It therefore alarms too, through the same channel, with the bound
+named. This is NOT SAFETY-20; nothing here changes what `freeze.py` measures its
+rail against.
+
+------------------------------------------------------------------------------
+WHERE THE WIND ACTUALLY SHOWS UP - READ THIS BEFORE "SIMPLIFYING" THE CALLER
+
+`control.compute()` bounds the integrator to `integrator_max_w or max_w` and
+THEN derives the command from it, so on a default install (`integrator_max_w`
+unset, i.e. following `max_w`) the command can never exceed `max_w` and the
+actuator-side clamp below IS UNREACHABLE. control.py says so in as many words:
+
+    SAFETY-03 ... must watch for THIS, not for "clamped" below.
+
+An alarm wired only to this module's `ClampResult.engaged` would therefore be
+silent on the exact configuration the whole ticket is about. The winding is
+visible one layer up, at the integrator bound, and that is why `Decision` now
+carries `i_clamped` / `clamped` BOOLEANS and the caller ORs them in here.
+
+AND WHY BOOLEANS RATHER THAN `Decision.reason`. `reason` is a single string that
+later stages overwrite: a cycle that clamps the integrator and is then slew
+limited reports "slew-limited", and one that clamps while saturated reports
+"saturated-freeze". Both are exactly the winding-into-a-rail case, and on the
+string the clamp signal is destroyed before anything can alarm on it. The two
+flags are set where the clamp happens and are never overwritten. A check in
+test_clamp.py drives that precise combination.
+
+------------------------------------------------------------------------------
+DISTINCT FROM SATURATION - THIS IS ACCEPTANCE CRITERION 2, NOT A NICETY
+
+    clamp      the COMPUTED value exceeded the rating. A software bug signal:
+               something upstream is winding. Alarm, every engagement.
+    saturation |command - inverter AC power| > `saturation_w` for
+               `saturation_cycles`. The HARDWARE cannot follow a perfectly legal
+               command. Action is "freeze the integrator" (11.2), not an alarm.
+
+A loop can be legally saturated all day - a cold pack, a curtailed inverter, an
+export limit - so a saturation-shaped alarm is one an operator learns to ignore.
+Routing the clamp through it puts the bug signal inside the noise, which is the
+same silence 10.3 is complaining about. They share no reason code, no
+notification id, no status row and no counter.
+
+------------------------------------------------------------------------------
+ANTI-FLOOD, WITHOUT GOING SILENT
+
+A genuinely winding loop clamps on EVERY cycle for as long as it winds. One HA
+notification per cycle is how an operator learns to dismiss notifications
+unread, and this add-on already made that argument once (see the fixed
+`notification_id` note in main.check_meter_frozen).
+
+So the two surfaces are split, deliberately:
+
+  - EVERY engagement is recorded, never deduplicated, and that record is what
+    says how hard the loop is pushing. 15's action log is this add-on's
+    `Controller.events`, and it gets a row from `write_setpoint()` on every
+    engaged WRITE; `engagements` here counts every engaged CYCLE. The two layers
+    are counted separately on purpose - the heartbeat re-writes an
+    already-clamped value between cycles, so a per-write count would inflate and
+    a per-cycle log would miss an out-of-cycle write.
+  - THE NOTIFICATION fires on the rising edge and then RE-ASSERTS every
+    `REASSERT_S`, so a loop pinned on the rail for an hour does not go quiet.
+  - It DE-ASSERTS only after `CLEAR_CYCLES` consecutive clean cycles, which is
+    the 10.2 hysteresis: a command sitting exactly on the rail dithers in and
+    out of engagement by one quantisation step, and without this the alarm
+    chatters.
+
+`REASSERT_S` and `CLEAR_CYCLES` are module constants, not options, for the same
+reason `freeze.RAIL_FRAC` is: they describe the event bus, not the plant, and
+every knob 10.3 asked to keep exposed is a LOOP TUNING knob and is untouched by
+this module. No new config key is added anywhere - CFG-03 already has three
+places a default has to be kept in step and this ticket does not earn a fourth.
+
+------------------------------------------------------------------------------
+NOT A TRIP
+
+Clamping does not stop the loop and does not command 0 W. The clamped value is
+written and control continues, which is what 11.2 asks for ("Clamp and alarm")
+and what distinguishes this from SAFETY-01/02, whose action is 0 W. It follows
+that this must NOT drive the failsafe status - `publish()` keeps reporting
+"running", because the controller is.
+"""
+
+import math
+from dataclasses import dataclass
+from datetime import datetime
+
+# The reason code, distinct from any saturation-freeze code by construction:
+# nothing else in this add-on uses it. See "DISTINCT FROM SATURATION".
+REASON_CODE = "OUTPUT_CLAMP"
+
+# Re-assert the notification this often while the clamp stays engaged. 30 s is
+# the planning cadence (2.3), i.e. slow enough not to flood and fast enough
+# that a pinned loop is never quiet for a whole billing quarter.
+REASSERT_S = 30.0
+
+# Consecutive clean cycles before the alarm de-asserts (10.2 hysteresis).
+CLEAR_CYCLES = 3
+
+
+@dataclass(frozen=True)
+class ClampResult:
+    """What the guard did, with the RAW value preserved.
+
+    AC 2 turns on "the raw computed value differed from the clamped one", so the
+    raw value has to survive the call - a guard that returns only the applied
+    number cannot be asked the question the acceptance criterion asks.
+    """
+
+    requested_w: float
+    applied_w: float
+    limit_w: float
+    engaged: bool
+    bound: str = ""          # "" | "max_w" | "device" - which stage bit
+
+    def describe(self) -> str:
+        return (f"{REASON_CODE}: the computed setpoint {self.requested_w:+.0f} W "
+                f"was clamped to {self.applied_w:+.0f} W by the {self.bound} "
+                f"bound (rating {self.limit_w:.0f} W) - something upstream is "
+                f"winding")
+
+
+def is_commandable(value) -> bool:
+    """False for None, NaN and the infinities.
+
+    A non-finite setpoint is LOSS OF INPUT, not an out-of-range value, and
+    11.1 rule 1 says loss of input means command zero and keep commanding. It
+    must not reach the clamp arithmetic: `min(limit, nan)` returns nan on
+    CPython, so a nan would sail straight through a naive clamp and then report
+    `engaged` True on the `applied != requested` test - because nan != nan - i.e.
+    a transport bug filed in the winding-loop counter, with a nan on the wire.
+    """
+    if value is None:
+        return False
+    try:
+        return math.isfinite(float(value))
+    except (TypeError, ValueError):
+        return False
+
+
+def clamp_to_rating(requested_w, limit_w, dev_min=None, dev_max=None) -> ClampResult:
+    """Bound a computed setpoint to the validated rating. The ONLY clamp.
+
+    `limit_w`  the validated magnitude bound - `max_w`. Symmetric, because
+               3.2 calls `setpoint_limit_w` a MAGNITUDE clamp: it binds import
+               (+) and export (-) identically.
+    `dev_min` / `dev_max`  the device's own asymmetric range, applied second and
+               expected never to bite. See the module note.
+
+    Public, and the predicate lives here rather than in the test, for the reason
+    `freeze.looks_frozen()` gives: a safety expression transcribed into its own
+    check is one copy plus a future disagreement about what the check means.
+
+    EXACTLY +-`limit_w` IS NOT AN ENGAGEMENT. The bound is inclusive; a loop
+    resting on the rail is doing what it was told, and alarming there would fire
+    on every healthy full-power hour.
+    """
+    requested = float(requested_w)
+    limit = abs(float(limit_w))
+
+    # ⚠️ BOTH STAGES ALWAYS RUN. THIS USED TO `return` FROM THE FIRST ONE, AND
+    # THAT WAS A REGRESSION AGAINST THE CODE IT REPLACED. `write_setpoint()`
+    # previously clamped to the device range unconditionally, under the comment
+    # "never send a value the device will reject outright"; short-circuiting here
+    # meant the device bound was applied only when the rating bound had NOT
+    # fired, i.e. THE BIGGER THE OVERSHOOT THE LESS THE GUARD DID. Measured on
+    # the shipped function at max_w 5000 against a device of +-4000:
+    #
+    #     +9999 -> +5000  bound='max_w'   <- outside the device range
+    #     +4500 -> +4000  bound='device'
+    #
+    # It also undercut this module's own argument for clamping to `max_w` rather
+    # than a runtime `min()`, which rests entirely on this stage catching the
+    # case where the startup validation did not run.
+    applied = max(-limit, min(limit, requested))
+    bound = "max_w" if applied != requested else ""
+
+    # Second stage. Arithmetically dead after a successful startup validation -
+    # and therefore worth alarming on precisely BECAUSE it fired.
+    if dev_min is not None and dev_max is not None:
+        bounded = max(float(dev_min), min(float(dev_max), applied))
+        if bounded != applied:
+            bound = "device" if not bound else "max_w+device"
+            applied = bounded
+
+    return ClampResult(requested, applied, limit, applied != requested, bound)
+
+
+class ClampWatchdog:
+    """One instance per controller. Counts every engagement, alarms sparsely.
+
+    `note()` is called once per write with whether the clamp bit; the caller ORs
+    in the loop's own `i_clamped` / `clamped` flags, which is where the winding
+    is actually visible on a default install (see the module note).
+    """
+
+    def __init__(self):
+        self.active = False
+        self.engagements = 0      # every engagement, never deduplicated
+        self.episodes = 0         # rising edges
+        self.since: datetime | None = None
+        self.last_alarm: datetime | None = None
+        self.reason = ""
+        self.clean_cycles = 0
+
+    def note(self, engaged: bool, reason: str, now: datetime) -> bool:
+        """Advance one cycle. True when the caller should raise the alarm.
+
+        `now` is the caller's clock, the same discipline as
+        `SignWatchdog.evaluate()` and `FreezeWatchdog.evaluate()`.
+        """
+        if engaged:
+            self.engagements += 1
+            self.clean_cycles = 0
+            self.reason = reason
+            if not self.active:
+                self.active = True
+                self.since = now
+                self.episodes += 1
+                self.last_alarm = now
+                return True
+            # Still engaged: re-assert on the slow cadence, not every cycle.
+            if (self.last_alarm is None
+                    or (now - self.last_alarm).total_seconds() >= REASSERT_S):
+                self.last_alarm = now
+                return True
+            return False
+
+        if not self.active:
+            return False
+        self.clean_cycles += 1
+        if self.clean_cycles >= CLEAR_CYCLES:
+            self.active = False
+            self.since = None
+            self.last_alarm = None
+            self.reason = ""
+            self.clean_cycles = 0
+        return False

goodwe_controller/app/control.py

@@ -64,6 +64,23 @@ class Decision:
     # and quantisation. Carry it back in as `i_w` next cycle; that is what keeps
     # it a separate quantity from the command.
     i_w: float = 0.0
+    # SAFETY-03. Did a clamp actually engage this cycle - i.e. did the RAW
+    # computed value differ from the bounded one?
+    #
+    # ⚠️ THESE EXIST BECAUSE `reason` CANNOT ANSWER THAT QUESTION. `reason` is
+    # one string and every later stage overwrites it: a cycle that clamps the
+    # integrator and is then slew limited reports "slew-limited", and one that
+    # clamps while saturated reports "saturated-freeze". Both ARE the winding
+    # case, and on the string the clamp signal is gone before anything can alarm
+    # on it. These two are written where the clamp happens and are never
+    # overwritten, so they mean exactly what they say and nothing else.
+    #
+    # `i_clamped` is the one that fires on a default install: the integrator
+    # bound is reached first, so `clamped` is unreachable unless
+    # `integrator_max_w` is deliberately set above `max_w`. Alarm on BOTH - see
+    # the comment at the bound below, and clamp.py.
+    i_clamped: bool = False
+    clamped: bool = False
 
 
 def compute(
@@ -95,19 +112,23 @@ def compute(
     # lets slew be larger than saturation_w.
     #
     # The spec states this window twice and differently: "> 10 s" (§11.2) and
-    # "3 samples" (§10.3). This counts CYCLES, and a cycle is not a unit of
-    # time: run_control() calls cycle() only when the meter value CHANGES
-    # (`if self.grid != last_grid`), so three cycles is three distinct meter
-    # readings and nothing more. At the reference P1's ~5 s update rate that is
-    # usually ~15 s, but there is no upper bound on it - a meter that repeats a
-    # value stalls the counter.
+    # "3 samples" (§10.3). This counts CYCLES, and a cycle is still not a unit
+    # of time - but it is now a BOUNDED one. run_control() runs a cycle on a
+    # changed meter value OR on `cycle_floor_s` elapsing, whichever comes first
+    # (SAFETY-12), so three cycles is at most 3 x cycle_floor_s = 45 s at the
+    # defaults, and usually ~15 s at the reference P1's ~5 s update rate.
     #
-    # That is a detection-latency limit, not a windup hazard: the same
-    # condition that stalls the counter stalls the whole loop, so nothing
-    # accumulates in the meantime either. If a wall-clock window is ever
-    # required, it belongs in Controller (which has a clock) and not here.
-    # ponytail: this function is worth keeping clockless; the ceiling is that
-    # saturation_cycles cannot express a guaranteed number of seconds.
+    # ⚠️ THIS COMMENT USED TO CLAIM there was no upper bound and that it did not
+    # matter, "because the same condition that stalls the counter stalls the
+    # whole loop, so nothing accumulates in the meantime". The first clause was
+    # true and the second was the bug: a stalled loop does not stop commanding,
+    # it goes on emitting its last command through the heartbeat. Windup was
+    # never the hazard; staleness was.
+    #
+    # The wall-clock window lives in Controller, which has a clock, exactly as
+    # this comment always said it should. ponytail: this function stays
+    # clockless; the remaining ceiling is that saturation_cycles expresses a
+    # bound in seconds rather than an exact number of them.
     saturated_now = abs(prev_w - actual_w) > tuning.saturation_w
     sat_count = min(sat_count + 1, 10) if saturated_now else 0
     frozen = sat_count >= tuning.saturation_cycles
@@ -184,7 +205,8 @@ def compute(
     # bound is not. It is what makes the worst-case unwind time finite and
     # knowable instead of a function of how long the error happened to stand.
     bounded = max(-limit, min(limit, i_w))
-    if bounded != i_w:
+    i_clamped = bounded != i_w
+    if i_clamped:
         # ⚠️ SAFETY-03 (alarm whenever the loop winds into a rail) must watch
         # for THIS, not for "clamped" below. At the default limit == max_w the
         # integrator bound is reached first and the command derived from it can
@@ -205,7 +227,8 @@ def compute(
     # --- ORDER MATTERS: clamp -> slew -> freeze ----------------------------
     # An early draft applied a floor after the clamp and let demand escape it.
     target = max(-tuning.max_w, min(tuning.max_w, want))
-    if target != want:
+    clamped = target != want
+    if clamped:
         reason = "clamped"
 
     slewed = max(prev_w - tuning.slew_w, min(prev_w + tuning.slew_w, target))
@@ -231,7 +254,8 @@ def compute(
     step = max(1, int(tuning.step_w))
     target = round(target / step) * step
 
-    return Decision(float(target), sat_count, frozen, reason, float(i_w))
+    return Decision(float(target), sat_count, frozen, reason, float(i_w),
+                    i_clamped, clamped)
 
 
 def maintenance_charge_floor(

goodwe_controller/app/freeze.py

@@ -0,0 +1,275 @@
+"""SAFETY-18 - the frozen-but-fresh meter detector.
+
+WHAT IT CATCHES, in one sentence: a meter that keeps answering 200 OK with a
+document that never changes, which every freshness mechanism in this stack reads
+as perfectly healthy while the loop winds to the rail and stays there.
+
+THE FAILURE NEEDS NO FAULT ANYWHERE ELSE. A frozen-but-talking meter is
+*arriving* on every poll, so:
+
+  - `meter_max_age_s` is structurally blind. Every response resets the arrival
+    stamp (p1.py, `HomeWizardLocalSource`), so the age never climbs. Age catches
+    a meter that stops TALKING; this one stops CHANGING.
+  - firmware layer 1 is fed. Its watchdog keys on setpoint staleness, which the
+    heartbeat satisfies, and on `sensor.goodwe_p1_sample_age`, which a talking
+    meter satisfies.
+  - the arbiter contributes only the device rating and +-`max_w` - it bounds the
+    magnitude, which is the number this fault drives us to, not away from.
+  - there is no SoC guard on the grid-following loop at all. `soc_floor` belongs
+    to the maintenance cycle; the BMS is the sole energy backstop.
+
+The loop reads a constant error and integrates it. Time from freeze to the rail,
+replaying the real `control.compute()` at 15 s cycles:
+
+    meter frozen at   to rail, max_w 2000   to rail, max_w 5000
+    350 W                    150 s                  360 s
+    1000 W                    60 s                  135 s
+    >= 3000 W                 30 s                   75 s
+
+⚠️ THE LIVE INSTALL RUNS `max_w: 5000`, which is both the schema maximum and the
+device rating, so the right-hand column is the one that describes this house.
+
+------------------------------------------------------------------------------
+THIS HAS A EURO FIGURE, AND IT IS THE REASON THE TICKET IS P1
+
+`maintenance_charge_floor()` caps MAINTENANCE charging against `peak_cap_w`. The
+grid-following loop is not capped by anything but `max_w`. A meter frozen
+reading a large export drives a 5 kW unattended grid IMPORT, and >= 15 minutes
+of that sets the month's billed capaciteitstarief peak: specs.md:583 records a
+measured case where a single 4998 W quarter moved a monthly peak from 4832 W to
+5013 W and billed the whole month at it.
+
+⚠️ THIS CUT DOES NOT CAP THAT. It notifies. See DOCS.md, "Capacity-tariff
+exposure of the grid-following loop", and SAFETY-07.
+
+------------------------------------------------------------------------------
+WHY IT IS A CONJUNCTION AND NOT AN `unchanged_s` THRESHOLD
+
+`unchanged_s` (p1.py) already measures exactly the right thing: seconds since
+the meter served a DIFFERENT measurement, fingerprinted over the power figure
+and both energy registers. It is computed, it is on the status page, and TEL-05
+deliberately refused to threshold it - correctly:
+
+    this controller regulates grid power toward ~0 W, and at a converged -10 W
+    the export register takes about six minutes to advance by its 1 Wh
+    resolution while the power figure legitimately repeats.
+
+So a bare `unchanged_s > N` false-trips at the exact operating point we aim for,
+and `p1.py` says as much in a note that ends "whoever wires a freeze detector
+must handle the low-power case first". This is that handling, and it is not a
+smaller number:
+
+    unchanged_s >= hold_s   AND   |commanded_w| is at the rail
+
+The second term is what TEL-05's case cannot satisfy. At the converged point the
+command is nowhere near +-`max_w`; on the 40 minutes of live converged behaviour
+in `sim/scenarios/p1-age-2026-08-26.jsonl.gz` the meter never once leaves
++-500 W, so the loop never even approaches a 5000 W rail. And the reverse case -
+a command genuinely pinned at the rail by a real 8 kW load - cannot satisfy the
+FIRST term, because a real railed condition means kilowatts still crossing the
+meter, and a kilowatt advances a 1 Wh register every 3.6 s.
+
+The two terms fail for independent reasons. That is the whole design.
+
+⚠️ AND THE SECOND HALF OF THAT WAS MEASURED ON THE RIG, WITH A RESULT WORTH
+READING CAREFULLY. Driving the real transport against the rig's own hwsim under
++8000 W of house load - a genuinely railed command, meter perfectly healthy - the
+POWER FIGURE DID NOT MOVE AT ALL: `active_power_w` sat at exactly 10130.0 W for
+26 consecutive polls. What kept `unchanged_s` pinned at 0.0 s was the kWh
+registers advancing, and nothing else.
+
+So the register terms in `measurement_fingerprint()` are not belt-and-braces
+here, they are the entire negative case. A freeze detector fingerprinted on the
+power figure alone would have raised a false alarm on that rig run - a healthy
+meter, a real load, a correctly railed command - which is the exact failure mode
+that gets a safety guard switched off. Anyone tempted to simplify the fingerprint
+should read that run first.
+
+------------------------------------------------------------------------------
+WHERE `hold_s` COMES FROM
+
+Measured on `sim/scenarios/p1-age-2026-08-26.jsonl.gz` - 2399 s (40 min) of the
+live house at the converged operating point, mean grid -14.2 W, 1194 polls:
+
+    polls that repeated the previous reading      735 of 1193  (61.6 %)
+    distinct-reading transitions                  458
+    median gap between distinct readings          6.0 s
+    p95 gap                                       6.0 s
+    LARGEST `unchanged_s` any sample observes     8.0 s
+    longest interval serving no distinct reading 15.4 s
+    samples outside +-500 W                       0
+
+The default 300 s is 37x the largest `unchanged_s` this house has been recorded
+producing while converged, and 19.5x the longest interval in which it served no
+distinct reading at all. The two figures differ because the capture has an 11.4 s
+hole in its OWN polling; the second is quoted because it is the pessimistic one.
+300 s is not fitted to either margin - it is picked as "clearly past any
+plausible register-tick interval, and clearly inside the 900 s quarter that bills
+the capacity tariff". test_freeze.py re-measures both every run, so this
+paragraph cannot quietly stop being true.
+
+⚠️ BE PRECISE ABOUT WHAT THAT CAPTURE PROVES. It is POWER-ONLY - the shipped
+fingerprint also covers both kWh registers, so a real `unchanged_s` on that data
+can only be shorter, never longer, which makes it a conservative measurement of
+the converged case. But it does NOT on its own refute a bare `unchanged_s`
+threshold, and saying it did would be exactly the overstatement this project
+keeps having to walk back: at 8 s worst, a bare 300 s threshold is silent on it
+too. The case that refutes the bare threshold is the one below, which no capture
+of THIS meter contains because this meter's power figure jitters.
+
+The floor on the other side: at the rail, the smallest residual grid flow that
+still ticks a 1 Wh register inside 300 s is 12 W. Any condition that genuinely
+pins this loop at +-5000 W has three orders of magnitude more than that crossing
+the meter.
+
+⚠️ AND THOSE TWO NUMBERS DO NOT MERELY HAVE MARGIN - THEY CANNOT BOTH BE TRUE.
+The worry the conjunction has to answer is "a HEALTHY meter whose register is
+slower than `hold_s`". At 300 s that is |grid| < 12 W. The shipped `deadband_w`
+is 15 W, so anywhere the register is that slow the control law is already inside
+its deadband and the command is parked - the rail term is not merely unlikely to
+be true there, it is 0 W. The two terms are mutually exclusive by construction
+at the defaults, not just far apart, and the check re-derives that every run.
+
+That relationship is the one to protect. `hold_s` may be lowered only while
+3600/hold_s stays under `deadband_w`; at the schema floor of 60 s that is 60 W
+against a 15 W deadband, and the mutual exclusion is gone. A 60 s `meter_freeze_s`
+is a supported configuration that gives up this argument and keeps only the
+margin - do not set one without a capture that says the margin is enough.
+
+⚠️ WHAT `hold_s` DOES NOT BUY IS DETECTION SPEED. The alert lands at
+max(hold_s, time-to-rail) after the freeze, so at the shipped default and
+`max_w: 5000` that is 300-360 s. The rail is REACHED first, from 75 s. A
+notification is not a brake; see the DOCS.md note.
+
+------------------------------------------------------------------------------
+THE RAIL TERM, PRECISELY
+
+    abs(commanded_w) >= RAIL_FRAC * max_w
+
+`commanded_w` is the EMITTED setpoint - what the arbiter resolved and
+`write_setpoint()` put on the wire - not the loop's raw wish, for the same
+reason SAFETY-02 uses the emitted value: the wire carries the emitted number.
+
+RAIL_FRAC is 0.95 and is a constant rather than an option. The command is
+quantised to `step_w` (max 100) and clamped to `max_w` (min 100), so at the rail
+the emitted value IS `max_w` on every schema-legal combination; the 5 % is slack
+for a device rating that clips `max_w` slightly in `write_setpoint()`, not a
+tuning knob. Making it configurable would offer a way to widen the one term that
+carries the whole no-false-positive argument.
+
+⚠️ NOT GATED ON `following`, and that is deliberate. A maintenance charge
+commands against the meter on purpose and can sit at the rail for hours - but it
+does so while pushing kilowatts through the meter, so the FIRST term is what
+excludes it, and it excludes it on physics rather than on bookkeeping. Gating on
+`following` as well would additionally blind the detector to a maintenance phase
+running against a meter that really has frozen, which is the same fault with a
+worse actuator behind it.
+
+------------------------------------------------------------------------------
+NOTIFY, DO NOT TRIP
+
+First cut is an alarm and nothing else: an HA persistent notification, an ERROR
+in the log, an event on the status page, and a failed check row. It does NOT
+claim the actuator, does NOT file a P_SAFETY claim and does NOT latch.
+
+That is a deliberate ordering of costs, not timidity. A false trip here parks
+the battery - on a house that is running this loop precisely to avoid buying
+power at the wrong moment - and the operator's response to a parked battery is
+to switch the guard off. A false notification costs one alert. The trip is a
+separate decision that has to be earned with observed data from a real install,
+and it needs an answer to a question this cut does not have one for: what should
+the loop do instead, given that 0 W is itself a grid import of whatever the
+house is drawing.
+
+⚠️ TRANSPORT-CONDITIONAL. `unchanged_s` exists ONLY on `homewizard_local`,
+because it is the only transport that sees the meter's own document. Under
+`ha_dsmr`, `mqtt_p1`, `ha_signed` and `meter_source: off` this detector is
+silent and the exposure above is uncovered. The caller passes None and gets
+False; there is no half-measure available on those paths, and pretending
+otherwise would be worse than the gap.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+# See "THE RAIL TERM, PRECISELY" above. A constant, on purpose.
+RAIL_FRAC = 0.95
+
+
+@dataclass(frozen=True)
+class FreezeWatchdogConfig:
+    """Default, not a constant - config.yaml carries `meter_freeze_s`."""
+
+    hold_s: float = 300.0
+
+
+def rail_w(max_w) -> float:
+    """The magnitude at or above which a command counts as railed."""
+    return abs(float(max_w)) * RAIL_FRAC
+
+
+def looks_frozen(unchanged_s, commanded_w, max_w,
+                 cfg: FreezeWatchdogConfig) -> bool:
+    """The predicate, and the ONLY place the conjunction is written down.
+
+    Public for the same reason `watchdog.disagrees()` is: the checks that grade
+    it must assert on THE SHIPPED EXPRESSION. A safety predicate transcribed
+    into its own test is one copy plus a future disagreement about what the
+    check means, and the copy that drifts is always the one doing the grading.
+
+    `unchanged_s`  seconds since the meter served a different measurement, or
+                   None on a transport that cannot know (see the module note).
+    `commanded_w`  the EMITTED setpoint standing on the wire.
+    `max_w`        the configured output bound the rail is measured against.
+    """
+    if unchanged_s is None or commanded_w is None or not max_w:
+        return False
+    return (float(unchanged_s) >= cfg.hold_s
+            and abs(float(commanded_w)) >= rail_w(max_w))
+
+
+class FreezeWatchdog:
+    """One instance per controller, evaluated once per control cycle.
+
+    Level-triggered state with an EDGE for the alarm: `evaluate()` returns True
+    on the cycle the conjunction first becomes true and False on every cycle
+    after, so the caller raises one notification per episode rather than one
+    every second. `active` is the level, for the status page.
+
+    No latch, deliberately - see "NOTIFY, DO NOT TRIP". A latch exists so a trip
+    cannot erase its own evidence by working; nothing here acts, so there is
+    nothing to erase. When the meter starts moving again the alert clears
+    itself, which is the honest report of the state.
+    """
+
+    def __init__(self, cfg: FreezeWatchdogConfig | None = None):
+        self.cfg = cfg or FreezeWatchdogConfig()
+        self.active = False
+        self.since: datetime | None = None
+        self.reason = ""
+        self.episodes = 0
+
+    def evaluate(self, unchanged_s, commanded_w, max_w, now: datetime) -> bool:
+        """Advance one cycle. Returns True ONLY on the rising edge.
+
+        `now` is the caller's clock so this stays testable and replayable - the
+        same discipline as `SignWatchdog.evaluate()`.
+        """
+        if not looks_frozen(unchanged_s, commanded_w, max_w, self.cfg):
+            self.active = False
+            self.since = None
+            self.reason = ""
+            return False
+
+        self.reason = (
+            f"METER_FROZEN: the meter has answered {float(unchanged_s):.0f} s "
+            f"without its measurement changing while the command stands at "
+            f"{float(commanded_w):+.0f} W, at the {float(max_w):.0f} W rail "
+            f"(limits: unchanged over {self.cfg.hold_s:.0f} s, command over "
+            f"{rail_w(max_w):.0f} W)")
+        if self.active:
+            return False
+        self.active = True
+        self.since = now
+        self.episodes += 1
+        return True

goodwe_controller/app/maintenance.py

@@ -28,9 +28,10 @@ _LOG = logging.getLogger("goodwe.maint")
 
 IDLE, DRAIN, CHARGE, HOLD = "idle", "drain", "charge", "hold"
 
-# A drain of a 13.5 kWh usable pack at 2500 W is ~5 h even with no house load
-# helping. 12 h means the battery is not following commands - a fault, not a
-# slow day. The charge phase deliberately waits for sun and for cheap hours, so
+# A drain of a 13.8 kWh usable pack (300 Ah x 51.2 V, DoD 90) at the shipped
+# 2000 W is ~6.9 h even with no house load helping - and less in practice, since
+# house load drains alongside the export and soc_floor stops short of empty.
+# 12 h means the battery is not following commands - a fault, not a slow day. The charge phase deliberately waits for sun and for cheap hours, so
 # it is expected to span a night; 36 h still bounds it.
 DRAIN_TIMEOUT_MIN = 720
 CHARGE_TIMEOUT_MIN = 2160

goodwe_controller/app/mqtt.py

@@ -45,13 +45,32 @@ SENSORS = [
     ("soc", "goodwe_battery_soc", "Battery SoC", "%", "battery", "measurement", None),
     ("phase", "goodwe_maintenance_phase", "Maintenance phase", None, None, None, "mdi:battery-sync"),
     ("status", "goodwe_controller_status", "Controller status", None, None, None, "mdi:heart-pulse"),
-    # ⚠️ This one deliberately breaks the goodwe_ prefix above: the entity id
-    # must be exactly `sensor.p1_sample_age_s`, because SAFETY-01's firmware
-    # watchdog subscribes to that literal id and the ENV-01 simulation rig
-    # asserts on it. Renaming it silently disarms a safety layer. It is seconds
-    # since the newest accepted P1 telegram, republished every second so that a
-    # meter frozen at a constant value still shows a climbing age - which is the
-    # false-trip that this entity exists to remove.
+    # ⚠️ THE LIVE ENTITY IS `sensor.goodwe_p1_sample_age`, NOT what this
+    # object_id spells. An earlier version of this comment said the id "must be
+    # exactly sensor.p1_sample_age_s" - that name has never existed on any HA,
+    # and believing it is how a safety layer gets disarmed by someone tidying up.
+    #
+    # On HA 2026.8 `object_id` in a discovery payload does NOT determine the
+    # entity_id. HA composes it from the device name plus the entity name:
+    # "GoodWe RS485 Controller" + "P1 sample age" -> sensor.goodwe_p1_sample_age.
+    # Verified against the live system 2026-08-26; the firmware subscribes to
+    # that composed name (goodwe-master-stage4-failsafe.yaml, homeassistant
+    # sensor p1_age_s), and its own comment records that sensor.p1_sample_age_s
+    # never existed.
+    #
+    # So: do NOT "fix" the firmware to match the object_id below, and do not
+    # rename the device or this entity's friendly name - either changes the
+    # composed id and silently disarms the ingest guard, because has_state()
+    # simply stays false forever and nothing reports it. The firmware calls this
+    # out as the failure that "FAILS SILENTLY AND LOOKS CORRECT".
+    #
+    # The value: seconds since the newest accepted P1 telegram, republished
+    # every second so a meter frozen at a constant value still shows a climbing
+    # age - the false-trip this entity exists to remove.
+    #
+    # ⚠️ Separately, and not fixed here: the firmware's ingest guard tests this
+    # 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),
 ]
 

goodwe_controller/app/p1.py

@@ -4,13 +4,22 @@ Everything downstream trusts this module: the safety checks, the capacity-tariff
 peak, the optimizer, the control loop's sign. So three things happen here and
 nowhere else.
 
-  1. The IMPORT/EXPORT DERIVATION. A Belgian P1 meter exposes two UNSIGNED
-     registers - consumption and injection - never one signed figure. Net power
-     is `import_w - export_w`, positive = import, and that subtraction is done
+  1. The IMPORT/EXPORT DERIVATION. A Belgian P1 read over DSMR exposes two
+     UNSIGNED registers - consumption and injection. Net power is
+     `import_w - export_w`, positive = import, and that subtraction is done
      exactly once, here (spec §5.2: "the derivation is the EMS's job, not a
      template the user has to write"). A second copy of it somewhere else is a
      second chance to invert the control loop.
 
+     Some P1 readers - the HomeWizard P1 among them - publish the OTHER shape:
+     one SIGNED figure, positive = import, and no unsigned registers at all.
+     `split_signed()` fans that back out into the same two magnitudes, so there
+     is still exactly one internal representation and one sign convention. ⚠️ It
+     lives here, next to the subtraction, for the same reason the subtraction
+     does: the moment a user is asked to write two template sensors that split a
+     signed value, the sign convention is back in unreviewed YAML underneath a
+     safety input, which is precisely what §5.2 moved into the EMS.
+
   2. THE INGEST TIMESTAMP. Every accepted sample is stamped on arrival. A value
      with no age is a value that cannot be trusted (§5.2), and staleness is the
      failsafe trigger (§11.2).
@@ -47,6 +56,8 @@ _LOG = logging.getLogger("goodwe.p1")
 
 SOURCE_HA = "ha_dsmr"
 SOURCE_MQTT = "mqtt_p1"
+SOURCE_HA_SIGNED = "ha_signed"
+SOURCE_HOMEWIZARD = "homewizard_local"
 
 QUARTER_S = 900
 
@@ -78,7 +89,7 @@ class P1Sample:
     ingest_ts: datetime            # tz-aware UTC, set at ingest
     ingest_mono: float             # time.monotonic() at ingest - see age_s()
     telegram_ts: datetime | None   # from the telegram, where the source has one
-    source: str                    # SOURCE_HA | SOURCE_MQTT
+    source: str                    # one of the SOURCE_* constants above
     import_w: float                # unsigned magnitude, as the meter reports it
     export_w: float                # unsigned magnitude
     net_w: float                   # import_w - export_w  (+ import, - export)
@@ -129,6 +140,29 @@ def _watts(value, what: str) -> float:
     return out
 
 
+def split_signed(net_w) -> tuple[float, float]:
+    """One signed figure -> the (import, export) magnitudes the module speaks.
+
+    The inverse of make_sample's subtraction, and the easy direction: no second
+    register to disagree with, so there is nothing to mix a fresh reading with a
+    stale one. `+` is import, `-` is export - verified in test_p1.py against real
+    captured readings from this house's own meter, not against a datasheet.
+
+    ⚠️ Exactly one of the two comes out non-zero. Splitting into `(max(v,0),
+    max(-v,0))` rather than clamping keeps `import_w - export_w == v` exactly, so
+    the signed value the meter published survives the round trip bit for bit -
+    a control loop must not be steered by a number that changed on the way in.
+
+    ⚠️ Validation is `_watts`, the same gate the unsigned path uses: NaN,
+    infinity, non-numbers and the §20 open-question-5 unsigned-decode
+    contamination (64954 for -582 W) are all refused here rather than believed.
+    A signed source makes that check MORE important, not less - on this path
+    64954 is not obviously wrong the way a negative "unsigned" register is.
+    """
+    v = _watts(net_w, "net")
+    return (v, 0.0) if v >= 0 else (0.0, -v)
+
+
 def make_sample(source: str, import_w, export_w, *, phases: int,
                 phase_import_w=None, phase_export_w=None,
                 telegram_ts: datetime | None = None,
@@ -252,6 +286,26 @@ class QuarterAverager:
         """Offtake watt-seconds accumulated in the open block so far."""
         return self._acc
 
+    @property
+    def held_net_w(self) -> float:
+        """The signed net power currently being held forward, in W.
+
+        PUBLIC BECAUSE SAFETY-07 DEPENDS ON IT, AND THAT IS THE WHOLE REASON.
+        `PeakTracker.project()` extrapolates the rest of the quarter from this
+        value and used to reach it as `getattr(averager, "_last_net", 0.0)`. A
+        default on a private name fails QUIET and fails in the DISARMING
+        direction: rename `_last_net` and every projection silently credits 0 W
+        held, which reads LOW, which puts the peak guard under the ceiling
+        exactly when the meter says it is over. Filed as TEST-13 item 4 and
+        fixed here rather than inherited - a money guard may not rest on a read
+        that can go wrong without a symptom.
+
+        Positive is offtake, matching `P1Sample.net_w`. It is the raw held
+        value, NOT floored at zero: the flooring is the accumulator's rule (only
+        offtake is billed) and belongs where it is applied, not here.
+        """
+        return self._last_net
+
     @property
     def offtake_avg_w(self) -> float:
         """Average offtake over the part of the open block seen so far."""
@@ -319,6 +373,54 @@ class QuarterAverager:
         self._last_pp = sample.per_phase_w
         return closed
 
+    # -- surviving a restart (TARIFF-01) ------------------------------------
+    def snapshot(self) -> dict:
+        """The open block's whole state, as JSON-safe primitives.
+
+        ⚠️ `last_t` is the HELD SAMPLE'S OWN timestamp and is stored as it is,
+        not refreshed to "now". That is what makes a restart integrate the gap
+        under exactly the `max_hold_s` rule a running process would have used:
+        a short restart is a plateau, a long one leaves uncovered seconds that
+        drag the closed block's average down. Rewriting it to the restore time
+        would silently credit the whole outage at the last value seen before it.
+        """
+        return {
+            "block": self._block,
+            "acc": self._acc,
+            "pp_acc": list(self._pp_acc),
+            "elapsed": self._elapsed,
+            "last_t": self._last_t,
+            "last_net": self._last_net,
+            "last_pp": list(self._last_pp) if self._last_pp is not None else None,
+            "phases": self.phases,
+        }
+
+    def restore(self, state: dict) -> bool:
+        """Put a `snapshot()` back. False if it does not fit this averager.
+
+        A phase-count change is a reconfiguration, not a resumption: the
+        per-phase accumulator would be reshaped mid-block and the two halves
+        would not be the same measurement. Refusing is the honest answer, and
+        the caller reports starting fresh rather than pretending it resumed.
+        """
+        try:
+            if int(state.get("phases", self.phases)) != self.phases:
+                return False
+            pp_acc = list(state.get("pp_acc") or [])
+            if len(pp_acc) != self.phases:
+                return False
+            self._block = None if state["block"] is None else int(state["block"])
+            self._acc = float(state["acc"])
+            self._pp_acc = [float(v) for v in pp_acc]
+            self._elapsed = float(state["elapsed"])
+            self._last_t = None if state["last_t"] is None else float(state["last_t"])
+            self._last_net = float(state["last_net"])
+            lp = state.get("last_pp")
+            self._last_pp = tuple(float(v) for v in lp) if lp is not None else None
+            return True
+        except (KeyError, TypeError, ValueError):
+            return False
+
 
 # --------------------------------------------------------------------------- #
 # what the rest of the add-on talks to
@@ -668,6 +770,333 @@ class MqttP1Source:
             self.ingest.reject(err)
 
 
+# --------------------------------------------------------------------------- #
+# transport 3: Home Assistant WebSocket, one signed entity
+# --------------------------------------------------------------------------- #
+class HaSignedSource(HaDsmrSource):
+    """The same websocket, subscribed to ONE signed power entity.
+
+    For readers that publish net power as a single signed figure - a HomeWizard
+    P1's `sensor.p1_meter_active_power`, positive = import - rather than the two
+    unsigned DSMR registers. This is the meter actually installed at the house,
+    and `ha_dsmr` cannot read it: it needs two registers and refuses a negative
+    one outright, which is every exporting telegram.
+
+    ⚠️ A subclass, not a copy. The connect / auth / subscribe / reconnect /
+    `_absorb` machinery above is transport, not shape, and it has already been
+    debugged once - notably "prime the cache from get_states but never build a
+    sample out of it" and "a reconnect emits nothing". Only `_wanted` (which
+    entity ids) and `build` (how they become a sample) differ, so only those two
+    are overridden. Everything TEL-01 established therefore applies unchanged:
+    ingest timestamping, meter_max_age_s, the clock-recomputed age sensor, and
+    `unavailable` treated as a missing reading rather than 0 W.
+
+    ⚠️ THE AGE ON THIS TRANSPORT MEASURES TIME SINCE THE VALUE CHANGED, not time
+    since the meter reported, and on one entity those are very different things.
+    Home Assistant offers no arrival signal for a repeated reading: it emits no
+    `state_changed`, it does not advance `last_reported` on either serialiser,
+    and `state_reported` cannot be subscribed to over the websocket at all
+    ("Event filter is required for event state_reported"). All three measured on
+    the ENV-01 rig against the real HomeWizard integration with the meter frozen
+    - 0 state_changed in 70 s, no timestamp movement anywhere.
+
+    `ha_dsmr` mostly escapes it because a DSMR telegram moves several entities at
+    once. This transport has ONE, so a healthy meter under a flat load looks
+    exactly like a dead one - and our own capture has the real meter going 42.2 s
+    and 97.0 s between changes, both past the default max_age_s of 30. Hence
+    DOCS.md: sensor.p1_sample_age_s is correct while the value moves and must not
+    yet be thresholded by the firmware watchdog on this transport. Raising
+    meter_max_age_s does not fix it, it only chooses which of the two errors you
+    get. The fix is an arrival stamp from the meter itself - reading the
+    HomeWizard local API rather than an HA entity - which is a separate ticket.
+
+    ⚠️ The debounce is inherited but does nothing useful here, and that is fine:
+    one telegram is one entity, so there is no burst of per-entity events to
+    coalesce and no window in which a new reading sits beside a stale one. It
+    costs one scheduled sleep per telegram at ~0.2 Hz. Left in place rather than
+    special-cased, because a second code path through build() is a second place
+    for the sign to go wrong.
+    """
+
+    def _wanted(self) -> set[str]:
+        out = set()
+        if self.entities.get("net"):
+            out.add(self.entities["net"])
+        out.update(e for e in self.entities.get("phase_net") or [] if e)
+        return out
+
+    def build(self) -> bool:
+        """Assemble one sample from the cache. Returns True if one was accepted."""
+        net_id = self.entities.get("net")
+        if net_id not in self.cache:
+            return False
+        pn = [self.cache.get(e) for e in self.entities.get("phase_net") or []]
+        if pn and None in pn:
+            return False           # incomplete phase set: wait, do not guess
+        try:
+            imp, exp = split_signed(self.cache[net_id])
+            pi = pe = None
+            if pn:
+                # ponytail: this split is arithmetically redundant today -
+                # make_sample subtracts the two lists again and does not
+                # sign-check per-phase figures, so handing it the signed values
+                # with a zero export list produces the identical tuple. Verified:
+                # mutating it that way leaves all 174 checks green, i.e. no test
+                # can tell the difference, and it is recorded here rather than
+                # left as a silent equivalent mutant for the next reviewer to
+                # rediscover. Kept because `phase_import_w` means a MAGNITUDE:
+                # a negative in it is the double-signing that make_sample refuses
+                # outright for the connection-level registers, and the day that
+                # check is extended per-phase the shortcut breaks the meter, not
+                # the test.
+                pairs = [split_signed(v) for v in pn]
+                pi = [a for a, _ in pairs]
+                pe = [b for _, b in pairs]
+            self.ingest.submit(make_sample(
+                SOURCE_HA_SIGNED, imp, exp,
+                phases=self.ingest.phases,
+                phase_import_w=pi, phase_export_w=pe,
+                # ⚠️ No telegram_ts, for the same reason as ha_dsmr: HA's
+                # last_changed is when the VALUE changed, which on a steady meter
+                # is minutes ago while the telegram is current. sensor.
+                # p1_sample_age_s is what covers a genuinely frozen meter.
+            ))
+            return True
+        except P1Error as err:
+            self.ingest.reject(err)
+            return False
+
+
+# --------------------------------------------------------------------------- #
+# transport 4: the HomeWizard P1's own local API
+# --------------------------------------------------------------------------- #
+HOMEWIZARD_PATH = "/api/v1/data"
+HOMEWIZARD_PORT = 80
+
+
+def parse_homewizard(doc, phases: int, *, now: datetime | None = None,
+                     ingest_mono: float | None = None) -> P1Sample:
+    """One `GET /api/v1/data` document -> a sample. Raises P1Error.
+
+    The meter's own JSON, of which we read four keys:
+
+        {"active_power_w": -5710.0,          # SIGNED, + import  - export
+         "active_power_l1_w": ..., "active_power_l2_w": ..., "..._l3_w": ...,
+         "total_power_import_kwh": 1234.567, "total_power_export_kwh": 890.123}
+
+    Same shape as `ha_signed` - one signed connection figure plus signed
+    per-phase figures - so it goes through the same `split_signed` and the same
+    `make_sample`. Nothing about the sign convention is re-derived here.
+
+    ⚠️ No telegram timestamp, because the API carries none, and that is correct
+    rather than a gap: the document was produced by the meter in the moment it
+    answered, so the ingest stamp IS the measurement time. This is the whole
+    reason the transport exists - see HomeWizardLocalSource.
+
+    ⚠️ Per-phase figures are taken only when the meter serves ALL `phases` of
+    them. A single-phase HomeWizard returns `active_power_l2_w: null`, and a
+    partial set must not become a fabricated tuple. Unlike the HA transports
+    there is no "wait for the rest" case to worry about: every field here came
+    out of ONE response, so a missing phase cannot be a stale phase, and the
+    connection-level reading is still a genuine, complete measurement. Dropping
+    the whole sample over an absent per-phase field would turn a healthy meter
+    into a climbing age, which is the exact false-trip this ticket removes.
+    """
+    if not isinstance(doc, dict):
+        raise P1Error(f"meter response is not a JSON object ({type(doc).__name__})")
+
+    imp, exp = split_signed(doc.get("active_power_w"))
+
+    pi = pe = None
+    # ⚠️ range(phases), not the legs the meter served: a 3-phase meter configured
+    # as meter_phases: 1 yields a per-phase tuple covering ONE leg of three.
+    # Control is unaffected (it uses the connection figure), but the
+    # capacity-tariff peak is understated. Filed separately - not fixed here.
+    legs = [doc.get(f"active_power_l{i + 1}_w") for i in range(phases)]
+    if all(v is not None for v in legs):
+        pairs = [split_signed(v) for v in legs]
+        pi = [a for a, _ in pairs]
+        pe = [b for _, b in pairs]
+
+    return make_sample(SOURCE_HOMEWIZARD, imp, exp, phases=phases,
+                       phase_import_w=pi, phase_export_w=pe,
+                       ingest_ts=now, ingest_mono=ingest_mono)
+
+
+def measurement_fingerprint(doc) -> tuple:
+    """The part of a response that a genuinely new measurement has to move.
+
+    Power plus both energy registers. A meter under any real load advances a
+    kWh counter (1 Wh resolution: ~10 s at 350 W), so this changes even when the
+    power figure happens to repeat. Used ONLY for `unchanged_s` - see there for
+    why it must not be allowed anywhere near the age.
+    """
+    if not isinstance(doc, dict):
+        return ()
+    return (doc.get("active_power_w"),
+            doc.get("total_power_import_kwh"),
+            doc.get("total_power_export_kwh"))
+
+
+class HomeWizardLocalSource:
+    """Polls the meter's own local HTTP API instead of a Home Assistant entity.
+
+    ⚠️ THIS IS THE ONLY TRANSPORT WHOSE AGE MEASURES ARRIVAL. That is the entire
+    reason it exists, and it is not an optimisation - it is the difference
+    between an age sensor a firmware watchdog may threshold and one it may not.
+
+    Every HTTP response is a genuine arrival: the meter answered, now, with its
+    current reading. Whether the NUMBER moved is irrelevant, so a healthy meter
+    under a flat load resets the age exactly like a busy one. Home Assistant
+    cannot provide this at all - it emits `state_changed` only on a change, does
+    not advance `last_reported` on either serialiser for a repeat, and refuses a
+    `state_reported` subscription outright ("Event filter is required"). Measured
+    on the ENV-01 rig over 70 s of a frozen meter, and independently against the
+    live house over ten repeated readings. So on `ha_signed` the age means "time
+    since the value changed", and our own capture of this house's meter has
+    42.2 s and 97.0 s between changes - both past the default `meter_max_age_s`
+    of 30, i.e. a false trip to 0 W on a perfectly healthy meter.
+
+    Everything else is TEL-01's pipeline unchanged: ingest timestamping,
+    `meter_max_age_s`, the clock-recomputed age, the plausibility bounds, and a
+    failed read treated as a MISSING reading rather than 0 W.
+
+    ⚠️ A failed or timed-out poll submits nothing. It is a rejection, so the
+    last good sample and its stamp stay exactly where they were and the age goes
+    on climbing - which is precisely the signal a dead meter should produce.
+
+    ⚠️ POLL CADENCE vs `meter_max_age_s`. The age can only be as fresh as the
+    poll interval, so `meter_poll_s` must sit well under `meter_max_age_s` or the
+    reading flaps in and out of staleness on a healthy meter. The real meter
+    updates every ~5.0 s (NOTES.md:640 measures 4.97 s), so polling faster than
+    that buys nothing but re-reads. Default 5 s against a 30 s max age; the
+    startup check in build_source refuses `meter_poll_s >= meter_max_age_s` and
+    warns past half of it.
+
+    ponytail: a plain `asyncio.sleep` loop rather than a scheduler, and no
+    backoff. A poll that fails costs one rejection and is retried on the next
+    tick; a meter that is down stays down and the age reports it. The ceiling is
+    a meter so slow that polls overlap - the request timeout is held under the
+    poll interval so they cannot.
+    """
+
+    def __init__(self, session, ingest: P1Ingest, host: str, *,
+                 port: int = HOMEWIZARD_PORT, poll_s: float = 5.0,
+                 timeout_s: float | None = None):
+        self.session = session
+        self.ingest = ingest
+        self.host, self.port = host, int(port)
+        self.poll_s = float(poll_s)
+        # ⚠️ Held under the poll interval on purpose: a timeout longer than the
+        # cadence queues polls behind a hung meter, and a backlog of requests
+        # all landing at once would stamp several arrivals for one measurement.
+        self.timeout_s = float(timeout_s) if timeout_s else max(1.0, self.poll_s * 0.8)
+        self.url = f"http://{self.host}:{self.port}{HOMEWIZARD_PATH}"
+        self.connected = False
+        self.polls = 0
+        self.poll_errors = 0
+        self._fingerprint: tuple | None = None
+        self._changed_mono: float | None = None
+
+    @property
+    def unchanged_s(self) -> float | None:
+        """Seconds since the meter last served a DIFFERENT measurement.
+
+        ⚠️ Diagnostic only, and deliberately NOT folded into
+        `sensor.p1_sample_age_s`. A frozen meter (SAFETY-01's six-minute
+        runaway) answers 200 OK with a stale document forever, so no arrival
+        detector can see it - only the document standing still can, and this is
+        that signal. It is exposed rather than acted on because it is NOT safe
+        as a 30 s watchdog input: this controller regulates grid power toward
+        ~0 W, and at a converged -10 W the export register takes six minutes to
+        advance by its 1 Wh resolution while the power figure legitimately
+        repeats. Thresholding that would rebuild the very limit cycle the
+        arrival stamp just removed, at the exact operating point we aim for.
+        Whoever wires a freeze detector must handle the low-power case first.
+        """
+        if self._changed_mono is None:
+            return None
+        return max(0.0, time.monotonic() - self._changed_mono)
+
+    async def run(self) -> None:
+        """Long-lived task: poll, submit, sleep, forever.
+
+        ⚠️ Nothing but cancellation may end this loop. An escaping exception
+        would kill the poll task for the lifetime of the add-on, and it would do
+        it QUIETLY: the failure mode is safe (no submissions, the age climbs, the
+        watchdog holds the battery at 0 W) but it looks identical to a dead
+        meter, so the operator goes hunting the wrong device. Retry on the next
+        tick instead - poll_s is already the retry cadence, so no backoff.
+        """
+        _LOG.info("P1 ingest: polling %s every %.1fs", self.url, self.poll_s)
+        while True:
+            try:
+                await self.poll_once()
+            except asyncio.CancelledError:
+                raise
+            except Exception as err:  # noqa: BLE001 - the task must outlive it
+                _LOG.warning("P1 meter poll %s: %s - retrying in %.1fs", self.url,
+                             str(err) or type(err).__name__, self.poll_s)
+            await asyncio.sleep(self.poll_s)
+
+    async def poll_once(self) -> bool:
+        """One GET. Returns True if a sample was accepted."""
+        self.polls += 1
+        try:
+            async with self.session.get(
+                    self.url,
+                    timeout=aiohttp.ClientTimeout(total=self.timeout_s)) as resp:
+                if resp.status != 200:
+                    raise P1Error(f"meter returned HTTP {resp.status}")
+                # content_type=None: the meter's own firmware is the authority on
+                # what it serves, and refusing a reading over a Content-Type
+                # header would be a fabricated outage.
+                # ⚠️ Kept because a real HomeWizard firmware that ever answers
+                # text/plain would otherwise read as a dead meter and hold the
+                # battery at 0 W. (This was once recorded here as an equivalent
+                # mutant - it is not. aiohttp's json_response always sets
+                # application/json, but web.Response(text=...) defaults to
+                # text/plain, so the fake meter CAN serve valid JSON under the
+                # wrong header, and test_p1.py now does.)
+                doc = await resp.json(content_type=None)
+        except asyncio.CancelledError:
+            raise
+        except Exception as err:  # noqa: BLE001 - any read failure is a gap
+            self.connected = False
+            self.poll_errors += 1
+            # ⚠️ str() of a bare asyncio.TimeoutError is the EMPTY STRING, so
+            # f"...: {err}" renders "last error:" and then nothing - on the
+            # status page, on a hung meter, at the moment the battery has just
+            # dropped to 0 W and someone is reading that line to find out why.
+            # The class name is the only thing that says "it timed out".
+            # ⚠️ str(err), not `err or ...`: an exception object is ALWAYS truthy,
+            # empty message or not, so the `or` would never reach the fallback.
+            self.ingest.reject(
+                f"meter poll {self.url}: {str(err) or type(err).__name__}")
+            return False
+
+        self.connected = True
+        try:
+            sample = parse_homewizard(doc, self.ingest.phases)
+            # ⚠️ Submitted unconditionally, INCLUDING a document identical to the
+            # last one. The response is the arrival; the number is not.
+            # Inside the try on purpose: submit() outside it would put a raise on
+            # a path with no handler at all, killing the poll task permanently -
+            # safely (the age climbs) but silently. run() backstops the rest.
+            self.ingest.submit(sample)
+            self._note(doc)
+        except P1Error as err:
+            self.ingest.reject(err)
+            return False
+        return True
+
+    def _note(self, doc) -> None:
+        fp = measurement_fingerprint(doc)
+        if self._changed_mono is None or fp != self._fingerprint:
+            self._fingerprint = fp
+            self._changed_mono = time.monotonic()
+
+
 # --------------------------------------------------------------------------- #
 # selection
 # --------------------------------------------------------------------------- #
@@ -683,15 +1112,133 @@ def is_enabled(opts: dict) -> bool:
     return str(opts.get("meter_source", "off") or "off").strip() not in ("off", "")
 
 
+def homewizard_host_port(opts: dict) -> tuple[str, str]:
+    """`p1_host` split into host and (still unparsed) port text.
+
+    One definition because validate_meter_options() and build_source() must
+    agree byte for byte about what counts as a usable address - a pasted browser
+    URL is the obvious way to fill this in wrong.
+    """
+    host = str(opts.get("p1_host", "") or "").strip()
+    host = host.removeprefix("http://").removeprefix("https://").rstrip("/")
+    host, _, port_s = host.partition(":")
+    return host, port_s
+
+
+def validate_meter_options(opts: dict, phases: int, max_age_s: float) -> list[str]:
+    """Every way `meter_source` can name a meter that will never produce a reading.
+
+    ⚠️ THIS IS THE ONLY PLACE THAT KNOWS THESE RULES. It used to be a run of
+    inline `return None`s inside build_source(); CFG-01 lifted them out because
+    the same predicates now have two callers with two different consequences:
+
+      validate.validate_startup_config()  refuses to start the add-on
+      build_source()                      returns None, as it always did
+
+    They are one function and not two on purpose. A second copy of "what makes a
+    meter config wrong" would drift, and the half that drifted would be the one
+    that decides whether the process is allowed to run.
+
+    Checked ONCE at startup rather than per telegram, because a misconfigured
+    source otherwise fails in the one way indistinguishable from a healthy source
+    nobody has sent anything to yet: no samples, a climbing age, the firmware
+    watchdog holding the battery at 0 W, and nothing in the log saying why.
+
+    Returns a list of human-readable problems; empty means the config is usable.
+    `phases` and `max_age_s` are passed in rather than read from opts so the
+    caller decides whether it is validating the options or an already-built
+    P1Ingest - build_source() has an ingest whose values may not have come from
+    this dict.
+    """
+    source = str(opts.get("meter_source", "off") or "off").strip()
+    if source in ("off", ""):
+        return []
+    problems: list[str] = []
+
+    if source == SOURCE_HA:
+        imp = str(opts.get("p1_import_entity", "") or "").strip()
+        exp = str(opts.get("p1_export_entity", "") or "").strip()
+        if not imp or not exp:
+            problems.append(
+                f"meter_source {SOURCE_HA} needs both p1_import_entity and "
+                f"p1_export_entity (got {imp or '<blank>'!r} / {exp or '<blank>'!r})")
+    elif source == SOURCE_HA_SIGNED:
+        net = str(opts.get("p1_net_entity", "") or "").strip()
+        phase_net = [str(e).strip() for e in
+                     (opts.get("p1_phase_net_entities") or []) if str(e).strip()]
+        if not net:
+            problems.append(
+                f"meter_source {SOURCE_HA_SIGNED} needs p1_net_entity "
+                "(sensor.p1_sample_age_s would otherwise be announced with "
+                "nothing feeding it)")
+        if phase_net and len(phase_net) != phases:
+            problems.append(
+                f"p1_phase_net_entities has {len(phase_net)} entities but "
+                f"meter_phases is {phases} - every telegram would be rejected "
+                "on the phase-count check")
+    elif source == SOURCE_MQTT:
+        if not str(opts.get("meter_mqtt_topic", "") or "").strip():
+            problems.append(f"meter_source {SOURCE_MQTT} needs meter_mqtt_topic")
+    elif source == SOURCE_HOMEWIZARD:
+        host, port_s = homewizard_host_port(opts)
+        if not host:
+            problems.append(
+                f"meter_source {SOURCE_HOMEWIZARD} needs p1_host (the meter's "
+                "own address, e.g. 192.168.2.250)")
+        if port_s:
+            try:
+                int(port_s)
+            except ValueError:
+                problems.append(f"p1_host {opts.get('p1_host')!r} has an "
+                                "unparseable port")
+        try:
+            # ⚠️ Not `or 5`: that turns an explicit 0 into the default, and a
+            # cadence of 0 is a misconfiguration that must be reported, not
+            # quietly corrected into something that looks like it was asked for.
+            raw = opts.get("meter_poll_s", 5)
+            poll_s = float(5 if raw is None or raw == "" else raw)
+        except (TypeError, ValueError):
+            problems.append(f"meter_poll_s {opts.get('meter_poll_s')!r} is not a number")
+        else:
+            if poll_s <= 0:
+                problems.append("meter_poll_s must be positive")
+            # ⚠️ The age can never be fresher than the poll interval. At or past
+            # max_age_s every reading is stale before its successor arrives, so
+            # the controller would sit permanently on missing inputs while the
+            # meter is perfectly healthy - refuse it rather than ship that.
+            elif poll_s >= max_age_s:
+                problems.append(
+                    f"meter_poll_s {poll_s:.1f} is not under meter_max_age_s "
+                    f"{max_age_s:.1f} - every reading would go stale before the "
+                    "next poll")
+    else:
+        problems.append(
+            f"meter_source {source!r} is not one of "
+            + ", ".join((SOURCE_HA, SOURCE_MQTT, SOURCE_HA_SIGNED, SOURCE_HOMEWIZARD)))
+    return problems
+
+
 def build_source(opts: dict, ingest: P1Ingest, session, broker: dict | None):
     """Return the transport named by `meter_source`, or None if disabled.
 
     This is the whole of AC 1's "switchable": every consumer reads P1Ingest, so
     changing transport is a config edit, never a code path.
+
+    ⚠️ In the add-on this is now unreachable with a bad config -
+    validate_startup_config() refuses to start on anything
+    validate_meter_options() rejects. The guard stays because this function is
+    also called directly by tests and by anything embedding P1Ingest, and
+    "returns None" is a safer default for those callers than a transport that
+    can never read.
     """
     source = str(opts.get("meter_source", "off") or "off").strip()
     if not is_enabled(opts):
         return None
+    problems = validate_meter_options(opts, ingest.phases, ingest.max_age_s)
+    if problems:
+        for problem in problems:
+            _LOG.error("%s - P1 ingestion disabled", problem)
+        return None
     if source == SOURCE_HA:
         return HaDsmrSource(session, ingest, {
             "import": opts.get("p1_import_entity", ""),
@@ -699,12 +1246,29 @@ def build_source(opts: dict, ingest: P1Ingest, session, broker: dict | None):
             "phase_import": opts.get("p1_phase_import_entities") or [],
             "phase_export": opts.get("p1_phase_export_entities") or [],
         })
+    if source == SOURCE_HA_SIGNED:
+        return HaSignedSource(session, ingest, {
+            "net": str(opts.get("p1_net_entity", "") or "").strip(),
+            "phase_net": [str(e).strip() for e in
+                          (opts.get("p1_phase_net_entities") or []) if str(e).strip()],
+        })
+    if source == SOURCE_HOMEWIZARD:
+        host, port_s = homewizard_host_port(opts)
+        port = int(port_s) if port_s else HOMEWIZARD_PORT
+        raw = opts.get("meter_poll_s", 5)
+        poll_s = float(5 if raw is None or raw == "" else raw)
+        # A warning, not a refusal: one missed poll costs a stale reading and a
+        # 0 W cycle, which is fail-safe. The refusal above is for cadences that
+        # can NEVER be fresh.
+        if poll_s > ingest.max_age_s / 2:
+            _LOG.warning("meter_poll_s %.1f leaves no room under meter_max_age_s "
+                         "%.1f: one missed poll makes the reading stale. The meter "
+                         "updates every ~5 s; 5 s against 30 s is the tested pair.",
+                         poll_s, ingest.max_age_s)
+        return HomeWizardLocalSource(session, ingest, host, port=port, poll_s=poll_s)
     if source == SOURCE_MQTT:
         broker = broker or {}
         return MqttP1Source(ingest, str(opts.get("meter_mqtt_topic", "")),
                             broker.get("host"), broker.get("port", 1883),
                             broker.get("username"), broker.get("password"))
-    if source:
-        _LOG.error("meter_source %r is not %s or %s - P1 ingestion disabled",
-                   source, SOURCE_HA, SOURCE_MQTT)
     return None

goodwe_controller/app/peakguard.py

@@ -0,0 +1,517 @@
+"""SAFETY-07 - the quarter-peak projection guard, and the only thing in this
+add-on that is allowed to spend the loop's freedom to save money.
+
+WHAT IT IS. TARIFF-01 built the INSTRUMENT: `tariff.py` measures the number the
+Belgian capaciteitstarief bills on - the highest 15-minute average offtake of the
+calendar month - and banks it where a restart cannot reach. It files no claim and
+commands nothing, and says so in its own first paragraph. This module is the
+CONSUMER it named. It turns that measurement into one arbiter claim and nothing
+else: no writes, no I/O, no clock, no state between calls. Given a projection and
+two measured numbers it returns a decision; `main.py` files it.
+
+------------------------------------------------------------------------------
+THE HAZARD, WITH THE EURO FIGURE
+
+specs.md:583 records a measured case: ONE 4998 W quarter moved a monthly peak
+from 4832 W to 5013 W and billed the whole month at it. The capacity tariff has
+no averaging and no forgiveness - the month's single worst quarter is the bill.
+
+SAFETY-18 shipped the ALARM for the way this system produces such a quarter by
+itself: a meter that answers 200 OK forever with a document that never changes,
+which every freshness mechanism in this stack reads as healthy while the loop
+integrates a constant error to the rail and holds it there. freeze.py's own
+table: at the live install's `max_w: 5000`, a meter frozen at >= 3000 W rails the
+command in 75 s. SAFETY-18 notifies at `meter_freeze_s` (300 s default), against
+a 900 s billing quarter. That is about nine minutes of human reaction time and
+nothing else - freeze.py says so in the words "THIS CUT DOES NOT CAP THAT."
+
+This is the cap. It is deliberately NOT a second freeze detector: it consumes
+freeze.py's shipped predicate rather than transcribing it.
+
+------------------------------------------------------------------------------
+THE MECHANISM: ONE `lo` LIMIT AT `P_PEAK`, AND WHY THAT SHAPE
+
+specs.md 10.1 row 2 asks for exactly two behaviours - "pre-emptive discharge as
+the projected quarter average approaches the soft limit; hard clamp on charging
+above it" - and 9.1 constrains the lever: "Discharge and export are never capped
+by the peak guard; only charging and import are."
+
+A LOWER BOUND on the setpoint is both of those in one object, and it is the only
+shape that is:
+
+  * incapable of capping discharge - a floor never stops the loop discharging
+    HARDER, so 9.1's asymmetry is structural here rather than remembered;
+  * incapable of capping export, for the same reason;
+  * a hard clamp on charging whenever the floor is above the standing charge;
+  * pre-emptive discharge whenever the floor is above zero.
+
+It is a LIMIT, not a SET, and that matters at both ends of the priority table.
+`P_PEAK` (50) is above `P_LOOP` (10), so it binds the grid-following loop. It is
+BELOW `P_MAINTENANCE` (60) and `P_SAFETY` (100), so a maintenance phase that owns
+the actuator and every layer-1 stop still outrank it: arbiter.py's clause 2 only
+applies limits whose priority is >= the WINNING SET's, so a P_SAFETY 0 W stop is
+not dragged off zero by this floor. That is the correct order - a controller
+pushing power the wrong way is wrong however much money it is trying to save.
+
+⚠️ AND A LIMIT DOES NOT OUT-VOTE ANOTHER LIMIT. This was assumed, and it is
+false: arbiter.py clause 2 applies EVERY limit at or above the winner's priority
+and takes the MOST RESTRICTIVE, with no notion of priority between them - which
+is exactly what makes the safety bounds unconditional and must not be changed.
+So this floor (`lo >= 0`) and the maintenance charge-only shaping (`hi <= 0`) do
+not resolve in P_PEAK's favour when both are filed. They resolve to `lo > hi`, a
+CONTRADICTION, which arbiter.py answers with 0 W - the battery parked in the one
+quarter of the month it should be shaving hardest. The rule for two limits that
+can cross is therefore SUPPRESSION, not priority: main.py drops the maintenance
+shaping for as long as this guard is engaged, which is the same thing that branch
+already did for `peak_forecast_entity` and is why 9.1's "money outranks the
+maintenance schedule" reads as a suppression there rather than as a priority
+here. The floor's clamp to `achievable_w` closes the only other pair that could
+cross - the P_SAFETY rating bounds.
+
+AND IT IS WHY OPT-04 NEEDS NO CHANGE HERE. 9.1 requires peak shaving to outrank
+arbitrage. Arbitrage does not exist yet, but it will arrive as a SET below
+P_PEAK, and arbiter.py clause 2 will bind it with this floor on the day it lands,
+with no edit to this file. Expressing the priority as a claim rather than as an
+if/else in main.py is the whole reason that holds.
+
+------------------------------------------------------------------------------
+THE FLOOR IS DERIVED, AND EVERY TERM OF IT IS MEASURED
+
+Let `ceiling_w` be the quarter average that must not be exceeded and `remaining`
+the seconds left in the open block. `project()` gives
+
+    projected = (acc + held * remaining) / 900
+
+so the held level that would land the quarter exactly on the ceiling is
+`held + 900 * (ceiling - projected) / remaining`, and the watts that must come
+off the meter are the difference between the two:
+
+    excess_w = 900 * (projected - ceiling) / remaining
+
+That single expression carries the whole control law, and two properties of it
+are the argument for this design:
+
+  1. THE CLAIM IS FILED WHILE THE FLOOR IS POSITIVE, NOT WHILE THE EXCESS IS.
+     `excess` is what must come off the METER, so it falls to zero the moment the
+     battery is already taking it - and a guard that disengaged there would hand
+     the actuator back, watch the offtake spring straight to the raw load, and
+     engage again next cycle. That is not a hypothetical: it is what the first
+     cut of this file did to 2026-08-20's billed quarter on replay - seventeen
+     engage/release cycles in 900 s, and the quarter still finished 49 W over the
+     limit it had spent a quarter of an hour holding. 10.2 names the cost
+     exactly: "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."
+
+     `batt_w + excess` IS the quantity to threshold: the offtake there would be
+     with the battery at zero, less the level this quarter can still afford. Read
+     as a LEVEL rather than as a switch, the same arithmetic gives a claim that
+     is filed for as long as a positive floor is needed and decays continuously
+     to nothing as the load falls. So there is still no hysteresis constant in
+     this file - not because oscillation was ruled out by argument, but because
+     the thresholded quantity is the one that does not oscillate.
+
+  2. THE GAIN IS 900/remaining, WHICH IS 1.0 AT THE START OF THE QUARTER AND
+     GROWS. This is the answer to the degeneracy at the top of a block, where the
+     projection is an extrapolation from almost no evidence: the guard is at its
+     GENTLEST exactly when its evidence is weakest, and becomes aggressive only
+     once most of the quarter is behind it and the projection is nearly a
+     measurement. The formula supplies that; no minimum-evidence threshold was
+     invented, because inventing one would delay the guard in the case it exists
+     for - a sustained rail from second zero.
+
+The floor itself is then
+
+    floor_w = batt_w + excess_w
+
+`batt_w` IS THE MEASURED BATTERY POWER, NOT THE STANDING COMMAND. Both were
+available. The measured one is right for two independent reasons. First, 9.1's
+settled constraint is that the utility bills what FLOWED - the arithmetic
+`grid = load - batt` is true of delivered power and false of intent. Second, and
+concretely: when the inverter cannot follow (the saturation case control.py
+already freezes the integrator for), a floor built on the command asks for
+`command + excess` every cycle while the command never arrives, and winds itself
+to the rail; a floor built on the measurement asks for `delivered + excess`,
+which stops rising the moment delivery stops rising. The delivered form cannot
+wind up. The intent form can.
+
+------------------------------------------------------------------------------
+THE CEILING IS `peak_cap_w`, RAISED ONLY BY AN OBSERVATION
+
+11.2's row is "Quarter peak | Projected quarter average approaches THE MONTHLY
+PEAK | Clamp the command", and 9.1's soft limit is `peak_cap_w`. Both matter,
+because the money is spent on `max(month's peak so far, this quarter)`:
+
+    ceiling_w = max(peak_cap_w, the month's banked peak)
+
+Once a month's peak already stands at 5013 W, holding every later quarter to
+3500 W buys nothing - the bill for that month is already 5013 W - while the
+holding itself costs real charging the site wanted. Raising the ceiling to a peak
+that has already been paid for is what stops one bad quarter from parking the
+battery's charging for three weeks.
+
+AND THAT RELAXATION IS GRANTED ONLY BY AN `OBSERVED` READING. `NO_RECORD` and
+`NOT_OBSERVED` both leave the ceiling at `peak_cap_w`, the tighter of the two, so
+a peak store that cannot be read makes this guard STRICTER and never looser. That
+direction is the whole point: tariff.py's `PeakReading` exists because a database
+that did not answer must not become a number, and the number it would have become
+here - a zero peak - is exactly the one that reads as "no peak recorded, full
+freedom". It is also why this module does NOT consume `headroom_w()`, whose
+disarming failure it would otherwise inherit: a peak read as 0 W returns FULL
+headroom, and full headroom is a guard that is not there.
+
+------------------------------------------------------------------------------
+BLINDNESS COMES FIRST, AND IT IS A DIFFERENT ACTION
+
+A projection is evidence only if the quantity under it was actually measured.
+Three ways it is not, all of them checked BEFORE the projection is graded,
+because grading a stimulus where the quantity it grades is degenerate is how a
+guard passes its own tests while being switched off:
+
+  * NO OPEN BLOCK. `project()` answers a fresh averager with
+    `Projection(0.0, 0.0, 0.0, 0.0, False, None, 0.0)` - a ZERO projection, which
+    compares as comfortably under any ceiling. That is not "the quarter is fine",
+    it is "there is no quarter". Graded as a number it silently disarms the guard
+    on exactly the startup path where nothing else is watching.
+
+  * COVERAGE. A meter gap longer than one `max_hold_s` window leaves seconds that
+    `QuarterAverager` deliberately does not accumulate (p1.py: holding a dead
+    meter's last value forward is how a fabricated peak gets onto a permanent
+    record). Those seconds make the projection read LOW, which is the
+    under-guarding direction. The threshold is `max_hold_s` itself - the point
+    p1.py already stops trusting a held sample - not a new number.
+
+  * FROZEN. SAFETY-18's conjunction, evaluated through `freeze.looks_frozen()`
+    rather than re-written here. A frozen meter is the worst case of all: the
+    samples keep ARRIVING, so coverage stays perfect and the projection is
+    confident - and if the stuck value is an export, the projection is a
+    confident ZERO while the real meter runs at the rail. This is the case
+    SAFETY-07 exists to backstop, and it is the case a projection cannot see.
+
+THE BLIND ACTION IS `floor_w = 0.0`: the battery may not IMPORT while the billed
+quantity is unobservable. It is the minimal action that closes the hazard, and it
+is one-directional - forbidding charging can only ever lower delivered offtake,
+never raise it - so a false blindness costs a charge the site wanted and cannot
+cost energy the pack did not want to give. Contrast the graded branch, which can
+force discharge; blindness deliberately does not earn that, because there is by
+definition no measurement to size it from.
+
+------------------------------------------------------------------------------
+WHY THIS ONE TRIPS WHERE SAFETY-18 ONLY NOTIFIES
+
+SAFETY-18 shipped notification-first, and config.yaml says why in one line: "A
+false trip parks the battery; a false alarm costs an alert." That reasoning is
+right for a DETECTOR whose negative case had to be established on a rig run. It
+does not carry to this guard, and the two committed captures say so:
+
+  * MEASURED FALSE-ENGAGEMENT RATE ON THE HEALTHY DAY: zero. 2026-08-23's worst
+    quarter is a few hundred watts against a 3500 W ceiling and nothing in its 95
+    quarters comes near engaging. test_peakguard.py re-measures that every run
+    from the committed capture rather than quoting it here.
+  * THE ACTION IS LEVEL-TRIGGERED AND UNLATCHED. It is re-derived from a fresh
+    projection every cycle and releases the instant the projection drops back
+    under the ceiling. There is no state to clear and no operator to wake. A
+    false engagement costs one cycle of discharge, not a parked battery - which
+    is precisely the cost SAFETY-18 could not bound and this one can.
+  * THE ACTION IS A LIMIT, NOT A SET. Every safety stop in 11.2's table outranks
+    it, so the worst thing a bug in this file can do is fail to relax a floor -
+    and a floor is bounded above by `achievable_w`, which main.py takes from the
+    same `max_w` and device rating the arbiter already enforces.
+
+So it trips. It is also the only guard here whose trigger IS the billed quantity
+itself, measured from parsed P1 telegrams, rather than a proxy for it.
+
+------------------------------------------------------------------------------
+SATURATION IS REPORTED, NOT ALARMED AS A BUG
+
+10.3's doctrine - "treat an out-of-range computed setpoint as a bug signal, clamp
+it AND alarm" - is SAFETY-03's, and it is right there: a loop computing 14 768 W
+is a winding integrator, i.e. a defect. A peak floor above the inverter's rating
+is NOT a defect. It is the ordinary physics of a 5900 W house load on a 5000 W
+inverter, which is literally what 2026-08-20 15:45 was. So the floor is clamped
+to `achievable_w` and the decision carries `saturated`, and main.py raises ONE
+notification on that - not because the controller is broken, but because it is
+the one case where the money WILL be spent and the controller has already done
+everything it can. An engagement that is not saturated is an ordinary control
+action and goes to the action log, like the clamp's engagements do.
+
+------------------------------------------------------------------------------
+NO NEW OPTION. CFG-03 STILL TRACKS THREE PLACES.
+
+`peak_cap_w` already ships, is already validated `int(500,15000)`, and is already
+read by `control.peak_at_risk()`. `max_hold_s` comes off the averager the caller
+already owns; `achievable_w` off `max_w` and the device rating the arbiter
+already enforces; the freeze predicate off `meter_freeze_s`. config.yaml and
+validate.py are untouched by this ticket, exactly as TARIFF-01 left them, and
+14's `capacity_peak_limit_kw` stays declined - a kW key beside a W key is the
+mismatch trap 14's own warning box describes.
+
+------------------------------------------------------------------------------
+⚠️ WHAT THIS GUARD DOES NOT HAVE: AN ENERGY BACKSTOP. SEE SAFETY-24.
+
+The graded branch can FORCE DISCHARGE, and nothing in this file or in the loop
+below it consults the state of charge - `soc_floor` belongs to the maintenance
+cycle, and freeze.py already records that for the grid-following loop "the BMS
+is the sole energy backstop". On the 2026-08-20 replay the guard asks for 878 Wh
+in a day. Against a pack sitting near 9 % that is not nothing, and the guard will
+keep asking as long as the meter says the quarter is over the ceiling.
+
+That is deliberate for THIS card and it is filed as SAFETY-24. It is also the
+reason this must not go to a client install before SAFETY-24 lands: on the
+reference site the BMS is a known quantity and an operator is present, and on a
+client site neither is true.
+
+------------------------------------------------------------------------------
+AND IT READS NO PER-PHASE QUANTITY, ON PURPOSE
+
+The sum/max/net reduction is an open product question with the owner. TARIFF-01
+put it behind `billed_w()` and defaulted to NET. Everything this module consumes
+- `PeakReading.peak_w`, `Projection.projected_w` - is already reduced by that one
+function, so whichever way the owner answers, this file does not change and does
+not need re-testing. Nothing here indexes a phase.
+"""
+
+from dataclasses import dataclass
+
+from .arbiter import P_PEAK, Claim
+from .control import peak_at_risk
+from .tariff import QUARTER_S
+
+# Why the projection may not be graded. Reasons, not booleans: the status page
+# and the action log both have to say WHICH, and "blind" alone is unactionable.
+BLIND_NO_BLOCK = "no open quarter - the meter has produced no sample yet"
+BLIND_COVERAGE = "meter gap"
+BLIND_FROZEN = "SAFETY-18: the meter is answering without changing"
+
+# Where the ceiling came from. Only the second is a relaxation, and only an
+# OBSERVED reading may produce it.
+CEILING_CAP = "peak_cap_w"
+CEILING_MONTH_PEAK = "the month's banked peak"
+
+SOURCE = "peak"
+
+
+@dataclass(frozen=True)
+class PeakDecision:
+    """What the guard concluded this cycle, with everything it concluded it from.
+
+    Every field is derived from a measurement taken in the same cycle. There is
+    no `floor_w_or(default)` and there must not be one, for `PeakReading`'s
+    reason: an accessor that turns "not measured" into a number re-creates the
+    defect the type exists to remove.
+    """
+
+    engaged: bool
+    floor_w: float | None            # the `lo` the claim carries; None = no claim
+    ceiling_w: float
+    ceiling_from: str
+    blind: str | None = None
+    projected_w: float | None = None
+    excess_w: float = 0.0
+    wanted_w: float | None = None    # the floor before `achievable_w` clamped it
+    saturated: bool = False
+    reason: str = ""
+
+    def explain(self) -> str:
+        if not self.engaged:
+            if self.projected_w is None:
+                return f"peak guard idle - {self.reason}"
+            return (f"peak guard idle - quarter projects "
+                    f"{self.projected_w:.0f} W under a {self.ceiling_w:.0f} W "
+                    f"ceiling ({self.ceiling_from})")
+        return self.reason
+
+
+def quarter_ceiling_w(cap_w, reading) -> tuple[float, str]:
+    """The average this quarter may not exceed, and where the number came from.
+
+    ONLY an OBSERVED reading may raise it. `NO_RECORD` (the store answered, this
+    month has nothing yet) and `NOT_OBSERVED` (the store did not answer) both
+    return the cap, which is the tighter answer. A failed read therefore makes
+    the guard stricter, never looser - see the module note.
+    """
+    cap = float(cap_w)
+    if (reading is not None and getattr(reading, "is_observed", False)
+            and reading.peak_w is not None and float(reading.peak_w) > cap):
+        return float(reading.peak_w), CEILING_MONTH_PEAK
+    return cap, CEILING_CAP
+
+
+def excess_w(projection, ceiling_w) -> float:
+    """Watts that must come off the meter NOW to land the quarter on the ceiling.
+
+    The whole control law, and the only place it is written down:
+
+        excess = 900 * (projected - ceiling) / remaining
+
+    Positive means the quarter is projected over; zero or negative means it is
+    not. `remaining <= 0` is not a large number, it is an undefined one - a
+    quarter with no seconds left cannot be influenced - so it answers 0.0 rather
+    than dividing.
+    """
+    remaining = QUARTER_S - float(projection.elapsed_s)
+    if remaining <= 0.0:
+        return 0.0
+    return QUARTER_S * (float(projection.projected_w) - float(ceiling_w)) / remaining
+
+
+def uncovered_s(projection) -> float:
+    """Seconds of the open block the meter did not actually cover.
+
+    Derived from what `Projection` already carries rather than re-measured:
+    `covered_frac` is `elapsed / elapsed_wall`, and `elapsed_s` IS that wall.
+    """
+    return max(0.0, float(projection.elapsed_s)
+               * (1.0 - float(projection.covered_frac)))
+
+
+def blindness(projection, max_hold_s, frozen: bool) -> str | None:
+    """Why this projection may not be graded, or None if it may be.
+
+    Evaluated BEFORE the projection is compared to anything. Each of the three is
+    a way for the projected number to be confident and wrong, and the first - a
+    fresh averager's all-zero `Projection` - is confident, wrong AND under every
+    ceiling there is.
+    """
+    if frozen:
+        return BLIND_FROZEN
+    if projection.block_start is None:
+        return BLIND_NO_BLOCK
+    gap = uncovered_s(projection)
+    if max_hold_s is not None and gap > float(max_hold_s):
+        return (f"{BLIND_COVERAGE}: {gap:.0f} s of this quarter uncovered, past "
+                f"the {float(max_hold_s):.0f} s the averager will hold a sample")
+    return None
+
+
+def decide(projection, *, batt_w, cap_w, reading, achievable_w,
+           max_hold_s=None, frozen: bool = False) -> PeakDecision:
+    """The whole guard. Pure: no clock, no I/O, no state carried between calls.
+
+    `batt_w`       MEASURED battery power, positive = discharge. None when the
+                   sensor for it is missing - and then there is nothing to size a
+                   floor from, so no floor is invented.
+    `achievable_w` the largest discharge the arbiter could actually grant
+                   (`min(max_w, device max)`). The floor is clamped to it so this
+                   claim can NEVER produce `lo > hi` in the resolver - a
+                   contradiction there resolves to 0 W, which would park the
+                   battery in the exact minute it should be discharging hardest.
+    """
+    ceiling, from_where = quarter_ceiling_w(cap_w, reading)
+    ceil_top = abs(float(achievable_w))
+
+    blind = blindness(projection, max_hold_s, frozen)
+    if blind is not None:
+        # 0.0, not a sized floor. There is no trustworthy measurement to size one
+        # from; the claim that remains is "do not add to the offtake you cannot
+        # see", which is one-directional and cannot cost pack energy.
+        return PeakDecision(
+            engaged=True, floor_w=0.0, ceiling_w=ceiling, ceiling_from=from_where,
+            blind=blind, projected_w=None,
+            reason=(f"PEAK GUARD BLIND ({blind}) - the battery may not import "
+                    f"while the billed quarter cannot be measured; commanding no "
+                    f"charging (floor 0 W)"))
+
+    projected = float(projection.projected_w)
+    if batt_w is None:
+        # main.py's P_SAFETY stop already owns a cycle with a missing input, at
+        # 0 W. Filing nothing is the honest answer: a floor sized from a
+        # measurement that is not there is a made-up number.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected,
+            reason="no battery measurement to size a floor from")
+    if QUARTER_S - float(projection.elapsed_s) <= 0.0:
+        # A block with no seconds left cannot be influenced. This is degenerate
+        # rather than urgent - `excess_w` answers 0.0 there and a floor equal to
+        # the battery's own current output would be a claim that says nothing.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected,
+            reason="the quarter has no seconds left to influence")
+
+    ex = excess_w(projection, ceiling)
+    wanted = float(batt_w) + ex
+    if wanted <= 0.0:
+        # ⚠️ THE TEST IS ON THE FLOOR, NOT ON `excess > 0`, AND THE REPLAY IS WHY.
+        # `excess` is the watts that must come off the METER, so it goes to zero
+        # as soon as the battery is already removing them - and a guard that
+        # disengaged there handed the actuator straight back, the offtake sprang
+        # back to the raw load, and the next cycle engaged again. On 2026-08-20's
+        # billed quarter that bang-bang cycled 17 times in 900 s and left the
+        # quarter 49 W over the limit it had just spent a quarter of an hour
+        # holding. §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."
+        #
+        # `batt_w + excess` is the offtake that would exist with the battery at
+        # zero, minus the level the quarter can afford. Testing THAT is the same
+        # arithmetic read as a level rather than as a switch: the claim is filed
+        # for as long as a positive floor is needed and decays continuously to
+        # nothing as the load falls, so there is still no hysteresis constant -
+        # the quantity being thresholded is simply the right one.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            wanted_w=wanted,
+            reason="the load is under the level this quarter can afford")
+
+    floor = min(wanted, ceil_top)
+    saturated = floor < wanted
+    return PeakDecision(
+        engaged=True, floor_w=floor, ceiling_w=ceiling, ceiling_from=from_where,
+        blind=None, projected_w=projected, excess_w=ex, wanted_w=wanted,
+        saturated=saturated,
+        reason=(
+            f"PEAK GUARD: quarter projects {projected:.0f} W against a "
+            f"{ceiling:.0f} W ceiling ({from_where}) with "
+            f"{QUARTER_S - projection.elapsed_s:.0f} s left, so {ex:.0f} W must "
+            f"come off the meter; battery measured {float(batt_w):+.0f} W, "
+            f"floor {floor:+.0f} W"
+            + (f" - SATURATED, {wanted:+.0f} W was needed and the inverter can "
+               f"only give {ceil_top:.0f} W" if saturated else "")))
+
+
+def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
+    """Must the maintenance charge-only shaping stand down this cycle?
+
+    THE ONE PLACE THIS CONJUNCTION IS WRITTEN, and it is public for the reason
+    `watchdog.loop_is_following()` and `freeze.looks_frozen()` are: the check
+    that grades it has to assert on THE SHIPPED EXPRESSION. A safety predicate
+    transcribed into its own test is one copy plus a future disagreement about
+    what the check means, and the copy that drifts is always the grading one.
+    It was inline in `main.py` and nothing could reach it; a reviewer mutated it
+    back to its historical broken form and all twelve suites stayed green.
+
+    ⚠️ WHY SUPPRESSION AND NOT PRIORITY. The shaping is a LIMIT (`hi <= 0`) and
+    the peak guard's claim is a LIMIT (`lo >= 0`). 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 outranking another - which is precisely what
+    makes the safety bounds unconditional and must not be changed. Two crossing
+    limits are therefore a CONTRADICTION, which resolves to 0 W: the battery
+    PARKED, in the one quarter of the month that sets the bill. P_PEAK 50 >
+    P_MAINT_SHAPE 40 does not save it and never could.
+
+    ⚠️ AND THE FIRST TERM IS NOT ENOUGH ON ITS OWN. `peak_forecast_entity` is
+    OPTIONAL and is empty on a default install, so `peak_forecast_w` is None
+    there and `peak_at_risk()` answers False forever. Before this card the
+    suspension therefore could not fire on the very site that needed it. The
+    second term is the MEASURED guard, which is always present wherever P1 is.
+    Deleting either term - or re-gating the whole thing on the forecast - parks
+    a default install at 0 W, silently, in the billed quarter. test_peakguard.py
+    part 7 drives the real cycle with each of those mutations in place.
+    """
+    if peak_at_risk(peak_forecast_w, float(cap_w)):
+        return True
+    return decision is not None and decision.engaged
+
+
+def claim(decision: PeakDecision) -> Claim | None:
+    """The decision as one arbiter claim, or None when the guard is idle.
+
+    A LIMIT with only `lo` set. `hi` stays `+inf`, which is 9.1's "discharge and
+    export are never capped by the peak guard" expressed as a fact about the
+    object rather than as a rule somebody has to remember.
+    """
+    if not decision.engaged or decision.floor_w is None:
+        return None
+    return Claim.limit(SOURCE, P_PEAK, lo=float(decision.floor_w),
+                       reason=("blind" if decision.blind else "quarter peak"))

goodwe_controller/app/price_forecast.py

@@ -0,0 +1,465 @@
+"""FCST-03 - the hours the feed has not published yet, and what may not rest on them.
+
+WHERE THIS LIVES. specs.md §2.2 puts price ingest under `ems/ingest/prices/`.
+That layout does not exist and is not being built; the product owner's decision
+of 2026-08-30 is that everything ships in `goodwe_controller/app/`. The
+BEHAVIOUR §8.3 describes is unchanged and still authoritative - only the path
+moved. Read `ems/...` as `app/...`.
+
+§8.3, in full, because every line below is one clause of it:
+
+    "Day-ahead prices arrive once daily. Until they do, unknown hours use
+     yesterday's profile and are flagged `provisional: true` - and NO
+     IRREVERSIBLE ACTION MAY BE TAKEN ON A PROVISIONAL PRICE. Real-time /
+     imbalance products are treated as high-volatility: arbitrage thresholds
+     widen."
+
+Three separate things, and this module owns the first two. The third - the
+widening arithmetic - lives in price.py beside the product enum it is derived
+from (`Uncertainty`, `widen_factor`, `required_spread`), and is spent by
+`static_tariff.TariffPlan.arbitrage()`, because that is where the verdict this
+repo already refuses to hand out casually is produced. FCST-03 added a refusal
+to that existing ladder rather than a second mechanism beside it.
+
+
+THE DEFECT THIS MODULE IS SHAPED BY: A COPY THAT KEEPS THE WRONG FLAG
+=====================================================================
+A point filled from yesterday and a point published this morning are the SAME
+SHAPE. Three floats and a bool; only the bool tells them apart. And the natural
+way to write a carry-forward fill is:
+
+    PricePoint(start=t, eur_per_kwh=y.eur_per_kwh, provisional=y.provisional)
+                                                                ^^^^^^^^^^^^^
+
+which copies yesterday's `False` onto today's guess and produces exactly the
+thing the ticket exists to prevent: STALE DATA PRESENTED AS CURRENT. It reads
+fine, it type-checks, it round-trips through §9.3's JSON, and every price on
+the status page looks like a price. This is the meter-side SAFETY-18 defect one
+layer up: the reading arrives on time, looks fresh, and is wrong - and a
+freshness check that only asks "did something arrive" cannot see it.
+
+So the flag is not passed through anywhere in this file:
+
+  * A CARRIED POINT IS BUILT BY `_carried()`, WHICH HAS NO PARAMETER FOR THE
+    FLAG. `provisional=True` is a literal in one place. There is no argument a
+    caller can pass, no keyword to forget, and no variable that could hold
+    yesterday's value at the moment the point is constructed.
+  * A PUBLISHED POINT IS NEVER COPIED AT ALL. It is passed through BY IDENTITY -
+    the object the provider produced is the object in the output series - so
+    there is no copy that could lose or gain a flag. `filled.points[i] is
+    fetched.points[j]` is a checkable property, and test_price_forecast.py
+    checks it.
+  * `_audit()` RE-DERIVES the expected flag for every output point from the set
+    of hours the feed actually published, and RAISES if any point disagrees.
+    It is a post-condition, not a filter: it never fixes a flag, because a
+    module that quietly corrects its own provenance is one whose provenance
+    cannot be trusted.
+  * and test_price_forecast.py walks THIS FILE'S AST and fails if any
+    `PricePoint(...)` in it passes anything but a literal for `provisional`, so
+    the pass-through idiom cannot come back in a later edit and pass review by
+    looking ordinary.
+
+⚠️ "PUBLISHED" DOES NOT MEAN "FIRM". `eneco_eddy` is an imbalance product whose
+current-quarter print is genuinely provisional and says so per point (§9.2,
+TARIFF-02). Such a point is published AND provisional, and the audit's rule for
+a published point is "the flag is whatever the feed said", never "False". A
+provenance check that forced published points to False would be a bug that
+looks like a guarantee.
+
+
+THE FILL, AND WHY IT KEYS ON THE WALL CLOCK
+===========================================
+For every whole hour in the requested horizon that the feed has not published,
+take yesterday's value for THE SAME BRUSSELS WALL-CLOCK HOUR - not `t - 86400
+s`. On the two days a year that matter those are different instants, and the
+difference is not academic: a 23-hour day has no 02:00 at all and a 25-hour day
+has two, so a fill that subtracts a fixed 24 h shifts every carried hour by one
+across a transition and misprices the whole day in a way nothing reports.
+
+On the 25-hour day the two 02:00 hours - `02:00+02:00` and `02:00+01:00` - both
+key to local hour 2 and are BOTH filled from yesterday's single 02:00 value.
+That is deliberate: they are both guesses, they are both flagged, and nothing
+irreversible may rest on either. If yesterday itself was a 25-hour day, the
+first of its two 02:00 points is the one used, deterministically.
+
+An hour with no published price AND no yesterday value is LEFT OUT of the
+series. It is not filled with a neighbour, a mean, or a zero. §11.4 applies to
+that hour - `_Series.at()` raises `Absence` for it - and the caller that wanted
+a tariff for the whole horizon falls back to the static profile (TARIFF-03),
+which is the row the spec actually writes for "no price data". If NOTHING can
+be produced, the result is `PriceRead.no_data(reason)` and not an empty series,
+because an empty series is not constructible on purpose (price.py trap 3).
+
+
+AC2: THE IRREVERSIBLE-ACTION GATE
+=================================
+"The distinction should be an explicit property of the action, not a judgement
+call at each call site" - so an irreversible action is a value, `Irreversible`,
+carrying the number of hours it COMMITS. `price_permits()` looks at exactly
+those hours and answers with a `Gate` variant that carries the evidence on the
+permitting arm and a reason on the blocking one, the `_Outcome` shape price.py
+borrowed from `sim/riglock.py`.
+
+The shipped example is the maintenance drain (§12): starting one commits hours
+of forced discharge that cannot be undone if the price turns out to have been
+yesterday's. Its commitment window is DERIVED from `maintenance.DRAIN_TIMEOUT_MIN`
+rather than typed here, so the gate and the phase machine cannot drift apart.
+
+⚠️ WHAT DOES NOT GO THROUGH THIS GATE, AND WHY THAT MATTERS MORE THAN WHAT
+DOES. The maintenance cycle is a CALENDAR obligation (§12.2: a cycle that
+silently never fires is indistinguishable from one that is not due yet), and a
+site with `price_provider: off` - the shipped default - has no price series at
+all. Routing every maintenance start through a gate that blocks on `no_data`
+would stop the monthly cycle on every default install, permanently and
+silently: the exact failure §12 opens by naming. So `begin_phase()` is the
+entry point for a start that is being JUSTIFIED BY A PRICE, main.py's existing
+calendar path is untouched by this ticket, and OPT-04/MAINT-05 own the decision
+of which one a site runs. Nothing here disables anything that runs today.
+
+Reversible actions - ordinary self-consumption modulation, the loop that
+actually holds the grid at zero - are not gated at all and cannot be: §6 says
+absent machinery must not disable the loop.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+
+from .maintenance import CHARGE_TIMEOUT_MIN, DRAIN_TIMEOUT_MIN
+from .price import PricePoint, PriceRead, _Outcome, brussels
+
+_LOG = logging.getLogger("goodwe.price.forecast")
+
+
+class Provenance(Enum):
+    """Where a point in a filled series came from. INTERNAL - §9.3's wire format
+    carries the boolean and nothing else, so this never leaves the module.
+
+    It exists so `_audit()` has a vocabulary to state its post-condition in, and
+    so the two cases have names in the log rather than being "the ones with the
+    flag" and "the others".
+    """
+    PUBLISHED = "published"    # the provider printed this hour. Flag: the
+                               # feed's own - an imbalance print may be
+                               # published AND provisional (§9.2).
+    CARRIED = "carried"        # yesterday's same-wall-clock hour (§8.3).
+                               # Flag: ALWAYS True, by construction.
+
+
+# --------------------------------------------------------------------------- #
+# The fill
+# --------------------------------------------------------------------------- #
+
+def _utc_hour(instant: datetime) -> datetime:
+    u = instant.astimezone(timezone.utc)
+    return u.replace(minute=0, second=0, microsecond=0)
+
+
+def _carried(start_utc: datetime, eur_per_kwh: float) -> PricePoint:
+    """A point filled from yesterday's profile. §8.3: ALWAYS provisional.
+
+    ⚠️ THERE IS NO `provisional` PARAMETER, AND THAT IS THE MECHANISM. This is
+    the only constructor of a carried point, the flag is a literal, and no
+    caller - including a future one editing in a hurry - has anything to pass,
+    default, or copy from the point being carried.
+    """
+    return PricePoint(start=brussels(start_utc),
+                      eur_per_kwh=round(float(eur_per_kwh), 6),
+                      provisional=True)
+
+
+def _audit(points, published) -> None:
+    """Post-condition: every flag matches the point's TRUE provenance (AC1).
+
+    `published` maps a UTC hour to the point the provider produced for it.
+
+    ⚠️ RAISES, NEVER REPAIRS. A module that silently corrects its own
+    provenance is one whose provenance means nothing; the only safe response to
+    "this point's flag disagrees with where it came from" is to refuse to emit
+    the series at all.
+    """
+    seen = set()
+    for p in points:
+        u = _utc_hour(p.start)
+        if u in seen:
+            raise ValueError(f"the filled series repeats {u.isoformat()}; a "
+                             f"duplicated hour is how a DST day gets mispriced")
+        seen.add(u)
+        src = published.get(u)
+        prov = Provenance.CARRIED if src is None else Provenance.PUBLISHED
+        if src is None:
+            if p.provisional is not True:
+                raise ValueError(
+                    f"{u.isoformat()} is {prov.value} and is flagged "
+                    f"provisional={p.provisional!r}. §8.3: an hour filled from "
+                    f"yesterday's profile is provisional whether or not the "
+                    f"number turns out to be right - the flag is a claim about "
+                    f"PROVENANCE, not about accuracy.")
+        else:
+            if p is not src:
+                raise ValueError(
+                    f"{u.isoformat()} is {prov.value} but the series carries a "
+                    f"COPY of that point rather than the point itself. A copy "
+                    f"is where the provisional flag gets lost; published points "
+                    f"pass through by identity.")
+
+
+def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
+                        since: datetime, until: datetime,
+                        stamp: datetime) -> PriceRead:
+    """§8.3: fill the hours the feed has not published with yesterday's profile.
+
+    Every argument is required and keyword-only past the first. In particular
+    `yesterday` has NO DEFAULT: a fill with no yesterday to fill from is a
+    different situation from a fill that found nothing useful in one, and a
+    default `None` would make the two arrive looking identical.
+
+    Returns a `PriceRead`:
+
+      * a series, whose points are the provider's own objects for the hours it
+        published and `_carried()` points for the rest, ordered by instant;
+      * `no_data` when neither source can produce a single hour - never an
+        empty series, which is not constructible (price.py trap 3).
+
+    ⚠️ IDEMPOTENT AND RE-RUNNABLE, WHICH IS THE §5.4 LATE-PUBLICATION CONTRACT.
+    Day-ahead publication at 14-16 h CET can be late or fail, so the fetcher
+    retries and this runs again against the fresher read. Published hours always
+    win over carried ones, so a re-run REPLACES a carried point with the real
+    print and the hour becomes firm - the flag and the number move together
+    because the whole series is rebuilt rather than patched in place.
+    """
+    for name, value in (("since", since), ("until", until), ("stamp", stamp)):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError(f"{name} must be tz-aware; a naive instant is "
+                             f"ambiguous for one hour every October")
+
+    published = read.match(
+        series=lambda r: {_utc_hour(p.start): p for p in r.points},
+        no_data=lambda _r: {})
+
+    # Yesterday's profile, keyed by BRUSSELS WALL-CLOCK HOUR. First point wins
+    # when yesterday itself was a 25-hour day and printed local hour 2 twice.
+    by_local_hour = {}
+    yesterday.match(
+        series=lambda r: [by_local_hour.setdefault(brussels(p.start).hour, p)
+                          for p in r.points],
+        no_data=lambda _r: [])
+
+    out = []
+    u = _utc_hour(since)
+    end = until.astimezone(timezone.utc)
+    while u < end:
+        if u in published:
+            out.append(published[u])                    # BY IDENTITY. No copy.
+        else:
+            src = by_local_hour.get(brussels(u).hour)
+            if src is not None:
+                out.append(_carried(u, src.eur_per_kwh))
+        u += timedelta(hours=1)
+
+    if not out:
+        reason = read.match(
+            series=lambda r: (f"the {len(r.points)} published hours all fall "
+                              f"outside {since.isoformat()}..{until.isoformat()}"),
+            no_data=lambda r: r.reason)
+        return PriceRead.no_data(
+            f"§8.3 carry-forward produced no hours: {reason}, and yesterday's "
+            f"profile has nothing to fill them with either. §11.4 applies: "
+            f"static profile, plan provisional, no arbitrage")
+
+    _audit(out, published)
+    carried = sum(1 for p in out if _utc_hour(p.start) not in published)
+    if carried:
+        _LOG.info("§8.3: %d of %d hours carried forward from yesterday's "
+                  "profile and flagged provisional; %d published",
+                  carried, len(out), len(out) - carried)
+
+    product = read.match(series=lambda r: r.product,
+                         no_data=lambda _r: yesterday.product)
+    provider = read.match(series=lambda r: r.provider,
+                          no_data=lambda r: yesterday.provider)
+    return PriceRead.series(out, product, provider, stamp)
+
+
+# --------------------------------------------------------------------------- #
+# AC2: irreversibility as a property of the ACTION, and the gate that reads it
+# --------------------------------------------------------------------------- #
+
+@dataclass(frozen=True)
+class Irreversible:
+    """An action that cannot be undone once started, and how far it commits.
+
+    `commits_h` is the horizon the action ties up - the hours whose prices must
+    therefore be firm before it may be justified by a price at all.
+    """
+
+    name: str            # the §10.2 reason code
+    commits_h: float
+
+    def __post_init__(self):
+        if not self.name or not isinstance(self.name, str):
+            raise ValueError("an irreversible action needs a reason code (§10.2)")
+        if isinstance(self.commits_h, bool) or \
+                not isinstance(self.commits_h, (int, float)) or \
+                not self.commits_h > 0:
+            raise ValueError(
+                f"commits_h must be a positive number of hours, not "
+                f"{self.commits_h!r}. An action that commits nothing is a "
+                f"reversible one and does not belong here.")
+
+
+# ⚠️ DERIVED FROM THE PHASE MACHINE'S OWN BOUNDS, NOT TYPED HERE. maintenance.py
+# already states how long each phase may run before it is a fault; a second copy
+# of those numbers here would be a place for them to drift apart, and the drift
+# would show up as a gate that checked the wrong hours.
+MAINTENANCE_DRAIN = Irreversible("MAINTENANCE_DRAIN", DRAIN_TIMEOUT_MIN / 60.0)
+MAINTENANCE_CHARGE = Irreversible("MAINTENANCE_CHARGE", CHARGE_TIMEOUT_MIN / 60.0)
+
+
+class Gate(_Outcome):
+    """May an irreversible action proceed on the price evidence available?
+
+      * `permitted` - carries `.action` and `.hours`, the firm points that were
+                      actually checked. The evidence exists only on this arm.
+      * `blocked`   - carries `.reason`. Nothing else; `.hours` raises `Absence`.
+
+    No `__bool__`, both `match()` arms required and keyword-only, for the reason
+    price.py's `_Outcome` gives: `if gate:` must not look like a guard while
+    being none.
+    """
+
+    def match(self, *, permitted, blocked):
+        return {"permitted": permitted, "blocked": blocked}[self.kind](self)
+
+    @staticmethod
+    def permit(action, hours):
+        return _Permitted(action, hours)
+
+    @staticmethod
+    def block(reason):
+        if not reason or not isinstance(reason, str):
+            raise ValueError(
+                "Gate.block() takes a reason a human can act on. §6 requires "
+                "every decision to explain itself, and 'the maintenance cycle "
+                "did not start' with no reason is indistinguishable from a bug.")
+        return _Blocked(reason)
+
+
+class _Permitted(Gate):
+    kind = "permitted"
+
+    def __init__(self, action, hours):
+        if not isinstance(action, Irreversible):
+            raise TypeError(f"action must be an Irreversible, not {action!r}")
+        pts = tuple(hours)
+        if not pts:
+            raise ValueError(
+                "a permission granted over ZERO checked hours is a permission "
+                "granted on no evidence - the shape this whole file exists to "
+                "refuse. Block instead.")
+        if any(p.provisional for p in pts):
+            raise ValueError(
+                "a permitted gate cannot carry a provisional hour: §8.3 is the "
+                "one rule this type has.")
+        self.action = action
+        self.hours = pts
+        self.words = (f"{action.name} permitted on {len(pts)} firm hours "
+                      f"({pts[0].start.isoformat()} ..)")
+
+
+class _Blocked(Gate):
+    kind = "blocked"
+
+    def __init__(self, reason):
+        self.reason = reason
+        self.words = f"blocked - {reason}"
+
+
+def committed_hours(now: datetime, action: Irreversible) -> tuple:
+    """The whole hours `action` started at `now` would run through.
+
+    Split out because the gate and its caller must agree on what "the hours it
+    commits" means, and because a window that quietly excluded the last hour
+    would be a gate that permits an action on an hour it never looked at.
+    """
+    if not isinstance(action, Irreversible):
+        raise TypeError(f"action must be an Irreversible, not {action!r}")
+    if now.tzinfo is None or now.utcoffset() is None:
+        raise ValueError("now must be tz-aware")
+    out = []
+    u = _utc_hour(now)
+    end = now.astimezone(timezone.utc) + timedelta(hours=action.commits_h)
+    while u < end:
+        out.append(u)
+        u += timedelta(hours=1)
+    return tuple(out)
+
+
+def price_permits(read: PriceRead, now: datetime,
+                  action: Irreversible) -> Gate:
+    """§8.3's rule, as a value: may this irreversible action rest on this price?
+
+    Blocks when the read observed nothing (§11.4 - an action justified by a
+    price nobody has is an action justified by nothing), when any hour it
+    commits has no price at all, and when any of those hours is provisional.
+    Names the offending hour, so an operator reading the log knows which one.
+    """
+    hours = committed_hours(now, action)
+    return read.match(
+        series=lambda r: _walk(r, hours, action),
+        no_data=lambda r: Gate.block(
+            f"{action.name} is gated on a price and there is no price data: "
+            f"{r.reason}. §11.4 - and a missing price is not a cheap one"))
+
+
+def _walk(series, hours, action) -> Gate:
+    pts = []
+    for u in hours:
+        if not series.covers(u):
+            return Gate.block(
+                f"{action.name} commits {action.commits_h:g} h from "
+                f"{hours[0].isoformat()} and no price covers "
+                f"{u.isoformat()}. An hour outside the series is an hour with "
+                f"no price (§11.4 for that hour), not a free one")
+        p = series.at(u)
+        if p.provisional:
+            return Gate.block(
+                f"{action.name} commits {action.commits_h:g} h from "
+                f"{hours[0].isoformat()} and {u.isoformat()} is PROVISIONAL - "
+                f"carried from yesterday's profile or standing in for a dead "
+                f"feed. §8.3: no irreversible action may be taken on a "
+                f"provisional price. It becomes available when the day-ahead "
+                f"print lands (~14-16 h CET, §5.4)")
+        pts.append(p)
+    return Gate.permit(action, pts)
+
+
+def begin_phase(maint, now: datetime, read: PriceRead,
+                action: Irreversible) -> Gate:
+    """Start a maintenance phase BECAUSE OF A PRICE, or refuse and say why.
+
+    The AC2 example made real: `maint.force_start(now)` - the call that moves
+    the phase machine out of `idle` and commits the pack to hours of forced
+    discharge - happens on the permitting arm and cannot happen on the other
+    one, because the blocking arm has no code path to it.
+
+    ⚠️ READ THE MODULE DOCSTRING'S LAST WARNING BEFORE WIRING THIS IN. This is
+    the price-justified entry point, not the calendar one; a site with no price
+    provider must keep starting its monthly cycle the way it does today, or
+    §12's opening sentence comes true - a cycle that silently never fires.
+    """
+    gate = price_permits(read, now, action)
+    return gate.match(permitted=lambda g: _go(maint, now, g),
+                      blocked=lambda g: _no(g))
+
+
+def _go(maint, now, gate) -> Gate:
+    maint.force_start(now)
+    _LOG.info("%s: %s", gate.action.name, gate.words)
+    return gate
+
+
+def _no(gate) -> Gate:
+    _LOG.warning("irreversible action refused - %s", gate.reason)
+    return gate

goodwe_controller/app/store.py

@@ -22,11 +22,30 @@ _LOG = logging.getLogger("goodwe.store")
 # `auto_start` option only when the key is absent - if a default supplied False,
 # the fallback could never fire and auto_start would silently do nothing on
 # every fresh install.
+#
+# ⚠️ `sign_tripped` IS in here, and the difference from `auto` is the whole
+# reason both decisions are written down. `auto` has an option to fall back to
+# (`auto_start`), so a stored default would mask a fresh install. A latched
+# failsafe has no such fallback: absent means "never tripped", which is exactly
+# what a default of False says.
+#
+# It is persisted for the reason this module's docstring gives for maintenance
+# state, applied to something with a much shorter fuse. SAFETY-02's latch is the
+# only thing standing between a controller that has been caught driving the wrong
+# way and its own restart, and "restart the add-on" is the FIRST thing an operator
+# looking at a FAILSAFE banner will try. Held only in memory it came back armed,
+# into the fault, unattended - measured: after reconstructing Controller against
+# the same store, `tripped` was False, the banner read NOT READY, and it resumed
+# commanding -1000, -2000 W before re-tripping 180 s later. Under a supervisor
+# that restarts a crashed add-on that is a loop, three minutes of wrong-direction
+# power at a time, forever.
 DEFAULTS = {
     "phase": "idle",
     "phase_started": None,
     "last_completed": None,
     "last_start_attempt": None,
+    "sign_tripped": False,
+    "sign_reason": "",
 }
 
 
@@ -42,8 +61,10 @@ class Store:
                 loaded = json.load(fh)
             if isinstance(loaded, dict):
                 self.data = {**DEFAULTS, **loaded}
-                _LOG.info("state restored: phase=%s last_completed=%s",
-                          self.data.get("phase"), self.data.get("last_completed"))
+                _LOG.info("state restored: phase=%s last_completed=%s "
+                          "sign_tripped=%s",
+                          self.data.get("phase"), self.data.get("last_completed"),
+                          self.data.get("sign_tripped"))
         except FileNotFoundError:
             _LOG.info("no saved state, starting fresh")
         except (json.JSONDecodeError, OSError) as err:

goodwe_controller/app/tariff.py

@@ -0,0 +1,702 @@
+"""TARIFF-01 - the monthly capacity-tariff peak, and the record that outlives it.
+
+WHAT THIS IS, AND WHAT IT DELIBERATELY IS NOT. This module is an INSTRUMENT. It
+measures the number the Belgian capaciteitstarief bills on - the highest
+15-minute average offtake of the calendar month (Fluvius / Resa / Ores) - and it
+writes that number down somewhere a restart cannot reach. It makes no claim,
+applies no clamp, and commands nothing. The guard that will read it is SAFETY-07,
+and it belongs in `arbiter.py` as a `P_PEAK` claim when it is built. Keeping the
+measurement and the actuation apart is the whole reason this file is small.
+
+WHAT WAS ALREADY BUILT, AND WHY THIS CARD IS NOT 8 SP OF NEW ARITHMETIC.
+`p1.QuarterAverager` already computes AC 1 in full: clock-aligned 900 s blocks,
+time-weighted over irregular telegram spacing, offtake-only, per-phase, with a
+`max_hold_s` gap rule. It was unwired and unpersisted - `P1Ingest.blocks` is a
+96-entry list in memory that a restart erases. So this file is the persistence
+and the monthly reduction, not a second accumulator. Adding one would be adding
+a second source of truth for the exact quantity the money depends on.
+
+  BLOCKS, NOT A SLIDING WINDOW.  The Description says "rolling"; AC 1 says
+  "15-min block average". They are different numbers and the utility bills the
+  second one. §9.1 calls the billed unit the "highest 15-minute average offtake",
+  and §9.1's own worked case - "one 4998 W quarter moved a monthly peak from
+  4832 -> 5013 W" - is stated per QUARTER, an object a sliding window does not
+  have. "Rolling" here means CONTINUOUSLY UPDATED (the open block's partial
+  average is readable at every sample), not a trailing-15-minutes window. A
+  trailing window would report a peak the meter never bills, and it reports it
+  HIGHER than the real one: a load burst straddling :15 fills a trailing window
+  completely while contributing to two block averages at partial weight. Guarding
+  that would spend battery defending an interval nobody charges for.
+
+  DELIVERED POWER, NOT INTENDED POWER.  SAFETY-20 has an open question about
+  whether guards should grade `Decision.target` (pre-clamp intent) or `standing`
+  (what actually reached the wire). For a capacity tariff there is no question to
+  ask: the utility's meter integrates the current that flowed. This module never
+  sees a setpoint at all - it consumes `P1Sample`, which is the meter's own
+  reading - and that is on purpose. A peak computed from intent would be wrong in
+  the expensive direction (a clamped 9 kW request that delivered 5 kW would
+  record 9 kW, and every consumer would shave against a peak that never existed).
+
+  AN UNREADABLE STORE IS NOT A ZERO PEAK.  This is the defect this repo spent a
+  day removing from `sim/riglock.py`, where `holder()` was rewritten to answer
+  `observed / not_observed / gone` instead of a partial dict every caller
+  `.get()`s a default out of. The same trap is here and it is worse, because the
+  degenerate value is not merely wrong, it is DISARMING: a peak read as 0 W gives
+  SAFETY-07 the maximum possible headroom and silently switches the guard off at
+  the moment its own storage is broken. So `peak()` returns a `PeakReading` whose
+  `state` is one of OBSERVED / NO_RECORD / NOT_OBSERVED, `peak_w` is `None`
+  unless the state is OBSERVED, and there is no `.get(..., 0)` shaped accessor
+  anywhere on it. NO_RECORD ("this month has no completed block yet", a normal
+  state on the 1st) and NOT_OBSERVED ("the database did not answer") are
+  different types of thing and are never spelled the same way.
+
+CONFIG: NONE ADDED, ON PURPOSE.  CFG-03 is open because the option defaults
+already live in three places held apart by a tripwire in `test_validate.py`. The
+soft limit this measurement is graded against already exists as `peak_cap_w`
+(config.yaml, default 3500), already validated, already read by
+`control.peak_at_risk()`. §14 names a `tariffs.capacity_peak_limit_kw: 2.5` - in
+KILOwatts, against watts everywhere else - and adding it would have made a fourth
+defaults site AND imported the unit mismatch §14's own warning box says must be
+caught at startup. So this module takes its limit as a plain constructor
+argument in WATTS and config.yaml is untouched by this ticket.
+
+THE DATABASE. SQLite in /data, the add-on's only durable volume, alongside
+`store.py`'s state.json. Two tiers from §15, and their retention is the point:
+
+  quarter_blocks   one row per completed 900 s block   INDEFINITE
+  monthly_peak     one row per calendar month          PERMANENT
+
+Neither is ever pruned here, and no sweep in this file can prune them - there is
+no DELETE statement against either table anywhere in this module. §15's asymmetry
+is why: raw samples vanish after 7 days, so a 15-minute aggregate that was not
+written AS IT HAPPENED can never be recomputed. `monthly_peak` is maintained as a
+derived record - upserted on every block close, and `recompute_month()` re-derives
+it from `quarter_blocks` so the two can be PROVEN not to have diverged rather
+than assumed not to have.
+
+RESTART MID-BLOCK. The open block's accumulator is memory. A restart at minute 12
+that dropped it would under-read the rest of the quarter, and SAFETY-07's clamp
+would release exactly when it was most needed. So the accumulator is checkpointed
+(`QuarterAverager.snapshot()`) into a single row, at most `CHECKPOINT_S` stale,
+and restored on startup. Three cases, all of them exercised in `test_tariff.py`:
+
+  * the checkpoint's block is the block containing `now`  -> restore it verbatim,
+    including the held sample's ORIGINAL timestamp, so the first sample after the
+    restart integrates the gap under the same `max_hold_s` rule a running process
+    would have applied. A restart longer than `max_hold_s` therefore leaves
+    uncovered seconds, and a closed block is always divided by the full 900 s, so
+    the gap DRAGS THE BILLED AVERAGE DOWN instead of being averaged away;
+  * the checkpoint's block ended while we were down -> that block really happened
+    and its measured part is real, so it is closed at `acc / 900` and recorded,
+    then a fresh block is opened. Discarding it would lose measured energy;
+  * no checkpoint, or one that cannot be read -> start clean and SAY SO. The
+    return value of `restore()` names which of the three happened; it is never
+    silently the first one.
+
+Double counting is answered structurally rather than by care: `quarter_start` is
+the PRIMARY KEY, and the recorded average may only ever be RAISED by a later
+write (`ON CONFLICT ... WHERE excluded.offtake_avg_w > ...`). Replaying the same
+block twice is therefore a no-op, and a restart that reprocesses a block with
+LESS coverage than the first pass cannot lower a figure already banked.
+
+MONTH BOUNDARY. Calendar months are LOCAL (Europe/Brussels); blocks are stored in
+UTC. In August those differ by two hours, so a block starting 2026-08-31 22:15
+UTC belongs to SEPTEMBER and putting it in August would move a month's bill.
+Block alignment itself needs no timezone - every Belgian offset is a whole number
+of hours, so the 900 s UTC grid lands on :00/:15/:30/:45 local on both sides of a
+DST transition, which is the argument `QuarterAverager` already carries.
+"""
+
+import json
+import logging
+import os
+import sqlite3
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone, tzinfo
+
+_LOG = logging.getLogger("goodwe.tariff")
+
+QUARTER_S = 900
+
+# How stale the partial-block checkpoint may be. This is the ONLY thing a crash
+# can lose from an open block, and the loss is bounded and one-directional: the
+# lost seconds were already integrated into `_acc`, so dropping them makes the
+# restored block read LOW, never high. At 15 s against a 900 s block the
+# worst-case under-read of one quarter's average is 15/900 = 1.7 % of that
+# quarter's own offtake - see test_tariff.py, which computes that bound from
+# these two constants rather than quoting it.
+CHECKPOINT_S = 15.0
+
+# -- reading states. Three, and never fewer. -------------------------------- #
+OBSERVED = "observed"          # the store answered and there is a peak
+NO_RECORD = "no_record"        # the store answered and this month has none yet
+NOT_OBSERVED = "not_observed"  # the store did not answer. NOT a zero peak.
+
+
+# --------------------------------------------------------------------------- #
+# local time, without a hard dependency on the tz database
+# --------------------------------------------------------------------------- #
+class _EUTimezone(tzinfo):
+    """Europe/Brussels by the EU harmonised rule, for hosts with no tzdata.
+
+    ⚠️ THIS IS A FALLBACK AND IT IS NOT SILENT. `zoneinfo` is tried first and is
+    what runs on the add-on's container. The fallback exists because the
+    alternative - quietly using UTC when tzdata is missing - misfiles every block
+    in the last two hours of a month into the wrong month's bill, and does it
+    without a symptom. Encoding the rule (CET, CEST from 01:00 UTC on the last
+    Sunday of March to 01:00 UTC on the last Sunday of October) is 20 lines and
+    is checked against zoneinfo, date by date, wherever zoneinfo is available.
+    """
+
+    # The rule, in both frames. `fromutc` is overridden rather than inherited
+    # because the base implementation calls back into `utcoffset` with a
+    # datetime whose tzinfo is self - and the first version of this class
+    # answered that by calling `astimezone`, which calls `utcoffset`, which
+    # recursed until the stack ran out. A tzinfo must answer from the value it
+    # is handed, never by converting it.
+    @staticmethod
+    def _last_sunday(year: int, month: int, hour: int) -> datetime:
+        d = datetime(year, month + 1, 1) - timedelta(days=1)
+        return (d - timedelta(days=(d.weekday() + 1) % 7)).replace(hour=hour)
+
+    def _dst_local(self, naive: datetime) -> bool:
+        """From a LOCAL wall clock: 02:00 CET last Sunday March -> 03:00 CEST
+        last Sunday October. The one ambiguous hour each autumn resolves to
+        standard time, which cannot move a month boundary."""
+        y = naive.year
+        return self._last_sunday(y, 3, 2) <= naive < self._last_sunday(y, 10, 3)
+
+    def _dst_utc(self, naive_utc: datetime) -> bool:
+        """From UTC: both EU transitions happen at 01:00 UTC, everywhere."""
+        y = naive_utc.year
+        return self._last_sunday(y, 3, 1) <= naive_utc < self._last_sunday(y, 10, 1)
+
+    def fromutc(self, dt: datetime) -> datetime:
+        return dt + timedelta(hours=2 if self._dst_utc(dt.replace(tzinfo=None)) else 1)
+
+    def utcoffset(self, dt):
+        if dt is None:
+            return timedelta(hours=1)
+        return timedelta(hours=2 if self._dst_local(dt.replace(tzinfo=None)) else 1)
+
+    def dst(self, dt):
+        if dt is None:
+            return timedelta(0)
+        return timedelta(hours=1 if self._dst_local(dt.replace(tzinfo=None)) else 0)
+
+    def tzname(self, dt):
+        return "CEST" if dt is not None and self._dst_local(dt.replace(tzinfo=None)) else "CET"
+
+
+def _billing_tz():
+    try:
+        from zoneinfo import ZoneInfo
+        tz = ZoneInfo("Europe/Brussels")
+        # Prove it resolves before trusting it: a ZoneInfo built from an empty
+        # tzdata answers, and answering wrongly is the failure being avoided.
+        if datetime(2026, 7, 1, tzinfo=timezone.utc).astimezone(tz).hour == 2:
+            return tz
+        _LOG.warning("zoneinfo Europe/Brussels resolved but gave the wrong "
+                     "summer offset - falling back to the encoded EU rule")
+    except Exception as err:                      # noqa: BLE001 - any failure
+        _LOG.info("no usable tz database (%s) - using the encoded EU rule", err)
+    return _EUTimezone()
+
+
+BILLING_TZ = _billing_tz()
+
+
+def month_key(when: datetime) -> str:
+    """The calendar month a UTC instant is billed in, as 'YYYY-MM' LOCAL time."""
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=timezone.utc)
+    local = when.astimezone(BILLING_TZ)
+    return f"{local.year:04d}-{local.month:02d}"
+
+
+# --------------------------------------------------------------------------- #
+# the per-phase reduction policy - one function, deliberately
+# --------------------------------------------------------------------------- #
+# §9.1 requires the average be computed per-phase-aware, but does NOT say whether
+# the BILLED figure on a three-phase connection is the sum of the phases or the
+# worst single phase. §5.2 requires the per-phase data; nothing states the
+# reduction. So it is one function with one argument, and correcting it later is
+# a one-line change plus a test parameter rather than a change to the
+# accumulator. §17's "Three-phase unbalanced load" scenario is the case that
+# tells the three apart - on a balanced load all three agree, which is exactly
+# why a balanced fixture must not be what this is tested on.
+POLICY_NET = "net"   # default: the connection's net offtake, what the meter bills
+POLICY_SUM = "sum"   # sum of the per-phase offtakes (differs when a phase exports)
+POLICY_MAX = "max"   # the worst single phase
+
+
+def billed_w(block, policy: str = POLICY_NET) -> float:
+    """Reduce one closed block to the single figure the month is billed on."""
+    pp = getattr(block, "per_phase_offtake_avg_w", None)
+    if policy == POLICY_NET or not pp:
+        return float(block.offtake_avg_w)
+    if policy == POLICY_SUM:
+        return float(sum(pp))
+    if policy == POLICY_MAX:
+        return float(max(pp))
+    raise ValueError(f"unknown per-phase reduction policy: {policy!r}")
+
+
+# --------------------------------------------------------------------------- #
+# what a read of the store answers
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class PeakReading:
+    """An answer about a month's peak, or an honest refusal to give one.
+
+    ⚠️ There is no `peak_w_or(default)` and there must never be one. Every
+    accessor that lets a caller turn "the database did not answer" into a number
+    re-creates the defect this type exists to remove. Callers ask `is_observed`
+    first, and a caller that forgets gets `None` and a TypeError, which is loud.
+    """
+
+    state: str
+    month: str
+    peak_w: float | None = None
+    quarter_start: datetime | None = None
+    per_phase_w: tuple | None = None
+    detail: str = ""
+
+    @property
+    def is_observed(self) -> bool:
+        return self.state == OBSERVED
+
+    @property
+    def is_unreadable(self) -> bool:
+        return self.state == NOT_OBSERVED
+
+    def explain(self) -> str:
+        if self.state == OBSERVED:
+            at = self.quarter_start.isoformat() if self.quarter_start else "?"
+            return f"{self.month}: peak {self.peak_w:.0f} W, set by the quarter at {at}"
+        if self.state == NO_RECORD:
+            return f"{self.month}: no completed quarter recorded yet"
+        return (f"{self.month}: PEAK UNREADABLE ({self.detail}) - this is NOT a "
+                f"zero peak and must not be used as headroom")
+
+
+# --------------------------------------------------------------------------- #
+# the store
+# --------------------------------------------------------------------------- #
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS quarter_blocks (
+    quarter_start   TEXT PRIMARY KEY,   -- ISO-8601 UTC, aligned to 900 s
+    month           TEXT NOT NULL,      -- 'YYYY-MM', LOCAL calendar month
+    offtake_avg_w   REAL NOT NULL,
+    per_phase_json  TEXT
+);
+CREATE INDEX IF NOT EXISTS ix_quarter_month ON quarter_blocks(month);
+CREATE TABLE IF NOT EXISTS monthly_peak (
+    month           TEXT PRIMARY KEY,
+    peak_w          REAL NOT NULL,
+    quarter_start   TEXT NOT NULL,
+    per_phase_json  TEXT
+);
+CREATE TABLE IF NOT EXISTS partial_block (
+    id              INTEGER PRIMARY KEY CHECK (id = 1),
+    state_json      TEXT NOT NULL
+);
+"""
+
+
+class PeakStore:
+    """SQLite behind /data. Every read answers with a state, never with a default."""
+
+    def __init__(self, path: str = "/data/tariff.db"):
+        self.path = path
+        self.ok = False
+        self.last_error: str | None = None
+        self._db: sqlite3.Connection | None = None
+        self._open()
+
+    def _open(self) -> None:
+        parent = os.path.dirname(self.path)
+        # ⚠️ THE DIRECTORY IS NOT CREATED. /data is mounted by the Supervisor and
+        # always exists on a real install, so `makedirs` here could only ever
+        # succeed where the durable volume is MISSING - manufacturing a database
+        # on the container's ephemeral layer that looks durable, reads fine, and
+        # is thrown away on the next restart. That is a peak store that silently
+        # forgets, which is worse than one that says it cannot answer.
+        if parent and not os.path.isdir(parent):
+            self.last_error = f"no durable volume at {parent}"
+            # INFO, not ERROR: on a dev host or in a test container there is no
+            # /data and nothing is wrong. A store that OPENED and then broke is
+            # the error case, and it is logged as one below.
+            _LOG.info("no peak store: %s - the monthly peak will read "
+                      "NOT_OBSERVED", self.last_error)
+            return
+        try:
+            self._db = sqlite3.connect(self.path, timeout=5.0,
+                                       check_same_thread=False)
+            # WAL: a power cut mid-write must not leave a torn database that
+            # reads as "no peak this month" - the exact shape of the defect.
+            self._db.execute("PRAGMA journal_mode=WAL")
+            self._db.executescript(_SCHEMA)
+            self._db.commit()
+            self.ok = True
+            self.last_error = None
+        except sqlite3.Error as err:
+            self._db = None
+            self.ok = False
+            self.last_error = str(err)
+            # ⚠️ Deliberately NOT raised. §6's fail-open rule: an aggregation
+            # fault must not stop a controller that is regulating a battery. The
+            # cost of continuing is a peak that reads NOT_OBSERVED, and every
+            # reader is built to treat that as "do not use me", not as 0 W.
+            _LOG.error("peak store unusable at %s (%s) - the monthly peak will "
+                       "read NOT_OBSERVED, which is not a zero peak", self.path, err)
+
+    def close(self) -> None:
+        if self._db is not None:
+            try:
+                self._db.close()
+            finally:
+                self._db = None
+                self.ok = False
+
+    # -- writing ------------------------------------------------------------
+    def record_block(self, block, policy: str = POLICY_NET) -> bool:
+        """Persist one completed block and fold it into its month's peak.
+
+        Both tables move in ONE transaction. A crash between them would leave a
+        banked quarter that the monthly peak does not know about, and the peak is
+        the record the money is read off.
+        """
+        if self._db is None:
+            return False
+        w = billed_w(block, policy)
+        start = block.start.astimezone(timezone.utc).isoformat()
+        month = month_key(block.start)
+        pp = getattr(block, "per_phase_offtake_avg_w", None)
+        pp_json = json.dumps(list(pp)) if pp else None
+        try:
+            with self._db:
+                # A block may only ever be RAISED. A restart that reprocesses a
+                # quarter it had already banked will have LESS coverage than the
+                # first pass (its first seconds are gone), so an unconditional
+                # REPLACE would silently lower a recorded figure.
+                self._db.execute(
+                    "INSERT INTO quarter_blocks(quarter_start, month, offtake_avg_w, per_phase_json)"
+                    " VALUES(?,?,?,?)"
+                    " ON CONFLICT(quarter_start) DO UPDATE SET"
+                    "   offtake_avg_w=excluded.offtake_avg_w,"
+                    "   per_phase_json=excluded.per_phase_json"
+                    " WHERE excluded.offtake_avg_w > quarter_blocks.offtake_avg_w",
+                    (start, month, w, pp_json))
+                self._db.execute(
+                    "INSERT INTO monthly_peak(month, peak_w, quarter_start, per_phase_json)"
+                    " VALUES(?,?,?,?)"
+                    " ON CONFLICT(month) DO UPDATE SET"
+                    "   peak_w=excluded.peak_w,"
+                    "   quarter_start=excluded.quarter_start,"
+                    "   per_phase_json=excluded.per_phase_json"
+                    " WHERE excluded.peak_w > monthly_peak.peak_w",
+                    (month, w, start, pp_json))
+            return True
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            _LOG.error("could not record quarter %s (%s)", start, err)
+            return False
+
+    # -- reading ------------------------------------------------------------
+    def peak(self, when: datetime | None = None, month: str | None = None) -> PeakReading:
+        """The billed peak for a month. Three possible answers, never a default."""
+        if month is None:
+            month = month_key(when or datetime.now(timezone.utc))
+        if self._db is None:
+            return PeakReading(NOT_OBSERVED, month,
+                               detail=self.last_error or "store never opened")
+        try:
+            row = self._db.execute(
+                "SELECT peak_w, quarter_start, per_phase_json FROM monthly_peak"
+                " WHERE month=?", (month,)).fetchone()
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            return PeakReading(NOT_OBSERVED, month, detail=str(err))
+        if row is None:
+            return PeakReading(NO_RECORD, month)
+        pp = tuple(json.loads(row[2])) if row[2] else None
+        return PeakReading(OBSERVED, month, peak_w=float(row[0]),
+                           quarter_start=datetime.fromisoformat(row[1]),
+                           per_phase_w=pp)
+
+    def recompute_month(self, month: str) -> PeakReading:
+        """Re-derive the peak from `quarter_blocks` - the divergence check.
+
+        `monthly_peak` is a derived record, so it can be PROVEN equal to the
+        tier it derives from instead of trusted to be. Read-only.
+        """
+        if self._db is None:
+            return PeakReading(NOT_OBSERVED, month,
+                               detail=self.last_error or "store never opened")
+        try:
+            row = self._db.execute(
+                "SELECT offtake_avg_w, quarter_start, per_phase_json FROM quarter_blocks"
+                " WHERE month=? ORDER BY offtake_avg_w DESC, quarter_start ASC LIMIT 1",
+                (month,)).fetchone()
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            return PeakReading(NOT_OBSERVED, month, detail=str(err))
+        if row is None:
+            return PeakReading(NO_RECORD, month)
+        pp = tuple(json.loads(row[2])) if row[2] else None
+        return PeakReading(OBSERVED, month, peak_w=float(row[0]),
+                           quarter_start=datetime.fromisoformat(row[1]),
+                           per_phase_w=pp)
+
+    def blocks_in(self, month: str) -> list:
+        """(quarter_start, offtake_avg_w) for a month, oldest first. [] on error
+        is safe here ONLY because no caller reads emptiness as a peak - AC 3's
+        counter reports the sample size it actually got."""
+        if self._db is None:
+            return []
+        try:
+            return [(datetime.fromisoformat(a), float(b)) for a, b in self._db.execute(
+                "SELECT quarter_start, offtake_avg_w FROM quarter_blocks"
+                " WHERE month=? ORDER BY quarter_start", (month,))]
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            return []
+
+    # -- the open block's checkpoint ----------------------------------------
+    def save_partial(self, state: dict) -> bool:
+        if self._db is None:
+            return False
+        try:
+            with self._db:
+                self._db.execute(
+                    "INSERT INTO partial_block(id, state_json) VALUES(1,?)"
+                    " ON CONFLICT(id) DO UPDATE SET state_json=excluded.state_json",
+                    (json.dumps(state),))
+            return True
+        except (sqlite3.Error, TypeError, ValueError) as err:
+            self.last_error = str(err)
+            return False
+
+    def load_partial(self) -> dict | None:
+        if self._db is None:
+            return None
+        try:
+            row = self._db.execute(
+                "SELECT state_json FROM partial_block WHERE id=1").fetchone()
+            return json.loads(row[0]) if row else None
+        except (sqlite3.Error, ValueError) as err:
+            self.last_error = str(err)
+            return None
+
+    def clear_partial(self) -> None:
+        # The one DELETE in this module, and it is against the checkpoint - a
+        # scratch row, not a retention tier. Neither quarter_blocks nor
+        # monthly_peak is deleted from anywhere in this file.
+        if self._db is None:
+            return
+        try:
+            with self._db:
+                self._db.execute("DELETE FROM partial_block WHERE id=1")
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+
+
+# --------------------------------------------------------------------------- #
+# the tracker: what main.py holds
+# --------------------------------------------------------------------------- #
+@dataclass(frozen=True)
+class Projection:
+    """The open block's end-of-quarter estimate, with the reasons to distrust it.
+
+    `elapsed_s` travels WITH the number rather than beside it, because early in a
+    quarter a projection is a 10-second extrapolation over 900 s and a consumer
+    that cannot see that will react to noise. `covered_frac` is separately useful:
+    it is below 1.0 when the meter had a gap, which is the "unreliable quarter"
+    the functional note asks be marked rather than reported low.
+    """
+
+    projected_w: float
+    elapsed_w: float
+    elapsed_s: float
+    covered_frac: float
+    complete: bool
+    block_start: datetime | None
+    held_w: float
+
+    def explain(self) -> str:
+        return (f"quarter projects {self.projected_w:.0f} W "
+                f"({self.elapsed_s:.0f} s elapsed, {self.covered_frac * 100:.0f} % covered"
+                + ("" if self.complete else ", INCOMPLETE") + ")")
+
+
+class PeakTracker:
+    """Drives the store from `P1Ingest`. Measures; never commands."""
+
+    def __init__(self, store: PeakStore, cap_w: float = 3500.0,
+                 policy: str = POLICY_NET, checkpoint_s: float = CHECKPOINT_S):
+        self.store = store
+        self.cap_w = float(cap_w)
+        self.policy = policy
+        self.checkpoint_s = float(checkpoint_s)
+        self.recorded = 0
+        self.restore_state = "not attempted"
+        self._seen: set = set()
+        self._last_ckpt = 0.0
+
+    # -- startup ------------------------------------------------------------
+    def restore(self, averager, now: datetime | None = None) -> str:
+        """Put the open block back. Returns which of the three cases happened."""
+        now = now or datetime.now(timezone.utc)
+        snap = self.store.load_partial()
+        if not snap:
+            self.restore_state = ("fresh: no checkpoint" if self.store.ok
+                                  else "fresh: store unreadable")
+            return self.restore_state
+        block = snap.get("block")
+        if block is None:
+            self.restore_state = "fresh: checkpoint had no open block"
+            return self.restore_state
+
+        current = int(now.timestamp() // QUARTER_S) * QUARTER_S
+        if block == current:
+            if not averager.restore(snap):
+                # A reshaped accumulator (meter_phases changed) is a different
+                # measurement, not a resumable one. Say so; do not half-resume.
+                self.store.clear_partial()
+                self.restore_state = "fresh: checkpoint does not fit this averager"
+                return self.restore_state
+            self.restore_state = (
+                f"resumed the open block at {snap.get('elapsed', 0.0):.0f} s "
+                f"of {QUARTER_S} s ({snap.get('acc', 0.0) / QUARTER_S:.0f} W banked)")
+            return self.restore_state
+
+        # The block ended while the add-on was down. Its measured part really
+        # happened, so bank it at acc/900 rather than discard measured energy.
+        # It reads LOW because the seconds after the shutdown were never covered,
+        # and that is the honest figure: coverage a closed block did not get.
+        closed = _ClosedBlock(
+            start=datetime.fromtimestamp(block, timezone.utc),
+            offtake_avg_w=float(snap.get("acc", 0.0)) / QUARTER_S,
+            per_phase_offtake_avg_w=(tuple(v / QUARTER_S for v in snap["pp_acc"])
+                                     if snap.get("pp_acc") and snap.get("last_pp") else None))
+        banked = self.store.record_block(closed, self.policy)
+        self.store.clear_partial()
+        self.restore_state = (
+            f"closed a stale block from {closed.start.isoformat()} at "
+            f"{closed.offtake_avg_w:.0f} W (partial coverage), "
+            + ("banked" if banked else "NOT banked - store unwritable"))
+        return self.restore_state
+
+    # -- steady state -------------------------------------------------------
+    def sync(self, ingest, now_mono: float | None = None) -> int:
+        """Bank any blocks that closed, and refresh the checkpoint. Returns the
+        number of blocks newly recorded on this call."""
+        import time as _t
+        n = 0
+        for block in getattr(ingest, "blocks", ()):
+            key = block.start.timestamp()
+            if key in self._seen:
+                continue
+            if self.store.record_block(block, self.policy):
+                self._seen.add(key)
+                self.recorded += 1
+                n += 1
+        if n:
+            # A block just closed, so the checkpoint's block is gone: clearing it
+            # in the same breath is what stops a crash here from replaying it.
+            self.store.clear_partial()
+            self._last_ckpt = 0.0
+        self.checkpoint(ingest, now_mono or _t.monotonic())
+        return n
+
+    def checkpoint(self, ingest, now_mono: float, force: bool = False) -> bool:
+        if not force and (now_mono - self._last_ckpt) < self.checkpoint_s:
+            return False
+        avg = getattr(ingest, "averager", None)
+        if avg is None:
+            return False
+        self._last_ckpt = now_mono
+        return self.store.save_partial(avg.snapshot())
+
+    # -- reading ------------------------------------------------------------
+    def peak(self, when: datetime | None = None) -> PeakReading:
+        return self.store.peak(when)
+
+    def headroom_w(self, when: datetime | None = None) -> float | None:
+        """Watts left under the soft limit, or None when it cannot be known.
+
+        ⚠️ `None`, not `self.cap_w`. An unreadable peak returning full headroom
+        is the disarming default this whole module is shaped against.
+        """
+        r = self.peak(when)
+        if r.state == NO_RECORD:
+            return self.cap_w
+        if not r.is_observed:
+            return None
+        return max(0.0, self.cap_w - r.peak_w)
+
+    def warning_frac(self, when: datetime | None = None) -> float | None:
+        """Peak as a fraction of the soft limit - §9.1's 80 % warning entity."""
+        r = self.peak(when)
+        if r.state == NO_RECORD:
+            return 0.0
+        if not r.is_observed or self.cap_w <= 0:
+            return None
+        return r.peak_w / self.cap_w
+
+    @staticmethod
+    def project(averager, now: datetime) -> Projection:
+        """End-of-quarter average if the last sample held for the rest of it.
+
+        ⚠️ The two divisors are DIFFERENT and only coincide at the end of the
+        block. `elapsed_w` divides by the seconds actually covered (what the
+        meter has shown so far); `projected_w` divides by the full 900 s and
+        credits the held value over what remains. At `elapsed_s == 900` and full
+        coverage they are equal - which is precisely why nothing may be tested
+        only at that point.
+        """
+        start = averager.block_start
+        if start is None:
+            # ⚠️ A ZERO PROJECTION, AND IT IS NOT "THE QUARTER IS FINE". It is
+            # "there is no quarter". `block_start is None` is the flag that says
+            # which, and SAFETY-07 grades that flag BEFORE it grades the number -
+            # see peakguard.blindness(). A consumer that reads only
+            # `projected_w` here reads 0 W, which is under every ceiling there
+            # is, on exactly the startup path where nothing else is watching.
+            return Projection(0.0, 0.0, 0.0, 0.0, False, None, 0.0)
+        elapsed_wall = max(0.0, (now - start).total_seconds())
+        elapsed = averager.elapsed_s
+        acc = averager.partial_ws
+        remaining = max(0.0, QUARTER_S - elapsed_wall)
+        # ⚠️ NO `getattr` DEFAULT, AND THAT IS THE FIX, NOT A TIDY-UP. This read
+        # was `getattr(averager, "_last_net", 0.0)`: a private name with a
+        # fallback, so renaming the attribute would have kept every projection
+        # green while crediting 0 W held - a projection that reads LOW, which is
+        # the UNDER-GUARDING direction for SAFETY-07's floor. TEST-13 item 4.
+        # `held_net_w` is now a documented public property on QuarterAverager and
+        # is read without a default, so the same rename raises AttributeError on
+        # the first cycle instead of quietly disarming the money guard.
+        held = max(averager.held_net_w, 0.0)
+        return Projection(
+            projected_w=(acc + held * remaining) / QUARTER_S,
+            elapsed_w=(acc / elapsed) if elapsed > 0 else 0.0,
+            elapsed_s=elapsed_wall,
+            covered_frac=(elapsed / elapsed_wall) if elapsed_wall > 0 else 0.0,
+            complete=elapsed_wall <= 0 or elapsed >= elapsed_wall - 1e-9,
+            block_start=start,
+            # Carried so a consumer can see WHAT was extrapolated, not only the
+            # extrapolation. It is the signed held value; `projected_w` uses the
+            # offtake-only form above, and the two differ whenever the site is
+            # exporting - which is the healthy operating point here.
+            held_w=averager.held_net_w)
+
+
+@dataclass(frozen=True)
+class _ClosedBlock:
+    """A block reconstructed from a checkpoint. Shaped like `p1.QuarterBlock` so
+    `record_block` has one input type; kept private so nothing else makes one."""
+
+    start: datetime
+    offtake_avg_w: float
+    per_phase_offtake_avg_w: tuple | None

goodwe_controller/app/validate.py

@@ -0,0 +1,572 @@
+"""Startup configuration validation - the gate before the control loop runs.
+
+WHAT THIS IS FOR, in one sentence: some configurations are not "a bit off", they
+are configurations under which the add-on's own safety machinery does not work,
+and for those the correct behaviour is to refuse to start rather than to log a
+line and carry on.
+
+⚠️ THE FAILURE THIS REPLACES. `main.py` used to read the setpoint device's own
+±5000 W rating, notice that a configured `max_w` of, say, 8000 W exceeded it,
+write one WARNING to a log nobody reads, and then run anyway with
+`write_setpoint()` quietly clamping. The operator's stated ceiling was simply not
+the ceiling, and the only evidence was a line that had scrolled off. specs §1.5
+is explicit that a configuration in which the system cannot honour what it was
+told is refused at startup, not survived at runtime.
+
+WHERE THE LINE IS DRAWN, and why it is not further out. A validator that refuses
+on trivia gets switched off by the first person it inconveniences, so this one
+refuses only where **continuing produces one of two outcomes:**
+
+  (a) **a stated limit is untrue** - the operator configured a bound, a lower
+      layer silently enforces a different one, and nothing says which won; or
+  (b) **the add-on is inert and indistinguishable from healthy** - it starts,
+      serves its UI, reports green, and moves no energy, with no symptom that
+      separates it from a correctly-idle system.
+
+⚠️ (b) IS NOT A SPECIAL CASE OF (a), and an earlier draft of this file wrongly
+implied it was by claiming every refusal here "makes a safety mechanism
+inoperative". It does not: when `setpoint_entity` is blank, layer 1 pinning the
+inverter at 0 W is the failsafe WORKING. The problem is not that the system
+becomes unsafe, it is that it becomes a very convincing impression of a working
+controller - and an operator has no way to tell. That is its own reason to
+refuse, and stating it as one is what stops the rule being stretched later to
+cover mere untidiness.
+
+Both halves have to stay narrow. (a) is not "any two numbers that could
+disagree"; it is a bound the operator SET being overridden by a layer they
+cannot see. (b) is not "anything degraded"; it is inert AND silent - if a red
+NOT READY banner already names the problem, (b) does not apply.
+
+  1. `max_w` outside the setpoint device's own rating.  [(a)]
+     The stated limit is untrue. arbiter.py's `supervised` SAFETY claim says the
+     output is bounded by ±max_w; it is not, it is bounded by the device, and the
+     two numbers disagree. Which one wins is a coin toss to anyone reading the
+     config.
+
+  2. No `setpoint_entity`.  [(b)]
+     A controller with no actuator, and nothing about it looks broken.
+     `write_setpoint()` returns immediately on a blank entity, so: no device
+     rating is ever read (the `device` SAFETY claim is never made at all), and
+     the ESP32 heartbeat - the thing that feeds LAYER 1 - never happens. The
+     add-on serves a UI, publishes MQTT, resolves claims, and moves nothing.
+     Layer 1 then holds the inverter at 0 W, which is the failsafe working
+     exactly as designed - this is (b), not (a). Nothing is unsafe; it is simply
+     impossible to tell from the outside that the thing is doing nothing.
+
+  3. A `meter_source` that can never produce a reading.  [(b)]
+     §5.1 makes P1 the only authoritative measurement and deliberately provides
+     no fallback, so a transport that cannot be built means `grid` is None
+     forever: permanent "inputs missing", 0 W, and a status page that reports a
+     meter with a climbing age exactly as it would for a healthy meter nobody has
+     sent anything to yet. The predicates live in `p1.validate_meter_options()`,
+     which is also what `build_source()` uses - one definition, two callers.
+
+  4. `meter_max_age_s` above the firmware's own ingest veto.  [(a)]
+     The purest example of (a) in the system, and structurally the same fault as
+     1. The add-on's schema accepts `int(5,300)`. The firmware's threshold is a
+     COMPILE-TIME SUBSTITUTION - `max_age_s: "30"` in
+     goodwe-master-stage4-failsafe.yaml - used by both its monotonic receipt
+     clock and its `ingest_stale` veto, which trips layer 1 on
+     `p1_age_s >= 30`. Set 120 and the add-on believes a 119 s reading is fresh
+     and keeps commanding into it, while the firmware vetoed at 30 s and is
+     holding the inverter at 0 W. Status page: healthy meter, running
+     controller, nothing moving, and no line anywhere saying the number you set
+     was overruled. That firmware file's own comment says a lower bound on this
+     "belongs in CFG-01, not here" - so here it is.
+
+  5. `sign_disagree_w` at or above `max_w`.  [(a)]
+     The arbiter's `supervised` limit bounds every command to +-max_w, and
+     SAFETY-02's predicate needs `abs(command) > sign_disagree_w`. Set the
+     threshold at or above the ceiling and the command side of the comparison
+     is unsatisfiable BY CONSTRUCTION: the watchdog can never fire, on any
+     input, ever. Same shape as 1 and 4 - the operator set a number, a layer
+     they cannot see makes it mean something else, and nothing says so. Worse
+     here, because what the status page reports in that state is "sign
+     watchdog: armed". A disarmed guard that advertises itself as armed is the
+     one thing this project has decided repeatedly it will not ship.
+
+  6. `maintenance_charge_w` above `max_w`.  [(a)]
+     The same shape as 5, and found the same way - by checking a worked example
+     against what actually ships. maintenance's cheap-window shaping files
+     `Claim.limit(hi=-maintenance_charge_w)` at P_MAINT_SHAPE, against the
+     `supervised` SAFETY limit's `lo=-max_w`. Both bind (P_SAFETY and
+     P_MAINT_SHAPE both outrank the loop that wins the SET), so a charge rate
+     above the ceiling gives `lo > hi` - the arbiter's clause 3, which it
+     correctly resolves to 0 W and logs as a CONTRADICTION. Measured against
+     the arbiter, loop asking +500 W:
+
+         max_w=2000  hi=-2500  ->     +0 W  contradiction=True
+         max_w=2500  hi=-2500  ->  -2500 W  limited by supervised(max_w)
+         max_w=3000  hi=-2500  ->  -2500 W  limited by maintenance(...)
+
+     So MAINTENANCE SILENTLY NEVER CHARGES IN A CHEAP WINDOW until max_w is at
+     or above the charge rate, and the only evidence is a contradiction line
+     that reads like a bug in the arbiter rather than like the two numbers the
+     operator set. Equality is fine and deliberately not refused - at
+     max_w == charge_w the window is a single reachable point, -max_w.
+
+     ⚠️ `maintenance_discharge_w` IS NOT THE SAME CASE, and this was checked
+     rather than assumed. THE SHAPING IS NOT SYMMETRIC: the drain phase does
+     not shape the loop, it OWNS the actuator - `Claim.set(P_MAINTENANCE,
+     +discharge_w)`. A SET is clamped by the limits above it, not contradicted
+     by them, so 2500 against a 2000 W ceiling emits +2000 W and the arbiter's
+     own explain() says `maintenance -> 2000 W, limited by supervised(max_w)`
+     on the status page every cycle. That is neither (a) - nothing is silent -
+     nor (b) - it moves energy and the cycle still completes, just slower
+     (13.8 kWh usable at 2000 W is ~6.9 h against the 720 min DRAIN_TIMEOUT).
+     It is warned about below, not refused.
+
+  7. A price configuration that cannot mean what it says.  [(a)]
+     Three cases, all in `_price_problems()`: an unknown `price_provider` id
+     (refused rather than defaulted to 'off', per the §14 warning box);
+     `price_provider` set alongside `price_now_entity`/`price_avg_entity`,
+     which is TWO PRICE SOURCES ON ONE SITE where the Home Assistant pair
+     silently wins; and `manual_csv` with no `price_csv_path`, which turns the
+     documented offline fallback into a permanent no-price-data condition
+     reached by accident. Same shape as 1, 4 and 5 every time - a source the
+     operator chose, overridden by a layer they cannot see.
+
+     ⚠️ `price_provider: "off"` IS NOT REFUSED AND MUST NOT BECOME SO. §11.4
+     makes no-price-data a supported state, and §9.2 says a large share of the
+     installed base is on a fixed or static tariff. Refusing to start without a
+     price feed would lock those sites out of the add-on entirely.
+
+WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
+
+  - `integrator_max_w` above `max_w`. DOCS.md is right that the only thing the
+    extra headroom buys is more wrong-direction power to unwind after
+    saturation - but the arbiter's `supervised` limit still binds the wire to
+    ±max_w, so nothing out of range ever reaches the inverter. The cost is
+    latency, not amperage. Warned about, not refused.
+  - A missing `soc_entity` / `batt_entity`. `inputs_ok` goes False, the loop
+    commands 0 W, and `checks()` already renders a red NOT READY banner naming
+    the missing entity. Fail-safe AND already loud; a refusal adds nothing.
+  - A `setpoint_entity` that exists in the config but is not found on the Core
+    API at startup. This is the transient case - ESPHome is frequently not up
+    yet when the add-on boots - and refusing here would turn a device that
+    arrives thirty seconds late into a restart loop needing a human. It stays a
+    NOT READY banner.
+  - `meter_poll_s` above half `meter_max_age_s`. One missed poll costs a stale
+    reading and a 0 W cycle. Warned about in p1.py, not refused.
+  - `maintenance_discharge_w` above `max_w`. Clamped, not contradicted, and the
+    clamp names itself in the arbiter's explain() - see rule 6. Warned about,
+    not refused.
+"""
+
+import logging
+
+from .p1 import is_enabled, validate_meter_options
+from .price import PROVIDERS
+from .static_tariff import ProfileInvalid, parse_static_profile
+
+_LOG = logging.getLogger("goodwe.config")
+
+# ⚠️ A MIRROR OF A FIRMWARE CONSTANT, AND IT CANNOT BE IMPORTED. The firmware
+# threshold is a compile-time YAML substitution baked into the ESP32 image
+# (`max_age_s: "30"`, master/goodwe-master-stage4-failsafe.yaml), so nothing at
+# runtime can ask the board what value it was built with. This number is a copy,
+# and a copy of a constant in another repo is a thing that goes stale.
+#
+# What makes that acceptable here: the copy can only ever be WRONG IN THE SAFE
+# DIRECTION for the check below. If the firmware's veto is raised above 30, this
+# refuses some configs that would in fact have worked - annoying, visible
+# immediately, and fixed by editing one line. It cannot start accepting a config
+# the firmware vetoes unless the firmware's number goes DOWN, which would be a
+# tightening nobody does silently.
+#
+# ⚠️ TEL-06 IS EDITING `ingest_stale` DIRECTLY. If that ticket changes what the
+# veto MEANS - e.g. thresholding arrival rather than the sensor's value - this
+# constant's justification has to be re-read, not just its number. Do not assume
+# a matching integer means a matching rule.
+FIRMWARE_INGEST_VETO_S = 30.0
+
+# ⚠️ The complete set of option keys through which this add-on can reach an
+# actuator. specs §1.5 makes "any configuration in which two writers can reach
+# one actuator" a non-goal, and the way that non-goal is ENFORCED here is by
+# construction: there is exactly one such key, so a second writer is not
+# expressible in the options schema at all. sim/inject.py's `two_writers`
+# scenario asserts on this tuple - if a second write path is ever added, that
+# scenario goes red and somebody has to decide how the two are arbitrated
+# BEFORE the config that allows both can ship.
+ACTUATOR_WRITE_KEYS = ("setpoint_entity",)
+
+
+class ConfigRefused(Exception):
+    """The configuration is wrong. Not "something broke" - see main.py's handler.
+
+    Carries the list of problems so the caller can render them; str() is the
+    first one, so an unhandled traceback still names something useful.
+    """
+
+    def __init__(self, problems: list[str]):
+        self.problems = problems
+        super().__init__(problems[0] if problems else "configuration refused")
+
+
+def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]:
+    """Return the list of reasons this configuration must not be started.
+
+    Empty list means go. `dev_min`/`dev_max` are the setpoint device's own
+    reported range (`hass.limits()`), or None when the device could not be
+    reached - in which case the range checks are skipped rather than guessed at,
+    for the transient reason in this module's docstring.
+
+    Pure and side-effect free apart from two warnings, so it can be called from
+    a test or from sim/inject.py without a Home Assistant anywhere near it.
+    """
+    problems: list[str] = []
+
+    # --- 1. an actuator to write to ------------------------------------------
+    writers = [k for k in ACTUATOR_WRITE_KEYS
+               if str(opts.get(k, "") or "").strip()]
+    if not writers:
+        problems.append(
+            "setpoint_entity is not set, so this add-on has no actuator: every "
+            "write is a no-op, the device's own rating is never read, and the "
+            "ESP32 heartbeat that holds off the layer-1 failsafe never happens. "
+            "It would run, look healthy, and move no energy at all. Set it to "
+            "the ESPHome number entity that carries the setpoint.")
+
+    # --- 2. the configured ceiling against the device's own rating -----------
+    max_w = _number(opts, "max_w", 2000.0)
+    if max_w is None:
+        problems.append(f"max_w {opts.get('max_w')!r} is not a number")
+    # ⚠️ config.yaml's int(100,5000) already blocks this on a real install, so
+    # the check is not for the Supervisor path - it is because
+    # validate_startup_config() is now also sim/inject.py's entry point and can
+    # be handed any dict at all. A max_w of 0 or below inverts the arbiter's
+    # `supervised` bounds (lo=-max_w becomes the HIGHER number), and a limit
+    # claim whose lo exceeds its hi is exactly the contradiction the arbiter
+    # resolves to 0 W - i.e. it would look like a safety trip rather than the
+    # nonsense config it is.
+    elif max_w <= 0:
+        problems.append(
+            f"max_w is {max_w:.0f} W and must be positive - it is a magnitude, "
+            "not a signed setpoint. At or below zero the arbiter's supervised "
+            f"limit becomes lo={-max_w:.0f} / hi={max_w:.0f}, which is a "
+            "contradiction it resolves to 0 W, so the controller would look "
+            "like it was tripping rather than misconfigured.")
+    elif dev_max is not None and max_w > dev_max:
+        problems.append(
+            f"max_w is {max_w:.0f} W but {opts.get('setpoint_entity') or 'the setpoint device'} accepts at "
+            f"most {dev_max:.0f} W - THE DEVICE WINS, so the {max_w:.0f} W you "
+            f"configured would silently never happen. Lower max_w to "
+            f"{dev_max:.0f} W or less, or point setpoint_entity at a device that "
+            f"can take {max_w:.0f} W.")
+    elif dev_min is not None and -max_w < dev_min:
+        problems.append(
+            f"max_w is {max_w:.0f} W, so this controller may command "
+            f"{-max_w:.0f} W, but {opts.get('setpoint_entity') or 'the setpoint device'} accepts no less "
+            f"than {dev_min:.0f} W - THE DEVICE WINS on the charge side. Lower "
+            f"max_w to {abs(dev_min):.0f} W or less.")
+
+    # --- 3. a meter that can actually read -----------------------------------
+    # ⚠️ Not a second copy of these rules - p1.py owns them, because
+    # build_source() has to apply the identical predicates and a drifted copy
+    # would be worse than no check.
+    phases = _number(opts, "meter_phases", 1.0)
+    max_age_s = _number(opts, "meter_max_age_s", 30.0)
+    if phases is None or max_age_s is None:
+        problems.append("meter_phases and meter_max_age_s must both be numbers "
+                        f"(got {opts.get('meter_phases')!r} / "
+                        f"{opts.get('meter_max_age_s')!r})")
+    else:
+        problems.extend(validate_meter_options(opts, int(phases), max_age_s))
+
+    # --- 4. the staleness window the FIRMWARE will actually enforce -----------
+    # ⚠️ Only when P1 ingestion is on, and that is a real scope limit rather than
+    # caution: meter_max_age_s is read by nothing but P1Ingest, and the veto it
+    # collides with keys off `p1_age_s.has_state()`, which is only ever published
+    # when ingestion is running (see Controller.publish()). With meter_source off
+    # there is no sensor, the veto is inert, and the number governs nothing.
+    #
+    # Strictly greater, not >=: the firmware trips at `>= 30` and P1Ingest goes
+    # stale at `> max_age_s`, so 30 against 30 has the firmware fractionally
+    # stricter by one sample. That is the shipped default and the tested pair.
+    # BELOW 30 is fine and deliberately not refused - the add-on then gives up
+    # first, which is fail-safe and visible on its own status page. Only ABOVE is
+    # the silent case, where the add-on keeps commanding into a reading the board
+    # has already rejected.
+    if (is_enabled(opts) and max_age_s is not None
+            and max_age_s > FIRMWARE_INGEST_VETO_S):
+        problems.append(
+            f"meter_max_age_s is {max_age_s:.0f} s but the ESP32 firmware vetoes "
+            f"any P1 sample at {FIRMWARE_INGEST_VETO_S:.0f} s and forces the "
+            "layer-1 failsafe - THE FIRMWARE WINS, and it wins silently. This "
+            f"add-on would treat a {max_age_s - 1:.0f} s reading as fresh and "
+            "keep commanding, while the inverter sat at 0 W with a healthy-"
+            "looking meter on the status page. Lower meter_max_age_s to "
+            f"{FIRMWARE_INGEST_VETO_S:.0f} s or less (30 s is the tested value), "
+            "or rebuild the firmware with a matching max_age_s and update "
+            "validate.FIRMWARE_INGEST_VETO_S.")
+
+    # --- 5. a sign watchdog that can actually fire ---------------------------
+    # ⚠️ Strictly `>=`, matching the predicate exactly: watchdog.py tests
+    # `abs(commanded_w) > min_w`, and the arbiter holds `abs(commanded_w)` at or
+    # below max_w, so threshold == max_w is already unsatisfiable. Anything
+    # BELOW max_w is reachable and therefore fine - this refuses the disarmed
+    # case only, not "close to the rail".
+    sign_w = _number(opts, "sign_disagree_w", 300.0)
+    if sign_w is None:
+        problems.append(f"sign_disagree_w {opts.get('sign_disagree_w')!r} is not a number")
+    elif max_w is not None and max_w > 0 and sign_w >= max_w:
+        problems.append(
+            f"sign_disagree_w is {sign_w:.0f} W but max_w is {max_w:.0f} W, so "
+            "the SAFETY-02 sign-disagreement watchdog can never fire: the "
+            "arbiter never lets a command exceed max_w, and the watchdog needs "
+            f"a command over {sign_w:.0f} W. It would sit there reporting "
+            "'armed' on the status page while being incapable of tripping - the "
+            f"one runaway failure mode this system has actually observed. Lower "
+            f"sign_disagree_w below {max_w:.0f} W (300 W is the measured "
+            "default), or raise max_w.")
+
+    # --- 6. a maintenance charge the ceiling can actually accommodate --------
+    # ⚠️ Strictly `>`, matching the arbiter exactly. The shaping is
+    # `Claim.limit(hi=-charge_w)` against `supervised`'s `lo=-max_w`, so
+    # charge_w == max_w leaves the single reachable point -max_w and works;
+    # only ABOVE is `lo > hi`, arbiter clause 3, 0 W and a contradiction.
+    #
+    # Not scoped to maintenance_enabled, deliberately. The pair is
+    # contradictory whether or not the schedule is on, and scoping it would
+    # leave the trap armed for the one operator action - ticking
+    # maintenance_enabled - that cannot possibly be expected to change what a
+    # charge rate means.
+    # ⚠️ THE FALLBACK IS config.yaml's SHIPPED VALUE, and it has to be kept
+    # equal to it - that is the whole point of AC3. It is reachable only when a
+    # caller hands over a dict with the key missing (sim/inject.py, a test); the
+    # Supervisor always supplies every key from config.yaml, so on a real
+    # install the argument is always present.
+    #
+    # ⚠️ KNOWN MISMATCH, LEFT DELIBERATELY AND FLAGGED RATHER THAN FIXED HERE:
+    # `main.py` still falls back to 2500 in two places
+    # (`opts.get("maintenance_charge_w", 2500)`), as does maintenance.py's
+    # MaintConfig dataclass. So a dict with the key ABSENT is accepted by this
+    # rule at 2000 and then built by main.py at 2500 - the contradiction this
+    # rule exists to catch, in the one case it cannot see. It is unreachable on
+    # a Supervisor install and those files are another ticket's right now.
+    # THE REAL FIX is one source of truth for option defaults; until then the
+    # divergence is PINNED BY A CHECK rather than by this comment - see
+    # test_validate.py, "the KNOWN cross-file default divergence". It asserts
+    # the mismatch as it stands and goes red if EITHER side moves, including
+    # when somebody closes it in main.py, at which point this block and that
+    # check both get deleted.
+    charge_w = _number(opts, "maintenance_charge_w", 2000.0)
+    if charge_w is None:
+        problems.append(
+            f"maintenance_charge_w {opts.get('maintenance_charge_w')!r} is not a number")
+    elif max_w is not None and max_w > 0 and charge_w > max_w:
+        problems.append(
+            f"maintenance_charge_w is {charge_w:.0f} W but max_w is "
+            f"{max_w:.0f} W, so a maintenance charge in a cheap window can "
+            "never happen: the shaping asks the arbiter for at most "
+            f"{-charge_w:.0f} W while the supervised limit allows no less than "
+            f"{-max_w:.0f} W, which is a contradiction it resolves to 0 W - "
+            "THE CEILING WINS, and what you would see is an ARBITER "
+            "CONTRADICTION line that reads like a bug rather than like these "
+            f"two numbers. Lower maintenance_charge_w to {max_w:.0f} W or less, "
+            f"or raise max_w to at least {charge_w:.0f} W.")
+
+    # --- 7. two price sources on one site ------------------------------------
+    problems.extend(_price_problems(opts))
+
+    # --- warnings: real, but not worth refusing over -------------------------
+    integ = opts.get("integrator_max_w")
+    integ_w = None if not integ else _number(opts, "integrator_max_w", None)
+    if integ_w is not None and max_w is not None and integ_w > max_w:
+        _LOG.warning(
+            "integrator_max_w %.0f W is above max_w %.0f W. Not refused - the "
+            "arbiter still bounds the wire to +-max_w - but the only thing the "
+            "extra headroom buys is more wrong-direction power to unwind after "
+            "saturation. 0 (follow max_w) is the recommended value.",
+            integ_w, max_w)
+
+    # ⚠️ THE SIBLING OF RULE 6, AND NOT THE SAME CASE - see the docstring. The
+    # drain phase OWNS the actuator (`Claim.set` at P_MAINTENANCE), and a SET is
+    # clamped by the limits above it rather than contradicted by them. So this
+    # drains at max_w instead of the configured rate, the arbiter says so in
+    # words on the status page every cycle, and the cycle still completes -
+    # slower, and eating into maintenance.DRAIN_TIMEOUT_MIN. Loud and it moves
+    # energy, so it is neither (a) nor (b): warned, not refused.
+    disch_w = _number(opts, "maintenance_discharge_w", 2000.0)
+    if disch_w is not None and max_w is not None and max_w > 0 and disch_w > max_w:
+        _LOG.warning(
+            "maintenance_discharge_w %.0f W is above max_w %.0f W. Not refused - "
+            "the drain phase SETS the setpoint and the arbiter clamps it to "
+            "%.0f W and names the clamp ('limited by supervised(max_w)'), so "
+            "nothing is silent and the cycle still completes. But it drains at "
+            "%.0f W, not the %.0f W you configured, and the drain phase has a "
+            "720 min timeout. Lower it to %.0f W or raise max_w to remove the "
+            "surprise.",
+            disch_w, max_w, max_w, max_w, disch_w, max_w)
+
+    return problems
+
+
+def _price_problems(opts: dict) -> list[str]:
+    """Rule 7 (TARIFF-02): the price configuration, refused where it is untrue.
+
+    ⚠️ NOTE WHAT IS *NOT* HERE. `price_provider: "off"` is not refused and never
+    will be: §11.4 makes no-price-data a first-class supported state (static
+    profile, provisional plan, no arbitrage), and an add-on that will not start
+    without a price feed is an add-on that a Belgian fixed-tariff site - a large
+    share of the installed base, per §9.2 - cannot run at all.
+
+    Four refusals and two log lines (TARIFF-03 added one refusal, one parse and
+    two notices), and every refusal is still case (a) from this module's
+    docstring: a source the operator SET being overridden by a layer they cannot
+    see. The additions are `static_profile` alongside the Home Assistant price
+    pair - the same silent-loser shape as provider-plus-pair, and a LIVE one -
+    and a `static_profile` that does not tile the day, which would leave hours
+    with no price at all.
+    """
+    problems: list[str] = []
+    pid = str(opts.get("price_provider", "") or "off").strip() or "off"
+
+    if pid != "off" and pid not in PROVIDERS:
+        problems.append(
+            f"price_provider is {pid!r}, which is not a shipped plugin. The "
+            f"ids that exist are: off, {', '.join(sorted(PROVIDERS))}. "
+            "Refused rather than defaulted, per the §14 warning box - a "
+            "silent fall back to 'off' would look exactly like a working "
+            "provider that happens never to find a cheap hour.")
+        return problems          # nothing below can be judged against an unknown id
+
+    # ⚠️ THE HA-SIDE OVERLAP THE PM TOLD US TO DECIDE ABOUT, DECIDED HERE.
+    # price_now_entity/price_avg_entity are the original delegation of pricing
+    # to Home Assistant: main.py reduces them to ONE BOOLEAN, `cheap`, read by
+    # the maintenance cheap-window charge floor. They are KEPT - retiring them
+    # would take a live install's only price signal away - but they may not run
+    # alongside another price source, because main.py reads exactly one and the
+    # loser is silent. That is (a), and it is the "silently double up" the PM
+    # named on 2026-08-30.
+    #
+    # ⚠️ THE REASON THIS REFUSAL GIVES WAS REWRITTEN BY TARIFF-03, AND THE OLD
+    # WORDING IS WHY. Until TARIFF-03 this message said the configured provider
+    # "would decide nothing", which was true only because nothing consumed the
+    # series; test_price.py section 12 carried a tripwire that went red the
+    # moment a consumer landed, with instructions to fix the wording here in the
+    # same commit. It landed, it went red, and this is that fix. What is true
+    # NOW, stated exactly and no wider:
+    #
+    #   * app/static_tariff.py consumes load_prices(). resolve_tariff() turns a
+    #     provider series into a TariffPlan, a cheap-window flag and an
+    #     arbitrage verdict, so the seam is no longer inert.
+    #   * main.py reads the STATIC side of that module every cycle
+    #     (static_status()), which makes static_profile a real writer of `cheap`.
+    #   * main.py does NOT yet call resolve_tariff() on the control tick, and
+    #     that is deliberate: a provider fetch is network I/O and the tick is
+    #     what feeds the ESP32 heartbeat. So a configured PROVIDER still shapes
+    #     no energy decision on its own; a configured STATIC PROFILE does.
+    #
+    # Hence two refusals below rather than one, and neither claims more than
+    # that list. When OPT-04 puts resolve_tariff() on a background refresh, the
+    # first message's middle clause is what changes - not the rule.
+    ha_price = [k for k in ("price_now_entity", "price_avg_entity")
+                if str(opts.get(k, "") or "").strip()]
+    if pid != "off" and ha_price:
+        problems.append(
+            f"price_provider is {pid!r} AND {' and '.join(ha_price)} "
+            f"{'is' if len(ha_price) == 1 else 'are'} set, which is two price "
+            "sources on one site. THE HOME ASSISTANT ENTITIES WIN: they are "
+            "what main.py reduces to the `cheap` flag the maintenance cycle "
+            "reads. The provider series IS consumed now - app/static_tariff.py "
+            "builds a tariff plan and an arbitrage verdict from it - but it is "
+            "not what main.py acts on, so the supplier you configured would "
+            "shape no energy decision while the status page named it. Clear "
+            "price_now_entity and price_avg_entity to use the "
+            f"{pid!r} plugin, or set price_provider to 'off' to keep the "
+            "Home Assistant sensors.")
+
+    # ⚠️ THE SAME RULE FOR THE SOURCE TARIFF-03 ADDED, AND THIS ONE IS A LIVE
+    # CONFLICT RATHER THAN A LATENT ONE. main.py's read_inputs() takes `cheap`
+    # from the Home Assistant pair when it is set and from the static profile
+    # otherwise - one flag, first writer wins, and the operator who filled in a
+    # day/night tariff has no way to see that it lost.
+    if ha_price and str(opts.get("static_profile", "") or "").strip():
+        problems.append(
+            f"static_profile is set AND {' and '.join(ha_price)} "
+            f"{'is' if len(ha_price) == 1 else 'are'} set, which is two "
+            "tariff sources feeding one cheap-window flag. THE HOME ASSISTANT "
+            "ENTITIES WIN: main.py reads them first and never looks at the "
+            "static profile, so the day/night tariff you typed would decide "
+            "nothing and nothing would say so. Clear price_now_entity and "
+            "price_avg_entity to use static_profile, or clear static_profile "
+            "to keep the Home Assistant sensors.")
+
+    # ⚠️ THE PROFILE ITSELF, PARSED AT STARTUP RATHER THAN AT 02:00. A profile
+    # that does not tile the day has hours with no price, and the only ways to
+    # serve those are to invent a number or to fail at the moment the clock
+    # reaches them. §14's warning box - refuse to start on a mismatch rather
+    # than clamp quietly - is the same instruction one level down.
+    raw_profile = opts.get("static_profile", "")
+    if str(raw_profile or "").strip() or isinstance(raw_profile, (list, dict)):
+        try:
+            profile = parse_static_profile(raw_profile)
+        except ProfileInvalid as e:
+            profile = None
+            problems.append(f"static_profile cannot be used: {e}")
+        if profile is not None and profile.product is not None \
+                and len(set(profile.prices)) == 1:
+            _LOG.info(
+                "static_profile carries one distinct price (%.4f EUR/kWh "
+                "all-in), so this site is priced as FULLY FIXED. Arbitrage is "
+                "off by arithmetic - a flat series has no spread - and the "
+                "add-on runs self-consumption only, which is §9.2's handling "
+                "for this product. Peak shaving, reserve management and the "
+                "maintenance cycle are unaffected.", profile.prices[0])
+
+    # ⚠️ 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
+    # is a real gap worth naming - but refusing to start over it would break
+    # every install TARIFF-02 shipped, none of which could have had one.
+    if pid != "off" and not str(opts.get("static_profile", "") or "").strip():
+        _LOG.warning(
+            "price_provider is %r but static_profile is empty. §11.4's "
+            "degradation row is 'no price data -> fall back to the static "
+            "profile'; with none configured, a feed outage leaves this site "
+            "with no tariff at all rather than with a coarse one. Not refused, "
+            "but filling it in is what makes that row work.", pid)
+
+    if pid == "manual_csv" and not str(opts.get("price_csv_path", "") or "").strip():
+        problems.append(
+            "price_provider is 'manual_csv' but price_csv_path is empty, so "
+            "the offline fallback has no file to read. Every fetch would "
+            "return no-price-data with a filesystem error as its reason - "
+            "which is §11.4 behaviour arrived at by accident rather than by "
+            "configuration. Point it at the CSV, or set price_provider to "
+            "'off', which says the same thing on purpose.")
+
+    return problems
+
+
+def _number(opts: dict, key, default):
+    raw = opts.get(key, default)
+    if raw is None or raw == "":
+        return default
+    try:
+        return float(raw)
+    except (TypeError, ValueError):
+        return None
+
+
+def refuse(problems: list[str]) -> None:
+    """Log a refusal an operator can tell apart from a crash. Does not raise.
+
+    ⚠️ THE POINT OF THE BANNER. "You configured this wrong" must not read like
+    "it broke". A Python traceback in an add-on log means the same thing to most
+    operators as a segfault - file a bug - whereas this block names the keys,
+    names the fix, and says in words that nothing is broken. main.py catches
+    ConfigRefused and exits 78 (sysexits EX_CONFIG), so no traceback is printed
+    at all and even the exit status distinguishes the two.
+    """
+    _LOG.error("=" * 72)
+    _LOG.error("REFUSING TO START: the add-on configuration is not usable.")
+    _LOG.error("This is a CONFIGURATION problem, not a crash. Nothing is broken;")
+    _LOG.error("the add-on will start as soon as the settings below are fixed.")
+    _LOG.error("Fix them in Settings > Add-ons > GoodWe RS485 Controller >")
+    _LOG.error("Configuration, then start the add-on again.")
+    _LOG.error("-" * 72)
+    for i, problem in enumerate(problems, 1):
+        _LOG.error("  %d. %s", i, problem)
+    _LOG.error("=" * 72)

goodwe_controller/app/watchdog.py

@@ -0,0 +1,354 @@
+"""SAFETY-02 - the sign-disagreement watchdog.
+
+WHAT IT CATCHES, in one sentence: a grid-following loop that is pushing power in
+the wrong direction, which every other guard in this system is blind to.
+
+The stale-input watchdog (SAFETY-01) asks "is the meter still talking?". The
+saturation freeze asks "can the inverter follow?". The output clamp asks "is the
+number too big?". A loop can pass all three and still be charging the battery
+out of the grid while the house imports - the meter is fresh, the inverter is
+tracking beautifully, and the magnitude is inside the rating. The only thing
+that separates that from healthy operation is the SIGN.
+
+⚠️ THIS IS NOT A HYPOTHETICAL. On 2026-08-20 the vendor controller (Illusmart)
+did exactly this four times in one day (NOTES.md §4.7). Both captures of that
+bus are committed - `sim/scenarios/bus-2026-08-20.log.gz` and the healthy
+`bus-2026-08-23.log.gz` in the infra repo - and `sim/replay_sign.py` drives this
+module over both of them. Every number in this file was measured on those two
+days, not chosen:
+
+    day          samples gated in    sign agreement
+    2026-08-23   4 212 / 17 280      93.4 %   (healthy)
+    2026-08-20   7 182 / 17 280      56.4 %   (the whole fault day)
+      cluster A  15:26-16:43            0.3 %
+      cluster B  17:11-18:28            0.9 %
+      cluster C  20:01-20:31           10.5 %
+      cluster D  20:55-21:11            0.0 %
+
+⚠️ THOSE AGREEMENT FIGURES ARE THE WEAKEST EVIDENCE ON THIS PAGE, and an earlier
+version of this comment leaned on them as though they were the strongest. The
+clusters are found by looking for sustained opposed samples, so measuring "how
+opposed is this cluster" over them is close to a tautology - and "the healthy day
+contains no such cluster" is the same sentence as "the healthy day produces no
+trip", not independent corroboration of it.
+
+What actually carries the argument is two things neither the detector nor the
+clustering assumes:
+
+  1. The RUN-LENGTH DISTRIBUTION. The longest unbroken opposed run on the healthy
+     day is 30 s. On the fault day there are 18 runs over 180 s and the longest is
+     1750 s. Nothing about that gap was chosen - it is what the two days measure.
+  2. The clusters land where a human independently wrote down onsets. NOTES.md
+     §4.7 records 15:01, 16:56, 19:57 and 20:23 from watching it happen, before
+     any of this existed, and cluster D coincides with the separately documented
+     inverter-off runaway of §4.7 item 2.
+
+Be precise about (2), because the convenient overstatement is available and wrong:
+the clustering does NOT reproduce four episodes. It yields THREE clusters over the
+four documented onsets - C spans both 19:57 and 20:23 - plus a fourth for §4.7
+item 2, which is not one of the four. Every trip does fall inside a documented
+window, which is the claim worth making.
+
+------------------------------------------------------------------------------
+WHY IT LIVES HERE AND NOT IN THE FIRMWARE OR THE WITNESS
+
+Three vantage points see three different things. The firmware knows what it
+WROTE, the witness Pi knows what was ON THE WIRE and whether the inverter ACKed
+it, and the add-on knows what it INTENDED and holds the authoritative meter.
+
+This check is not command-versus-wire; it is command-versus-physics. It needs
+the emitted setpoint and the P1 net figure in the same place, and it needs the
+authority to command zero when they fight:
+
+  - the witness is read-only by charter and cannot command anything, so it could
+    raise the alarm but never take the trip action the AC requires;
+  - the firmware has the wire but not the meter. §5.1 makes P1 the only
+    authoritative grid figure and the board only ever receives its AGE
+    (`sensor.goodwe_p1_sample_age`), never its value. Putting the check there
+    would mean shipping the meter to the ESP32 for no other reason, and it would
+    be C++ per install rather than one generic guard;
+  - the add-on has both halves already, plus an arbiter that can outrank every
+    strategy with a P_SAFETY claim.
+
+The cost of standing here is real and worth stating: this watchdog compares what
+we MEANT to put on the wire against the meter. If the firmware or the driver
+inverts the sign on the way out, the add-on's own view still agrees with itself
+and this check stays silent. That gap is a wire-versus-intent problem and it
+belongs to the witness, not here.
+
+------------------------------------------------------------------------------
+WHAT "DISAGREEMENT" MEANS, PRECISELY
+
+    disagree = following
+               and commanded_w * grid_w < 0
+               and abs(commanded_w) > min_w
+               and abs(grid_w)      > min_w
+
+Four gates, and each one exists to exclude a specific thing that is NOT a fault:
+
+1. `following`. ⚠️ THE GATE THAT IS EASIEST TO FORGET AND MOST EXPENSIVE TO
+   OMIT. Sign agreement is a property of a GRID-FOLLOWING loop. It is not
+   expected of a strategy that deliberately commands against the meter -
+   maintenance is exactly that. A maintenance grid charge of 1500 W into a house
+   drawing 500 W puts +2000 W on the meter against a -1500 W command: opposed,
+   both far over any sane threshold, and sustained for HOURS. Armed
+   unconditionally this watchdog would trip on every single maintenance cycle,
+   which is not a tuning problem, it is the wrong question being asked. So the
+   caller says whether the grid-following loop actually won the arbitration this
+   cycle, and the timer only accumulates when it did.
+
+   ⚠️ 1500 W, NOT THE DEFAULT 2500 W, AND THE REASON IS NOT COSMETIC. At the
+   shipped defaults `maintenance_charge_w` is 2500 and `max_w` is 2000, so the
+   cheap-window claim is `hi = -2500` against a supervised `lo = -2000`: lo > hi,
+   which arbiter.py resolves as a CONTRADICTION and 0 W, not as a -2500 W charge.
+   The example above is written at 1500 W because that is a combination the
+   schema and the arbiter both actually produce. (The contradiction at the
+   defaults is a real pre-existing bug - a default maintenance charge silently
+   never happens in a cheap window - but it is maintenance's, not this module's,
+   and it is filed separately. Do not "fix" it here.)
+
+2. The strict `< 0` product. "Opposed" and "neither side is zero" in one
+   expression.
+
+3. The 300 W magnitude gate ON BOTH SIDES. Near zero the sign is noise, and near
+   zero is where a healthy loop LIVES - the deadband holds the command still
+   while the meter wanders either side of `target_grid_w`. On the healthy day
+   only 4 212 of 17 280 samples (24 %) are even gated in; the other 76 % are the
+   converged band where sign carries no information. This is also why the
+   deadband cannot produce a false trip: inside it the meter is by definition
+   under 300 W.
+
+4. The 180 s continuity requirement. This is what excludes the legitimate
+   transient. A load step reverses the meter's sign instantly while the command
+   is still where the last cycle left it; slew limiting then needs a few cycles
+   to cross over. Measured on the healthy day, the LONGEST such crossing is 30 s
+   - and that is with a vendor controller far cruder than ours. 180 s is six
+   times that. It is not a fitted threshold: at 60 s the healthy day still
+   produces zero trips, and at 300 s the fault day still produces 13.
+
+⚠️ A BATTERY THAT REFUSES A COMMAND CANNOT TRIP THIS, and that is structural
+rather than lucky. At SoC 10 % in Standby, a 1350 W discharge command into a
+1350 W import is DECLINED: the battery does nothing, so the meter stays at
++1350 W and the command stays at +1350 W. Same sign. Agreement. A refusal leaves
+the meter where it was; only the inverter ACTING moves it, and acting in the
+commanded direction moves it toward zero, not through it. The failure mode this
+check keys on is the opposite of a refusal - it is the inverter obediently doing
+a wrong thing.
+
+⚠️ A FROZEN METER cannot trip it either, for the same reason read the other way:
+a stuck reading of +800 W makes the loop command discharge and keep commanding
+discharge. Command and meter converge on AGREEING. Freezes are SAFETY-12's and
+SAFETY-01's problem, and this watchdog neither helps nor hinders there.
+
+⚠️ ALL OF THAT DEPENDS ON ONE PROPERTY OF THE CONTROL LAW, so it is an invariant
+and not a happy accident: the saturation freeze in control.py must keep letting
+the command FALL, CROSS ZERO AND REVERSE - "may not wind further in the direction
+it is already pushing", not "only corrections that shrink |i_w|". control.py
+records the shrink-only encoding as tried and rejected because it pins the command
+at its last value indefinitely; a pinned command against a meter that has moved on
+is precisely a sustained sign disagreement, so under that encoding this watchdog
+WOULD false-trip on a plain load step. If anyone ever revisits that freeze, this
+module's no-false-positive argument is downstream of the answer.
+
+------------------------------------------------------------------------------
+WHAT IT DOES NOT CATCH
+
+An inverter that ACTS opposite to what it was told. Tell it to discharge 2000 W
+and have it charge instead, and the meter moves FURTHER the way it was already
+going - so the command and the meter agree, all the way into the rail. This
+watchdog compares the loop's output direction against the input state it was
+regulating; it is blind to the plant lying about which way it went. That is the
+saturation freeze's question (|command - the battery's actual power| > 500 W,
+NOTES.md §4.7 row 4), and the two checks are complementary rather than
+overlapping. Neither substitutes for the other.
+
+Nor does it see a sign inversion introduced DOWNSTREAM of this add-on - in the
+firmware, on the wire, or in a future driver. Our view stays self-consistent and
+this stays silent. That is a wire-versus-intent problem and it belongs to the
+witness, which is the only vantage point that sees both.
+
+------------------------------------------------------------------------------
+STATE, TRIP AND LATCH
+
+One timestamp, not a sample counter. The cycle rate is not fixed - a meter
+arrival, or `cycle_floor_s` elapsing, whichever comes first - so N samples is a
+different wall-clock window on every path, and the AC is written in minutes.
+
+The latch is not optional and not a nicety. Commanding 0 W removes the command
+side of the comparison (|0| is not > 300), so the disagreement disappears the
+instant the trip works. Un-latched, this watchdog would trip, clear itself, and
+hand the actuator straight back to the loop that was driving the wrong way -
+three minutes later, forever. `tripped` therefore stays true until an operator
+`reset()`s it by starting control again, which is a deliberate human act after
+looking at why.
+
+⚠️ AND THE LATCH HAS TO OUTLIVE THE PROCESS. Held only in memory it is not a
+latch at all - a container restart clears it and the add-on comes back armed,
+into the same fault, unattended. Worse than merely losing state: "restart the
+add-on" is the first thing an operator confronted with a FAILSAFE banner and a
+0 W inverter will try, and under a supervisor that restarts a crashed add-on it
+is a loop of three-minute wrong-direction bursts. `tripped` and `reason` are
+therefore constructor arguments, restored from `Store` in `Controller.__init__`
+and written back the moment the trip happens. See store.py.
+"""
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class SignWatchdogConfig:
+    """Defaults, not constants - config.yaml carries both (SAFETY-02 AC 5)."""
+
+    min_w: float = 300.0
+    hold_s: float = 180.0
+
+
+def disagrees(commanded_w, grid_w, following: bool,
+              cfg: SignWatchdogConfig) -> bool:
+    """The predicate, and the ONLY place it is written down.
+
+    ⚠️ Public because `sim/replay_sign.py` needs it too - to describe episodes, to
+    measure agreement, to sweep the clock-skew guard - and it had reimplemented it
+    inline. Two copies of a safety predicate is one copy plus a future
+    disagreement about what the check means, and the copy that drifts is always
+    the one in the harness that grades it.
+    """
+    return (following
+            and commanded_w is not None and grid_w is not None
+            and commanded_w * grid_w < 0
+            and abs(commanded_w) > cfg.min_w
+            and abs(grid_w) > cfg.min_w)
+
+
+def loop_is_following(resolution, loop_asked) -> bool:
+    """Did the grid-following loop actually choose the number going on the wire?
+
+    Gate 1 of the predicate above, and it lives here rather than inline in
+    `cycle()` for the reason `disagrees()` does: the test suite has to be able to
+    assert on THE SHIPPED EXPRESSION, not on a transcription of it that drifts
+    apart from it in silence.
+
+    ⚠️ IT WAS A TRANSCRIPTION, AND THAT WAS MEASURED, NOT FEARED. The P_PEAK case
+    in test_watchdog.py exists to make whoever lands peak shaving come here and
+    change an expectation. With the expression copied into the test it did not do
+    that: editing the shipped gate alone to `winner in ("loop", "peak")` left every
+    suite green while the watchdog went blind for the whole of every peak event.
+    One definition, two callers, and that test now bites.
+
+    `resolution`  the arbiter's Resolution. Duck-typed on `.winner` and
+                  `.target_w` so this module still imports nothing from arbiter.
+    `loop_asked`  what the grid-following loop claimed this cycle, or None if it
+                  did not claim at all.
+
+    "The loop won" is NOT the question, and the difference is a whole class of
+    false trip. A LIMIT claim can survive the loop winning and still replace its
+    number: maintenance's cheap-window shaping is `hi = -maintenance_charge_w`, so
+    at 1500 W the loop can ask for +500 W of discharge, win the arbitration, and
+    have the emitted value come out at -1500 W of grid charge. Winner says "loop";
+    the wire carries maintenance's intent.
+
+    So the test is on the NUMBER: the loop is following only while the emitted
+    value points the way the loop asked AND is no larger than it asked - limits
+    reduced it, they did not redirect it. The magnitude half is load-bearing on
+    its own, because a `lo` limit can raise magnitude without flipping sign, and
+    that is not the loop following either. Zero on either side falls out as
+    not-following, which costs nothing: a 0 W command cannot be a
+    wrong-direction command.
+
+    ⚠️ FORWARD HAZARD, and the claim block in cycle() already anticipates it.
+    `winner == "loop"` disarms the watchdog under ANY higher-priority SET claim.
+    Today only maintenance and the safety stops emit one and neither follows the
+    meter, so the gate costs nothing. A peak-shaving strategy claiming SET at
+    P_PEAK **is** grid-following in sign, and the moment it lands this goes blind
+    for the duration of every peak event. Widening it means asking "does the
+    winning strategy follow the meter", not adding another name to a comparison.
+    """
+    return (resolution.winner == "loop" and loop_asked is not None
+            and resolution.target_w * loop_asked > 0
+            and abs(resolution.target_w) <= abs(loop_asked))
+
+
+class SignWatchdog:
+    """One instance per actuator, evaluated once per control cycle.
+
+    ⚠️ NOT SHARED ACROSS CADENCES. `disagree_since` is a wall-clock start time,
+    so driving one instance from two loops at two rates would have each one
+    resetting the other's window. If a fast on-device path ever wants this
+    check, it gets its own instance - the same exactly-one-writer discipline the
+    arbiter applies to the actuator, applied to the detector's own state.
+    """
+
+    def __init__(self, cfg: SignWatchdogConfig | None = None, *,
+                 tripped: bool = False, reason: str = ""):
+        self.cfg = cfg or SignWatchdogConfig()
+        self.disagree_since: datetime | None = None
+        # ⚠️ RESTORED FROM THE STORE, NOT DEFAULTED. A latch that lives only in
+        # memory is not a latch: a container restart clears it, and the add-on
+        # comes back armed, into the same fault, with no operator involved. See
+        # store.py's note on `sign_tripped` for the measured behaviour.
+        self.tripped = bool(tripped)
+        self.reason = reason if self.tripped else ""
+
+    # -- the whole check, and it is a pure function of its arguments ----------
+    def evaluate(self, commanded_w, grid_w, following: bool,
+                 now: datetime) -> bool:
+        """Advance the detector one cycle. Returns True while tripped.
+
+        `commanded_w`  the EMITTED setpoint - what is standing on the wire now,
+                       after deadband, slew, quantisation and the arbiter. Not
+                       the optimizer's raw wish: the wire carries the emitted
+                       value, so anything else can disagree with the meter for a
+                       reason that is not a fault.
+        `grid_w`       net P1, + = importing. None when the meter is stale or
+                       missing, which CLEARS the timer rather than accumulating
+                       - a frozen figure held against a moving command would
+                       otherwise manufacture a disagreement in about three
+                       minutes, on top of SAFETY-01 having already commanded
+                       zero for the same cause.
+        `following`    did the grid-following loop actually win this cycle? See
+                       gate 1 in the module docstring.
+        `now`          the caller's clock, so this stays testable and replayable.
+        """
+        if self.tripped:
+            # Latched. Do not re-evaluate: the trip removed the evidence.
+            return True
+
+        cfg = self.cfg
+        if not disagrees(commanded_w, grid_w, following, cfg):
+            self.disagree_since = None
+            return False
+
+        if self.disagree_since is None:
+            self.disagree_since = now
+            return False
+
+        held = (now - self.disagree_since).total_seconds()
+        if held < cfg.hold_s:
+            return False
+
+        self.tripped = True
+        self.reason = (
+            f"SIGN_DISAGREEMENT: commanded {commanded_w:+.0f} W against a meter "
+            f"reading {grid_w:+.0f} W for {held:.0f} s continuously "
+            f"(limits: both over {cfg.min_w:.0f} W, held over {cfg.hold_s:.0f} s)"
+        )
+        return True
+
+    def held_s(self, now: datetime) -> float:
+        """How long the current disagreement has been standing, for the UI.
+
+        ⚠️ Takes the clock rather than reading one. It was a property calling
+        `datetime.now()`, which quietly broke the property this module's header
+        advertises - every other observable here is a pure function of what it
+        was handed - and an unclocked function is one nothing can test, which is
+        exactly what happened to it.
+        """
+        if self.disagree_since is None:
+            return 0.0
+        return (now - self.disagree_since).total_seconds()
+
+    def reset(self) -> None:
+        self.disagree_since = None
+        self.tripped = False
+        self.reason = ""

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.3.0"
+version: "0.5.2"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -42,11 +42,24 @@ options:
   # --- P1 meter ingestion (specs §5.2 / §14 `meter:`) -------------------------
   # `off` keeps the original single meter_entity path above, so an existing
   # install is untouched until it opts in. ha_dsmr subscribes to the DSMR
-  # integration's entities over the HA WebSocket; mqtt_p1 reads the topic below.
+  # integration's entities over the HA WebSocket; mqtt_p1 reads the topic below;
+  # ha_signed reads ONE signed HA entity (+ import / - export), which is what a
+  # HomeWizard P1 publishes and what ha_dsmr cannot consume.
+  # homewizard_local skips Home Assistant entirely and polls the meter's own
+  # local API. ⚠️ It is the ONLY mode whose sensor.p1_sample_age_s measures when
+  # the meter REPORTED rather than when the value last CHANGED - HA emits
+  # nothing at all for a repeated reading - so it is the only mode a firmware
+  # watchdog may threshold. See DOCS.md.
   meter_source: "off"
   meter_phases: 1
   meter_max_age_s: 30
   meter_mqtt_topic: ""
+  # homewizard_local only. The meter's own address, `host` or `host:port`.
+  p1_host: ""
+  # homewizard_local only. Seconds between polls. Must be well under
+  # meter_max_age_s - the age is never fresher than this interval - and there is
+  # nothing to gain below the meter's own ~5.0 s update rate (NOTES.md:640).
+  meter_poll_s: 5
   # The two UNSIGNED Belgian registers. The EMS derives net power from them
   # (import - export); do NOT point these at a signed template sensor.
   p1_import_entity: ""
@@ -55,6 +68,15 @@ options:
   # three-phase connection; the list length must equal meter_phases.
   p1_phase_import_entities: []
   p1_phase_export_entities: []
+  # ha_signed only. ONE signed net-power sensor: positive = import from the
+  # grid, negative = export to it. Do NOT split it into two template sensors -
+  # the split is done in the add-on (p1.split_signed) precisely so the sign
+  # convention is tested rather than living in unreviewed YAML.
+  p1_net_entity: ""
+  # Optional, in L1..L3 order, each one signed the same way. Same role as
+  # p1_phase_import_entities: the capacity-tariff peak on a three-phase
+  # connection. The list length must equal meter_phases.
+  p1_phase_net_entities: []
 
   # --- control ---------------------------------------------------------------
   max_w: 2000
@@ -68,14 +90,71 @@ options:
   integrator_max_w: 0
   heartbeat_s: 10
   stale_input_s: 15
+  cycle_floor_s: 15
   auto_start: false
 
+  # --- SAFETY-02 sign-disagreement watchdog ----------------------------------
+  # Trips when the emitted setpoint and the P1 net figure point OPPOSITE ways,
+  # both over sign_disagree_w, continuously for sign_disagree_s. Action: 0 W and
+  # a failsafe that latches until an operator starts control again.
+  #
+  # Both defaults are measured, not chosen. On the captured healthy day
+  # (2026-08-23) the longest legitimate opposed run - a load step the loop has
+  # not caught up with - is 30 s, and sign agreement over the gated samples is
+  # 93.4 %. On the captured fault day (2026-08-20) the clusters run 0.0-10.5 %
+  # agreement with opposed runs up to 1752 s. 300 W / 180 s sits in the middle of
+  # a very wide gap: at 60 s the healthy day still trips nothing, at 300 s the
+  # fault day still trips 13 times. There is no reason to move either number
+  # without a capture that says so. They are options because the AC says
+  # thresholds are defaults rather than constants - not because they are knobs
+  # anyone is expected to turn.
+  #
+  # ⚠️ sign_disagree_w must stay BELOW max_w or the watchdog can never fire (the
+  # arbiter bounds the command to +-max_w). validate.py refuses that config.
+  sign_disagree_w: 300
+  sign_disagree_s: 180
+
+  # --- SAFETY-18 frozen-but-fresh meter detector -----------------------------
+  # Seconds the meter may keep answering with an UNCHANGED measurement while the
+  # command stands at the rail before the add-on raises an alarm. Both halves
+  # are required: neither one alone is safe, and app/freeze.py carries why.
+  #
+  # ALARM ONLY. It does not command 0 W and does not latch. A false trip parks
+  # the battery; a false notification costs an alert.
+  #
+  # ⚠️ Only `meter_source: homewizard_local` can see this at all - it is the
+  # only transport that reads the meter's own document. On every other source
+  # the status page says NOT COVERED rather than "armed".
+  #
+  # 300 s is measured, not chosen. Over 2399 s of the live house at the
+  # converged operating point (sim/scenarios/p1-age-2026-08-26.jsonl.gz, mean
+  # grid -14.2 W, 1194 polls, 735 of them repeating the previous reading) the
+  # LONGEST run without a distinct reading is 15.4 s (the largest unchanged_s any
+  # sample observes is 8.0 s). 300 s is 19.5x the pessimistic figure, and
+  # still inside the 900 s quarter that bills the capacity tariff.
+  meter_freeze_s: 300
+
   # --- maintenance -----------------------------------------------------------
   maintenance_enabled: false
   maintenance_interval_days: 28
   maintenance_start_hour: 10
-  maintenance_discharge_w: 2500
-  maintenance_charge_w: 2500
+  # ⚠️ BOTH MUST STAY AT OR BELOW max_w, and that is why they are 2000 rather
+  # than the 2500 they shipped as. The cheap-window charge shaping asks the
+  # arbiter for `hi = -maintenance_charge_w` against the supervised `lo =
+  # -max_w`: above the ceiling that is `lo > hi`, a contradiction resolved to
+  # 0 W, so maintenance would SILENTLY NEVER CHARGE in a cheap window on a
+  # default install. validate.py refuses that config (rule 6), so these
+  # defaults had to become self-consistent with the max_w above rather than
+  # ship a configuration the validator rejects.
+  #
+  # The discharge side is clamped rather than contradicted - it drains at max_w
+  # and the arbiter says so - so it is only warned about; it is 2000 here for
+  # symmetry and to keep the shipped config warning-free.
+  #
+  # Raising max_w (the live reference install runs 5000) is what unlocks a
+  # faster maintenance cycle. Raise max_w FIRST, then these.
+  maintenance_discharge_w: 2000
+  maintenance_charge_w: 2000
   maintenance_soc_floor: 11
   maintenance_soc_target: 99
   maintenance_hold_min: 120
@@ -83,9 +162,84 @@ options:
   # --- tariff / capacity tariff (all optional) ------------------------------
   peak_forecast_entity: ""
   peak_cap_w: 3500
+
+  # ⚠️ THE OLD PRICE PATH, AND IT IS NOT DEAD YET. These two entities are the
+  # add-on delegating the whole price question to Home Assistant: main.py reads
+  # both and derives ONE BOOLEAN, `cheap = now <= avg`, which is consumed by
+  # nothing except the maintenance cycle's cheap-window charge floor. That is
+  # all they have ever done. They are kept, because retiring them would take
+  # the maintenance cycle's only price signal away on a live install before
+  # anything replaces it - TARIFF-03 (static profile) and OPT-04 (arbitrage)
+  # are the cards that replace it, and neither has landed.
+  #
+  # ⚠️ They may NOT be combined with price_provider below. Two price sources on
+  # one site, one of which silently wins, is exactly the "double up" the PM
+  # named; validate.py rule 7 refuses that configuration at startup rather than
+  # letting an operator believe the provider they configured is driving
+  # something. See app/validate.py.
   price_now_entity: ""
   price_avg_entity: ""
 
+  # --- price providers (TARIFF-02, specs §9.3 / §14 `tariffs:`) --------------
+  # `off` is the shipped default and means the §11.4 no-price-data row applies:
+  # static profile, plan provisional, NO ARBITRAGE. Nothing in 0.5.x consumes
+  # the series yet - OPT-04 is the consumer - so turning this on today fetches,
+  # validates and publishes prices and changes no energy decision.
+  #
+  # ⚠️ THESE DEFAULTS ARE MIRRORED ONCE, IN app/price.py's
+  # PRICE_OPTION_DEFAULTS, and test_price.py reads THIS FILE and asserts the two
+  # agree key for key. Do not add a third copy in main.py - CFG-03 is open
+  # because that has already happened three times.
+  #
+  # markup/taxes are the §14 `tariffs.energy_price.*` figures and are added by
+  # the FRAMEWORK, only for the components the chosen plugin declares its feed
+  # does not already contain. engie_dynamic, totalenergies_dynamic, eneco_eddy
+  # and manual_csv publish a figure that already carries the markup, so setting
+  # it under those is ignored - and logged as ignored, never applied twice.
+  price_provider: "off"
+  price_markup_eur_kwh: 0.03
+  price_taxes_eur_kwh: 0.06
+  price_csv_path: "/share/goodwe_prices.csv"
+  price_feed_url: ""
+  price_horizon_h: 48
+  price_timeout_s: 10
+
+  # --- static / fully-fixed tariffs (TARIFF-03, specs §9.2 / §11.4) ----------
+  # §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".
+  #
+  # A JSON object, on one line, whose periods must tile every day type exactly
+  # once - no gap and no overlap. A gap is REFUSED at startup rather than
+  # defaulted, because an invented price is one an optimiser would trade on.
+  # A fully-fixed tariff is ONE period covering 00:00-24:00, all days; the
+  # add-on derives "fixed" from there being one distinct price, so there is no
+  # box to tick and none to tick wrongly.
+  #
+  #   {"periods": [
+  #      {"name":"day",  "from":"07:00","to":"22:00","days":"mon-fri","eur_per_kwh":0.34},
+  #      {"name":"night","from":"22:00","to":"07:00","days":"mon-fri","eur_per_kwh":0.26},
+  #      {"name":"night","from":"00:00","to":"24:00","days":"sat,sun", "eur_per_kwh":0.26}]}
+  #
+  # ⚠️ A window written "22:00-07:00 mon-fri" does NOT cover Saturday morning -
+  # a period applies on the day the CLOCK reads, so the weekend row above is
+  # required, not decorative. See DOCS.md.
+  #
+  # eur_per_kwh is ALL-IN (energy + markup + taxes, §9.3), the same basis the
+  # dynamic providers are assembled onto. price_markup_eur_kwh and
+  # price_taxes_eur_kwh are NOT added to it.
+  #
+  # ⚠️ RECOMMENDED EVEN ON A DYNAMIC SITE. §11.4's degradation row is "no price
+  # data -> fall back to the static profile"; with this empty there is nothing
+  # to fall back to and a dead feed leaves the site with no tariff at all.
+  # validate.py warns about exactly that.
+  static_profile: ""
+
+  # §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.
+  export_price_eur_kwh: 0.04
+
   # --- site ------------------------------------------------------------------
   estop_fitted: false
   log_level: info
@@ -98,20 +252,25 @@ schema:
   batt_invert: bool
   setpoint_entity: str
 
-  meter_source: list(off|ha_dsmr|mqtt_p1)
+  meter_source: list(off|ha_dsmr|mqtt_p1|ha_signed|homewizard_local)
   # ⚠️ 2 is accepted by this range but is not a real Belgian connection. A
   # telegram whose phase count disagrees is rejected at ingest and logged, so a
   # mis-set 2 shows up immediately as "0 telegrams accepted" rather than as a
   # quietly wrong number.
   meter_phases: int(1,3)
   meter_max_age_s: int(5,300)
+  meter_poll_s: int(1,60)
   meter_mqtt_topic: str?
+  p1_host: str?
   p1_import_entity: str?
   p1_export_entity: str?
   p1_phase_import_entities:
     - str
   p1_phase_export_entities:
     - str
+  p1_net_entity: str?
+  p1_phase_net_entities:
+    - str
 
   max_w: int(100,5000)
   gain: float(0.05,1.0)
@@ -124,8 +283,23 @@ schema:
   integrator_max_w: int(0,15000)
   heartbeat_s: int(2,25)
   stale_input_s: int(5,120)
+  cycle_floor_s: int(5,60)
   auto_start: bool
 
+  # No "off" value, deliberately: this is a P0 safety check and the schema is
+  # not the place to make disarming it a supported configuration.
+  sign_disagree_w: int(50,5000)
+  sign_disagree_s: int(30,1800)
+
+  # No "off" value, for SAFETY-02's reason: disarming a safety alarm is not a
+  # supported configuration. ⚠️ THE FLOOR OF 60 IS NOT A RECOMMENDATION. At 300 s
+  # the slowest a HEALTHY meter's 1 Wh register can tick and still look unchanged
+  # is 12 W, which is inside the 15 W deadband, so the two terms of the
+  # conjunction are mutually exclusive rather than merely far apart. At 60 s that
+  # figure is 60 W and the argument is gone - only the margin is left. See
+  # app/freeze.py.
+  meter_freeze_s: int(60,3600)
+
   maintenance_enabled: bool
   maintenance_interval_days: int(1,90)
   maintenance_start_hour: int(0,23)
@@ -140,5 +314,28 @@ schema:
   price_now_entity: str?
   price_avg_entity: str?
 
+  # ⚠️ The provider list is written out rather than left as `str`, so the
+  # Supervisor rejects a typo in the UI. validate.py ALSO refuses an unknown id
+  # against app/price.py's PROVIDERS registry, because sim/inject.py and the
+  # checks reach validate_startup_config() with a dict the Supervisor never saw.
+  # Adding a sixth plugin means adding it here and to PROVIDERS - and nowhere
+  # else, which is AC2.
+  price_provider: list(off|generic_dayahead|engie_dynamic|totalenergies_dynamic|eneco_eddy|manual_csv)
+  price_markup_eur_kwh: float(0,1)
+  price_taxes_eur_kwh: float(0,1)
+  price_csv_path: str?
+  price_feed_url: str?
+  price_horizon_h: int(1,72)
+  price_timeout_s: int(2,60)
+  # 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?
+  # ⚠️ The lower bound is NEGATIVE on purpose. Belgian injection tariffs have
+  # gone below zero (you pay to export at midday in summer), and a schema that
+  # bottoms out at 0 would make that site inexpressible.
+  export_price_eur_kwh: float(-1,1)
+
   estop_fitted: bool
   log_level: list(trace|debug|info|warning|error)

goodwe_controller/test_clamp.py

@@ -0,0 +1,550 @@
+"""Runnable check for SAFETY-03, the output clamp and its winding-loop alarm.
+
+    python3 test_clamp.py
+
+No framework, asserts only, same house style as test_freeze.py.
+
+Five parts, and parts 3 and 4 are the ones that carry the acceptance criteria:
+
+  1. THE CLAMP ARITHMETIC, on the shipped `clamp_to_rating()` - boundaries,
+     symmetry, the device second stage, and the non-finite cases. Table driven.
+  2. THE ALARM'S CADENCE - rising edge, re-assert, hysteresis - on the shipped
+     `ClampWatchdog`. Every engagement counted, notifications not flooded.
+  3. AC 1 + AC 3, WIRED. A computed setpoint that exceeds the rating, driven
+     through the REAL `Controller.cycle()`: nothing over the rating reaches the
+     device, and the alarm fires. Includes the historical runaway from
+     specs.md 10.3 replayed against an unclamped transcription, so the check
+     says what the clamp is actually worth in watts rather than asserting a
+     constant.
+  4. AC 2, AND IT IS THE LOAD-BEARING HALF. A loop that SATURATES WITHOUT
+     CLAMPING - the inverter refusing to follow a perfectly legal command - must
+     raise NO clamp alarm. If it does, the bug signal is inside the noise again
+     and the whole ticket has bought nothing.
+  5. NO PATH BYPASSES IT. write_setpoint() is the only route to the wire, so it
+     is called directly with an out-of-range value the way the heartbeat and the
+     operator's buttons call it.
+
+------------------------------------------------------------------------------
+WHY PART 4 ALSO ASSERTS ON `Decision`'s BOOLEANS AND NOT ON `reason`
+
+`Decision.reason` is one string and the stages after the clamp overwrite it. The
+check below drives a cycle that clamps the integrator AND is then slew limited,
+and asserts that `reason` does NOT say so while `i_clamped` does. That is not a
+style preference - an alarm keyed on the string is silent on exactly the cycles a
+winding loop produces, and this is the check that would go red if someone
+"simplified" main.py back onto it.
+
+------------------------------------------------------------------------------
+WHAT THIS CHECK DOES NOT COVER
+
+- The firmware-side magnitude clamp (the card's "two clamps, not one"). This
+  add-on's `write_setpoint()` is the add-on half; the ESP32 half is DRIVER-07's
+  and is not in this repo's Python.
+- A rig run. Nothing here needs one: the clamp is arithmetic on the write path
+  and part 3 drives the shipped `Controller.cycle()` against a stub Home
+  Assistant, which is the same surface test_freeze.py part 1-2 use. The wire-
+  level invariant the card asks for (`|emitted| <= rating` on every frame) is
+  asserted here over every value that reached `set_number()`, which is the last
+  thing this process controls; proving it at the inverter needs the witness log
+  and belongs with DRIVER-07.
+"""
+
+import asyncio
+import math
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app.clamp import (
+    CLEAR_CYCLES, REASON_CODE, REASSERT_S, ClampWatchdog, clamp_to_rating,
+    is_commandable,
+)
+from app.control import Tuning, compute
+from app.main import Controller
+
+fails = []
+T0 = datetime(2026, 8, 30, 9, 0, 0, tzinfo=timezone.utc)
+
+# The live install's numbers. NOTES.md and freeze.py both say max_w: 5000 there,
+# which is also the device rating, so this is the bound the alarm is written at.
+LIVE_MAX_W = 5000.0
+CLAMP_ID = "goodwe_output_clamp"
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+# ==============================================================================
+print("1. the clamp arithmetic, on the shipped expression")
+
+# (requested, limit, expected applied, expected engaged, expected bound)
+TABLE = [
+    (5001.0, 5000.0, 5000.0, True, "max_w"),      # +limit+1
+    (-5001.0, 5000.0, -5000.0, True, "max_w"),    # -limit-1, the export side
+    (5000.0, 5000.0, 5000.0, False, ""),          # exactly +limit: NOT engaged
+    (-5000.0, 5000.0, -5000.0, False, ""),        # exactly -limit: NOT engaged
+    (0.0, 5000.0, 0.0, False, ""),                # the failsafe value
+    (1234.0, 5000.0, 1234.0, False, ""),
+    (14768.0, 5000.0, 5000.0, True, "max_w"),     # 10.3's reported runaway
+]
+for requested, limit, want_applied, want_engaged, want_bound in TABLE:
+    r = clamp_to_rating(requested, limit)
+    check(f"{requested:+.0f} W against a {limit:.0f} W rating -> "
+          f"{r.applied_w:+.0f} W, engaged={r.engaged}, bound={r.bound!r}",
+          r.applied_w == want_applied and r.engaged is want_engaged
+          and r.bound == want_bound)
+
+# It is a MAGNITUDE clamp (3.2), so import and export must be bound identically.
+# Derived over a sweep rather than asserted on two hand-picked values.
+asym = [m for m in range(0, 12001, 37)
+        if clamp_to_rating(m, LIVE_MAX_W).applied_w
+        != -clamp_to_rating(-m, LIVE_MAX_W).applied_w]
+check(f"symmetric over {len(range(0, 12001, 37))} magnitudes "
+      f"({len(asym)} asymmetric)", not asym)
+
+# The engagement flag has to mean "the RAW value differed", which is the words
+# AC 2 uses. Re-derived from the result's own fields, not from the table.
+mismatch = [m for m in range(0, 12001, 37)
+            for r in [clamp_to_rating(m, LIVE_MAX_W)]
+            if r.engaged != (r.requested_w != r.applied_w)]
+check("engaged is exactly 'raw differs from applied', over the same sweep",
+      not mismatch)
+
+# The device second stage. Only reachable when max_w is ABOVE the device range,
+# i.e. when validate_startup_config() did not run or no longer holds.
+r = clamp_to_rating(3000.0, 5000.0, dev_min=-2000.0, dev_max=2000.0)
+check(f"a device narrower than max_w still bites, and says which bound "
+      f"({r.applied_w:+.0f} W, {r.bound!r})",
+      r.applied_w == 2000.0 and r.engaged and r.bound == "device")
+r = clamp_to_rating(3000.0, 5000.0, dev_min=-5000.0, dev_max=5000.0)
+check("...and is a no-op once the startup validation holds",
+      r.applied_w == 3000.0 and not r.engaged)
+
+# ⚠️ REGRESSION, REVIEW-FOUND. THE FIRST STAGE USED TO `return` AND THE DEVICE
+# STAGE WAS THEN NEVER REACHED, so the harder the overshoot the less the guard
+# did: at max_w 5000 against a +-4000 device, +9999 emitted +5000 - OUTSIDE THE
+# DEVICE RANGE - while a mere +4500 was correctly held to +4000. That inverts
+# the guard and it was a regression against the pre-PR `write_setpoint()`, whose
+# comment read "never send a value the device will reject outright".
+#
+# The property is asserted over a sweep, not on the two witness values, because
+# the defect was invisible to every single-value check that happened to sit
+# inside one stage.
+DEV_LO, DEV_HI = -4000.0, 4000.0
+escapes = [(m, clamp_to_rating(m, 5000.0, DEV_LO, DEV_HI).applied_w)
+           for m in range(-15000, 15001, 61)
+           for a in [clamp_to_rating(m, 5000.0, DEV_LO, DEV_HI).applied_w]
+           if not (DEV_LO <= a <= DEV_HI)]
+big = clamp_to_rating(9999.0, 5000.0, DEV_LO, DEV_HI)
+small = clamp_to_rating(4500.0, 5000.0, DEV_LO, DEV_HI)
+print(f"    max_w 5000 vs a device of {DEV_LO:+.0f}..{DEV_HI:+.0f}: "
+      f"+9999 -> {big.applied_w:+.0f} W ({big.bound}), "
+      f"+4500 -> {small.applied_w:+.0f} W ({small.bound})")
+check(f"BOTH stages always run - {big.requested_w:+.0f} W emits "
+      f"{big.applied_w:+.0f} W, inside the device's {DEV_HI:+.0f} W, and names "
+      f"both bounds ({big.bound!r})",
+      big.applied_w == DEV_HI and big.bound == "max_w+device")
+check(f"...and it holds over the whole range, so no overshoot escapes the "
+      f"device ({len(escapes)} escapes in {len(range(-15000, 15001, 61))})",
+      not escapes)
+check("...a big overshoot is not clamped LESS than a small one",
+      abs(big.applied_w) <= abs(small.applied_w) + 0.0)
+
+print("   non-finite input is loss of input, not an out-of-range value")
+for bad in (None, float("nan"), float("inf"), float("-inf"), "abc", object()):
+    check(f"is_commandable({bad!r:.30}) is False", is_commandable(bad) is False)
+for good in (0, -5000.0, 5000, 12.5):
+    check(f"is_commandable({good!r}) is True", is_commandable(good) is True)
+
+# ⚠️ WHY THAT GUARD EXISTS, AND THE ANSWER IS WORSE THAN "it passes a nan
+# through". MEASURED HERE, not recalled: every comparison against a nan is
+# False, so `min(limit, nan)` keeps its FIRST argument and a naive clamp turns a
+# nan into a command at the FULL RATING - and then reports engaged=True, because
+# limit != nan, so the winding-loop counter gets a transport bug filed in it.
+# The number below is computed by the same expression the guard replaces.
+nan = float("nan")
+naive = max(-LIVE_MAX_W, min(LIVE_MAX_W, nan))
+check(f"a naive clamp turns a nan into {naive:+,.0f} W and calls it "
+      f"engaged={naive != nan} - hence the guard",
+      naive == LIVE_MAX_W and (naive != nan) is True)
+
+
+# ==============================================================================
+print()
+print("2. the alarm's cadence: every engagement counted, no flood")
+
+wd = ClampWatchdog()
+t = T0
+fired = [wd.note(True, "winding", t + timedelta(seconds=i)) for i in range(10)]
+check(f"the rising edge fires ({fired[0]})", fired[0] is True)
+check(f"the next 9 one-second cycles fire {sum(fired[1:])} more times "
+      f"(re-assert is {REASSERT_S:.0f} s)", sum(fired[1:]) == 0)
+check(f"but every one of them is counted: engagements={wd.engagements}",
+      wd.engagements == 10)
+check(f"and it is one episode, not ten: episodes={wd.episodes}",
+      wd.episodes == 1)
+
+# --- THE RE-ASSERT CADENCE, PINNED IN BOTH DIRECTIONS ------------------------
+# ⚠️ REVIEW-FOUND. This used to read `wd.note(True, ..., T0 + REASSERT_S + 9)`,
+# which is green for ANY value of the constant - REASSERT_S = 3600 passed, and an
+# hour of silence is precisely what the module promises not to do. A check whose
+# stimulus is written in terms of the constant it is grading cannot grade it.
+#
+# The requirements are stated in wall-clock seconds and derived from what the
+# alarm is FOR, so they do not move when the constant does:
+#
+#   floor - a loop pinned on the rail must speak at least MIN_PER_QUARTER times
+#           inside the 900 s quarter that bills the capacity tariff. That window
+#           is the same one freeze.py and DOCS.md reason about.
+#   ceiling - it must not speak on more than MAX_FRACTION of cycles, or it is
+#           the per-cycle flood the split exists to remove.
+QUARTER_S = 900.0
+MIN_PER_QUARTER = 5
+MAX_FRACTION = 0.20
+
+pinned = ClampWatchdog()
+alarms = sum(1 for i in range(int(QUARTER_S))
+             if pinned.note(True, "pinned", T0 + timedelta(seconds=i)))
+print(f"    pinned on the rail for {QUARTER_S:.0f} s at 1 s cycles: "
+      f"{pinned.engagements} engagements, {alarms} alarm(s) "
+      f"({alarms / QUARTER_S:.1%} of cycles)")
+check(f"a loop pinned for a whole billing quarter speaks at least "
+      f"{MIN_PER_QUARTER} times (it spoke {alarms})",
+      alarms >= MIN_PER_QUARTER)
+check(f"...and on no more than {MAX_FRACTION:.0%} of cycles (it was "
+      f"{alarms / QUARTER_S:.1%})", alarms <= MAX_FRACTION * QUARTER_S)
+check("...while every single cycle is still counted",
+      pinned.engagements == int(QUARTER_S))
+
+# --- THE HYSTERESIS, PINNED AGAINST THE CHATTER DIRECTION --------------------
+# ⚠️ REVIEW-FOUND. This used to issue `range(CLEAR_CYCLES - 1)` clean cycles,
+# which at CLEAR_CYCLES = 1 issues ZERO of them and passes while printing
+# "0 clean cycles do NOT clear it". Green for every value >= 1 - including 1,
+# which IS the chatter the constant exists to prevent. The stimulus is a literal
+# now: ONE clean cycle must not clear the alarm, whatever the constant says.
+wd2 = ClampWatchdog()
+wd2.note(True, "winding", T0)
+wd2.note(False, "", T0 + timedelta(seconds=1))
+check(f"ONE clean cycle does NOT clear the alarm (active={wd2.active}) - "
+      f"a command dithering across the rail must not chatter",
+      wd2.active is True)
+survived = 1
+while wd2.active and survived < 50:
+    wd2.note(False, "", T0 + timedelta(seconds=1 + survived))
+    survived += 1
+print(f"    it took {survived} consecutive clean cycles to de-assert "
+      f"(CLEAR_CYCLES = {CLEAR_CYCLES})")
+check(f"...and it does de-assert, after {survived} of them, rather than "
+      f"latching", wd2.active is False and survived == CLEAR_CYCLES)
+check("...and the engagement count survives the clear, so the evidence does",
+      wd2.engagements == 1)
+check("a clean cycle on an idle watchdog says nothing",
+      wd2.note(False, "", T0 + timedelta(seconds=300)) is False)
+
+
+# ==============================================================================
+print()
+print("3. AC 1 + AC 3, wired: over the rating both clamps AND alarms")
+
+
+class _Store:
+    data = {}
+
+    def set(self, *a):
+        pass
+
+    def get_time(self, *a):
+        return None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    """Stub HA. `track` False models an inverter that is switched off entirely,
+    which is the 10.3 runaway's own setup."""
+
+    def __init__(self, grid, batt=0.0, track=True):
+        self.grid = grid
+        self.batt = batt
+        self.track = track
+        self.calls = []
+        self.writes = []
+
+    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, "sensor.soc": 50.0,
+                "sensor.batt": self.batt}.get(entity)
+
+    async def set_number(self, entity, value):
+        self.writes.append(float(value))
+        if self.track:
+            self.batt = float(value)
+        return True
+
+    async def call(self, domain, service, data):
+        self.calls.append((domain, service, data))
+        return True
+
+
+def wired(grid, cycles=40, batt=0.0, track=True, **over):
+    async def go():
+        hass = _Hass(grid, batt=batt, track=track)
+        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},
+            **over), hass, _Store(), _Pub(), stop=asyncio.Event())
+        c.auto = True
+        c.dev_min, c.dev_max = -LIVE_MAX_W, LIVE_MAX_W
+        # The red status row exists only WHILE the clamp is engaged, and the
+        # hysteresis clears it a few cycles later - so it is captured live
+        # rather than looked for after the run, when it is correctly gone.
+        c.red_snapshot = []
+        for _ in range(cycles):
+            await c.read_inputs()
+            await c.cycle()
+            if c.clamp_wd.active and not c.red_snapshot:
+                c.red_snapshot = c.checks()
+        return hass, c
+    return asyncio.run(go())
+
+
+def clamp_notes(hass):
+    return [d for dom, svc, d in hass.calls
+            if (dom, svc) == ("persistent_notification", "create")
+            and d.get("notification_id") == CLAMP_ID]
+
+
+# THE 10.3 RUNAWAY, replayed. "With the inverter switched off entirely, an
+# unclamped integrator climbed ~130 W per 4 s to over 10 kW and, pinned at the
+# 5 kW rail, reported 14 768 W." `track=False` is the inverter switched off: it
+# reports 0 W however hard it is commanded, so the error never closes.
+hass_r, ctl_r = wired(6000.0, cycles=60, track=False)
+emitted = [abs(w) for w in hass_r.writes]
+
+# What the SAME error would have done to an accumulator with no bound - the
+# transcription is deliberately the unclamped velocity form 10.3 describes, so
+# the figure below is computed here and not quoted from the spec.
+runaway, err = 0.0, 6000.0
+for _ in range(60):
+    runaway += 0.6 * err
+print(f"    unclamped, the same 60 cycles reach {runaway:,.0f} W; "
+      f"the largest value that reached the device is {max(emitted):,.0f} W")
+check(f"an unbounded accumulator really does run away here "
+      f"({runaway:,.0f} W >> {LIVE_MAX_W:.0f} W)", runaway > 3 * LIVE_MAX_W)
+check(f"AC 1: NOT ONE of the {len(emitted)} values that reached the device "
+      f"exceeds the {LIVE_MAX_W:.0f} W rating",
+      emitted and max(emitted) <= LIVE_MAX_W)
+# ⚠️ AND THE CLAMP IS NOT THE ONLY THING HOLDING THAT LINE HERE, which is worth
+# saying out loud rather than letting the number above imply otherwise. Against
+# an inverter reporting 0 W the saturation freeze engages after
+# `saturation_cycles` and pins the command well BELOW the rail - that is why the
+# largest emitted value is what it is and not 5000 W. The clamp is what makes it
+# bounded; the freeze is what makes it small. A check that read
+# `max(emitted) == max_w` would have been asserting the freeze, not the clamp.
+check(f"...and the saturation freeze is what pins it at {max(emitted):,.0f} W "
+      f"rather than the rail", ctl_r.sat_count >= ctl_r.tuning.saturation_cycles)
+
+notes_r = clamp_notes(hass_r)
+print(f"    the loop clamped on {ctl_r.clamp_wd.engagements} of {60} cycles, "
+      f"in {ctl_r.clamp_wd.episodes} episode(s), raising {len(notes_r)} "
+      f"notification(s)")
+check("AC 3: and it ALARMED - silently clipping this is the defect",
+      ctl_r.clamp_wd.engagements > 0 and len(notes_r) >= 1)
+check("...with its own notification_id, not shared with any other guard",
+      all(d["notification_id"] == CLAMP_ID for d in notes_r))
+check("...one episode, re-asserted rather than one per cycle",
+      ctl_r.clamp_wd.episodes == 1 and len(notes_r) < ctl_r.clamp_wd.engagements)
+check("...and it names itself a bug signal, not a limit in use",
+      bool(notes_r) and "out of range" in notes_r[0]["message"])
+rows_r = [e for e in ctl_r.events if REASON_CODE in e]
+check(f"the action log records every engagement, coalesced into one row per "
+      f"episode ({len(rows_r)} row(s), {ctl_r.clamp_wd.engagements} "
+      f"engagement(s))",
+      len(rows_r) == ctl_r.clamp_wd.episodes
+      and f"{ctl_r.clamp_wd.engagements} engagement(s)" in rows_r[0])
+
+# ⚠️ REGRESSION, AND IT WAS A REAL BUG BEFORE IT WAS A CHECK. `log_event()` keeps
+# 40 rows. A row per engagement flushes that ring inside 40 cycles of a winding
+# loop, and the first thing it evicted was SAFETY-18's own "METER FROZEN?" row -
+# i.e. this guard silencing another guard's log. Driven here with a plant that
+# TRACKS the command, so the saturation freeze never engages and the integrator
+# clamps on essentially every cycle.
+hass_l, ctl_l = wired(9000.0, cycles=80, track=True)
+rows_l = [e for e in ctl_l.events if REASON_CODE in e]
+other_l = [e for e in ctl_l.events if REASON_CODE not in e]
+print(f"    80 winding cycles: {ctl_l.clamp_wd.engagements} engagement(s) -> "
+      f"{len(rows_l)} log row(s), leaving room for {len(other_l)} other event(s)")
+check(f"a long winding episode does NOT flood the 40-row event log "
+      f"({len(rows_l)} rows for {ctl_l.clamp_wd.engagements} engagements)",
+      ctl_l.clamp_wd.engagements > 40 and len(rows_l) <= ctl_l.clamp_wd.episodes)
+check("...and the count in the row is the counter's, so nothing is lost",
+      f"{ctl_l.clamp_wd.engagements} engagement(s)" in rows_l[-1])
+# The RED row exists only while engaged, and the episode above is short, so it
+# is captured mid-run rather than asserted after the hysteresis has cleared it.
+check("the status page goes red WHILE it is engaged",
+      any(not c["ok"] and not c["warn"] and "OUTPUT CLAMP ENGAGED" in c["text"]
+          for c in ctl_r.red_snapshot))
+check("...and once clear, a warn row still says how many times it engaged",
+      any(c["warn"] and f"{ctl_r.clamp_wd.engagements} time(s)" in c["text"]
+          for c in ctl_r.checks()))
+
+# ⚠️ NOT A TRIP. 11.2's action is "clamp and alarm"; the loop keeps running and
+# keeps writing the clamped value. If a later cut changes that it must come here.
+check(f"it is NOT a trip - the command stands at {ctl_r.target:+.0f} W, not 0 W",
+      ctl_r.target != 0.0 and ctl_r.target == hass_r.writes[-1])
+check("...and the controller still reports itself running, not failsafe",
+      ctl_r.auto and not ctl_r.sign_wd.tripped)
+
+# The export side, because the clamp is a magnitude clamp and a sign bug in it
+# would be invisible on the import case alone.
+hass_x, ctl_x = wired(-6000.0, cycles=60, track=False)
+check(f"the export side clamps and alarms too "
+      f"({min(hass_x.writes):+,.0f} W, {len(clamp_notes(hass_x))} note(s), "
+      f"{ctl_x.clamp_wd.engagements} engagement(s))",
+      min(hass_x.writes) < 0 and abs(min(hass_x.writes)) <= LIVE_MAX_W
+      and clamp_notes(hass_x) and ctl_x.clamp_wd.engagements > 0)
+
+
+# ==============================================================================
+print()
+print("4. AC 2: saturation WITHOUT clamping must NOT raise a clamp alarm")
+
+# A legal command the inverter will not follow. The meter sits just outside the
+# deadband so the loop moves a little and then rests; `batt` is pinned far from
+# whatever is commanded, which is the saturation condition (|cmd - actual| >
+# saturation_w) and nothing else. The integrator never approaches the rating.
+hass_s, ctl_s = wired(60.0, cycles=40, batt=2500.0, track=False)
+peak = max(abs(w) for w in hass_s.writes)
+print(f"    saturated for {ctl_s.sat_count} consecutive cycles; the command "
+      f"peaked at {peak:.0f} W, {peak / LIVE_MAX_W:.1%} of the rating")
+# ⚠️ THE POSITIVE HALF FIRST. A negative check that saw nothing happen is not an
+# observation - if the saturation freeze never engaged, "no clamp alarm" is
+# vacuous and this check is worthless.
+check(f"the saturation freeze REALLY DID engage (sat_count="
+      f"{ctl_s.sat_count} >= {ctl_s.tuning.saturation_cycles})",
+      ctl_s.sat_count >= ctl_s.tuning.saturation_cycles)
+check("...and the event log says so, in the saturation's own words",
+      any("saturation freeze" in e for e in ctl_s.events))
+check(f"...while the command stayed well inside the rating "
+      f"({peak:.0f} W < {LIVE_MAX_W:.0f} W)", peak < LIVE_MAX_W)
+# Now the negative, which is only worth anything because of the three above.
+check("AC 2: NO clamp notification was raised", not clamp_notes(hass_s))
+check("AC 2: the clamp counted ZERO engagements", ctl_s.clamp_wd.engagements == 0)
+check("AC 2: no OUTPUT_CLAMP row in the action log",
+      not [e for e in ctl_s.events if REASON_CODE in e])
+check("AC 2: and no clamp row on the status page",
+      not [c for c in ctl_s.checks() if "output clamp" in c["text"].lower()])
+
+print("   ...and the two alarms do not share a notification_id")
+ids_clamp = {d["notification_id"] for d in clamp_notes(hass_r)}
+ids_other = {d.get("notification_id") for dom, svc, d in hass_r.calls
+             if svc == "create"} - ids_clamp
+check(f"clamp ids {sorted(ids_clamp)} are disjoint from every other alarm's "
+      f"{sorted(x for x in ids_other if x)}", not (ids_clamp & ids_other))
+
+print("   ...and the alarm cannot be keyed on Decision.reason")
+# A cycle that clamps the integrator AND is then slew limited. `reason` reports
+# the LAST stage, so a string-keyed alarm is silent on it; the boolean is not.
+t = Tuning(max_w=2000.0, slew_w=100.0, gain=0.6)
+d = compute(prev_w=1000.0, grid_w=6000.0, actual_w=1000.0, tuning=t, i_w=1900.0)
+print(f"    reason={d.reason!r}  i_clamped={d.i_clamped}  clamped={d.clamped}")
+check("the integrator DID clamp on that cycle", d.i_clamped is True)
+check("...but `reason` says 'slew-limited' - the clamp was overwritten "
+      "downstream, so a string-keyed alarm is SILENT here",
+      d.reason == "slew-limited" and "clamp" not in d.reason)
+# And the same for the OUTPUT clamp, on a config that lets the integrator run
+# above the rail - then both flags fire and `reason` still reports neither.
+t2 = Tuning(max_w=2000.0, integrator_max_w=3000.0, slew_w=100.0, gain=0.6)
+d2 = compute(prev_w=1000.0, grid_w=6000.0, actual_w=1000.0, tuning=t2, i_w=2900.0)
+print(f"    reason={d2.reason!r}  i_clamped={d2.i_clamped}  clamped={d2.clamped}")
+check("both clamps engaged, and `reason` reports neither",
+      d2.i_clamped and d2.clamped and "clamp" not in d2.reason)
+# ⚠️ HOW THE FREEZE AND THE CLAMP INTERACT, MEASURED RATHER THAN ASSUMED, AND
+# THE MEASUREMENT REFUSED TWO GUESSES BEFORE THIS ONE. Written first as "a
+# frozen cycle never clamps" (false), then as "only the i_w == 0 reseed
+# exception clamps" (also false - at i_w == 0 with a matching actual the cycle
+# is not saturated at all, so it is never frozen). What the sweep actually
+# shows: a frozen cycle clamps exactly when the integrator REVERSES. control.py
+# permits that on purpose - "it may fall, cross zero, or reverse outright" -
+# because the alternative deadlocks the loop, and a reversal is a full swing
+# that can clear the bound on the far side in one step.
+#
+# That matters for this ticket rather than being trivia: it is the one shape
+# where the saturation freeze and a clamp engagement coincide, so it is exactly
+# where an alarm that shared a channel with saturation would lose the clamp.
+grid_sweep = (-9000.0, -3000.0, 3000.0, 9000.0)
+grid = [(pp, g) for pp in (-1900.0, -500.0, 0.0, 500.0, 1900.0)
+        for g in grid_sweep]
+runs = {(pp, g): compute(pp, g, 0.0, t, sat_count=5, i_w=pp) for pp, g in grid}
+frozen = [k for k, d in runs.items() if d.frozen]
+frozen_clamps = [k for k in frozen if runs[k].i_clamped]
+# The property, stated independently of the control law's own branches: the
+# correction pushes AGAINST the standing integrator, and the resulting swing
+# clears the bound.
+reversals = [(pp, g) for pp, g in frozen
+             if pp * g < 0 and abs(pp + t.gain * g) > t.max_w]
+print(f"    {len(frozen)} of {len(grid)} sweep cells are frozen; "
+      f"those that also clamp: {frozen_clamps}")
+check(f"a frozen cycle CAN clamp, and only by reversing "
+      f"({len(frozen_clamps)} of {len(frozen)} frozen cells)",
+      frozen_clamps and frozen_clamps == reversals)
+check("...and a frozen cycle pushing the way it already leans never clamps - "
+      "that is the freeze doing its job",
+      not [k for k in frozen if runs[k].i_clamped and k[0] * k[1] > 0])
+check("a healthy cycle sets neither flag",
+      not any([compute(0.0, 100.0, 0.0, t).i_clamped,
+               compute(0.0, 100.0, 0.0, t).clamped]))
+
+
+# ==============================================================================
+print()
+print("5. no path reaches the wire around the clamp")
+
+
+async def _direct():
+    hass = _Hass(0.0)
+    c = Controller({"setpoint_entity": "number.sp", "max_w": 2000,
+                    "meter_source": "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.
+    await c.write_setpoint(9999.0, force=True)
+    await c.write_setpoint(-9999.0, force=True)
+    await c.write_setpoint(float("nan"), force=True)
+    await c.write_setpoint(1500.0, force=True)
+    return hass, c
+
+
+hass_d, ctl_d = asyncio.run(_direct())
+print(f"    asked for 9999 / -9999 / nan / 1500 W; the device saw "
+      f"{hass_d.writes}")
+check("a direct out-of-range write is clamped, not passed through",
+      hass_d.writes[:2] == [2000.0, -2000.0])
+check("a nan is refused and becomes 0 W, per 11.1 rule 1",
+      hass_d.writes[2] == 0.0)
+check("...and is NOT counted as a clamp engagement - it is a transport bug",
+      sum(1 for e in ctl_d.events if REASON_CODE in e) == 2)
+check("an in-range value is untouched", hass_d.writes[3] == 1500.0)
+check("every emitted frame satisfies |emitted| <= the rating",
+      all(abs(w) <= 2000.0 for w in hass_d.writes))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_loop.py

@@ -0,0 +1,213 @@
+"""Runnable check for the control loop's cadence.  `python3 test_loop.py`
+
+SAFETY-12: the loop must evaluate on a clock as well as on a change. Before the
+fix, `run_control()` ran `cycle()` only when the meter value differed from the
+previous poll, so a meter that repeats a value ran NO control cycles while the
+heartbeat kept re-emitting the last command - measured on the rig during TEL-05
+as 70 s at a literally constant 350.0 W with 14 arrivals and zero cycles.
+
+⚠️ THIS TEST TAKES ~95 SECONDS OF WALL CLOCK (measured 93 s), on purpose, and
+that figure is the only thing standing between it and a future developer who
+decides a slow test is a broken one. The thing under test is a wall-clock floor
+inside a loop that sleeps 1 s; mocking the clock would leave the assertion
+testing the mock. It drives the real `run_control()` and counts what actually
+happened. Eight runs of the real loop is what the eight scenarios cost.
+
+⚠️ If you shorten the windows, re-measure and update this number and the one in
+HANDOVER.md. An understated runtime reads as a hang.
+
+`cycle_floor_s` is read from options with no lower bound in code, so a huge
+value reproduces the pre-fix behaviour exactly. Every claim below is therefore
+an A/B on one binary, not a comparison against a remembered old one.
+"""
+
+import asyncio
+import sys
+import time
+
+from app.main import Controller
+
+fails = []
+NEVER = 1e9          # cycle_floor_s so large the floor can never elapse: pre-fix
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+class FakeHass:
+    """A scripted meter and a plant that tracks the command instantly."""
+
+    def __init__(self, meter, soc_dies_at=None):
+        self.meter = meter
+        self.soc_dies_at = soc_dies_at
+        self.batt = 0.0
+        self.writes = []
+        self.t0 = time.monotonic()
+
+    async def limits(self, entity):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def number(self, entity, invert=False):
+        now = time.monotonic() - self.t0
+        if entity == "sensor.grid":
+            return self.meter(now)
+        if entity == "sensor.batt":
+            return self.batt
+        if entity == "sensor.soc":
+            if self.soc_dies_at is not None and now >= self.soc_dies_at:
+                return None
+            return 50.0
+        return None
+
+    async def set_number(self, entity, value):
+        self.writes.append(float(value))
+        self.batt = float(value)
+        return True
+
+
+class _Store:
+    data = {}
+
+    def set(self, *a):
+        pass
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+BASE = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+        "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+        "meter_source": "off", "max_w": 2000, "gain": 0.6, "slew_w": 1000,
+        "deadband_w": 15, "target_grid_w": -10, "step_w": 10,
+        "heartbeat_s": 10, "stale_input_s": 15}
+
+
+def drive(meter, floor, seconds, soc_dies_at=None, **over):
+    """Run the real control loop for `seconds`; return (cycle times, writes)."""
+    async def go():
+        hass = FakeHass(meter, soc_dies_at)
+        c = Controller(dict(BASE, cycle_floor_s=floor, **over), hass, _Store(),
+                       _Pub(), stop=asyncio.Event())
+        c.auto = True
+        stamps = []
+        real = c.cycle
+
+        async def counted():
+            stamps.append(time.monotonic() - hass.t0)
+            await real()
+
+        c.cycle = counted
+        task = asyncio.create_task(c.run_control())
+        await asyncio.sleep(seconds)
+        c.stopping = True
+        await asyncio.wait_for(task, timeout=10)
+        return stamps, hass.writes, c.target, c.reason
+    return asyncio.run(go())
+
+
+def worst_gap(stamps, seconds):
+    """Longest stretch with no cycle, including the tail after the last one."""
+    edges = [0.0] + list(stamps) + [seconds]
+    return max(b - a for a, b in zip(edges, edges[1:]))
+
+
+# --------------------------------------------------------------------------- #
+print("a meter that repeats the same value")
+FLAT = lambda t: 350.0                                          # noqa: E731
+FLOOR, SECONDS = 3.0, 12.0
+
+pre_stamps, pre_writes, _, _ = drive(FLAT, NEVER, SECONDS)
+# The defect itself, demonstrated rather than described: one cycle at startup
+# and then nothing for the rest of the window, while writes keep happening.
+check("pre-fix: a constant meter runs exactly one cycle, at startup",
+      len(pre_stamps) == 1)
+check("...while the heartbeat keeps writing anyway, so nothing looks wrong",
+      len(pre_writes) >= 2)
+
+post_stamps, post_writes, _, _ = drive(FLAT, FLOOR, SECONDS)
+check("post-fix: the same constant meter runs cycles throughout",
+      len(post_stamps) >= int(SECONDS / FLOOR) - 1)
+# The actual acceptance criterion: a BOUND on the gap, not a count.
+gap = worst_gap(post_stamps, SECONDS)
+check(f"...with no gap longer than the floor ({gap:.1f}s <= {FLOOR + 1.5:.1f}s)",
+      gap <= FLOOR + 1.5)
+check("...and the loop actually corrected, instead of holding a stale command",
+      len(post_writes) > len(pre_writes))
+
+# --------------------------------------------------------------------------- #
+print("a meter that changes normally - nothing may move")
+# ⚠️ THE REGRESSION GUARD, and the more important half. The floor is a deadline
+# on the gap between cycles, reset by every cycle whichever trigger fired - not
+# a second scheduler. On a healthy meter it must never elapse, so the cycle
+# count, the write count and the commanded values must be IDENTICAL either side
+# of the fix. Anything else is a new write cadence, which SAFETY-12 forbids:
+# the deadband, step_w and the 10 s force-write decide what reaches the wire,
+# and this change is only allowed to alter when the loop thinks.
+STEPS = [0.0, 300.0, 850.0, -400.0, 120.0, -900.0, 60.0]
+LIVE = lambda t: STEPS[int(t // 2) % len(STEPS)]                # noqa: E731
+
+a_stamps, a_writes, _, _ = drive(LIVE, NEVER, 12.0)
+b_stamps, b_writes, _, _ = drive(LIVE, FLOOR, 12.0)
+check("a changing meter runs the same number of cycles as before the fix",
+      len(a_stamps) == len(b_stamps))
+check("...commanding exactly the same sequence of values", a_writes == b_writes)
+
+# --------------------------------------------------------------------------- #
+print("a meter parked at the target - the converged operating point")
+# The case TEL-05 warned about: at the converged target the power figure
+# legitimately repeats for minutes. The loop must still run, and must still
+# write nothing but the heartbeat, because the deadband - not the arrival
+# trigger - is what holds the command still.
+AT_TARGET = lambda t: -10.0                                     # noqa: E731
+c_stamps, c_writes, _, _ = drive(AT_TARGET, NEVER, 12.0)
+d_stamps, d_writes, _, _ = drive(AT_TARGET, FLOOR, 12.0)
+check("the loop evaluates at the converged point too", len(d_stamps) > len(c_stamps))
+check("...and the deadband still holds the command, so writes are unchanged",
+      d_writes == c_writes)
+
+# --------------------------------------------------------------------------- #
+print("an input dies while the meter repeats - the safety claim must still fire")
+# ⚠️ THE STRONGEST PROPERTY IN SAFETY-12, and the one that makes it a safety fix
+# rather than a latency fix. The `inputs missing -> 0 W` claim lives INSIDE
+# cycle() (main.py, the stale_input_s branch and the P_SAFETY claim below it).
+# Pre-fix, on a meter whose value happened to repeat, cycle() was never called
+# again - so that claim could not fire AT ALL. The controller held its last
+# command through an input outage of unbounded length with the status line still
+# reading "loop -> N W".
+#
+# Layer 1 does not cover this either on a `meter_source: off` install: no P1 age
+# sensor is published (see Controller.publish), so the firmware has nothing to
+# veto on, and the heartbeat keeps its watchdog fed the whole time.
+#
+# stale_input_s is shortened to 3 s here so the outage resolves inside a test
+# rather than inside a quarter of a minute. The mechanism is the default one.
+c2_stamps, c2_writes, pre_target, pre_reason = drive(
+    FLAT, NEVER, 10.0, soc_dies_at=4.0, stale_input_s=3)
+check("pre-fix: a dead input during a constant meter never reaches the safety claim",
+      pre_target != 0.0 and "safety" not in pre_reason)
+check(f"...so it holds its last command instead ({pre_target:g} W, {pre_reason!r})",
+      pre_target == 220.0)
+
+d2_stamps, d2_writes, post_target, post_reason = drive(
+    FLAT, FLOOR, 10.0, soc_dies_at=4.0, stale_input_s=3)
+check("post-fix: the same outage commands 0 W", post_target == 0.0)
+check(f"...through the safety claim, not by accident ({post_reason!r})",
+      "safety" in post_reason)
+check("...and the 0 W actually reached the device", 0.0 in d2_writes)
+
+# --------------------------------------------------------------------------- #
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + "; ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_p1.py

@@ -11,6 +11,7 @@ computes the wrong quarter-hour figure whenever the telegram cadence changes.
 """
 
 import asyncio
+import json
 import sys
 import time
 from datetime import datetime, timedelta, timezone
@@ -18,8 +19,11 @@ from datetime import datetime, timedelta, timezone
 import aiohttp   # already required by app.p1, so this adds no new dependency
 
 from app.p1 import (
-    P1Error, P1Ingest, HaDsmrSource, QuarterAverager, SOURCE_HA, SOURCE_MQTT,
-    make_sample, parse_mqtt_payload,
+    P1Error, P1Ingest, HaDsmrSource, HaSignedSource, HomeWizardLocalSource,
+    QuarterAverager,
+    SOURCE_HA, SOURCE_HA_SIGNED, SOURCE_HOMEWIZARD, SOURCE_MQTT,
+    build_source, is_enabled, make_sample, parse_homewizard, parse_mqtt_payload,
+    split_signed,
 )
 
 fails = []
@@ -56,6 +60,25 @@ def raises(name, fn):
     fails.append(name)
 
 
+def built(src):
+    """`src.build()`, with any escaping exception turned into a visible value.
+
+    ⚠️ Legibility of a RED, not leniency. build() is contracted to return a bool
+    and to funnel every bad telegram through ingest.reject() - a guard that goes
+    missing (say the "is the net entity cached at all" one) makes it raise
+    instead. That still fails the suite, but by aborting it with a traceback at
+    whichever check happened to run first, which costs the next person ten
+    minutes deciding whether the suite is broken or the code is. Returning the
+    exception makes it compare unequal to True/False, so the NAMED check goes red
+    and says which rule died.
+    """
+    try:
+        return src.build()
+    except Exception as err:  # noqa: BLE001 - a raise here is itself the failure
+        print(f"       build() raised {type(err).__name__}: {err}")
+        return err
+
+
 def sample(net_import, net_export=0.0, at=BASE, phases=1, pi=None, pe=None):
     return make_sample(SOURCE_HA, net_import, net_export, phases=phases,
                        phase_import_w=pi, phase_export_w=pe,
@@ -548,6 +571,726 @@ check("the averager integrated the live stream", live.averager.elapsed_s > 0.2)
 check("the primed cache let the first telegram build immediately",
       live.samples == 2 and live.last.import_w == 0.0)
 
+# --------------------------------------------------------------------------- #
+print("ha_signed: one signed entity -> the same two magnitudes")
+# The meter actually fitted at this house is a HomeWizard P1 publishing ONE
+# signed sensor. ha_dsmr cannot read it - it wants two unsigned registers and
+# refuses a negative one, which is every exporting telegram.
+
+check("a positive reading is import", split_signed(1500.0) == (1500.0, 0.0))
+check("a negative reading is export", split_signed(-900.0) == (0.0, 900.0))
+check("zero is a balanced reading, not a missing one",
+      split_signed(0.0) == (0.0, 0.0))
+check("exactly one magnitude is ever non-zero",
+      all(a == 0.0 or b == 0.0 for a, b in
+          (split_signed(v) for v in (-5710.0, -1.0, 0.0, 1.0, 4384.0))))
+# ⚠️ The split must not change the number. A control loop steered by a value
+# that was rounded or clamped on the way in is steered by a different meter.
+check("the split round-trips the signed value exactly",
+      all(make_sample(SOURCE_HA_SIGNED, *split_signed(v), phases=1).net_w == v
+          for v in (-11763.0, -5710.0, -0.5, 0.0, 0.5, 775.0, 4384.0)))
+
+raises("a non-numeric signed reading is rejected", lambda: split_signed("n/a"))
+raises("a signed None is rejected, not read as zero", lambda: split_signed(None))
+raises("a signed NaN is rejected", lambda: split_signed(float("nan")))
+raises("a signed infinity is rejected", lambda: split_signed(float("inf")))
+# ⚠️ This one matters MORE on the signed path than on the unsigned one. On
+# ha_dsmr the §20 contamination is also caught by "unsigned cannot be negative";
+# here 64954 arrives as a perfectly well-formed positive signed reading and the
+# plausibility ceiling is the only thing standing in front of it.
+raises("the 64954 signed-decode contamination is still rejected",
+       lambda: split_signed(64954.0))
+raises("...and its negative twin too", lambda: split_signed(-64954.0))
+
+# --------------------------------------------------------------------------- #
+print("ha_signed: the sign convention, against real captured readings")
+# ⚠️ Not a datasheet claim. These are literal values out of
+# sim/scenarios/ha-p1_meter_active_power-2026-08-{20,23}.json, HA recorder
+# exports of sensor.p1_meter_active_power at this house, copied here rather than
+# read from that repo so this file still runs on a laptop with nothing installed
+# (§17). If the convention were inverted, the physics below would be absurd.
+
+# 2026-08-23T11:46:52Z - the day's most negative reading, 13:46 local, full sun.
+s = make_sample(SOURCE_HA_SIGNED, *split_signed(-5710.0), phases=1)
+check("the midday PV peak (-5710 W) is EXPORT, not a 5.7 kW draw",
+      s.net_w == -5710.0 and s.export_w == 5710.0 and s.import_w == 0.0)
+# 2026-08-19T22:00:00Z - midnight local, 20 Aug's file starts here. No sun.
+s = make_sample(SOURCE_HA_SIGNED, *split_signed(775.0), phases=1)
+check("the overnight base load (+775 W) is IMPORT",
+      s.net_w == 775.0 and s.import_w == 775.0 and s.export_w == 0.0)
+# 2026-08-20T12:20:58Z - 14:20 local, the largest export in either capture.
+s = make_sample(SOURCE_HA_SIGNED, *split_signed(-11763.0), phases=1)
+check("the -11763 W midday extreme is export and survives the ceiling",
+      s.net_w == -11763.0 and s.export_w == 11763.0)
+# 2026-08-23T10:18:28Z - the largest import in the healthy capture.
+s = make_sample(SOURCE_HA_SIGNED, *split_signed(4384.0), phases=1)
+check("the +4384 W peak is import", s.net_w == 4384.0 and s.import_w == 4384.0)
+# The whole convention in one line: night draws, midday feeds back.
+check("night is positive and midday is negative, which is the convention",
+      split_signed(775.0)[0] > 0 and split_signed(-5710.0)[1] > 0)
+
+# --------------------------------------------------------------------------- #
+print("ha_signed transport: building a sample out of one entity state")
+
+NET = {"net": "sensor.p1_meter_active_power", "phase_net": []}
+ing = P1Ingest(phases=1, max_age_s=30.0)
+sig = HaSignedSource(None, ing, NET, token="x")
+
+check("nothing cached yet builds nothing", built(sig) is False and ing.last is None)
+sig._absorb("sensor.p1_meter_active_power", "1000")
+check("one signed entity is a complete telegram on its own",
+      built(sig) is True and ing.net_w == 1000.0)
+check("the sample is tagged with its own transport",
+      ing.last.source == SOURCE_HA_SIGNED)
+sig._absorb("sensor.p1_meter_active_power", "-2500")
+built(sig)
+check("a negative state lands as a negative net", ing.net_w == -2500.0)
+
+before = ing.last
+sig._absorb("sensor.p1_meter_active_power", "unavailable")
+check("an unavailable signed entity is a parse error", ing.parse_errors == 1)
+check("an unavailable entity does not build a sample", built(sig) is False)
+# ⚠️ The rule the whole ticket turns on: a missing reading is MISSING. Resolving
+# it to 0 W would read as a perfectly balanced house and defeat the staleness
+# trigger that FW-01's watchdog is built on.
+check("an unavailable entity leaves the last good sample untouched, not 0 W",
+      ing.last is before and ing.net_w == -2500.0)
+sig._absorb("sensor.p1_meter_active_power", "unknown")
+check("an unknown signed entity is treated the same way", ing.parse_errors == 2)
+sig._absorb("sensor.p1_meter_active_power", "banana")
+check("a non-numeric signed state is a parse error, not 0 W",
+      ing.parse_errors == 3 and ing.net_w == -2500.0)
+sig._absorb("sensor.p1_meter_active_power", "64954")
+check("64954 is refused at the signed transport too",
+      built(sig) is False and ing.parse_errors == 4)
+sig._absorb("sensor.not_ours", "123")
+check("an unsubscribed entity is never cached by the signed transport",
+      "sensor.not_ours" not in sig.cache)
+
+# A rejected reading must not make the age look fresh - the age is what the
+# firmware watchdog reads, and a rejection is exactly when it must keep climbing.
+ing = P1Ingest(phases=1, max_age_s=30.0)
+sig = HaSignedSource(None, ing, dict(NET), token="x")
+ing.submit(make_sample(SOURCE_HA_SIGNED, 1200, 0, phases=1,
+                       ingest_mono=time.monotonic() - 20.0))
+sig._absorb("sensor.p1_meter_active_power", "unavailable")
+built(sig)
+check("a rejected reading does not reset the published age",
+      ing.published_age_s > 19 and ing.net_w == 1200.0)
+ing.submit(make_sample(SOURCE_HA_SIGNED, 1200, 0, phases=1,
+                       ingest_mono=time.monotonic() - 40.0))
+check("...and the age keeps climbing past max_age_s on its own",
+      ing.stale is True and ing.net_w is None)
+
+# The three-phase reading the TEL-04 survey recorded at this house: L1 +2301 W,
+# L2 +468 W, L3 -2582 W, netting +187 W. A signed per-phase set splits the same
+# way, and the exporting phase must still clamp out of the billed figure.
+ing3 = P1Ingest(phases=3, max_age_s=30.0)
+NET3 = {"net": "sensor.p1_meter_active_power",
+        "phase_net": ["sensor.p1_l1", "sensor.p1_l2", "sensor.p1_l3"]}
+sig3 = HaSignedSource(None, ing3, NET3, token="x")
+for eid, val in (("sensor.p1_meter_active_power", "187"), ("sensor.p1_l1", "2301")):
+    sig3._absorb(eid, val)
+check("an incomplete signed phase set waits instead of guessing", built(sig3) is False)
+sig3._absorb("sensor.p1_l2", "468")
+sig3._absorb("sensor.p1_l3", "-2582")
+check("a complete signed three-phase set builds", built(sig3) is True)
+check("signed per-phase entities keep the exporting phase negative",
+      ing3.last.per_phase_w == (2301.0, 468.0, -2582.0))
+check("per-phase IMPORT clamps the exporting phase to zero",
+      ing3.last.per_phase_import_w == (2301.0, 468.0, 0.0))
+check("the phase import sum is 2769 W while the connection nets 187 W",
+      sum(ing3.last.per_phase_import_w) == 2769.0 and ing3.last.net_w == 187.0)
+check("the signed per-phase tuple length matches meter_phases",
+      len(ing3.last.per_phase_w) == ing3.phases == 3)
+
+sig_bad = HaSignedSource(None, P1Ingest(phases=3, max_age_s=30.0),
+                         {"net": "sensor.net", "phase_net": ["sensor.a", "sensor.b"]},
+                         token="x")
+for eid in ("sensor.net", "sensor.a", "sensor.b"):
+    sig_bad._absorb(eid, "100")
+check("two phases delivered against meter_phases 3 is rejected, not padded",
+      built(sig_bad) is False and sig_bad.ingest.last is None
+      and sig_bad.ingest.parse_errors == 1)
+
+# --------------------------------------------------------------------------- #
+print("ha_signed transport: end to end against a fake Home Assistant")
+# The transport is a subclass, so this is what proves the INHERITED machinery -
+# auth, subscribe, the get_states priming rule, the reconnect-emits-nothing
+# rule - still behaves when only _wanted() and build() were replaced.
+
+
+async def _e2e_signed():
+    from aiohttp import web
+    import app.p1 as p1mod
+
+    done = asyncio.Event()
+    eid = "sensor.p1_meter_active_power"
+
+    async def fake_ha(request):
+        ws = web.WebSocketResponse()
+        await ws.prepare(request)
+        await ws.send_json({"type": "auth_required", "ha_version": "2026.8"})
+        auth = await ws.receive_json()
+        assert auth["type"] == "auth" and auth["access_token"] == "tok"
+        await ws.send_json({"type": "auth_ok"})
+        sub = await ws.receive_json()
+        assert sub["type"] == "subscribe_events"
+        await ws.send_json({"id": sub["id"], "type": "result", "success": True})
+        get = await ws.receive_json()
+        assert get["type"] == "get_states"
+        await ws.send_json({"id": get["id"], "type": "result", "success": True, "result": [
+            {"entity_id": eid, "state": "775.0"},
+            {"entity_id": "sensor.something_else", "state": "hello"},
+        ]})
+        # Two real telegrams, both literal captured values: overnight import,
+        # then the midday export peak.
+        for val in ("775.0", "-5710.0"):
+            await asyncio.sleep(0.5)
+            await ws.send_json({"type": "event", "event": {"data": {
+                "entity_id": eid,
+                "new_state": {"entity_id": eid, "state": val}}}})
+        await asyncio.sleep(0.5)
+        await ws.send_json({"type": "event", "event": {"data": {
+            "entity_id": eid,
+            "new_state": {"entity_id": eid, "state": "unavailable"}}}})
+        await asyncio.sleep(0.5)
+        done.set()
+        return ws
+
+    srv = web.Application()
+    srv.router.add_get("/ws", fake_ha)
+    runner = web.AppRunner(srv)
+    await runner.setup()
+    site = web.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+    p1mod.WS_URL = f"http://127.0.0.1:{port}/ws"
+
+    ing = P1Ingest(phases=1, max_age_s=30.0)
+    async with aiohttp.ClientSession() as sess:
+        src = HaSignedSource(sess, ing, dict(NET), token="tok")
+        task = asyncio.get_running_loop().create_task(src.run())
+        try:
+            await asyncio.wait_for(done.wait(), 20)
+            await asyncio.sleep(0.5)
+        finally:
+            task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+    await runner.cleanup()
+    return ing, src
+
+
+live, wire = asyncio.run(_e2e_signed())
+# ⚠️ TWO, not three - the same rule as the ha_dsmr e2e. get_states primes the
+# cache but must never become a sample: after a Core restart it is a
+# RestoreEntity value of unknown age, and stamping it with ingest_ts=now reports
+# a fresh meter that may have been dead for an hour.
+check("ha_signed does not manufacture a sample from cached HA state",
+      live.samples == 2)
+check("the signed telegrams arrived over a real websocket",
+      live.last.source == SOURCE_HA_SIGNED)
+check("the final export telegram nets negative, over the wire",
+      live.last.net_w == -5710.0 and live.last.export_w == 5710.0)
+check("ha_signed subscribes to the one entity and caches nothing else",
+      wire.ids == {"sensor.p1_meter_active_power"}
+      and "sensor.something_else" not in wire.cache)
+check("a mid-stream unavailable signed state is a parse error, not a sample",
+      live.parse_errors == 1 and live.samples == 2)
+# ⚠️ And the cached half is DROPPED, so no later telegram can be assembled out
+# of a value that stopped reporting.
+check("an unavailable entity is evicted from the cache", wire.cache == {})
+check("the last good reading survives the unavailable, and is not 0 W",
+      live.net_w == -5710.0)
+check("the averager integrated the live signed stream", live.averager.elapsed_s > 0.2)
+# ⚠️ The entity FW-01 waits on. It must be a number here exactly as it is on the
+# other transports - the house P1 went 51.1 s and 36.2 s between state changes
+# overnight, and without this the watchdog false-trips the battery to 0 W.
+check("sensor.p1_sample_age_s is a live number on this transport too",
+      isinstance(live.published_age_s, float) and live.published_age_s >= 0.0)
+
+# --------------------------------------------------------------------------- #
+print("ha_signed: selection by config")
+
+check("ha_signed is enabled", is_enabled({"meter_source": SOURCE_HA_SIGNED}) is True)
+# ⚠️ `sel`, not `built` - that name is the build() wrapper defined at the top of
+# this file, and rebinding it here silently disarms every check appended below
+# this line. Caught in review: an added check went `TypeError: 'HaSignedSource'
+# object is not callable` and aborted the suite, which is the exact failure the
+# wrapper exists to prevent, reintroduced by a name collision.
+sel = build_source({"meter_source": SOURCE_HA_SIGNED,
+                    "p1_net_entity": "sensor.p1_meter_active_power"},
+                   P1Ingest(), None, None)
+check("meter_source ha_signed selects the signed transport",
+      isinstance(sel, HaSignedSource))
+check("...wired to p1_net_entity, and subscribed to exactly that one entity",
+      sel.ids == {"sensor.p1_meter_active_power"})
+# ⚠️ The three modes must not bleed into each other: ha_dsmr must keep ignoring
+# p1_net_entity, or a half-configured install silently reads the wrong sensor.
+plain = build_source({"meter_source": SOURCE_HA,
+                      "p1_import_entity": "sensor.i", "p1_export_entity": "sensor.e",
+                      "p1_net_entity": "sensor.p1_meter_active_power"},
+                     P1Ingest(), None, None)
+check("ha_dsmr still selects the unsigned transport and ignores p1_net_entity",
+      type(plain) is HaDsmrSource and plain.ids == {"sensor.i", "sensor.e"})
+check("meter_source off still selects nothing",
+      build_source({"meter_source": "off"}, P1Ingest(), None, None) is None)
+check("an unrecognised meter_source selects nothing rather than guessing",
+      build_source({"meter_source": "ha_signd"}, P1Ingest(), None, None) is None)
+
+# ⚠️ Caught once at startup, not once per telegram. A source that is wired up
+# wrong otherwise fails in the one way indistinguishable from a healthy source
+# nobody has sent anything to yet: no samples, a climbing age, the watchdog
+# holding the battery at 0 W, and nothing in the log saying why.
+check("a blank p1_net_entity is refused rather than silently never receiving",
+      build_source({"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": ""},
+                   P1Ingest(), None, None) is None)
+check("...and whitespace does not sneak past it",
+      build_source({"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": "   "},
+                   P1Ingest(), None, None) is None)
+check("a phase list that disagrees with meter_phases is refused at startup",
+      build_source({"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": "sensor.n",
+                    "p1_phase_net_entities": ["sensor.a", "sensor.b"]},
+                   P1Ingest(phases=3), None, None) is None)
+check("a phase list that agrees with meter_phases is accepted",
+      isinstance(build_source(
+          {"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": "sensor.n",
+           "p1_phase_net_entities": ["sensor.a", "sensor.b", "sensor.c"]},
+          P1Ingest(phases=3), None, None), HaSignedSource))
+check("no phase list at all is still fine - per-phase billing is optional",
+      isinstance(build_source(
+          {"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": "sensor.n"},
+          P1Ingest(phases=3), None, None), HaSignedSource))
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: parsing the meter's own /api/v1/data document")
+# The same JSON `sim/hwsim.py` serves and the same JSON the real meter at
+# 192.168.2.250 serves. One SIGNED connection figure plus three signed legs, so
+# it goes through the same split_signed as ha_signed - the sign convention is
+# not re-derived on this transport, it is reused.
+
+
+def hw_doc(w, l1=None, l2=None, l3=None, imp_kwh=1234.567, exp_kwh=890.123):
+    return {"wifi_ssid": "sim", "smr_version": 50, "meter_model": "SIM-P1",
+            "total_power_import_kwh": imp_kwh, "total_power_export_kwh": exp_kwh,
+            "active_power_w": w,
+            "active_power_l1_w": l1, "active_power_l2_w": l2,
+            "active_power_l3_w": l3, "total_gas_m3": 0.0}
+
+
+s = parse_homewizard(hw_doc(775.0, l1=775.0), 1)
+check("the overnight base load (+775 W) is import on this transport too",
+      s.net_w == 775.0 and s.import_w == 775.0 and s.export_w == 0.0)
+check("the sample is tagged homewizard_local", s.source == SOURCE_HOMEWIZARD)
+s = parse_homewizard(hw_doc(-5710.0, l1=-5710.0), 1)
+check("the midday PV peak (-5710 W) is export, not a 5.7 kW draw",
+      s.net_w == -5710.0 and s.export_w == 5710.0)
+check("a single-phase document still yields its one leg", s.per_phase_w == (-5710.0,))
+
+# The TEL-04 three-phase survey reading, served the HomeWizard way.
+s = parse_homewizard(hw_doc(187.0, 2301.0, 468.0, -2582.0), 3)
+check("signed legs keep the exporting phase negative",
+      s.per_phase_w == (2301.0, 468.0, -2582.0))
+check("per-phase import clamps the exporting leg out of the billed figure",
+      s.per_phase_import_w == (2301.0, 468.0, 0.0))
+check("the legs sum to 2769 W while the connection nets 187 W",
+      sum(s.per_phase_import_w) == 2769.0 and s.net_w == 187.0)
+
+# ⚠️ A single-phase HomeWizard serves `active_power_l2_w: null`. Unlike the HA
+# transports there is no "wait for the rest" case - every field came out of ONE
+# response, so a missing leg cannot be a STALE leg. Dropping the whole sample
+# over it would turn a healthy meter into a climbing age, which is the exact
+# false trip this transport exists to remove.
+def parsed(doc, phases=1):
+    """parse_homewizard(), with an escaping exception turned into a visible value.
+
+    Same reason as `built()` above: if the "all legs or none" guard goes missing,
+    parsing raises, and without this the suite aborts on a traceback instead of
+    reddening the NAMED check that says which rule died.
+    """
+    try:
+        return parse_homewizard(doc, phases)
+    except Exception as err:  # noqa: BLE001 - a raise here is itself the failure
+        print(f"       parse_homewizard raised {type(err).__name__}: {err}")
+        return err
+
+
+s = parsed(hw_doc(500.0, l1=500.0), 3)
+check("a meter serving fewer legs than meter_phases still gives a reading",
+      getattr(s, "net_w", None) == 500.0 and getattr(s, "per_phase_w", "?") is None)
+check("...and does not fabricate a partial phase tuple",
+      getattr(s, "per_phase_import_w", "?") is None)
+
+raises("a response that is not a JSON object is rejected",
+       lambda: parse_homewizard([1, 2, 3], 1))
+raises("a document with no active_power_w is rejected, not read as 0 W",
+       lambda: parse_homewizard({"total_gas_m3": 0.0}, 1))
+raises("a null active_power_w is rejected", lambda: parse_homewizard(hw_doc(None), 1))
+raises("a string active_power_w is rejected", lambda: parse_homewizard(hw_doc("775"), 1))
+raises("a NaN active_power_w is rejected",
+       lambda: parse_homewizard(hw_doc(float("nan")), 1))
+raises("the 64954 signed-decode contamination is refused here too",
+       lambda: parse_homewizard(hw_doc(64954.0), 1))
+raises("a non-numeric leg is rejected rather than quietly dropped",
+       lambda: parse_homewizard(hw_doc(600.0, "2000", 0.0, 100.0), 3))
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: every HTTP response is an arrival")
+# THE WHOLE TICKET. sensor.p1_sample_age_s has to mean "time since the meter
+# REPORTED", not "time since the value CHANGED". Home Assistant cannot express
+# the first: a repeated reading emits no state_changed, advances last_reported
+# on neither serialiser, and state_reported cannot be subscribed to at all
+# ("Event filter is required"). Measured on the ENV-01 rig over 70 s of a frozen
+# meter and again against the live house over ten repeated readings. Our own
+# capture of this house's meter goes 42.2 s and 97.0 s between changes, both past
+# the default meter_max_age_s of 30 - i.e. the age sensor would command 0 W on a
+# perfectly healthy meter. Polling the meter itself removes that: the response is
+# the arrival, and the number in it is not consulted.
+
+
+class _FakeMeter:
+    """hwsim in eight lines: serves whatever document it is told to, or a fault."""
+
+    def __init__(self, doc=None):
+        self.doc = doc
+        self.status = 200
+        self.body = None          # set to raw text to serve something unparseable
+        self.delay = 0.0          # set to seconds to imitate a meter that hangs
+        self.hits = 0
+
+    async def handle(self, request):
+        from aiohttp import web
+        self.hits += 1
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        # ⚠️ web.Response(text=...) defaults to text/plain. That is not just the
+        # "unparseable body" path: fed VALID json it serves a good document under
+        # the wrong mimetype, which is the only way to reach the content_type
+        # guard in poll_once - json_response can never produce it.
+        if self.body is not None:
+            return web.Response(text=self.body, status=self.status)
+        return web.json_response(self.doc, status=self.status)
+
+
+async def _hw_rig(fn):
+    """Run `fn(make_source, meter)` against a real HTTP server on localhost."""
+    from aiohttp import web
+    meter = _FakeMeter(hw_doc(350.0, l1=350.0))
+    app = web.Application()
+    app.router.add_get("/api/v1/data", meter.handle)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    port = site._server.sockets[0].getsockname()[1]
+    async with aiohttp.ClientSession() as sess:
+        try:
+            return await fn(sess, port, meter)
+        finally:
+            await runner.cleanup()
+
+
+async def _arrivals(sess, port, meter):
+    ing = P1Ingest(phases=1, max_age_s=30.0)
+    src = HomeWizardLocalSource(sess, ing, "127.0.0.1", port=port, poll_s=1.0)
+    out = {}
+    out["first"] = await src.poll_once()
+    out["stamp1"] = ing.last.ingest_mono
+    # Four more polls of the IDENTICAL document - the meter has not moved a watt.
+    for _ in range(4):
+        await asyncio.sleep(0.05)
+        await src.poll_once()
+    out["ing"], out["src"], out["meter"] = ing, src, meter
+    return out
+
+
+r = asyncio.run(_hw_rig(_arrivals))
+ing, src = r["ing"], r["src"]
+check("a poll of the meter's own API builds a sample",
+      r["first"] is True and ing.net_w == 350.0)
+# ⚠️ THE acceptance criterion. Five identical readings, five arrivals. On
+# ha_signed this whole sequence produces exactly ONE state_changed and then
+# silence, and the age climbs to 30 s on a meter that is answering perfectly.
+check("five identical readings are five arrivals, not one",
+      ing.samples == 5 and r["meter"].hits == 5 and src.polls == 5)
+check("an unchanged value still stamps a NEW arrival time",
+      ing.last.ingest_mono > r["stamp1"])
+check("...so the age resets on a response carrying an unchanged number",
+      ing.published_age_s < 1.0 and ing.stale is False)
+check("no arrival was ever a parse error", ing.parse_errors == 0)
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: frozen vs steady, the pair HA cannot separate")
+# ⚠️ Read this before changing anything here. A frozen meter (hwsim --fault
+# freeze) answers 200 OK forever with a stale document. It is ARRIVING. So the
+# age - an arrival detector, correctly - reads fresh on both, and that is not a
+# defect in the age, it is the definition of the signal. What the local API adds
+# that Home Assistant never had is the ENERGY REGISTERS: a meter under real load
+# advances total_power_import_kwh (1 Wh resolution, ~10 s at 350 W) even when the
+# power figure repeats, and a frozen one does not. That is the discriminator, and
+# it is exposed as `unchanged_s` - deliberately NOT folded into the age, because
+# this controller regulates grid power toward ~0 W and at a converged -10 W the
+# export register needs six minutes to move. Thresholding unchanged_s at 30 s
+# would rebuild the false-trip limit cycle at the exact operating point we aim
+# for. See DOCS.md and HomeWizardLocalSource.unchanged_s.
+
+
+async def _freeze_vs_steady(sess, port, meter):
+    ing_f = P1Ingest(phases=1, max_age_s=30.0)
+    frozen = HomeWizardLocalSource(sess, ing_f, "127.0.0.1", port=port, poll_s=1.0)
+    meter.doc = hw_doc(350.0, l1=350.0)          # --fault freeze: never moves
+    for i in range(4):
+        if i:
+            await asyncio.sleep(0.1)             # sleep BEFORE, so unchanged_s
+        await frozen.poll_once()                 # is read the instant a poll lands
+
+    ing_s = P1Ingest(phases=1, max_age_s=30.0)
+    steady = HomeWizardLocalSource(sess, ing_s, "127.0.0.1", port=port, poll_s=1.0)
+    kwh = 1234.567
+    for i in range(4):
+        if i:
+            await asyncio.sleep(0.1)
+        # A steady 350 W house: the power figure repeats, the register climbs.
+        kwh += 0.001
+        meter.doc = hw_doc(350.0, l1=350.0, imp_kwh=round(kwh, 3))
+        await steady.poll_once()
+    return (ing_f, frozen), (ing_s, steady)
+
+
+(ing_f, frozen), (ing_s, steady) = asyncio.run(_hw_rig(_freeze_vs_steady))
+check("a frozen meter keeps arriving, so both read the same power",
+      ing_f.net_w == 350.0 and ing_s.net_w == 350.0)
+# ⚠️ Recorded as a rule, not a shortcoming: the age is an ARRIVAL detector and a
+# frozen meter genuinely is arriving. Anyone tempted to make the age catch freeze
+# is about to reintroduce the false trip on a steady house.
+check("the age cannot separate them, and is fresh on both",
+      ing_f.published_age_s < 1.0 and ing_s.published_age_s < 1.0)
+check("the frozen meter's measurement stands still", frozen.unchanged_s > 0.25)
+check("...while the steady meter's energy register keeps advancing",
+      steady.unchanged_s < 0.05)
+check("so the two ARE separable on the local API, which HA could not do",
+      frozen.unchanged_s > steady.unchanged_s * 3)
+check("unchanged_s is None before the first response ever lands",
+      HomeWizardLocalSource(None, P1Ingest(), "h").unchanged_s is None)
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: a failed poll is a missing reading, never 0 W")
+
+
+async def _failures(sess, port, meter):
+    ing = P1Ingest(phases=1, max_age_s=30.0)
+    src = HomeWizardLocalSource(sess, ing, "127.0.0.1", port=port, poll_s=1.0)
+    await src.poll_once()
+    # Age the good sample by hand so a reset would be unmistakable.
+    ing.submit(make_sample(SOURCE_HOMEWIZARD, 350.0, 0.0, phases=1,
+                           ingest_mono=time.monotonic() - 90.0))
+    out = {}
+    meter.status = 500
+    out["http500"] = await src.poll_once()
+    out["conn_after_500"] = src.connected
+    meter.status, meter.body = 200, "<html>gateway</html>"
+    out["notjson"] = await src.poll_once()
+    meter.body = None
+    meter.doc = {"total_gas_m3": 0.0}            # 200 OK, no power in it
+    out["nopower"] = await src.poll_once()
+    out["ing"], out["src"] = ing, src
+
+    # And a meter that is not listening at all: `--fault down`.
+    dead = HomeWizardLocalSource(sess, P1Ingest(phases=1, max_age_s=30.0),
+                                 "127.0.0.1", port=1, poll_s=1.0)
+    out["down"] = await dead.poll_once()
+    out["dead"] = dead
+    return out
+
+
+r = asyncio.run(_hw_rig(_failures))
+ing, src = r["ing"], r["src"]
+check("an HTTP 500 is not a reading", r["http500"] is False)
+# A source that was connected and then failed must SAY it is disconnected -
+# otherwise the diagnostic reads healthy while the age climbs, which is exactly
+# the "connected: True, parse_errors: 0, samples: 0" state the rig recorded.
+check("a poll that fails clears the connected flag", r["conn_after_500"] is False)
+check("a 200 OK carrying something that is not JSON is not a reading",
+      r["notjson"] is False)
+check("a 200 OK with no active_power_w in it is not a reading", r["nopower"] is False)
+check("a meter that refuses the connection is not a reading",
+      r["down"] is False and r["dead"].connected is False)
+check("every failure was counted as a parse error", ing.parse_errors == 3)
+check("...and the transport records the transport-level ones separately",
+      src.poll_errors == 2 and src.polls == 4)
+# ⚠️ The rule the safety chain rests on. A failed poll must not manufacture a
+# balanced house, and must not reset the clock the watchdog reads.
+check("a failed poll does not reset the age", ing.published_age_s > 89)
+check("a failed poll leaves the last good value in place, and it is not 0 W",
+      ing.last.net_w == 350.0 and ing.stale is True and ing.net_w is None)
+check("no failed poll ever became a sample", ing.samples == 2)
+check("a 200 OK marks the transport connected even when its body is refused",
+      src.connected is True)
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: a wrong header, a hung meter, a submit that throws")
+# Three failure shapes that all end the same way if they are mishandled - no
+# sample, a climbing age, the battery at 0 W - and each of which would send the
+# operator hunting the wrong device.
+
+
+async def _header_and_timeout(sess, port, meter):
+    out = {}
+    # Valid JSON under text/plain: exactly what content_type=None is for.
+    meter.body = json.dumps(hw_doc(350.0, l1=350.0))
+    ing = P1Ingest(phases=1, max_age_s=30.0)
+    src = HomeWizardLocalSource(sess, ing, "127.0.0.1", port=port, poll_s=1.0)
+    out["mimetype"] = await src.poll_once()
+    out["ing"] = ing
+    meter.body = None
+
+    # A meter that takes the connection and then does not answer.
+    meter.delay = 0.6
+    ing_t = P1Ingest(phases=1, max_age_s=30.0)
+    slow = HomeWizardLocalSource(sess, ing_t, "127.0.0.1", port=port,
+                                 poll_s=1.0, timeout_s=0.05)
+    out["timeout"] = await slow.poll_once()
+    out["timeout_err"] = ing_t.last_error
+    meter.delay = 0.0
+    return out
+
+
+r = asyncio.run(_hw_rig(_header_and_timeout))
+# ⚠️ A real firmware answering text/plain must not read as a dead meter. Drop
+# content_type=None from poll_once and this goes red with "unexpected mimetype".
+check("valid JSON under the wrong Content-Type is still a reading",
+      r["mimetype"] is True and r["ing"].samples == 1 and r["ing"].net_w == 350.0)
+# ⚠️ str(asyncio.TimeoutError()) is the EMPTY STRING. Without the class-name
+# fallback the status page reads "last error:" and then nothing, on a hung
+# meter, at the moment someone is reading that line to find out why the battery
+# went to 0 W.
+check("a timed-out poll names the fault instead of logging an empty reason",
+      r["timeout"] is False and "TimeoutError" in (r["timeout_err"] or ""))
+
+
+async def _submit_rejects(sess, port, meter):
+    """submit() raising P1Error must be a rejection, not an escaping exception."""
+    class _P1Boom(P1Ingest):
+        def submit(self, sample):
+            raise P1Error("register went backwards")
+
+    ing = _P1Boom(phases=1, max_age_s=30.0)
+    src = HomeWizardLocalSource(sess, ing, "127.0.0.1", port=port, poll_s=1.0)
+    try:
+        ok = await src.poll_once()
+    except Exception as err:      # noqa: BLE001 - an escape IS the failure
+        ok = err
+    return ok, ing.parse_errors
+
+
+ok, errs = asyncio.run(_hw_rig(_submit_rejects))
+check("a submit that rejects the sample is handled, not left to escape",
+      ok is False and errs == 1)
+
+
+async def _submit_explodes(sess, port, meter):
+    """And an UNEXPECTED raise must not kill the poll task for good."""
+    class _Boom(P1Ingest):
+        def submit(self, sample):
+            raise RuntimeError("kaboom")
+
+    src = HomeWizardLocalSource(sess, _Boom(phases=1, max_age_s=30.0),
+                                "127.0.0.1", port=port, poll_s=0.05)
+    task = asyncio.create_task(src.run())
+    await asyncio.sleep(0.3)
+    alive = not task.done()
+    task.cancel()
+    # ⚠️ BaseException, and the same reason built() exists: if run() loses its
+    # guard the task is already dead HOLDING the RuntimeError, and awaiting it
+    # re-raises - aborting the whole suite with a traceback instead of reddening
+    # the check that names the rule. The death is what `alive` records; catching
+    # it here is bookkeeping, not leniency.
+    try:
+        await task
+    except BaseException:  # noqa: BLE001
+        pass
+    return alive, src.polls
+
+
+# ⚠️ The silent-death case. A dead poll task fails SAFE - the age climbs and the
+# controller commands 0 W - but it looks exactly like a dead meter, so the
+# operator spends the outage power-cycling hardware that was never at fault.
+alive, polls = asyncio.run(_hw_rig(_submit_explodes))
+check("a raise inside a poll does not permanently kill the polling task",
+      alive is True and polls > 1)
+
+# --------------------------------------------------------------------------- #
+print("homewizard_local: selection by config")
+
+check("homewizard_local is enabled", is_enabled({"meter_source": SOURCE_HOMEWIZARD}) is True)
+sel = build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "192.168.2.250"},
+                   P1Ingest(), None, None)
+check("meter_source homewizard_local selects the polling transport",
+      isinstance(sel, HomeWizardLocalSource))
+# ⚠️ getattr, not attribute access, for the same reason `built()` exists: a
+# startup guard that goes wrong returns None here, and `None.url` would abort the
+# suite with a traceback instead of reddening the check that names the rule.
+check("...pointed at the meter's own local API on the default port",
+      getattr(sel, "url", None) == "http://192.168.2.250:80/api/v1/data")
+check("the default cadence is the meter's own ~5 s update rate",
+      getattr(sel, "poll_s", None) == 5.0)
+# ⚠️ The request must not outlive the poll interval: a backlog of queued requests
+# behind a slow meter would land several arrivals for one measurement.
+check("the request timeout is held under the poll interval",
+      getattr(sel, "timeout_s", 99) < getattr(sel, "poll_s", 0))
+
+sel = build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "10.0.0.9:8080"},
+                   P1Ingest(), None, None)
+check("an explicit host:port is honoured, which is how the sim is reached",
+      getattr(sel, "url", None) == "http://10.0.0.9:8080/api/v1/data")
+sel = build_source({"meter_source": SOURCE_HOMEWIZARD,
+                    "p1_host": "http://192.168.2.250/"}, P1Ingest(), None, None)
+check("a pasted browser URL still resolves to the right host",
+      getattr(sel, "url", None) == "http://192.168.2.250:80/api/v1/data")
+
+# ⚠️ Caught once at startup, not once per poll - a source wired up wrong
+# otherwise fails in the one way indistinguishable from a healthy one nobody has
+# polled yet: no samples, a climbing age, the watchdog at 0 W, nothing in the log.
+check("a blank p1_host is refused rather than silently never polling",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": ""},
+                   P1Ingest(), None, None) is None)
+check("...and whitespace does not sneak past it",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "   "},
+                   P1Ingest(), None, None) is None)
+check("an unparseable port is refused rather than guessed",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "meter:eighty"},
+                   P1Ingest(), None, None) is None)
+# ⚠️ The age can never be fresher than the poll interval, so a cadence at or past
+# max_age_s means every reading is stale before its successor arrives: the
+# controller would sit permanently on missing inputs while the meter is fine.
+check("a poll cadence at meter_max_age_s is refused",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "m",
+                    "meter_poll_s": 30}, P1Ingest(max_age_s=30), None, None) is None)
+check("...and one past it too",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "m",
+                    "meter_poll_s": 45}, P1Ingest(max_age_s=30), None, None) is None)
+check("a cadence with headroom is accepted",
+      isinstance(build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "m",
+                               "meter_poll_s": 5}, P1Ingest(max_age_s=30),
+                              None, None), HomeWizardLocalSource))
+check("a zero cadence is refused rather than spinning",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "m",
+                    "meter_poll_s": 0}, P1Ingest(max_age_s=30), None, None) is None)
+check("a non-numeric cadence is refused",
+      build_source({"meter_source": SOURCE_HOMEWIZARD, "p1_host": "m",
+                    "meter_poll_s": "fast"}, P1Ingest(max_age_s=30), None, None) is None)
+# The four modes must not bleed into each other.
+check("ha_signed ignores p1_host and still selects the entity transport",
+      type(build_source({"meter_source": SOURCE_HA_SIGNED, "p1_net_entity": "sensor.n",
+                         "p1_host": "192.168.2.250"}, P1Ingest(), None, None))
+      is HaSignedSource)
+check("homewizard_local ignores p1_net_entity and needs its own host",
+      build_source({"meter_source": SOURCE_HOMEWIZARD,
+                    "p1_net_entity": "sensor.n"}, P1Ingest(), None, None) is None)
+
 # --------------------------------------------------------------------------- #
 print("the age sensor must not exist when P1 is off")
 # ⚠️ This is a fleet-wide regression guard, not a nicety. The ESP32 watchdog
@@ -556,7 +1299,6 @@ print("the age sensor must not exist when P1 is off")
 # age were published with meter_source off it would climb past 30 s on every
 # existing install within half a minute and pin the inverter at 0 W forever.
 
-from app.p1 import is_enabled          # noqa: E402
 from app.mqtt import SENSORS, MqttPublisher   # noqa: E402
 
 check("meter_source off is disabled", is_enabled({"meter_source": "off"}) is False)
@@ -564,6 +1306,8 @@ check("a missing meter_source is disabled", is_enabled({}) is False)
 check("an empty meter_source is disabled", is_enabled({"meter_source": ""}) is False)
 check("ha_dsmr is enabled", is_enabled({"meter_source": SOURCE_HA}) is True)
 check("mqtt_p1 is enabled", is_enabled({"meter_source": SOURCE_MQTT}) is True)
+check("homewizard_local is enabled here too",
+      is_enabled({"meter_source": SOURCE_HOMEWIZARD}) is True)
 
 # The entity id SAFETY-01's firmware subscribes to, pinned by object_id.
 row = [s for s in SENSORS if s[0] == "p1_age"]
@@ -602,6 +1346,17 @@ check("with P1 on the age sensor IS announced",
 from app.main import Controller            # noqa: E402
 
 
+def _never():
+    """A stop Event these publish-only tests never set.
+
+    `stop` is a REQUIRED keyword argument (CFG-01): a Controller that cannot
+    stop itself used to be the default one, and on the late-refusal path that
+    meant a live process with no control loop and no exit. These cases only call
+    publish(), so any Event will do - but they may not skip it.
+    """
+    return asyncio.Event()
+
+
 class _Store:
     data = {}
 
@@ -624,18 +1379,80 @@ class _Pub:
 
 
 pub_off = _Pub()
-Controller({"meter_source": "off"}, None, _Store(), pub_off).publish()
+Controller({"meter_source": "off"}, None, _Store(), pub_off, stop=_never()).publish()
 check("with P1 off, p1_age is absent from the published payload",
       "p1_age" not in pub_off.last)
 check("...while the normal status keys are still published",
       "setpoint" in pub_off.last and "grid" in pub_off.last)
 
 pub_on = _Pub()
-Controller({"meter_source": SOURCE_HA}, None, _Store(), pub_on).publish()
+Controller({"meter_source": SOURCE_HA}, None, _Store(), pub_on, stop=_never()).publish()
 check("with P1 on, p1_age is published", "p1_age" in pub_on.last)
 check("...as a number, so has_state() becomes true only once we feed it",
       isinstance(pub_on.last["p1_age"], float))
 
+# ⚠️ And on ha_signed identically - this is the whole reason TEL-04 exists. The
+# age sensor is a hard prerequisite for the FW-01 flash, and it has to appear on
+# the transport that can actually read the meter in this house.
+pub_sig = _Pub()
+Controller({"meter_source": SOURCE_HA_SIGNED}, None, _Store(), pub_sig, stop=_never()).publish()
+check("with ha_signed selected, p1_age is published too",
+      "p1_age" in pub_sig.last and isinstance(pub_sig.last["p1_age"], float))
+
+# ⚠️ And on homewizard_local, where it is the one age FW-01 may actually
+# threshold - every other transport's age measures when the VALUE changed.
+pub_hw = _Pub()
+Controller({"meter_source": SOURCE_HOMEWIZARD}, None, _Store(), pub_hw, stop=_never()).publish()
+check("with homewizard_local selected, p1_age is published",
+      "p1_age" in pub_hw.last and isinstance(pub_hw.last["p1_age"], float))
+
+# --------------------------------------------------------------------------- #
+print("unchanged_s has somewhere an operator can read it")
+# ⚠️ The counter is deliberately NOT thresholded and NOT folded into the age -
+# at the converged -10 W this controller aims for, a 1 Wh register needs six
+# minutes to move, so any limit false-trips at the target operating point. That
+# refusal only holds up if a HUMAN can interpret the number instead, and DOCS.md
+# tells them "the transport tracks it as unchanged_s". Before this, nothing ever
+# read the transport object back: connected, polls, poll_errors and unchanged_s
+# were all write-only, and the documented signal existed nowhere an operator
+# could see it.
+
+
+def p1_rows(ctl):
+    """The P1 status line(s), or the exception that stopped checks() making one.
+
+    Same reason as built(): a status line that raises would abort the suite with
+    a traceback instead of reddening the check that names the rule.
+    """
+    try:
+        return [c["text"] for c in ctl.checks() if c["text"].startswith("P1 meter")]
+    except Exception as err:  # noqa: BLE001 - a raise here is itself the failure
+        print(f"       checks() raised {type(err).__name__}: {err}")
+        return err
+
+
+def _fed(source):
+    ctl = Controller({"meter_source": source}, None, _Store(), _Pub(), stop=_never())
+    ctl.p1.submit(make_sample(source, 350.0, 0.0, phases=1,
+                              ingest_mono=time.monotonic()))
+    return ctl
+
+
+hw_ctl = _fed(SOURCE_HOMEWIZARD)
+hw_src = HomeWizardLocalSource(None, hw_ctl.p1, "127.0.0.1")
+hw_src._note(hw_doc(350.0, l1=350.0))
+hw_ctl.p1_source = hw_src            # what amain() does once the transport exists
+rows = p1_rows(hw_ctl)
+check("the healthy P1 status line reports the transport's unchanged_s",
+      isinstance(rows, list) and len(rows) == 1 and "unchanged" in rows[0])
+
+# ⚠️ getattr, not attribute access: p1_source is None until amain() builds one,
+# and ha_dsmr/ha_signed/mqtt_p1 have no such counter at all. Reaching for it
+# directly would turn the whole status page into a 500 on every other transport.
+ha_rows = p1_rows(_fed(SOURCE_HA))
+check("...and the line is unharmed on a transport that has no such counter",
+      isinstance(ha_rows, list) and len(ha_rows) == 1 and "unchanged" not in ha_rows[0])
+
 print()
 if fails:
     print(f"{len(fails)} of {total} FAILED: {', '.join(fails)}")

goodwe_controller/test_price_forecast.py

@@ -0,0 +1,889 @@
+"""Runnable check for FCST-03 - provisional prices.  `python3 test_price_forecast.py`
+
+WHAT THIS FILE IS DEFENDING, in the order the ticket's acceptance criteria name
+it:
+
+  AC1  Every price point carries a `provisional` flag MATCHING ITS TRUE
+       PROVENANCE - a point filled from yesterday's profile is provisional even
+       when the number happens to be right, a point the feed published keeps
+       whatever flag the feed gave it, and an unmarked carry-forward is not
+       constructible rather than merely discouraged.
+  AC2  An irreversible action gated on a provisional price is REJECTED, with the
+       spec's own example - a maintenance-phase transition - actually refused:
+       the phase machine is still in `idle` afterwards.
+  AC3  Real-time / imbalance prices get MEASURABLY WIDER thresholds. Measured,
+       by finding the smallest spread each regime will accept and comparing the
+       two numbers - not by reading a constant back out of the module that
+       defines it.
+
+THREE RULES THIS FILE HOLDS ITSELF TO, because the reviewer will:
+
+  * EVERY VERDICT IS DERIVED. The carried/published split is re-derived here
+    from the set of hours the fixture published, by different arithmetic than
+    app/price_forecast.py uses; the DST day lengths come from the offset
+    difference rather than from a 23 or a 25 typed into a check; the widening
+    factor is MEASURED by bisecting the accept/refuse boundary and then
+    compared with the declared one.
+
+  * NO STIMULUS IS EVALUATED WHERE THE QUANTITY IT GRADES IS DEGENERATE, and
+    this ticket is full of that trap:
+      - YESTERDAY AND TODAY MUST PRICE EVERY HOUR DIFFERENTLY, or a fill that
+        carried the wrong day forward is invisible. Asserted first, as a check.
+      - THE PROVISIONAL HOURS MUST CONTAIN THE CHEAPEST HOUR, or "arbitrage
+        ignores provisional hours" grades nothing: the firm-only spread and the
+        whole-series spread would be the same number. Asserted before it is
+        used, and it is the realistic shape of the danger - yesterday's cheap
+        hour luring a charge that today's prices do not justify.
+      - THE TWO WIDENING FACTORS MUST DIFFER, or `max`, `sum` and `product` are
+        indistinguishable combination rules. Asserted, then all three are
+        computed and only one matches what the code does.
+      - THE LOCAL-HOUR FILL AND A NAIVE `t - 24 h` FILL MUST DISAGREE on the
+        transition days, or the DST check passes for both implementations.
+        Asserted, then the correct one is graded.
+      - PRICES ARE WRITTEN TO SIX DECIMALS with distinct 3-, 4- and 6-dp
+        roundings, so an implementation that rounds differently is visible.
+        (TARIFF-03's fixtures were 3-dp, where those three are one number.)
+
+  * A FAILED READ IS NOT AN OBSERVATION. A missing price is not a zero price
+    and a stale one is not a fresh one: the gate blocks on `no_data`, blocks on
+    an hour the series does not cover, and blocks on a provisional hour - three
+    different reasons, none of them an answer.
+"""
+
+import ast
+import inspect
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app import price as _price
+from app import price_forecast as _fc
+from app import static_tariff as _st
+from app.maintenance import (
+    CHARGE_TIMEOUT_MIN, DRAIN_TIMEOUT_MIN, DRAIN, IDLE, MaintConfig, Maintenance,
+)
+from app.price import (
+    Absence, PricePoint, PriceProduct, PriceRead, PROVIDERS, Uncertainty,
+    WIDEN_FACTOR, brussels, brussels_offset, plan_is_provisional,
+    required_spread, uncertainty_of, widen_factor,
+)
+from app.price_forecast import (
+    MAINTENANCE_CHARGE, MAINTENANCE_DRAIN, Gate, Irreversible, committed_hours,
+    fill_from_yesterday, price_permits, begin_phase,
+)
+from app.static_tariff import Arbitrage, TariffPlan
+
+UTC = timezone.utc
+HERE = os.path.dirname(os.path.abspath(__file__))
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+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
+    the same."""
+    try:
+        fn()
+    except exc:
+        return True
+    except Exception:
+        return False
+    return False
+
+
+class _Raised:
+    def __init__(self, e):
+        self.e = e
+
+    def __eq__(self, other):
+        return False
+
+    def __hash__(self):
+        return id(self)
+
+    def __bool__(self):
+        return False
+
+    def __repr__(self):
+        return f"<raised {type(self.e).__name__}: {self.e}>"
+
+
+def derived(fn):
+    """A value a check grades. An exception becomes `_Raised`, which equals
+    nothing and is falsy - NOT a default."""
+    try:
+        return fn()
+    except Exception as e:                                    # noqa: BLE001
+        return _Raised(e)
+
+
+def near(a, b, tol=1e-9):
+    try:
+        return abs(float(a) - float(b)) <= tol
+    except (TypeError, ValueError):
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures.
+#
+# ⚠️ SIX-DECIMAL PRICES, DELIBERATELY. TARIFF-03's fixtures were 0.3410 /
+# 0.2570, where rounding to 3, 4 and 6 decimals gives the same number - so an
+# implementation that rounded differently from the one being graded survived
+# every check. These are chosen so those three roundings differ.
+# --------------------------------------------------------------------------- #
+
+def y_price(h):
+    """Yesterday's all-in EUR/kWh for local hour h."""
+    return round(0.123437 + 0.010700 * h, 6)
+
+
+def t_price(h):
+    """Today's PUBLISHED all-in EUR/kWh for local hour h. Different from
+    yesterday's at every hour, on purpose - see the degeneracy note above."""
+    return round(0.206562 + 0.009300 * h, 6)
+
+
+def local_midnight(y, m, d) -> datetime:
+    """The UTC instant of Brussels local midnight on that date, derived from
+    `brussels_offset` rather than from a table of dates."""
+    naive = datetime(y, m, d, 0, 0)
+    for hours in (1, 2):
+        guess = naive.replace(tzinfo=UTC) - timedelta(hours=hours)
+        if brussels_offset(guess).utcoffset(None) == timedelta(hours=hours):
+            return guess
+    raise AssertionError(f"no consistent Brussels offset for {naive}")
+
+
+def hours_between(a, b):
+    out, u = [], a
+    while u < b:
+        out.append(u)
+        u += timedelta(hours=1)
+    return out
+
+
+def series_of(instants, price_of, product, provider, *, provisional):
+    return PriceRead.series(
+        [PricePoint(start=brussels(u), eur_per_kwh=price_of(u),
+                    provisional=provisional) for u in instants],
+        product, provider, instants[0])
+
+
+# A plain winter day: local 2026-01-15, 24 hours, no transition in sight.
+D0 = local_midnight(2026, 1, 15)
+D1 = local_midnight(2026, 1, 16)
+YEST0 = local_midnight(2026, 1, 14)
+DAY = hours_between(D0, D1)
+YDAY = hours_between(YEST0, D0)
+
+YESTERDAY = series_of(YDAY, lambda u: y_price(brussels(u).hour),
+                      PriceProduct.DAY_AHEAD, "generic_dayahead",
+                      provisional=False)
+# The feed has published the first 12 hours of today and nothing after - the
+# ordinary state of a dynamic site before the 14-16 h CET print (§5.4).
+PUBLISHED_N = 12
+TODAY_PART = series_of(DAY[:PUBLISHED_N], lambda u: t_price(brussels(u).hour),
+                       PriceProduct.DAY_AHEAD, "generic_dayahead",
+                       provisional=False)
+
+
+print()
+print("0. the fixtures are not degenerate (checked before anything is graded)")
+
+check("yesterday and today price EVERY shared hour differently, so a fill that "
+      "carried the wrong day forward would be visible in the value and not "
+      "only in the flag",
+      all(y_price(h) != t_price(h) for h in range(24)))
+_roundings = derived(lambda: {round(y_price(3), n) for n in (3, 4, 6)})
+check(f"...and a fixture price rounds to three DIFFERENT numbers at 3, 4 and 6 "
+      f"decimals {sorted(_roundings)}, so a divergent rounding cannot hide",
+      len(_roundings) == 3)
+check("...and both widening factors differ, so max / sum / product are three "
+      "distinguishable answers",
+      len(set(WIDEN_FACTOR.values())) == len(WIDEN_FACTOR) >= 2)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("1. AC1 - the flag matches PROVENANCE, and an unmarked fill is not "
+      "constructible")
+
+FILLED = fill_from_yesterday(TODAY_PART, yesterday=YESTERDAY,
+                             since=D0, until=D1, stamp=D0)
+
+_pub_starts = {u for u in DAY[:PUBLISHED_N]}
+_expected_prov = {u: (u not in _pub_starts) for u in DAY}
+_got_prov = derived(lambda: {p.start.astimezone(UTC): p.provisional
+                             for p in FILLED.points})
+check(f"the filled series covers every hour of the day "
+      f"{len(FILLED.points) if FILLED.kind == 'series' else FILLED}",
+      FILLED.kind == "series" and len(FILLED.points) == len(DAY))
+check("...and EVERY point's flag equals what its provenance says it should be, "
+      "re-derived here from the set of hours the fixture published",
+      _got_prov == _expected_prov)
+_carried = derived(lambda: [p for p in FILLED.points if p.provisional])
+check(f"...which is {len(DAY) - PUBLISHED_N} carried hours and {PUBLISHED_N} "
+      f"published ones, counted rather than asserted",
+      len(_carried) == len(DAY) - PUBLISHED_N)
+check("...and the carried hours carry YESTERDAY's number for the same wall "
+      "clock hour, not today's and not a neighbour's",
+      all(near(p.eur_per_kwh, y_price(brussels(p.start).hour))
+          for p in _carried))
+check("...while the published hours carry TODAY's, so the two halves are not "
+      "the same data wearing two flags",
+      all(near(p.eur_per_kwh, t_price(brussels(p.start).hour))
+          for p in FILLED.points if not p.provisional))
+
+# ⚠️ THE COPY IS THE DEFECT. A published point that survives as a COPY is one
+# whose flag could have been rewritten on the way through; identity is the only
+# property that rules that out for every field at once.
+check("a published point is passed through BY IDENTITY - the object the "
+      "provider produced is the object in the filled series",
+      all(any(p is q for q in TODAY_PART.points)
+          for p in FILLED.points if not p.provisional))
+check("...and the canonical §9.3 dict carries the flag out to the wire for "
+      "both kinds",
+      FILLED.canonical()["prices"][0]["provisional"] is False
+      and FILLED.canonical()["prices"][-1]["provisional"] is True)
+check("...and plan_is_provisional() sees the series as provisional overall, "
+      "because at least one hour is",
+      plan_is_provisional(FILLED) is True)
+
+# The audit is a post-condition that RAISES. Feed it the exact defect.
+_stale_copy = PricePoint(start=FILLED.points[-1].start,
+                         eur_per_kwh=FILLED.points[-1].eur_per_kwh,
+                         provisional=False)         # the copy-the-flag bug
+check("the provenance audit REFUSES a carried hour flagged non-provisional - "
+      "the 'stale but plausible' point, which is SAFETY-18's frozen-but-fresh "
+      "meter one layer up",
+      raises(lambda: _fc._audit([_stale_copy], {}), ValueError))
+check("...and refuses a published hour that arrived as a COPY rather than as "
+      "the published object, which is where a flag gets lost",
+      raises(lambda: _fc._audit(
+          [PricePoint(start=TODAY_PART.points[0].start,
+                      eur_per_kwh=TODAY_PART.points[0].eur_per_kwh,
+                      provisional=TODAY_PART.points[0].provisional)],
+          {D0: TODAY_PART.points[0]}), ValueError))
+check("...and never repairs a flag: the audit's only outcomes are silence and "
+      "an exception, so a series it passed was already correct",
+      _fc._audit(list(FILLED.points), {u: TODAY_PART.points[i]
+                                       for i, u in enumerate(DAY[:PUBLISHED_N])})
+      is None)
+
+# ⚠️ A PUBLISHED POINT MAY BE PROVISIONAL. eneco_eddy's current-quarter print
+# is settled after the fact and says so (§9.2). "Published" is not "firm".
+_eddy = series_of(DAY[:2], lambda u: t_price(brussels(u).hour),
+                  PriceProduct.REALTIME, "eneco_eddy", provisional=True)
+_eddy_filled = derived(lambda: fill_from_yesterday(
+    _eddy, yesterday=YESTERDAY, since=D0, until=D1, stamp=D0))
+check("a PUBLISHED point that the feed itself flagged provisional keeps that "
+      "flag - the audit checks provenance, and does not force published hours "
+      "to False",
+      _eddy_filled.kind == "series"
+      and all(p.provisional for p in _eddy_filled.points[:2])
+      and _eddy_filled.points[0] is _eddy.points[0])
+
+# The structural half: the constructor has nothing to pass, and the file is
+# scanned so the pass-through idiom cannot come back looking ordinary.
+check("_carried() has NO `provisional` parameter, so a caller has nothing to "
+      "forget, default, or copy from the point being carried",
+      "provisional" not in inspect.signature(_fc._carried).parameters)
+_SRC = derived(lambda: open(os.path.join(HERE, "app", "price_forecast.py"),
+                            encoding="utf-8").read())
+
+
+def _nonliteral_provisional(src):
+    """Every `PricePoint(...)` in the module whose `provisional` is not a
+    literal. AST, not a substring: the module docstring quotes the defect it
+    exists to prevent, and a text scan would match its own documentation."""
+    out = []
+    for node in ast.walk(ast.parse(src)):
+        if isinstance(node, ast.Call) and \
+                getattr(node.func, "id", None) == "PricePoint":
+            kw = {k.arg: k.value for k in node.keywords}
+            v = kw.get("provisional")
+            if not isinstance(v, ast.Constant):
+                out.append(ast.dump(node)[:80])
+    return out
+
+
+_leaks = derived(lambda: _nonliteral_provisional(_SRC))
+check(f"no PricePoint built in app/price_forecast.py takes its `provisional` "
+      f"from an expression - it is a literal at every construction site, so "
+      f"`provisional=y.provisional` cannot reappear in a later edit {_leaks}",
+      _leaks == [])
+# The scan must be able to fail, or it grades nothing.
+check("...and that scan FAILS on the defect it names, so it is a check and not "
+      "a decoration",
+      _nonliteral_provisional(
+          "PricePoint(start=t, eur_per_kwh=v, provisional=y.provisional)") != [])
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("2. the fill keys on the WALL CLOCK, so the 23- and 25-hour days are right")
+
+for label, (y, m, d) in (("spring forward (23 h)", (2026, 3, 29)),
+                         ("fall back (25 h)", (2026, 10, 25))):
+    a = local_midnight(y, m, d)
+    b = local_midnight(y, m, d + 1)
+    yb = local_midnight(y, m, d - 1)
+    yesterday = series_of(hours_between(yb, a),
+                          lambda u: y_price(brussels(u).hour),
+                          PriceProduct.DAY_AHEAD, "generic_dayahead",
+                          provisional=False)
+    # Nothing published at all yet: the whole day is carried forward.
+    nothing = PriceRead.no_data("the day-ahead print has not landed yet")
+    got = derived(lambda: fill_from_yesterday(nothing, yesterday=yesterday,
+                                              since=a, until=b, stamp=a))
+    # ⚠️ DERIVED FROM THE OFFSETS, not from a 23 or a 25 typed here.
+    off_a = brussels_offset(a).utcoffset(None).total_seconds() / 3600
+    off_b = brussels_offset(b - timedelta(seconds=1)).utcoffset(None) \
+        .total_seconds() / 3600
+    expect = int(24 - (off_b - off_a))
+    check(f"{label}: the day is {expect} hours long, derived from the offset "
+          f"change {off_a:+.0f} -> {off_b:+.0f}, and the fill emits exactly "
+          f"that many",
+          got.kind == "series" and len(got.points) == expect)
+    check(f"{label}: every hour of it is flagged provisional - nothing was "
+          f"published",
+          got.kind == "series" and all(p.provisional for p in got.points))
+    # The discriminating part: a naive `t - 24 h` fill would give a DIFFERENT
+    # answer here, so this check separates the two implementations.
+    y_by_utc = {u: y_price(brussels(u).hour) for u in hours_between(yb, a)}
+    naive = [y_by_utc.get(u - timedelta(hours=24)) for u in hours_between(a, b)]
+    wall = [y_price(brussels(u).hour) for u in hours_between(a, b)]
+    check(f"{label}: the wall-clock fill and a naive t-24h fill DISAGREE, so "
+          f"the check below can tell them apart",
+          naive != wall)
+    check(f"{label}: ...and the emitted values are the WALL-CLOCK ones",
+          got.kind == "series"
+          and [round(p.eur_per_kwh, 6) for p in got.points] == wall)
+
+# The 25-hour day's two 02:00 hours are two distinct instants, both filled.
+_oct = local_midnight(2026, 10, 25)
+_oct_end = local_midnight(2026, 10, 26)
+_oct_fill = fill_from_yesterday(
+    PriceRead.no_data("nothing yet"),
+    yesterday=series_of(hours_between(local_midnight(2026, 10, 24), _oct),
+                        lambda u: y_price(brussels(u).hour),
+                        PriceProduct.DAY_AHEAD, "generic_dayahead",
+                        provisional=False),
+    since=_oct, until=_oct_end, stamp=_oct)
+_twos = [p for p in _oct_fill.points if brussels(p.start).hour == 2]
+check("the 25-hour day has TWO local 02:00 points, at different offsets, and "
+      "both are filled and both are flagged - a 24-slot implementation would "
+      "collide them into one",
+      len(_twos) == 2
+      and _twos[0].start.utcoffset() != _twos[1].start.utcoffset()
+      and all(p.provisional for p in _twos))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("3. §5.4 - a late publication REPLACES a carried hour and re-flags it")
+
+_late = fill_from_yesterday(
+    series_of(DAY, lambda u: t_price(brussels(u).hour),
+              PriceProduct.DAY_AHEAD, "generic_dayahead", provisional=False),
+    yesterday=YESTERDAY, since=D0, until=D1, stamp=D1)
+_h20 = DAY[20]
+_before = derived(lambda: FILLED.at(_h20))
+_after = derived(lambda: _late.at(_h20))
+check("before the print, hour 20 is provisional and carries YESTERDAY's number",
+      _before.provisional is True and near(_before.eur_per_kwh, y_price(20)))
+check("...after it, the same hour is FIRM and carries today's - the flag and "
+      "the number move together, because the series is rebuilt and not patched",
+      _after.provisional is False and near(_after.eur_per_kwh, t_price(20)))
+check("...and the two numbers actually differ, so 'it was replaced' is a "
+      "measurement and not a restatement",
+      not near(_before.eur_per_kwh, _after.eur_per_kwh))
+check("...and re-running the fill over an already-complete series changes "
+      "nothing: it is idempotent",
+      [p.canonical() for p in fill_from_yesterday(
+          _late, yesterday=YESTERDAY, since=D0, until=D1, stamp=D1).points]
+      == [p.canonical() for p in _late.points])
+
+# Nothing to fill from, and nothing published: no_data, never an empty series.
+_nothing = derived(lambda: fill_from_yesterday(
+    PriceRead.no_data("the feed timed out"),
+    yesterday=PriceRead.no_data("and there is no yesterday either"),
+    since=D0, until=D1, stamp=D0))
+check("with neither a published hour nor a yesterday, the result is no_data - "
+      "not an empty series, and not a series of zeros",
+      _nothing.kind == "no_data")
+check("...so it has no .points to iterate and no .get() to default out of",
+      raises(lambda: _nothing.points, Absence)
+      and raises(lambda: _nothing.get("points", []), Absence))
+check("...and its reason names §11.4 for an operator",
+      "§11.4" in _nothing.reason)
+check("a naive `since` is refused rather than silently interpreted as UTC",
+      raises(lambda: fill_from_yesterday(TODAY_PART, yesterday=YESTERDAY,
+                                         since=datetime(2026, 1, 15),
+                                         until=D1, stamp=D0), ValueError))
+check("...and `yesterday` has no default, so a fill with nothing to fill from "
+      "cannot be written by accident",
+      raises(lambda: fill_from_yesterday(TODAY_PART, since=D0, until=D1,
+                                         stamp=D0), TypeError))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("4. AC2 - an irreversible action is REJECTED on a provisional price")
+
+
+class FakeStore:
+    """Same surface as app/store.Store, no disk. Copied from test_maintenance."""
+
+    def __init__(self):
+        self.data = {"phase": IDLE, "phase_started": None,
+                     "last_completed": None, "last_start_attempt": None}
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def set_time(self, k, when):
+        self.data[k] = when
+
+    def get_time(self, k):
+        return self.data.get(k)
+
+    def save(self):
+        pass
+
+
+def maint():
+    return Maintenance(MaintConfig(enabled=True), FakeStore())
+
+
+check("the drain's commitment window is DERIVED from the phase machine's own "
+      "timeout, so the gate and maintenance.py cannot drift apart",
+      near(MAINTENANCE_DRAIN.commits_h, DRAIN_TIMEOUT_MIN / 60.0)
+      and near(MAINTENANCE_CHARGE.commits_h, CHARGE_TIMEOUT_MIN / 60.0))
+# The shipped `maintenance_start_hour` is 10:00 local, so a drain started on
+# schedule runs into the evening - hours a morning-only day-ahead print has not
+# covered. That is the ticket's scenario and it is where the window is placed.
+START = D0 + timedelta(hours=MaintConfig().start_hour)
+_hours = derived(lambda: committed_hours(START, MAINTENANCE_DRAIN))
+check(f"...and it commits {len(_hours) if not isinstance(_hours, _Raised) else _hours} "
+      f"whole hours, one per hour of the timeout",
+      len(_hours) == int(DRAIN_TIMEOUT_MIN / 60))
+check("an action that commits nothing is not an irreversible one and cannot be "
+      "declared", raises(lambda: Irreversible("X", 0), ValueError)
+      and raises(lambda: Irreversible("", 4), ValueError))
+
+# The stimulus: the first hours are firm, the drain's window reaches into the
+# carried ones. THIS is the ticket's scenario - a cycle started at 10:00 on
+# prices that were published for the morning and guessed for the evening.
+_m = maint()
+_gate_bad = derived(lambda: begin_phase(_m, START, FILLED, MAINTENANCE_DRAIN))
+_first_prov = derived(lambda: next(u for u in _hours if FILLED.at(u).provisional))
+check("the drain's window really does reach past the published hours while "
+      "staying INSIDE the series, so the refusal below is about provenance and "
+      "not about a short series",
+      FILLED.covers(_hours[-1])
+      and any(not FILLED.at(u).provisional for u in _hours)
+      and any(FILLED.at(u).provisional for u in _hours))
+check("a maintenance DRAIN whose window includes a carried-forward hour is "
+      "BLOCKED", _gate_bad.kind == "blocked")
+check("...and the phase machine did not move: it is still idle, so the "
+      "rejection is of the ACTION and not merely of a verdict object",
+      _m.phase == IDLE)
+check("...and the reason names §8.3, the offending hour, and when the real "
+      "price is expected",
+      "§8.3" in _gate_bad.reason
+      and _first_prov.isoformat() in _gate_bad.reason
+      and "14-16" in _gate_bad.reason)
+
+# The positive arm, so the block above is discriminating rather than universal.
+_firm_long = series_of(hours_between(START,
+                                     START + timedelta(hours=len(_hours) + 2)),
+                       lambda u: t_price(brussels(u).hour % 24),
+                       PriceProduct.DAY_AHEAD, "generic_dayahead",
+                       provisional=False)
+_m2 = maint()
+_gate_ok = derived(lambda: begin_phase(_m2, START, _firm_long,
+                                       MAINTENANCE_DRAIN))
+check("...while the SAME transition on a fully published series is PERMITTED, "
+      "and the phase machine actually moves to drain",
+      _gate_ok.kind == "permitted" and _m2.phase == DRAIN)
+check("...and the permitting arm carries the evidence it checked - one firm "
+      "point per committed hour",
+      _gate_ok.kind == "permitted" and len(_gate_ok.hours) == len(_hours)
+      and not any(p.provisional for p in _gate_ok.hours))
+
+# The other two ways a price can fail to be an observation.
+_m3 = maint()
+_gate_none = begin_phase(_m3, START, PriceRead.no_data("the feed timed out"),
+                         MAINTENANCE_DRAIN)
+check("no price data at all BLOCKS an irreversible action too - a missing "
+      "price is not a cheap one (§11.4)",
+      _gate_none.kind == "blocked" and "§11.4" in _gate_none.reason
+      and _m3.phase == IDLE)
+_short = series_of(DAY[:4], lambda u: t_price(brussels(u).hour),
+                   PriceProduct.DAY_AHEAD, "generic_dayahead",
+                   provisional=False)
+_gate_short = price_permits(_short, D0, MAINTENANCE_DRAIN)
+check("...and so does an hour the series does not cover, which is §11.4 for "
+      "that hour rather than a reason to reach for a neighbour",
+      _gate_short.kind == "blocked" and "no price covers" in _gate_short.reason)
+
+# The variant type itself, held to the same shape as PriceRead and Arbitrage.
+check("a BLOCKED gate carries a reason and nothing else: .hours and .action "
+      "raise Absence rather than answering with an empty tuple",
+      raises(lambda: _gate_bad.hours, Absence)
+      and raises(lambda: _gate_bad.action, Absence))
+check("...it is not iterable and has no .get(), the other two routes to an "
+      "empty, harmless-looking loop",
+      raises(lambda: list(_gate_bad), Absence)
+      and raises(lambda: _gate_bad.get("hours", []), Absence))
+check("...match() demands BOTH arms, so the block cannot be fallen through",
+      raises(lambda: _gate_bad.match(permitted=lambda g: 1), TypeError))
+check("...and there is no falsy variant, so `if gate:` cannot look like a "
+      "guard while being none",
+      bool(_gate_bad) is True and bool(_gate_ok) is True)
+# A genuinely carried point - the flagged one, not the mis-flagged copy above.
+_prov_pt = FILLED.points[-1]
+check("the point the two constructor checks below are handed really is "
+      "provisional, or they would be grading nothing",
+      _prov_pt.provisional is True)
+check("a permitted gate cannot be built over a provisional hour or over no "
+      "hours at all - §8.3 is the one rule this type has",
+      raises(lambda: Gate.permit(MAINTENANCE_DRAIN, [_prov_pt]), ValueError)
+      and raises(lambda: Gate.permit(MAINTENANCE_DRAIN, []), ValueError))
+
+# TEST-14, PORTED. A default on any of these constructors reopens the exact
+# hole `_NoData.reason` had - and static_tariff's `_Refused.reason` still has,
+# because nothing scanned it. Scanned by SIGNATURE, so a default added later is
+# red without anyone remembering to write a new case.
+def _defaulted(fn):
+    try:
+        ps = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError) as e:                      # pragma: no cover
+        return _Raised(e)
+    return [q.name for q in ps
+            if q.name != "self" and q.default is not inspect.Parameter.empty]
+
+
+_ctors = {"Gate.permit": Gate.permit, "Gate.block": Gate.block,
+          "Gate.match": Gate.match,
+          "_Permitted.__init__": _fc._Permitted.__init__,
+          "_Blocked.__init__": _fc._Blocked.__init__,
+          # ⚠️ static_tariff's outcome type is scanned HERE because nothing
+          # scanned it before: TEST-14 records `_Refused.reason` gaining a
+          # default as a mutation that survived every check in that file.
+          "Arbitrage.allow": Arbitrage.allow, "Arbitrage.refuse": Arbitrage.refuse,
+          "Arbitrage.match": Arbitrage.match,
+          "_Allowed.__init__": _st._Allowed.__init__,
+          "_Refused.__init__": _st._Refused.__init__}
+_with_defaults = derived(lambda: {n: d for n, d in
+                                  ((n, _defaulted(f)) for n, f in _ctors.items())
+                                  if d})
+check(f"no constructor or handler of an outcome type - Gate's OR Arbitrage's - "
+      f"carries a DEFAULT, so a verdict can never be built out of nothing "
+      f"{_with_defaults}", _with_defaults == {})
+check("...so a block with no reason is a TypeError at the call site, not a "
+      "blank status line",
+      raises(lambda: Gate.block(), TypeError)
+      and raises(lambda: Gate.block(""), ValueError))
+check("...and the same holds for the refusal FCST-03 added to Arbitrage",
+      raises(lambda: Arbitrage.refuse(), TypeError))
+# ⚠️ ONE CALL PER ROLE, AND THE FIRST DRAFT SHOWED WHY. Passing the provisional
+# point as BOTH `cheapest` and `dearest` is a stimulus that cannot distinguish
+# "the constructor guards the cheapest hour" from "the constructor guards both
+# hours": a guard on either one alone raises, and the check goes green for an
+# implementation that leaves the sell hour unguarded. That is the degeneracy
+# rule this file states at the top, in a new dress - so the two roles are
+# stimulated SEPARATELY, each with a firm point in the other seat.
+_firm_pt = TODAY_PART.points[0]
+check("the two points these constructor checks use really differ in provenance, "
+      "or neither of them grades anything",
+      _prov_pt.provisional is True and _firm_pt.provisional is False)
+check("an ALLOWED arbitrage verdict cannot be constructed with a provisional "
+      "CHEAPEST hour - the buy hour - even directly: §8.3 is enforced at the "
+      "constructor, not only in the ladder above it",
+      raises(lambda: Arbitrage.allow(0.1, _prov_pt, _firm_pt, "normal",
+                                     PriceProduct.DAY_AHEAD, 0.0, frozenset()),
+             ValueError))
+check("...nor with a provisional DEAREST hour - the sell hour - which a guard "
+      "written for `cheapest` alone would have let through",
+      raises(lambda: Arbitrage.allow(0.1, _firm_pt, _prov_pt, "normal",
+                                     PriceProduct.DAY_AHEAD, 0.0, frozenset()),
+             ValueError))
+check("...while two firm points build the verdict perfectly well, so the two "
+      "refusals above are discriminating rather than universal",
+      Arbitrage.allow(0.1, _firm_pt, _firm_pt, "normal",
+                      PriceProduct.DAY_AHEAD, 0.0, frozenset()).kind
+      == "allowed")
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("5. AC3 - real-time thresholds are MEASURABLY wider (measured, not read)")
+
+
+def plan_with_spread(spread, product, provider):
+    """A two-hour series with exactly `spread` between its two prices."""
+    lo, hi = 0.150000, round(0.150000 + spread, 6)
+    pts = [PricePoint(start=brussels(D0), eur_per_kwh=lo, provisional=False),
+           PricePoint(start=brussels(D0 + timedelta(hours=1)),
+                      eur_per_kwh=hi, provisional=False)]
+    return TariffPlan(PriceRead.series(pts, product, provider, D0), None,
+                      "provider")
+
+
+def min_accepted_spread(product, sources, base, provider="generic_dayahead"):
+    """The SMALLEST spread this configuration will trade on, found by bisecting
+    the accept/refuse boundary of the real verdict. Nothing here reads a
+    factor out of the module it is grading."""
+    lo, hi = 0.0, 4.0
+    for _ in range(60):
+        mid = (lo + hi) / 2
+        v = plan_with_spread(mid, product, provider).arbitrage(
+            peak_guard_active=False, min_spread_eur_kwh=base,
+            uncertainty=sources)
+        if v.kind == "allowed":
+            hi = mid
+        else:
+            lo = mid
+    return hi
+
+
+BASE = 0.104000        # a caller's own round-trip cost threshold, EUR/kWh
+_normal = derived(lambda: min_accepted_spread(PriceProduct.DAY_AHEAD,
+                                              frozenset(), BASE))
+_wide = derived(lambda: min_accepted_spread(PriceProduct.REALTIME,
+                                            frozenset(), BASE))
+_weather = derived(lambda: min_accepted_spread(
+    PriceProduct.DAY_AHEAD, frozenset({Uncertainty.NO_WEATHER}), BASE))
+_both = derived(lambda: min_accepted_spread(
+    PriceProduct.REALTIME, frozenset({Uncertainty.NO_WEATHER}), BASE))
+
+check(f"a day-ahead product trades on any spread above its own threshold "
+      f"{_normal:.6f}, which is the base {BASE} it was given",
+      near(_normal, BASE, 1e-6))
+check(f"a REAL-TIME / imbalance product needs {_wide:.6f} - MEASURABLY wider, "
+      f"by a factor of {(_wide / _normal) if _normal else 0:.3f} measured from "
+      f"two verdict boundaries and not read from any constant",
+      _wide > _normal + 1e-6)
+check(f"...and that measured factor equals the declared one for "
+      f"REALTIME_PRODUCT ({WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT]}), so "
+      f"the declaration and the behaviour are the same thing",
+      near(_wide / _normal, WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT], 1e-4))
+check(f"§11.4's no-weather row reaches the SAME widening path by a different "
+      f"trigger, and lands at {_weather:.6f}",
+      near(_weather / _normal, WIDEN_FACTOR[Uncertainty.NO_WEATHER], 1e-4))
+
+# ⚠️ THE COMBINATION RULE, ON A STIMULUS WHERE THE THREE CANDIDATES DIFFER.
+_f1 = WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT]
+_f2 = WIDEN_FACTOR[Uncertainty.NO_WEATHER]
+check(f"with BOTH sources active the threshold is max(f1,f2)={max(_f1, _f2)} x "
+      f"base and NOT the product ({_f1 * _f2}) or the sum ({_f1 + _f2}) - two "
+      f"independent doubts must not compound into a threshold nothing can "
+      f"clear",
+      near(_both / _normal, max(_f1, _f2), 1e-4)
+      and not near(_both / _normal, _f1 * _f2, 1e-3)
+      and not near(_both / _normal, _f1 + _f2, 1e-3))
+
+# The regime must follow the DECLARED product, never the plugin id.
+_wide_named_dayahead = derived(lambda: min_accepted_spread(
+    PriceProduct.REALTIME, frozenset(), BASE, provider="generic_dayahead"))
+_normal_named_eddy = derived(lambda: min_accepted_spread(
+    PriceProduct.DAY_AHEAD, frozenset(), BASE, provider="eneco_eddy"))
+check("the widening follows the DECLARED PriceProduct even when the provider "
+      "is called 'generic_dayahead', and does NOT follow the name "
+      "'eneco_eddy' when the declared product is day-ahead - so a sixth "
+      "supplier is widened by its declaration and not by an id in a list",
+      near(_wide_named_dayahead, _wide, 1e-9)
+      and near(_normal_named_eddy, _normal, 1e-9))
+check("...and the shipped plugin §9.2 names IS the one that declares REALTIME, "
+      "so the mechanism is pointed at the real product",
+      PROVIDERS["eneco_eddy"].capabilities().product is PriceProduct.REALTIME
+      and uncertainty_of(PriceProduct.REALTIME)
+      == frozenset({Uncertainty.REALTIME_PRODUCT})
+      and uncertainty_of(PriceProduct.DAY_AHEAD) == frozenset())
+check("a string in the uncertainty set is REFUSED rather than widening by 1.0 "
+      "and reporting that it widened",
+      raises(lambda: widen_factor({"realtime"}), TypeError)
+      and raises(lambda: required_spread(0.1, {"realtime"}), TypeError))
+check("...and a negative or non-finite base threshold is refused, since it is "
+      "one every spread clears",
+      raises(lambda: required_spread(-0.01, frozenset()), ValueError)
+      and raises(lambda: required_spread(float("nan"), frozenset()), ValueError))
+check("required_spread() with nothing uncertain is the base itself, so the "
+      "widening is additive machinery and not a permanent surcharge",
+      near(required_spread(BASE, frozenset()), BASE))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("6. the refusal ladder - provisional hours are DROPPED, not traded on")
+
+# ⚠️ THE PROVISIONAL HOURS CARRY THE CHEAPEST PRICE. That is the realistic
+# danger (yesterday's cheap night luring a charge) AND the non-degenerate
+# stimulus: the firm-only spread and the whole-series spread differ, so a check
+# on the spread can tell which set was used.
+_cheap_stale = [PricePoint(start=brussels(DAY[i]),
+                           eur_per_kwh=0.041250, provisional=True)
+                for i in range(3)]
+_firm_rest = [PricePoint(start=brussels(DAY[i]),
+                         eur_per_kwh=round(0.212500 + 0.013750 * i, 6),
+                         provisional=False) for i in range(3, 12)]
+_mixed = TariffPlan(PriceRead.series(_cheap_stale + _firm_rest,
+                                     PriceProduct.DAY_AHEAD,
+                                     "generic_dayahead", D0), None, "provider")
+_all_spread = derived(lambda: _mixed.spread_eur_kwh())
+_firm_spread = derived(lambda: round(
+    max(p.eur_per_kwh for p in _firm_rest)
+    - min(p.eur_per_kwh for p in _firm_rest), 6))
+check(f"the fixture is non-degenerate: the whole-series spread "
+      f"{_all_spread:.6f} and the firm-only spread {_firm_spread:.6f} are "
+      f"different numbers, so a verdict can be traced to one of them",
+      not near(_all_spread, _firm_spread, 1e-6))
+_v = derived(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                      min_spread_eur_kwh=0.0,
+                                      uncertainty=frozenset()))
+check("a PART-published series still allows arbitrage - §8.3 forbids acting on "
+      "a provisional price, not trading at all until 16:00",
+      _v.kind == "allowed")
+check(f"...on the FIRM spread {_firm_spread:.6f}, not the one yesterday's "
+      f"carried-forward cheap hour would have invented",
+      near(_v.spread_eur_kwh, _firm_spread, 1e-9))
+check("...and the cheapest and dearest hours it hands an optimiser are both "
+      "PUBLISHED hours - the two points ARE the trade",
+      _v.cheapest.provisional is False and _v.dearest.provisional is False)
+check("...and it reports the threshold it cleared and why, rather than leaving "
+      "OPT-04 to re-derive it from a product enum",
+      near(_v.required_spread_eur_kwh, 0.0) and _v.uncertainty == frozenset())
+
+_all_prov = TariffPlan(PriceRead.series(_cheap_stale, PriceProduct.DAY_AHEAD,
+                                        "generic_dayahead", D0), None,
+                       "fallback")
+_vp = derived(lambda: _all_prov.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=0.0,
+                                          uncertainty=frozenset()))
+check("a WHOLLY provisional series - the §11.4 fallback, or a day before any "
+      "print - is still refused, and the reason counts the firm hours",
+      _vp.kind == "refused" and "0 of 3" in _vp.reason and "§8.3" in _vp.reason)
+check("...and the refusal carries no numbers to trade on",
+      raises(lambda: _vp.spread_eur_kwh, Absence)
+      and raises(lambda: _vp.cheapest, Absence))
+_one_firm = TariffPlan(
+    PriceRead.series(_cheap_stale + _firm_rest[:1], PriceProduct.DAY_AHEAD,
+                     "generic_dayahead", D0), None, "provider")
+check("one firm hour is not enough either: a buy hour and a sell hour must "
+      "BOTH be published before a cycle can be committed",
+      _one_firm.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0,
+                          uncertainty=frozenset()).kind == "refused")
+check("§10.1 still holds above all of it: the peak guard refuses the same "
+      "series that is otherwise allowed",
+      _mixed.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0,
+                       uncertainty=frozenset()).kind == "refused")
+check("the three questions cannot be skipped: all of peak_guard_active, "
+      "min_spread_eur_kwh and uncertainty are required and keyword-only",
+      raises(lambda: _mixed.arbitrage(peak_guard_active=False), TypeError)
+      and raises(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=0.0), TypeError)
+      and raises(lambda: _mixed.arbitrage(False, 0.0, frozenset()), TypeError))
+check("...nor answered with a truthy 'unknown' or a negative threshold",
+      raises(lambda: _mixed.arbitrage(peak_guard_active=None,
+                                      min_spread_eur_kwh=0.0,
+                                      uncertainty=frozenset()), TypeError)
+      and raises(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=-0.1,
+                                          uncertainty=frozenset()), TypeError))
+
+# The cheap-window flag is the other consumer of provisionality, and it is the
+# one a live install's maintenance charge floor already reads.
+_firm_hour = _firm_rest[0].start
+_prov_hour = _cheap_stale[0].start
+check("the cheap-window flag is decided per HOUR: a provisional hour is never "
+      "cheap, whatever its (stale) number says",
+      _mixed.cheap_now(_prov_hour) is False)
+check("...while a firm hour below the firm mean still is, so carry-forward "
+      "filling does not switch the maintenance charge floor off every morning",
+      _mixed.cheap_now(_firm_hour) is True)
+# ⚠️ GRADED DIRECTLY, BECAUSE ITS CONSUMERS CANNOT GRADE IT. The §11.4 refusal
+# and `cheap_now` both guard provenance independently, so `firm_points()`
+# returning the carried hours TOO still leaves both of them answering correctly
+# - a stimulus that cannot distinguish an over-reporting accessor from a
+# correct one. So the tuple itself is compared with the published points, by
+# identity and in order, rather than only the mean it feeds.
+check("firm_points() returns EXACTLY the published points, in order - not the "
+      "carried ones as well, which its two consumers would have absorbed "
+      "without either of them changing its answer",
+      list(_mixed.firm_points()) == _firm_rest
+      and all(a is b for a, b in zip(_mixed.firm_points(), _firm_rest)))
+check("...and the firm mean it compares against is derived from published "
+      "hours only",
+      near(sum(p.eur_per_kwh for p in _mixed.firm_points())
+           / len(_mixed.firm_points()),
+           sum(p.eur_per_kwh for p in _firm_rest) / len(_firm_rest)))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("7. CFG-03 and validate.py rule 7 - what this ticket did NOT widen")
+
+_defaults = derived(lambda: sorted(_price.PRICE_OPTION_DEFAULTS))
+_cfg = derived(lambda: open(os.path.join(HERE, "config.yaml"),
+                            encoding="utf-8").read())
+check(f"FCST-03 added ZERO option keys: the in-code mirror still holds exactly "
+      f"TARIFF-02's and TARIFF-03's {_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"]))
+check("...and every one of them is still in config.yaml, which stays the "
+      "source of truth",
+      isinstance(_cfg, str)
+      and all(f"\n  {k}:" in _cfg for k in _price.PRICE_OPTION_DEFAULTS))
+
+
+def _names(path):
+    try:
+        tree = ast.parse(open(path, encoding="utf-8").read())
+    except (OSError, SyntaxError):                            # pragma: no cover
+        return set()
+    out = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            out |= {a.name for a in node.names}
+        if isinstance(node, ast.Name):
+            out.add(node.id)
+        if isinstance(node, ast.Attribute):
+            out.add(node.attr)
+    return out
+
+
+_FC = os.path.join(HERE, "app", "price_forecast.py")
+_used = derived(lambda: _names(_FC))
+check("app/price_forecast.py reads NO options at all - it takes a PriceRead "
+      "and instants, so there is no fourth place for an option default to live",
+      isinstance(_used, set)
+      and not ({"price_option", "PRICE_OPTION_DEFAULTS", "PluginOptions"}
+               & _used))
+# ⚠️ RULE 7'S TRIPWIRE, RESPECTED RATHER THAN TRIPPED. test_price.py section 12
+# pins the set of modules that consume `load_prices()` to exactly
+# ["static_tariff.py"], and goes red when a second one appears. This module
+# deliberately does NOT fetch: it transforms a read somebody else obtained, so
+# rule 7's message about what a configured provider does or does not drive is
+# unchanged by this ticket and needed no rewording.
+check("...and it does not consume load_prices(), so validate.py rule 7's "
+      "pinned consumer list is still true and its wording still accurate",
+      "load_prices" not in _used)
+
+
+print()
+print("FAILED" if fails else "OK")
+for f in fails:
+    print("  -", f)
+sys.exit(1 if fails else 0)

goodwe_controller/test_static_tariff.py

@@ -0,0 +1,861 @@
+"""Runnable check for static day/night and fully-fixed tariffs.  `python3 test_static_tariff.py`
+
+WHAT THIS FILE IS DEFENDING, in the order the ticket's acceptance criteria name
+it:
+
+  AC1  `static_profile` (§14) drives TIME-WINDOW SHIFTING for a two-period
+       tariff - the right window at the right local instant, on both sides of
+       both 2026 DST transitions, and reaching the one shiftable load the add-on
+       actually has.
+  AC2  Fully-fixed pricing DISABLES ARBITRAGE and leaves self-consumption only.
+  AC3  The Belgian scenario suite carries a static-profile regression case.
+
+THREE RULES THIS FILE HOLDS ITSELF TO, because the reviewer will:
+
+  * EVERY VERDICT IS DERIVED. No `check("the split is right", True)`. Where a
+    check needs an expected number it is computed HERE, by different arithmetic
+    than app/static_tariff.py uses - the window split is re-derived by summing
+    over samples with an independent local-hour test, the profile mean by a
+    second pass, the saving by two routes that must agree.
+
+  * NO STIMULUS IS EVALUATED WHERE THE QUANTITY IT GRADES IS DEGENERATE. A
+    two-period tariff has this trap BUILT IN and it is the main hazard here:
+
+      - THE PERIOD BOUNDARY IS THE DEGENERACY. At 07:00 and at 22:00 the "which
+        window" question and the "is it cheap" question agree under almost any
+        bug, and a probe at 12:00 cannot tell a correct wrap-around from one
+        that treats 22:00-07:00 as 22:00-24:00. So probes sit at 06:59 / 07:00 /
+        07:01 and 21:59 / 22:00 / 22:01, and a Saturday 03:00 probe exists
+        specifically because the mon-fri night window MUST NOT cover it.
+      - MEAN-CHEAP AND MINIMUM-CHEAP AGREE ON A TWO-LEVEL TARIFF. Under two
+        prices "below the mean" and "is the cheapest price" are the same set, so
+        a two-period profile cannot tell `cheap_now` from `price == min`.
+        Section 3 therefore runs a THREE-level profile where those two answers
+        differ, and asserts they differ before grading anything with it.
+      - DAY AND NIGHT MUST HAVE DIFFERENT PRICES AND NEITHER MAY BE ZERO, or the
+        whole shifting question collapses. Asserted as checks in their own
+        right, first, rather than assumed.
+      - THE DST CHECKS RUN ON THE 23-HOUR AND 25-HOUR DAYS, not on a normal day
+        where a 24-slot implementation and a correct one agree exactly.
+      - THE REPLAY DAY MUST CARRY IMPORT IN BOTH WINDOWS. A day whose whole
+        import fell in one window grades no split at all; section 6 asserts that
+        before it reports a saving.
+
+  * A FAILED READ IS NOT AN OBSERVATION. A missing static_profile is not a zero
+    price, and zero is exactly the value that makes everything look free. So
+    `static_plan` with no profile is checked to produce a read with NO
+    `.points`, and `price_at` on it must RAISE rather than answer 0.0.
+"""
+
+import gzip
+import json
+import sys
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from app.price import (
+    Absence, PricePoint, PriceProduct, PriceRead, arbitrage_allowed, brussels,
+    plan_is_provisional,
+)
+from app.static_tariff import (
+    MEAN_WINDOW_DAYS, ProfileInvalid, StaticProfile, TariffPlan,
+    parse_static_profile, resolve_tariff, static_plan, static_status,
+)
+from app.validate import validate_startup_config
+
+HERE = Path(__file__).resolve().parent
+UTC = timezone.utc
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+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
+    the same."""
+    try:
+        fn()
+    except exc:
+        return True
+    except Exception:
+        return False
+    return False
+
+
+def reason(fn):
+    try:
+        fn()
+    except Exception as e:                                    # noqa: BLE001
+        return str(e)
+    return ""
+
+
+class _Raised:
+    def __init__(self, e):
+        self.e = e
+
+    def __eq__(self, other):
+        return False
+
+    def __hash__(self):
+        return id(self)
+
+    def __bool__(self):
+        return False
+
+    def __repr__(self):
+        return f"<raised {type(self.e).__name__}: {self.e}>"
+
+
+def derived(fn):
+    """A value a check grades. An exception becomes `_Raised`, which equals
+    nothing and is falsy - NOT a default. See test_price.py for why."""
+    try:
+        return fn()
+    except Exception as e:                                    # noqa: BLE001
+        return _Raised(e)
+
+
+def near(a, b, tol=1e-9):
+    try:
+        return abs(float(a) - float(b)) <= tol
+    except (TypeError, ValueError):
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# The fixtures. Belgian day/night numbers, and their degeneracies asserted.
+# --------------------------------------------------------------------------- #
+
+DAY_P = 0.3410           # all-in EUR/kWh, day
+NIGHT_P = 0.2570         # all-in EUR/kWh, night
+FIXED_P = 0.3070         # all-in EUR/kWh, single-tariff site
+
+TWO_PERIOD = {"periods": [
+    {"name": "day", "from": "07:00", "to": "22:00", "days": "mon-fri",
+     "eur_per_kwh": DAY_P},
+    {"name": "night", "from": "22:00", "to": "07:00", "days": "mon-fri",
+     "eur_per_kwh": NIGHT_P},
+    {"name": "night", "from": "00:00", "to": "24:00", "days": "sat,sun",
+     "eur_per_kwh": NIGHT_P},
+]}
+
+FULLY_FIXED = {"periods": [
+    {"name": "fixed", "from": "00:00", "to": "24:00", "days": "all",
+     "eur_per_kwh": FIXED_P},
+]}
+
+# ⚠️ THREE LEVELS, AND SECTION 3 EXISTS BECAUSE OF IT. Under two prices "cheaper
+# than the mean" and "is the minimum price" are the same set of hours, so a
+# two-period profile cannot distinguish `cheap_now`'s rule from `price == min`.
+# Here the middle level sits BELOW the mean without being the minimum (the four
+# expensive evening hours pull the mean up past it), so those two rules give
+# DIFFERENT answers at 12:00 - and section 3 proves they differ before grading
+# anything with it.
+THREE_LEVEL = {"periods": [
+    {"name": "peak", "from": "17:00", "to": "21:00", "days": "all",
+     "eur_per_kwh": 0.4800},
+    {"name": "day", "from": "07:00", "to": "17:00", "days": "all",
+     "eur_per_kwh": 0.2900},
+    {"name": "evening", "from": "21:00", "to": "24:00", "days": "all",
+     "eur_per_kwh": 0.2900},
+    {"name": "night", "from": "00:00", "to": "07:00", "days": "all",
+     "eur_per_kwh": 0.1900},
+]}
+
+
+def opts(profile=None, **over):
+    o = {"price_provider": "off",
+         "static_profile": "" if profile is None else json.dumps(profile)}
+    o.update(over)
+    return o
+
+
+# --------------------------------------------------------------------------- #
+print("0. the arithmetic this file grades with must not be degenerate")
+# ⚠️ These ARE the guard against a section that passes for the wrong reason. If
+# any goes red, every shifting assertion below is measuring nothing.
+check("day and night prices differ, so 'used the wrong window' is visible",
+      DAY_P != NIGHT_P)
+check("...and neither is zero, so 'dropped the price entirely' is visible",
+      DAY_P != 0 and NIGHT_P != 0)
+check("...and the fixed price is neither of them, so a fixed-tariff result "
+      "cannot be a day/night result in disguise",
+      FIXED_P not in (DAY_P, NIGHT_P))
+check("...and the day/night spread is not the fixed price, so 'reported the "
+      "spread where the price was wanted' is visible",
+      not near(DAY_P - NIGHT_P, FIXED_P))
+_lv = sorted({p["eur_per_kwh"] for p in THREE_LEVEL["periods"]})
+check(f"the three-level fixture really has three levels {_lv}", len(_lv) == 3)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("1. AC1 - the two-period profile puts the right window on the right hour")
+
+TWO = parse_static_profile(json.dumps(TWO_PERIOD))
+check("a JSON string parses (what config.yaml's flat `str?` option carries)",
+      isinstance(TWO, StaticProfile))
+check("...and so does an already-parsed dict (what /data/options.json would "
+      "carry under a nested schema, and what sim/inject.py hands over)",
+      isinstance(parse_static_profile(TWO_PERIOD), StaticProfile))
+check("...and a bare list of periods, without the wrapper",
+      isinstance(parse_static_profile(TWO_PERIOD["periods"]), StaticProfile))
+
+# ⚠️ THE PRODUCT IS DERIVED FROM THE DATA. Nobody ticks a box saying 'static'.
+check("the product is derived from the number of distinct prices, not declared: "
+      "two levels -> STATIC", TWO.product is PriceProduct.STATIC)
+check("...and one level -> FIXED, from the same code, with no flag anywhere",
+      parse_static_profile(FULLY_FIXED).product is PriceProduct.FIXED)
+# ...and it is really the PRICES, not the row count: three rows, one price.
+_three_rows_one_price = parse_static_profile({"periods": [
+    dict(p, eur_per_kwh=FIXED_P) for p in TWO_PERIOD["periods"]]})
+check("...and THREE rows carrying ONE price is still FIXED, so the derivation "
+      "is on the prices and not on len(periods)",
+      _three_rows_one_price.product is PriceProduct.FIXED
+      and len(_three_rows_one_price.periods) == 3)
+
+# ⚠️ PROBES AT THE BOUNDARY, NOT IN THE MIDDLE OF A WINDOW. 2026-01-15 is a
+# Thursday and Belgium is on CET (+01:00) then, so local == UTC + 1 h.
+THU = datetime(2026, 1, 15, tzinfo=UTC)
+
+
+def at_local(day, hh, mm=0):
+    """A UTC instant whose BRUSSELS wall clock reads hh:mm on `day`.
+
+    Built by search rather than by adding an offset, so this helper cannot
+    inherit the same offset bug it is meant to detect.
+    """
+    for minutes in range(-180, 24 * 60 + 180):
+        u = day + timedelta(minutes=minutes)
+        loc = brussels(u)
+        if loc.hour == hh and loc.minute == mm and loc.date() == \
+                brussels(day + timedelta(hours=12)).date():
+            return u
+    raise AssertionError(f"no instant reads {hh:02d}:{mm:02d} local on {day}")
+
+
+_probes = [(6, 59, "night"), (7, 0, "day"), (7, 1, "day"),
+           (21, 59, "day"), (22, 0, "night"), (22, 1, "night"),
+           (12, 0, "day"), (3, 0, "night")]
+_got = [(hh, mm, TWO.at(at_local(THU, hh, mm)).name) for hh, mm, _ in _probes]
+check(f"the half-open boundaries land exactly - 06:59 night, 07:00 day, "
+      f"21:59 day, 22:00 night {_got}",
+      all(name == want for (hh, mm, want), (_, __, name)
+          in zip(_probes, _got)))
+check("...and the 22:00-07:00 window really wraps midnight: Thursday 03:00 is "
+      "night, which a [22:00,24:00) reading would call uncovered",
+      TWO.at(at_local(THU, 3)).name == "night")
+
+# ⚠️ THE DAY-TYPE TRAP. A `mon-fri` night window must NOT bleed into Saturday
+# morning - a period applies on the day the CLOCK reads. The weekend row is what
+# covers Saturday 03:00, and it is a DIFFERENT Period object.
+SAT = datetime(2026, 1, 17, tzinfo=UTC)          # a Saturday
+_sat3 = TWO.at(at_local(SAT, 3))
+_thu3 = TWO.at(at_local(THU, 3))
+check("Saturday 03:00 is served by the WEEKEND row, not by Friday's night "
+      "window bleeding over - same name and price, different period",
+      _sat3.name == _thu3.name and _sat3 is not _thu3
+      and 5 in _sat3.days and 5 not in _thu3.days)
+check("...and Saturday 12:00 is night-priced, because a Belgian weekend tariff "
+      "runs all day - a weekday-shaped lookup would call it day",
+      near(TWO.price_at(at_local(SAT, 12)), NIGHT_P))
+check("...while Thursday 12:00 is day-priced, so the two are really different "
+      "answers and not one answer twice",
+      near(TWO.price_at(at_local(THU, 12)), DAY_P))
+
+# next_change: the shifting primitive - "how long until the cheap window".
+_nc = TWO.next_change(at_local(THU, 12))
+check(f"next_change from Thursday 12:00 is the 22:00 flip "
+      f"{None if _nc is None else brussels(_nc).isoformat()}",
+      _nc is not None and brussels(_nc).hour == 22 and brussels(_nc).minute == 0)
+_nc2 = TWO.next_change(at_local(SAT, 12))
+check("...and from Saturday noon it is Monday 07:00, because the whole weekend "
+      "is one window - a scan that stopped at midnight would say 24 h",
+      _nc2 is not None and brussels(_nc2).hour == 7
+      and brussels(_nc2).weekday() == 0)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("2. AC2 - a fully-fixed tariff disables arbitrage, by arithmetic")
+
+FIX = parse_static_profile(FULLY_FIXED)
+# ⚠️ The window OPENS A DAY EARLY. `at_local(THU, 0)` is 23:00 UTC on the 14th -
+# Belgium is an hour ahead - so a plan starting at THU would not cover midnight
+# local, and `price_at` would correctly raise for it. That raise is the right
+# behaviour (an hour outside the series is an hour with no price) but it is not
+# what these sections are grading.
+SPAN_A, SPAN_B = THU - timedelta(days=1), THU + timedelta(days=2)
+p_fixed = static_plan(opts(FULLY_FIXED), SPAN_A, SPAN_B)
+p_two = static_plan(opts(TWO_PERIOD), SPAN_A, SPAN_B)
+
+check("the fixed plan really produced a series (so the refusal below is about "
+      "the tariff, not about a failed read)",
+      p_fixed.has_prices and len(p_fixed.read.points) == 72)
+_spread_fixed = derived(p_fixed.spread_eur_kwh)
+_spread_two = derived(p_two.spread_eur_kwh)
+check(f"...and its spread is exactly zero {_spread_fixed}",
+      near(_spread_fixed, 0.0))
+check(f"...while the two-period spread is the day/night difference "
+      f"{_spread_two}, re-derived here as {DAY_P - NIGHT_P:.4f}",
+      near(_spread_two, DAY_P - NIGHT_P, 1e-9))
+
+_v_fixed = p_fixed.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset())
+_v_two = p_two.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset())
+check("a fully-fixed tariff REFUSES arbitrage", _v_fixed.kind == "refused")
+check("...for the true reason - the series is flat, so there is nothing to buy "
+      "low and sell high, not because a FIXED enum was matched on",
+      "flat" in _v_fixed.reason and "self-consumption only" in _v_fixed.reason)
+check("...and a two-period tariff, on the same code path, ALLOWS it - so the "
+      "refusal is discriminating rather than universal",
+      _v_two.kind == "allowed")
+
+# ⚠️ NOT KEYED ON THE PRODUCT ENUM. A DAY-AHEAD series that happens to print one
+# price all day must be refused for the same reason, or the rule is a label
+# check wearing arithmetic's clothes.
+_flat_dayahead = TariffPlan(
+    PriceRead.series(
+        [PricePoint(start=brussels(THU + timedelta(hours=i)),
+                    eur_per_kwh=0.2222, provisional=False) for i in range(24)],
+        PriceProduct.DAY_AHEAD, "generic_dayahead", THU),
+    None, "provider")
+check("a DAY_AHEAD series that happens to be flat is refused too, so the rule "
+      "is arithmetic and not a product label",
+      _flat_dayahead.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused")
+
+# The numbers an optimiser needs exist ONLY on the permitting variant.
+check("the allowed verdict carries the spread, the cheapest hour and the "
+      "dearest hour - the whole input set for a trade",
+      near(_v_two.spread_eur_kwh, DAY_P - NIGHT_P)
+      and near(_v_two.cheapest.eur_per_kwh, NIGHT_P)
+      and near(_v_two.dearest.eur_per_kwh, DAY_P))
+check("...and a REFUSED verdict carries none of them: .spread_eur_kwh raises "
+      "Absence rather than answering 0.0, which is the number that would make "
+      "every hour look equally good",
+      raises(lambda: _v_fixed.spread_eur_kwh, Absence)
+      and raises(lambda: _v_fixed.cheapest, Absence))
+check("...and it is not iterable and has no .get(), the other two routes from "
+      "a refusal to an empty, harmless-looking loop",
+      raises(lambda: list(_v_fixed), Absence)
+      and raises(lambda: _v_fixed.get("spread_eur_kwh", 0.0), Absence))
+check("...and match() demands BOTH arms, so the refusal cannot be fallen "
+      "through", raises(lambda: _v_fixed.match(allowed=lambda v: 1), TypeError))
+check("...and there is no falsy variant, so `if verdict:` cannot look like a "
+      "guard while being none", bool(_v_fixed) is True and bool(_v_two) is True)
+
+# §10.1 priority 2 over priority 3, expressed so OPT-04 cannot skip it.
+check("peak shaving outranks arbitrage: the SAME allowed plan is refused when "
+      "the peak guard is holding",
+      p_two.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused")
+check("...and the reason names the ordering rather than the tariff",
+      "priority 2" in p_two.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0, uncertainty=frozenset()).reason)
+check("...and the question cannot be skipped: peak_guard_active is required "
+      "and keyword-only, so a spread is not obtainable without answering it",
+      raises(lambda: p_two.arbitrage(), TypeError)
+      and raises(lambda: p_two.arbitrage(False), TypeError))
+check("...nor answered with a truthy 'unknown'",
+      raises(lambda: p_two.arbitrage(peak_guard_active=None), TypeError)
+      and raises(lambda: p_two.arbitrage(peak_guard_active="no"), TypeError))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("3. the cheap-window rule, on a tariff where it is not degenerate")
+# ⚠️ WHY THREE LEVELS. Under two prices, "below the mean" and "equal to the
+# minimum" select the SAME hours, so a two-period profile cannot tell
+# cheap_now()'s actual rule from `price == min(prices)`. This fixture's `day`
+# level sits between the two, and the check below PROVES the two rules disagree
+# before anything is graded with it.
+
+THREE = parse_static_profile(THREE_LEVEL)
+p3 = static_plan(opts(THREE_LEVEL), SPAN_A,
+                 SPAN_A + timedelta(days=MEAN_WINDOW_DAYS))
+_mean3 = p3.mean_eur_kwh()
+_min3 = min(p.eur_per_kwh for p in p3.read.points)
+_day3 = 0.2900
+check(f"the three-level fixture is non-degenerate: the minimum {_min3:.4f} is "
+      f"strictly below the middle level {_day3:.4f}, which is strictly below "
+      f"the mean {_mean3:.4f} - so 'below the mean' and 'is the minimum' select "
+      f"DIFFERENT sets of hours and this fixture can tell them apart",
+      _min3 < _day3 < _mean3)
+check("...so cheap_now() calls the 07:00-17:00 MIDDLE level cheap - it is under "
+      "the mean without being the cheapest price of the day, which a "
+      "`price == min(prices)` rule would get wrong and a `price < mean` rule "
+      "gets right", p3.cheap_now(at_local(THU, 12)) is True)
+check("...and the middle level really is not the minimum, so that check graded "
+      "the difference rather than restating it",
+      not near(p3.price_at(at_local(THU, 12)), _min3))
+check("...and calls the 00:00-07:00 minimum cheap",
+      p3.cheap_now(at_local(THU, 3)) is True)
+check("...and the 17:00-21:00 peak not cheap",
+      p3.cheap_now(at_local(THU, 18)) is False)
+
+# ⚠️ STRICTLY BELOW, AND THAT IS AC2 IN THE SHIFTING HALF. On a flat series
+# `<=` would make EVERY hour a cheap window and a fixed-tariff site would top
+# the battery up from the grid at any hour - the opposite of self-consumption
+# only.
+_fixed_hours = [at_local(THU, h) for h in range(0, 24, 3)]
+check(f"a fully-fixed tariff has NO cheap window at any hour of the day "
+      f"{[h for h in range(0, 24, 3) if p_fixed.cheap_now(at_local(THU, h))]} - "
+      f"which is what `<` buys and `<=` would destroy",
+      not any(p_fixed.cheap_now(t) for t in _fixed_hours))
+check("...and the price really is defined at every one of those hours, so the "
+      "'no cheap window' answer is a priced no and not a missing read",
+      all(near(p_fixed.price_at(t), FIXED_P) for t in _fixed_hours))
+# ...and on the two-period tariff the cheap hours are exactly the night ones.
+_cheap_h = {h for h in range(24) if p_two.cheap_now(at_local(THU, h))}
+_night_h = {h for h in range(24) if TWO.at(at_local(THU, h)).name == "night"}
+check(f"on the day/night tariff the cheap hours ARE the night hours, derived "
+      f"two ways {sorted(_cheap_h)}",
+      _cheap_h == _night_h and 0 < len(_cheap_h) < 24)
+
+# ⚠️ THE MEAN IS OVER SEVEN DAYS, NOT OVER THE HOUR YOU ASKED AT. A 48 h mean on
+# a Friday afternoon is ~2/3 weekend, so the same Tuesday 09:00 would come out
+# cheap or dear depending on when the question was put.
+FRI = datetime(2026, 1, 16, tzinfo=UTC)
+_from_thu = static_status(opts(TWO_PERIOD), at_local(THU, 12))
+_from_fri = static_status(opts(TWO_PERIOD), at_local(FRI, 15))
+_mean_thu = static_plan(opts(TWO_PERIOD), at_local(THU, 12),
+                        at_local(THU, 12) + timedelta(days=MEAN_WINDOW_DAYS)
+                        ).mean_eur_kwh()
+_mean_fri = static_plan(opts(TWO_PERIOD), at_local(FRI, 15),
+                        at_local(FRI, 15) + timedelta(days=MEAN_WINDOW_DAYS)
+                        ).mean_eur_kwh()
+check(f"the 7-day mean is stable across the day it is asked on "
+      f"({_mean_thu:.4f} vs {_mean_fri:.4f}), so a window's cheapness is a "
+      f"property of the tariff and not of the clock",
+      near(_mean_thu, _mean_fri, 5e-4))
+_mean48_thu = static_plan(opts(TWO_PERIOD), at_local(THU, 12),
+                          at_local(THU, 12) + timedelta(days=2)).mean_eur_kwh()
+_mean48_fri = static_plan(opts(TWO_PERIOD), at_local(FRI, 15),
+                          at_local(FRI, 15) + timedelta(days=2)).mean_eur_kwh()
+check(f"...and the 48 h mean this replaces is NOT stable ({_mean48_thu:.4f} vs "
+      f"{_mean48_fri:.4f}), so the seven days are buying something real",
+      not near(_mean48_thu, _mean48_fri, 5e-4))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("4. DST - 23 and 25 hour days, where a 24-slot implementation is wrong")
+# ⚠️ 2026: CEST from 01:00 UTC Sunday 29 March, CET from 01:00 UTC Sunday
+# 25 October (price.py's brussels_offset, checked in PR #16 against zoneinfo
+# over 149,040 instants). Both are SUNDAYS, so the weekend row prices them -
+# which is itself worth knowing, because the wrap-around weekday row is not what
+# is under test here.
+SPRING = datetime(2026, 3, 29, tzinfo=UTC)
+AUTUMN = datetime(2026, 10, 25, tzinfo=UTC)
+
+
+def local_day_points(profile, day_utc):
+    """Hourly points whose BRUSSELS date is that of `day_utc` + 12 h."""
+    target = brussels(day_utc + timedelta(hours=12)).date()
+    pts = profile.series(day_utc - timedelta(hours=6),
+                         day_utc + timedelta(hours=30), provisional=False)
+    return [p for p in pts if p.start.date() == target]
+
+
+_spring = derived(lambda: local_day_points(TWO, SPRING))
+_autumn = derived(lambda: local_day_points(TWO, AUTUMN))
+check(f"the spring-forward local day emits 23 points, not 24 "
+      f"({len(_spring) if not isinstance(_spring, _Raised) else _spring})",
+      not isinstance(_spring, _Raised) and len(_spring) == 23)
+check(f"the autumn-back local day emits 25 points, not 24 "
+      f"({len(_autumn) if not isinstance(_autumn, _Raised) else _autumn})",
+      not isinstance(_autumn, _Raised) and len(_autumn) == 25)
+check("...and the two 02:00 points in October are DIFFERENT instants at "
+      "DIFFERENT offsets, which a naive local-hour key would collide",
+      len({p.start.utcoffset() for p in _autumn if p.start.hour == 2}) == 2)
+check("...and every emitted start is strictly increasing in UTC, which is what "
+      "price.py's boundary check demands of a fetched feed too",
+      all(a.start.astimezone(UTC) < b.start.astimezone(UTC)
+          for a, b in zip(_autumn, _autumn[1:])))
+# A weekday profile across a transition, so the wrap-around path sees one too.
+_wrapdays = local_day_points(TWO, datetime(2026, 3, 30, tzinfo=UTC))
+check("a normal Monday still emits 24, so the 23/25 above are the transitions "
+      "and not a systematic miscount", len(_wrapdays) == 24)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("5. a failed read is not an observation, and a gap is not a price")
+
+_none = static_plan(opts(None), THU, THU + timedelta(days=1))
+check("no static_profile produces a NO-DATA read, not an empty series and not "
+      "a zero one", not _none.has_prices)
+check("...and reading a price off it RAISES rather than answering 0.0 - the "
+      "value that would make every hour look free",
+      raises(lambda: _none.price_at(THU), Absence)
+      and raises(_none.mean_eur_kwh, Absence)
+      and raises(_none.spread_eur_kwh, Absence))
+check("...and its underlying read has no .points at all, so `min(read.points)` "
+      "cannot run against it",
+      raises(lambda: _none.read.points, Absence))
+check("...and arbitrage is refused, per §11.4",
+      _none.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused"
+      and arbitrage_allowed(_none.read) is False)
+check("...and static_status() says so in words rather than reporting a price",
+      static_status(opts(None), THU) == (False, "no static profile"))
+
+# ⚠️ THE TILING REFUSAL. An uncovered hour has no price and the only ways to
+# serve it are to invent one or to fail when the clock reaches it.
+_gap = {"periods": [
+    {"name": "day", "from": "07:00", "to": "22:00", "days": "all",
+     "eur_per_kwh": DAY_P},
+    {"name": "night", "from": "23:00", "to": "07:00", "days": "all",
+     "eur_per_kwh": NIGHT_P}]}
+check("a profile with a 22:00-23:00 gap is REFUSED, not defaulted",
+      raises(lambda: parse_static_profile(_gap), ProfileInvalid))
+check("...and names the uncovered range so the operator can fix it",
+      "22:00-23:00" in reason(lambda: parse_static_profile(_gap)))
+_overlap = {"periods": [
+    {"name": "day", "from": "07:00", "to": "22:00", "days": "all",
+     "eur_per_kwh": DAY_P},
+    {"name": "night", "from": "21:00", "to": "07:00", "days": "all",
+     "eur_per_kwh": NIGHT_P}]}
+check("...and an overlap is refused too - two prices for one hour means one "
+      "wins on list order",
+      raises(lambda: parse_static_profile(_overlap), ProfileInvalid)
+      and "2 prices" in reason(lambda: parse_static_profile(_overlap)))
+# THE CLASSIC MISTAKE the docstring warns about: no weekend row.
+_noweekend = {"periods": [
+    {"name": "day", "from": "07:00", "to": "22:00", "days": "mon-fri",
+     "eur_per_kwh": DAY_P},
+    {"name": "night", "from": "22:00", "to": "07:00", "days": "mon-fri",
+     "eur_per_kwh": NIGHT_P}]}
+check("a weekday-only profile is refused because Saturday and Sunday have no "
+      "price - the mistake a wrap-around window invites",
+      raises(lambda: parse_static_profile(_noweekend), ProfileInvalid)
+      and "sat" in reason(lambda: parse_static_profile(_noweekend)))
+# ...and the shipped shape is accepted, so the rule is not simply "refuse all".
+check("...while the three-row Belgian shape IS accepted, so the tiling rule "
+      "discriminates rather than refusing everything",
+      isinstance(parse_static_profile(TWO_PERIOD), StaticProfile))
+
+_bad = [
+    ("not JSON at all", "day 07:00-22:00 0.34"),
+    ("a price in cents", {"periods": [dict(FULLY_FIXED["periods"][0],
+                                           eur_per_kwh=30.7)]}),
+    ("a non-numeric price", {"periods": [dict(FULLY_FIXED["periods"][0],
+                                              eur_per_kwh="cheap")]}),
+    ("a missing days selector", {"periods": [
+        {"name": "x", "from": "00:00", "to": "24:00", "eur_per_kwh": 0.3}]}),
+    ("an unknown day name", {"periods": [dict(FULLY_FIXED["periods"][0],
+                                              days="mon-frd")]}),
+    ("a decimal hour", {"periods": [dict(FULLY_FIXED["periods"][0],
+                                         **{"from": "7.5"})]}),
+    ("an unsupported timezone", dict(FULLY_FIXED, timezone="Europe/Madrid")),
+    ("an empty periods list", {"periods": []}),
+]
+for label, value in _bad:
+    payload = value if isinstance(value, str) else json.dumps(value)
+    check(f"refused: {label}",
+          raises(lambda p=payload: parse_static_profile(p), ProfileInvalid))
+check("...and every one of those refusals says something an operator can act "
+      "on, rather than just failing",
+      all(len(reason(lambda p=(v if isinstance(v, str) else json.dumps(v)):
+                     parse_static_profile(p))) > 40 for _, v in _bad))
+for label, value in (("empty", ""), ("null", "null"), ("absent", None),
+                     ("whitespace", "   ")):
+    check(f"...while {label!r} means 'no profile' rather than an error",
+          parse_static_profile(value) is None)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("6. AC3 - the static-profile regression case, on the Belgian data that exists")
+# ⚠️ WHAT THE "BELGIAN SCENARIO SUITE" ACTUALLY IS IN THIS REPO. specs §17 names
+# six scenarios; none of them is a static-profile case, which is why AC3 asks
+# for a seventh. What exists as DATA is two days of this house's real P1 net
+# power, captured from the live meter and committed as
+# `scenarios/p1-net-2026-08-{20,23}.jsonl.gz` - the same fixtures test_tariff.py
+# part 9 replays for the capacity tariff. Nothing longer was ever captured.
+#
+# So this case is measured against REAL BELGIAN HOUSEHOLD LOAD, and the two days
+# happen to be one weekday and one weekend day, which is exactly the pair a
+# day/night tariff needs to be graded on. It is NOT a 30-day replay and this
+# section does not claim to be one; the numbers it prints are the numbers those
+# two days actually produce.
+
+REPLAY = sorted((HERE / "scenarios").glob("p1-net-*.jsonl.gz"))
+print(f"    replay fixtures found: {len(REPLAY)} "
+      f"({', '.join(p.name for p in REPLAY) or 'none'})")
+check("the committed replay fixtures are present - a regression fixture CI "
+      "cannot see is not a regression fixture", len(REPLAY) >= 2)
+
+MAX_GAP_S = 60.0        # a longer hole in the capture is not counted as energy
+
+
+def replay_import(path):
+    """(kWh imported per local tariff window, total kWh, span hours, weekday).
+
+    ⚠️ THE WINDOW IS DECIDED HERE BY AN INDEPENDENT ROUTE - the Brussels-local
+    hour of the sample, tested against the fixture's own 07:00/22:00 boundaries
+    - rather than by asking the module under test. The two must agree; that
+    agreement is the check.
+    """
+    per_window = {}
+    total = 0.0
+    first = last = None
+    prev = None
+    days = set()
+    with gzip.open(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            row = json.loads(line)
+            t = datetime.fromisoformat(row["t"])
+            w = float(row["w"])
+            if first is None:
+                first = t
+            last = t
+            if prev is not None:
+                dt = (t - prev[0]).total_seconds()
+                if 0 < dt <= MAX_GAP_S and prev[1] > 0:
+                    kwh = prev[1] * dt / 3_600_000.0
+                    loc = brussels(prev[0])
+                    days.add(loc.weekday())
+                    window = ("day" if loc.weekday() < 5
+                              and 7 <= loc.hour < 22 else "night")
+                    per_window[window] = per_window.get(window, 0.0) + kwh
+                    total += kwh
+            prev = (t, w)
+    span = (last - first).total_seconds() / 3600.0 if first else 0.0
+    return per_window, total, span, days
+
+
+def cost_under(path, profile):
+    """EUR the imported energy cost, priced sample by sample by the MODULE."""
+    total = 0.0
+    prev = None
+    with gzip.open(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            row = json.loads(line)
+            t = datetime.fromisoformat(row["t"])
+            w = float(row["w"])
+            if prev is not None:
+                dt = (t - prev[0]).total_seconds()
+                if 0 < dt <= MAX_GAP_S and prev[1] > 0:
+                    total += (prev[1] * dt / 3_600_000.0) * profile.price_at(prev[0])
+            prev = (t, w)
+    return total
+
+
+replay_days = 0.0
+graded = 0
+for path in REPLAY:
+    windows, total_kwh, span_h, weekdays = replay_import(path)
+    replay_days += span_h / 24.0
+    day_kwh = windows.get("day", 0.0)
+    night_kwh = windows.get("night", 0.0)
+    kind = "weekday" if weekdays and min(weekdays) < 5 else "weekend"
+    print(f"    {path.name}: {span_h:.1f} h, {kind} "
+          f"(weekday indices {sorted(weekdays)}), {total_kwh:.3f} kWh imported "
+          f"= {day_kwh:.3f} day + {night_kwh:.3f} night")
+
+    check(f"{path.name}: the two routes to the total agree",
+          near(day_kwh + night_kwh, total_kwh, 1e-9))
+
+    # The module's own pricing must reproduce the independently-split volumes.
+    c_two = cost_under(path, TWO)
+    c_expect = day_kwh * DAY_P + night_kwh * NIGHT_P
+    check(f"{path.name}: the module prices the real day at "
+          f"EUR {c_two:.4f}, which equals the independently-split "
+          f"{day_kwh:.3f} kWh x {DAY_P} + {night_kwh:.3f} kWh x {NIGHT_P} = "
+          f"EUR {c_expect:.4f}", near(c_two, c_expect, 1e-9))
+
+    c_fix = cost_under(path, FIX)
+    check(f"{path.name}: under a FULLY FIXED tariff the same energy costs "
+          f"EUR {c_fix:.4f} = {total_kwh:.3f} kWh x {FIXED_P}, one price for "
+          f"every hour", near(c_fix, total_kwh * FIXED_P, 1e-9))
+
+    # ⚠️ THE SHIFTING FIGURE, AND THE DEGENERACY GUARD IN FRONT OF IT. A day
+    # whose entire import landed in one window grades nothing: the saving would
+    # be 0 under a correct implementation AND under one that ignored the clock.
+    if day_kwh > 0 and night_kwh > 0:
+        graded += 1
+        saving = c_two - total_kwh * NIGHT_P
+        check(f"{path.name}: this day DOES import in both windows "
+              f"({day_kwh:.3f} / {night_kwh:.3f} kWh), so the split grades "
+              f"something", True)
+        check(f"{path.name}: shifting every day-window kWh into the night "
+              f"window saves EUR {saving:.4f}, which is exactly "
+              f"{day_kwh:.3f} kWh x the {DAY_P - NIGHT_P:.4f} spread - two "
+              f"routes to one number",
+              near(saving, day_kwh * (DAY_P - NIGHT_P), 1e-9) and saving > 0)
+        # AC2 on the same real data: under a fixed tariff there is nothing to
+        # shift, and that is arithmetic rather than a special case.
+        check(f"{path.name}: under the FIXED tariff the identical shift saves "
+              f"exactly nothing, so self-consumption-only is the right "
+              f"behaviour for that product",
+              near(c_fix - total_kwh * FIXED_P, 0.0, 1e-12))
+    else:
+        print(f"    {path.name}: import fell in ONE window only "
+              f"({day_kwh:.3f} day / {night_kwh:.3f} night) - this day is a "
+              f"day-typing witness, not a shifting one, and no saving is "
+              f"claimed from it")
+
+print()
+print(f"    AC3 MEASURED: {replay_days:.1f} DAYS of real Belgian household "
+      f"P1 data, {graded} of {len(REPLAY)} days carrying import in BOTH tariff "
+      f"windows and therefore grading the split.")
+print(f"    AC3 ASKS FOR A REGRESSION CASE IN THE BELGIAN SUITE, AND THIS IS "
+      f"ONE - but the suite holds two captured days, not a season, so nothing "
+      f"here is a claim about annual savings. §17's six named scenarios do not "
+      f"include a static-profile case; this is the seventh, and TEST-01 should "
+      f"say so.")
+check("the replay produced a measurable split over a stated sample size, "
+      "rather than a criterion quietly redefined to fit the data",
+      graded >= 1 and replay_days < 30)
+check("...and BOTH day types are present in the fixtures, which is what makes "
+      "the weekend row testable on real data at all",
+      len({("weekday" if min(replay_import(p)[3]) < 5 else "weekend")
+           for p in REPLAY}) == 2)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("7. §11.4 - the profile is the fallback, and the fallback is provisional")
+
+
+async def _dead(url, timeout_s):
+    raise OSError("the supplier's feed is down")
+
+
+def run(coro):
+    import asyncio
+    return asyncio.run(coro)
+
+
+_cfg = opts(TWO_PERIOD, price_provider="generic_dayahead",
+            price_feed_url="https://api.energy-charts.info/price?bzn=BE",
+            price_timeout_s=1, price_markup_eur_kwh=0.03,
+            price_taxes_eur_kwh=0.06)
+_fb = run(resolve_tariff(_cfg, THU, THU + timedelta(days=1), transport=_dead))
+check("a dead feed falls back to the static profile rather than to nothing",
+      _fb.origin == "fallback" and _fb.has_prices)
+check("...with the SAME prices the configured-product path produces, because "
+      "it is one generator and not a second implementation",
+      [p.eur_per_kwh for p in _fb.read.points]
+      == [p.eur_per_kwh for p in static_plan(
+          opts(TWO_PERIOD), THU, THU + timedelta(days=1)).read.points])
+check("...marked PROVISIONAL, which is the one flag that differs",
+      _fb.provisional and plan_is_provisional(_fb.read))
+check("...and arbitrage is refused on it, per §11.4, even though a full series "
+      "exists and has a real spread",
+      _fb.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused"
+      and near(_fb.spread_eur_kwh(), DAY_P - NIGHT_P))
+check("...while the SAME profile as the configured product allows it - so the "
+      "refusal is about provisionality and not about the profile",
+      static_plan(opts(TWO_PERIOD), THU, THU + timedelta(days=1)
+                  ).arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "allowed")
+check("...and the provisional plan has no cheap window either: §8.3 forbids an "
+      "irreversible action on a provisional price, and a grid top-up is one",
+      not any(_fb.cheap_now(at_local(THU, h)) for h in range(24)))
+_fb_none = run(resolve_tariff(opts(None, price_provider="generic_dayahead",
+                                   price_timeout_s=1),
+                              THU, THU + timedelta(days=1), transport=_dead))
+check("a dead feed with NO static_profile has nothing to fall back to, and "
+      "says that rather than inventing a tariff",
+      _fb_none.origin == "none" and not _fb_none.has_prices)
+
+# A live feed still wins over the profile.
+_body = json.dumps({"data": [
+    {"start": (THU + timedelta(hours=i)).isoformat(), "price_eur_mwh": 40 + i}
+    for i in range(24)]}).encode()
+
+
+async def _live(url, timeout_s):
+    return _body
+
+
+_live_plan = run(resolve_tariff(_cfg, THU, THU + timedelta(days=1),
+                                transport=_live))
+check("a live feed is used in preference to the static profile",
+      _live_plan.origin == "provider"
+      and _live_plan.product is PriceProduct.DAY_AHEAD)
+check("...and arbitrage is allowed on it, with the spread derived from the "
+      "feed rather than from the profile",
+      _live_plan.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "allowed"
+      and near(_live_plan.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).spread_eur_kwh,
+               0.023, 1e-9))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("8. the startup gate, and CFG-03")
+
+
+def vbase(**over):
+    o = {"setpoint_entity": "number.goodwe_setpoint", "max_w": 2000,
+         "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+         "meter_source": "off",
+         "maintenance_charge_w": 2000, "maintenance_discharge_w": 2000}
+    o.update(over)
+    return o
+
+
+def why(problems, needle):
+    return any(needle in p for p in problems)
+
+
+check("a good static_profile starts",
+      validate_startup_config(
+          vbase(static_profile=json.dumps(TWO_PERIOD)), -5000, 5000) == [])
+check("a gapped one is REFUSED at startup, not at 22:00 on the day it bites",
+      why(validate_startup_config(vbase(static_profile=json.dumps(_gap)),
+                                  -5000, 5000),
+          "static_profile cannot be used"))
+check("...and the refusal names the uncovered range",
+      why(validate_startup_config(vbase(static_profile=json.dumps(_gap)),
+                                  -5000, 5000), "22:00-23:00"))
+check("static_profile alongside the Home Assistant price entities is refused - "
+      "main.py reads one of them and the loser is silent",
+      why(validate_startup_config(
+          vbase(static_profile=json.dumps(TWO_PERIOD),
+                price_now_entity="sensor.now", price_avg_entity="sensor.avg"),
+          -5000, 5000), "HOME ASSISTANT"))
+check("...and the Home Assistant pair ALONE still starts, so nothing is taken "
+      "away from a live install",
+      validate_startup_config(vbase(price_now_entity="sensor.now",
+                                    price_avg_entity="sensor.avg"),
+                              -5000, 5000) == [])
+check("...and an empty static_profile is never refused: §9.2 puts a large share "
+      "of the installed base on a fixed tariff, and §11.4 makes no-price-data a "
+      "supported state",
+      validate_startup_config(vbase(static_profile=""), -5000, 5000) == []
+      and validate_startup_config(vbase(), -5000, 5000) == [])
+check("...and a fully-fixed profile starts, since a one-price site is a "
+      "supported product and not a misconfiguration",
+      validate_startup_config(vbase(static_profile=json.dumps(FULLY_FIXED)),
+                              -5000, 5000) == [])
+
+# ⚠️ CFG-03 IS NOT WIDENED BY THIS TICKET. `static_profile` was added to
+# app/price.py's PRICE_OPTION_DEFAULTS - the ONE in-code mirror TARIFF-02
+# created and pinned to config.yaml - rather than to a second defaults dict in
+# the new module. That mirror is enforced by test_price.py section 1, which
+# reads config.yaml; this check is the other half of the claim: the new module
+# must carry NO defaults dict of its own.
+_SRC = (HERE / "app" / "static_tariff.py").read_text(encoding="utf-8")
+check("the new module holds no option-defaults dict of its own, so this ticket "
+      "added ZERO new places an option default lives (CFG-03)",
+      "OPTION_DEFAULTS" not in _SRC.replace("PRICE_OPTION_DEFAULTS", ""))
+check("...and it reads the option through price.price_option(), the framework's "
+      "single read path, rather than through opts.get(key, <a number>)",
+      "price_option(opts" in _SRC and 'opts.get("static_profile"' not in _SRC)
+_MAIN = (HERE / "app" / "main.py").read_text(encoding="utf-8")
+check("...and main.py grew no `o.get(\"static_profile\", <a default>)` fallback "
+      "either - it calls static_status(o, now), and the option is read once, "
+      "inside the framework",
+      'get("static_profile"' not in _MAIN and "static_status(" in _MAIN)
+
+
+# --------------------------------------------------------------------------- #
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + "; ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_tariff.py

@@ -0,0 +1,910 @@
+"""Runnable check for TARIFF-01, the capacity-tariff measurement.
+
+    python3 test_tariff.py
+
+Ten parts. What each is for, and - where it matters - what it is deliberately
+NOT allowed to be tested at:
+
+  1. THE BLOCK ARITHMETIC, against a worked example written out segment by
+     segment. The fixture is chosen to be non-degenerate on three axes at once:
+     irregular sample spacing, a sample that STRADDLES the :15 boundary, and a
+     gap longer than `max_hold_s` so the block's coverage is short of 900 s.
+  2. THE 900 s DEGENERACY, named and then avoided. `acc/elapsed`, `acc/900` and
+     the end-of-quarter projection are THREE DIFFERENT FORMULAS that all agree
+     at exactly full coverage of a complete block. A check run only there proves
+     nothing about any of them, so part 2 first shows them agreeing at that
+     point (so the trap is documented rather than asserted around), then shows
+     part 1's fixture separating all three - and every later part uses fixtures
+     that are away from it.
+  3. RESTART MID-BLOCK, through the real `QuarterAverager.snapshot()`/`restore()`
+     and a real SQLite file: a restarted run must land on the same closed block
+     as an uninterrupted one, and a run that DOES NOT restore must land lower.
+     Without that second half, "restore works" is satisfied by a fixture where
+     restoring changes nothing.
+  4. MONTH ROLLOVER, in LOCAL time, including a restart that straddles it.
+  5. AN UNREADABLE STORE IS NOT A ZERO PEAK - the acceptance argument. Three
+     states, three different answers, and no accessor that turns "the database
+     did not answer" into a number.
+  6. THE TIMEZONE FALLBACK, graded against `zoneinfo` day by day.
+  7. THE PER-PHASE REDUCTION on an UNBALANCED load. §17's three-phase case. On a
+     balanced load net/sum/max all coincide, which is why a balanced fixture is
+     worth nothing here.
+  8. `monthly_peak` vs a recompute from `quarter_blocks` - the derived record
+     proven equal to the tier it derives from, and proven never to be lowered.
+  9. AC 3, ON THE REPLAY DATA THAT ACTUALLY EXISTS. See the honesty note below.
+ 10. THE WIRING, through the real `Controller` and its real status page.
+
+------------------------------------------------------------------------------
+⚠️ AC 3 IS NOT MET, AND PART 9 DOES NOT PRETEND OTHERWISE.
+
+AC 3 asks for "the monthly peak held under the soft limit in >= 95 % of
+intervals over a 30-day simulation replay". THERE IS NO 30-DAY DATASET. The
+infra repo's `sim/scenarios/` holds exactly two days of this house's real meter
+- 2026-08-20 (the Illusmart failure day) and 2026-08-23 (the healthy reference)
+- exported on 2026-08-25 because they were about to age out of HA's recorder,
+and nothing longer was ever captured. `sim/scenarios/README.md` lists the whole
+inventory; the rest is RS485 bus frames, OTA witness logs and a 578-row rollback
+poll, none of which carries grid power over calendar time.
+
+So part 9 replays the two days that exist, reports the percentage over them, and
+states the sample size in days next to it. It is a MEASUREMENT, not a verdict:
+nothing in it exits non-zero on the 95 % figure, because a 2-day run cannot pass
+or fail a 30-day criterion and a check that claimed it could would be the more
+expensive of the two mistakes. Both days are also *uncontrolled* - the add-on
+was not shaving peaks on either - so the figure they give is the BASELINE the
+guard has to improve on, which is the useful thing a 2-day replay can say.
+
+The two days are committed here as `scenarios/p1-net-<date>.jsonl.gz`
+(`{"t": iso8601, "w": signed_watts}` per line, derived from the HA recorder
+export) for the reason `scenarios/p1-age-2026-08-26.jsonl.gz` already is: the
+infra repo is private, CI's token is minted for this repository only, and a
+regression fixture that CI cannot see is not a regression fixture.
+
+Closing AC 3 needs 30 days of capture. That is TEST-01's replay harness, and it
+cannot start before somebody starts recording.
+"""
+
+import asyncio
+import gzip
+import json
+import shutil
+import sys
+import tempfile
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+from app.main import Controller
+from app.p1 import P1Ingest, QuarterAverager, QUARTER_S, make_sample, split_signed
+from app.tariff import (
+    BILLING_TZ, CHECKPOINT_S, NO_RECORD, NOT_OBSERVED, POLICY_MAX,
+    POLICY_NET, POLICY_SUM, PeakStore, PeakTracker, _EUTimezone, billed_w,
+    month_key,
+)
+
+fails = []
+HERE = Path(__file__).resolve().parent
+TMP = Path(tempfile.mkdtemp(prefix="goodwe-tariff-"))
+
+# The live install's numbers: NOTES.md and freeze.py both record max_w 5000
+# there. `peak_cap_w` ships at 3500 in config.yaml and is the SOFT LIMIT AC 3
+# grades against - read out of the shipped file in part 10 rather than typed.
+LIVE_MAX_W = 5000.0
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def near(a, b, tol=1e-6):
+    return a is not None and b is not None and abs(a - b) <= tol
+
+
+def sample(t: datetime, net_w: float, phases=1, phase_net=None):
+    """One P1 telegram, through the SHIPPED derivation.
+
+    `split_signed` and `make_sample` are what the real transports call, so the
+    sign convention under test is the one that ships rather than a local
+    re-derivation of it.
+    """
+    imp, exp = split_signed(net_w)
+    pi = pe = None
+    if phase_net is not None:
+        pairs = [split_signed(v) for v in phase_net]
+        pi = [a for a, _ in pairs]
+        pe = [b for _, b in pairs]
+    return make_sample("ha_signed", imp, exp, phases=phases,
+                       phase_import_w=pi, phase_export_w=pe,
+                       ingest_ts=t, ingest_mono=t.timestamp())
+
+
+def fresh_store(name: str) -> PeakStore:
+    return PeakStore(str(TMP / f"{name}.db"))
+
+
+# B is a clock-aligned quarter boundary: proved, not assumed, because every
+# other number in part 1 rests on it.
+B = datetime(2026, 8, 30, 9, 0, 0, tzinfo=timezone.utc)
+
+
+# ==============================================================================
+print("1. the block arithmetic, on a worked example")
+
+check(f"the fixture's start {B.isoformat()} really is 900 s aligned",
+      int(B.timestamp()) % QUARTER_S == 0)
+
+# (t seconds after B, net W). Deliberately irregular, with an export, a gap
+# longer than max_hold_s, and a last sample that straddles the boundary.
+MAX_HOLD_S = 30.0
+FIXTURE = [(0, 1000.0), (20, 2000.0), (30, -500.0), (50, 3000.0),
+           (250, 4000.0), (880, 1200.0), (1000, 900.0)]
+
+# The worked example, written as the segments a person would compute by hand:
+# each HELD value and how many seconds of the FIRST block it is evidence for.
+# Two rules do all the work: a sample is held forward until the next one, capped
+# at MAX_HOLD_S; and export is 0 W of offtake, never a negative contribution.
+SEGMENTS = [
+    (1000.0, 20),    # 0 -> 20, a normal telegram interval, held in full
+    (2000.0, 10),    # 20 -> 30, likewise
+    (0.0, 20),       # 30 -> 50: -500 W is EXPORT, so 0 W of offtake for 20 s
+    (3000.0, 30),    # 50 -> 250 is a 200 s GAP; only the first 30 s is evidence
+    (4000.0, 30),    # 250 -> 880 is a 630 s gap; again only 30 s is evidence
+    (1200.0, 20),    # 880 -> 900: the STRADDLE's first half, up to the boundary
+]
+# The straddle's second half: the same held 1200 W, from the boundary until its
+# hold expires at 880 + 30. It must be credited to the NEXT block, not to this
+# one and not to neither.
+SPLIT_TAIL_W, SPLIT_TAIL_S = 1200.0, 10
+EXP_WS = sum(w * s for w, s in SEGMENTS)
+EXP_COVERED_S = sum(s for _, s in SEGMENTS)
+EXP_BLOCK_AVG = EXP_WS / QUARTER_S              # what the utility bills
+EXP_ELAPSED_AVG = EXP_WS / EXP_COVERED_S        # what a /elapsed divisor gives
+NAIVE_MEAN = sum(max(w, 0.0) for _, w in FIXTURE[:-1]) / (len(FIXTURE) - 1)
+
+avg = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+closed = []
+for dt_s, w in FIXTURE:
+    closed += avg.add(sample(B + timedelta(seconds=dt_s), w))
+
+print(f"    {len(SEGMENTS)} held segments -> {EXP_WS:,.0f} Ws over "
+      f"{EXP_COVERED_S:.0f} s of the {QUARTER_S} s block")
+check(f"exactly one block closed", len(closed) == 1)
+check(f"...starting at the fixture's own boundary {B.isoformat()}",
+      bool(closed) and closed[0].start == B)
+check(f"...averaging {EXP_BLOCK_AVG:.2f} W - the worked example's "
+      f"{EXP_WS:,.0f} Ws over the FULL {QUARTER_S} s",
+      bool(closed) and near(closed[0].offtake_avg_w, EXP_BLOCK_AVG, 1e-9))
+
+# The three ways of being wrong, each of which produces a plausible number.
+print(f"    the same data read three other ways: /elapsed = {EXP_ELAPSED_AVG:.2f} W, "
+      f"naive mean of samples = {NAIVE_MEAN:.2f} W, "
+      f"billed = {EXP_BLOCK_AVG:.2f} W")
+check("...and /elapsed is NOT the billed figure - a gap must drag the average "
+      "down, not be averaged away",
+      abs(EXP_ELAPSED_AVG - EXP_BLOCK_AVG) > 1.0)
+check("...and a naive mean over samples is NOT the billed figure either - it "
+      "weights a burst of fast telegrams like a slow one",
+      abs(NAIVE_MEAN - EXP_BLOCK_AVG) > 1.0)
+
+# The straddle: the 4000 W sample at t=400 is held ACROSS 900. Its evidence
+# expires at 430, so the second block gets none of it - and the second block
+# must still have been OPENED at 900, not at 1000.
+check(f"the block after the straddle opens at the boundary, not at the sample",
+      avg.block_start == B + timedelta(seconds=QUARTER_S))
+print(f"    the straddling sample is SPLIT at the boundary: "
+      f"{SEGMENTS[-1][0]:.0f} W x {SEGMENTS[-1][1]} s into the first block, "
+      f"x {SPLIT_TAIL_S} s into the second")
+check(f"...and the second block is credited the tail "
+      f"({SPLIT_TAIL_W * SPLIT_TAIL_S:,.0f} Ws), so a sample spanning :15 is "
+      f"attributed to BOTH blocks in proportion and wholly to neither",
+      near(avg.partial_ws, SPLIT_TAIL_W * SPLIT_TAIL_S, 1e-9))
+
+
+# ==============================================================================
+print()
+print("2. the 900 s degeneracy - where three different formulas agree")
+
+# A complete block at a constant power, fully covered. Here acc/elapsed,
+# acc/900 and the projection are ALL the same number. Anything checked only
+# here is checked against nothing.
+HELD_W = 2400.0
+deg = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+deg_closed = []
+for i in range(0, QUARTER_S + 1, 5):
+    deg_closed += deg.add(sample(B + timedelta(seconds=i), HELD_W))
+d_block = deg_closed[0].offtake_avg_w
+deg2 = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+LAST_S = QUARTER_S - 5
+for i in range(0, LAST_S + 1, 5):
+    deg2.add(sample(B + timedelta(seconds=i), HELD_W))
+d_partial = deg2.offtake_avg_w
+# Graded AT the last sample: full coverage behind it, a held value in front.
+d_proj = PeakTracker.project(deg2, B + timedelta(seconds=LAST_S)).projected_w
+print(f"    at full coverage of a whole block: acc/900 = {d_block:.2f} W, "
+      f"acc/elapsed = {d_partial:.2f} W, projection = {d_proj:.2f} W")
+check("all three formulas coincide at exactly 900 s of full coverage - so a "
+      "check placed only there distinguishes none of them",
+      near(d_block, HELD_W, 1e-6) and near(d_partial, HELD_W, 1e-6)
+      and near(d_proj, HELD_W, 1e-6))
+
+# Away from it, on part 1's fixture at a point mid-block, they must separate.
+mid = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+for dt_s, w in FIXTURE[:-1]:
+    mid.add(sample(B + timedelta(seconds=dt_s), w))
+NOW = B + timedelta(seconds=500)
+p = PeakTracker.project(mid, NOW)
+print(f"    at t=500 s on part 1's fixture: acc/elapsed = {p.elapsed_w:.2f} W, "
+      f"projection = {p.projected_w:.2f} W, coverage = {p.covered_frac * 100:.1f} %")
+check("mid-block, with a gap in it, the elapsed average and the projection are "
+      "DIFFERENT numbers", abs(p.elapsed_w - p.projected_w) > 1.0)
+check("...and the projection carries elapsed_s, so a consumer can see it is an "
+      f"extrapolation over {QUARTER_S - p.elapsed_s:.0f} s it has not seen",
+      near(p.elapsed_s, 500.0, 1e-6))
+check("...and a gap shows up as coverage below 1.0 rather than as a confident "
+      "low number", p.covered_frac < 1.0 and not p.complete)
+
+
+# ==============================================================================
+print()
+print("3. restart mid-block: the same block, or a lower one, never a lost one")
+
+RUN_W = 2000.0
+STEP_S = 1
+RESTART_AT_S = 600      # minute 10 of the quarter - the functional note's case
+
+
+def feed(avg, t0_s, t1_s, w=RUN_W):
+    out = []
+    for i in range(t0_s, t1_s + 1, STEP_S):
+        out += avg.add(sample(B + timedelta(seconds=i), w))
+    return out
+
+
+# (a) the control: no restart at all.
+ctrl = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+ctrl_closed = feed(ctrl, 0, QUARTER_S)
+CTRL_W = ctrl_closed[0].offtake_avg_w
+
+# (b) restarted at minute 10, checkpoint restored through a real SQLite file.
+st = fresh_store("restart")
+tr = PeakTracker(st, cap_w=LIVE_MAX_W)
+a1 = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+feed(a1, 0, RESTART_AT_S)
+check("the checkpoint round-trips through SQLite", st.save_partial(a1.snapshot()))
+a2 = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)   # a brand-new process
+restored = tr.restore(a2, B + timedelta(seconds=RESTART_AT_S + 1))
+print(f"    restore() said: {restored}")
+check("...and restore() reports RESUMING rather than starting fresh",
+      restored.startswith("resumed"))
+r_closed = feed(a2, RESTART_AT_S + STEP_S, QUARTER_S)
+RESTART_W = r_closed[0].offtake_avg_w if r_closed else None
+
+# (c) the mutation guard: the SAME restart with no restore.
+a3 = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+n_closed = feed(a3, RESTART_AT_S + STEP_S, QUARTER_S)
+NORESTORE_W = n_closed[0].offtake_avg_w if n_closed else None
+
+print(f"    uninterrupted {CTRL_W:.2f} W | restored {RESTART_W:.2f} W | "
+      f"restart with no restore {NORESTORE_W:.2f} W")
+check(f"a restart at {RESTART_AT_S} s lands on the SAME billed block as an "
+      f"uninterrupted run", near(RESTART_W, CTRL_W, 1e-6))
+check("...and without the restore it lands LOWER - so 'the restore works' is "
+      "not satisfied by a fixture where restoring changes nothing",
+      NORESTORE_W is not None and NORESTORE_W < CTRL_W - 1.0)
+# Derived, not asserted against a literal: the lost part is exactly the seconds
+# before the restart, at the power that was flowing.
+DROPPED_S = RESTART_AT_S + STEP_S     # the resumed feed starts one step later
+check(f"...and it is lower by exactly the {DROPPED_S} s it dropped "
+      f"({RUN_W * DROPPED_S / QUARTER_S:.2f} W)",
+      near(CTRL_W - NORESTORE_W, RUN_W * DROPPED_S / QUARTER_S, 1e-6))
+
+# (d) a LONG outage: restored, but the meter was away past max_hold_s. The
+# uncovered seconds must drag the block DOWN, not be held forward.
+OUTAGE_S = 200
+a4 = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+st4 = fresh_store("outage")
+st4.save_partial(a1.snapshot())
+PeakTracker(st4, cap_w=LIVE_MAX_W).restore(a4, B + timedelta(seconds=RESTART_AT_S + OUTAGE_S))
+o_closed = feed(a4, RESTART_AT_S + OUTAGE_S, QUARTER_S)
+OUTAGE_UNCOVERED_S = OUTAGE_S - MAX_HOLD_S
+print(f"    a {OUTAGE_S} s outage inside the quarter, of which "
+      f"{OUTAGE_UNCOVERED_S:.0f} s is past the {MAX_HOLD_S:.0f} s hold: "
+      f"{o_closed[0].offtake_avg_w:.2f} W")
+check(f"...reads lower than the uninterrupted block by exactly the uncovered "
+      f"seconds ({RUN_W * OUTAGE_UNCOVERED_S / QUARTER_S:.2f} W) - a gap is "
+      f"never held forward across the whole outage",
+      near(CTRL_W - o_closed[0].offtake_avg_w,
+           RUN_W * OUTAGE_UNCOVERED_S / QUARTER_S, 1e-6))
+
+# (e) double counting is answered by the primary key, not by care.
+st5 = fresh_store("dedupe")
+st5.record_block(ctrl_closed[0])
+st5.record_block(ctrl_closed[0])
+st5.record_block(ctrl_closed[0])
+rows = st5.blocks_in(month_key(B))
+check("banking the same quarter three times leaves ONE row - quarter_start is "
+      "the primary key, so a replay or a restart cannot double-count",
+      len(rows) == 1 and near(rows[0][1], CTRL_W, 1e-9))
+
+# ...and a later pass with LESS coverage may not lower a banked figure.
+from app.tariff import _ClosedBlock as _CB
+st5.record_block(_CB(start=B, offtake_avg_w=CTRL_W / 2, per_phase_offtake_avg_w=None))
+after = st5.blocks_in(month_key(B))
+check(f"...and re-banking the same quarter at half the figure leaves it at "
+      f"{CTRL_W:.0f} W - a restart's partial re-run must never lower a "
+      f"quarter that was already measured in full",
+      len(after) == 1 and near(after[0][1], CTRL_W, 1e-9))
+
+# (f) the checkpoint's own staleness bound, derived from the constant.
+print(f"    CHECKPOINT_S = {CHECKPOINT_S:.0f} s, so a crash can lose at most "
+      f"{CHECKPOINT_S / QUARTER_S * 100:.1f} % of one quarter's average")
+check("the checkpoint bound is small enough that its worst case is under 2 % "
+      "of a quarter", CHECKPOINT_S / QUARTER_S < 0.02)
+
+
+# ==============================================================================
+print()
+print("4. month rollover, in LOCAL time, and across a restart that straddles it")
+
+# CEST is UTC+2, so the last two hours of 31 August UTC are already September.
+AUG_LATE = datetime(2026, 8, 31, 21, 45, tzinfo=timezone.utc)
+SEP_EARLY = datetime(2026, 8, 31, 22, 15, tzinfo=timezone.utc)
+print(f"    {AUG_LATE.isoformat()} is local "
+      f"{AUG_LATE.astimezone(BILLING_TZ).isoformat()} -> {month_key(AUG_LATE)}")
+print(f"    {SEP_EARLY.isoformat()} is local "
+      f"{SEP_EARLY.astimezone(BILLING_TZ).isoformat()} -> {month_key(SEP_EARLY)}")
+check("a quarter starting 21:45 UTC on 31 Aug bills in AUGUST",
+      month_key(AUG_LATE) == "2026-08")
+check("a quarter starting 22:15 UTC on 31 Aug bills in SEPTEMBER - filing it "
+      "under August would move a whole month's bill",
+      month_key(SEP_EARLY) == "2026-09")
+check("...and the two are genuinely on opposite sides of the boundary, not "
+      "the same answer twice", month_key(AUG_LATE) != month_key(SEP_EARLY))
+# Winter, where the offset is +1 and the boundary sits an hour later.
+JAN_LATE = datetime(2026, 1, 31, 22, 45, tzinfo=timezone.utc)
+check("in WINTER the same trap is an hour later: 22:45 UTC on 31 Jan is still "
+      "January, and 23:15 UTC is February",
+      month_key(JAN_LATE) == "2026-01"
+      and month_key(JAN_LATE + timedelta(minutes=30)) == "2026-02")
+
+st6 = fresh_store("months")
+AUG_PEAK_W, SEP_PEAK_W = 4998.0, 900.0
+st6.record_block(_CB(AUG_LATE, AUG_PEAK_W, None))
+st6.record_block(_CB(SEP_EARLY, SEP_PEAK_W, None))
+r_aug, r_sep = st6.peak(month="2026-08"), st6.peak(month="2026-09")
+print(f"    {r_aug.explain()}")
+print(f"    {r_sep.explain()}")
+check(f"August's peak is the {AUG_PEAK_W:.0f} W quarter (specs.md:583's own "
+      f"measured case) and September's is not",
+      r_aug.is_observed and near(r_aug.peak_w, AUG_PEAK_W)
+      and r_sep.is_observed and near(r_sep.peak_w, SEP_PEAK_W))
+check("...so a new month starts from its OWN quarters, not from the previous "
+      "month's peak", r_sep.peak_w < r_aug.peak_w)
+
+# The restart that straddles the boundary: a checkpoint whose open block is in
+# August, restored when `now` is already September.
+st7 = fresh_store("straddle")
+tr7 = PeakTracker(st7, cap_w=LIVE_MAX_W)
+straddler = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+for i in range(0, 400, STEP_S):
+    straddler.add(sample(AUG_LATE + timedelta(seconds=i), RUN_W))
+st7.save_partial(straddler.snapshot())
+after_boot = QuarterAverager(phases=1, max_hold_s=MAX_HOLD_S)
+said = tr7.restore(after_boot, SEP_EARLY + timedelta(minutes=3))
+print(f"    restore() across the boundary said: {said}")
+aug7, sep7 = st7.peak(month="2026-08"), st7.peak(month="2026-09")
+check("a restart that straddles the month boundary BANKS the dead August "
+      "quarter rather than dropping measured energy",
+      said.startswith("closed a stale block") and aug7.is_observed)
+check(f"...at its partial-coverage figure ({aug7.peak_w:.2f} W = "
+      f"{RUN_W * 399 / QUARTER_S:.2f} W, the seconds it actually covered)",
+      near(aug7.peak_w, RUN_W * 399 / QUARTER_S, 1e-6))
+check("...and September reads NO_RECORD, which is a different answer from "
+      "August's peak AND from a zero",
+      sep7.state == NO_RECORD and sep7.peak_w is None)
+check("...and the checkpoint is cleared, so a second boot cannot re-bank it",
+      st7.load_partial() is None)
+
+
+# ==============================================================================
+print()
+print("5. AN UNREADABLE STORE IS NOT A ZERO PEAK  (the acceptance argument)")
+
+# Three stores, three states, and the three must not answer alike.
+good = fresh_store("states")
+good_tr = PeakTracker(good, cap_w=LIVE_MAX_W)
+empty_r = good_tr.peak(B)
+
+gone = fresh_store("gone")
+gone_tr = PeakTracker(gone, cap_w=LIVE_MAX_W)
+gone.record_block(_CB(B, 3000.0, None))
+gone.close()                       # the database goes away under a live reader
+gone_r = gone_tr.peak(B)
+
+never = PeakStore(str(TMP / "no-such-dir" / "x.db"))
+never_tr = PeakTracker(never, cap_w=LIVE_MAX_W)
+never_r = never_tr.peak(B)
+
+# A store that is OPEN and whose query FAILS is a third code path - a closed
+# handle short-circuits before the SQL ever runs, so without this the
+# `except sqlite3.Error` arm of peak() is never executed by anything.
+broken = fresh_store("broken-table")
+broken.record_block(_CB(B, 3000.0, None))
+broken._db.execute("DROP TABLE monthly_peak")
+broken._db.commit()
+broken_r = PeakTracker(broken, cap_w=LIVE_MAX_W).peak(B)
+
+for label, r in (("fresh store, no quarter yet", empty_r),
+                 ("store that broke under a live reader", gone_r),
+                 ("store that never opened", never_r),
+                 ("store open, query failed", broken_r)):
+    print(f"    {label:38s} -> {r.state:13s} {r.explain()}")
+
+check("a fresh store with no quarter yet says NO_RECORD - a normal state on "
+      "the 1st of the month", empty_r.state == NO_RECORD)
+check("a store that broke says NOT_OBSERVED", gone_r.state == NOT_OBSERVED)
+check("a store that never opened says NOT_OBSERVED", never_r.state == NOT_OBSERVED)
+check("a store whose QUERY fails says NOT_OBSERVED too - a different code path "
+      "from a closed handle, and the one a half-corrupt database takes",
+      broken_r.state == NOT_OBSERVED and broken_r.peak_w is None)
+# ...and losing the DERIVED record does not lose the peak, which is the whole
+# argument for keeping monthly_peak recomputable from the 15-min tier.
+_rec = broken.recompute_month(month_key(B))
+print(f"    ...but with the 15-min tier intact, recompute_month() still "
+      f"answers: {_rec.explain()}")
+check("...while recompute_month() STILL answers from the surviving 15-min "
+      "tier - the permanent record is derived, so losing it is recoverable",
+      _rec.is_observed and near(_rec.peak_w, 3000.0))
+broken._db.execute("DROP TABLE quarter_blocks")
+broken._db.commit()
+check("...and once BOTH tiers are gone it says NOT_OBSERVED rather than "
+      "raising into the control loop",
+      broken.recompute_month(month_key(B)).state == NOT_OBSERVED)
+check("...and NO_RECORD and NOT_OBSERVED are DIFFERENT states, not two "
+      "spellings of the same one", empty_r.state != gone_r.state)
+check("...and they read differently to a human, too",
+      empty_r.explain() != gone_r.explain()
+      and "NOT" in gone_r.explain() and "zero peak" in gone_r.explain())
+
+check("an unreadable peak is None, not 0.0 - there is no number to mistake",
+      gone_r.peak_w is None and never_r.peak_w is None)
+check("...and NO_RECORD carries no number either", empty_r.peak_w is None)
+_typed = False
+try:
+    float(gone_r.peak_w)
+except TypeError:
+    _typed = True
+check("...and a caller who forgets to ask gets a TypeError rather than a "
+      "silently disarming zero", _typed)
+check("PeakReading exposes no accessor that defaults a missing peak to a "
+      "number - no .get(), no _or() ",
+      not [a for a in dir(gone_r)
+           if a.startswith(("get", "value")) or a.endswith("_or")])
+
+# The consequence, which is the reason any of this matters.
+print(f"    headroom under a {LIVE_MAX_W:.0f} W limit: "
+      f"no quarter yet -> {good_tr.headroom_w(B)}, "
+      f"unreadable -> {gone_tr.headroom_w(B)}")
+check("an unreadable store yields NO headroom figure - the disarming default "
+      "(full headroom, guard silently off) is unreachable",
+      gone_tr.headroom_w(B) is None and never_tr.headroom_w(B) is None)
+check(f"...where a genuinely empty month yields the full {LIVE_MAX_W:.0f} W, "
+      f"which is correct and is a different answer",
+      near(good_tr.headroom_w(B), LIVE_MAX_W))
+check("the 80 % warning fraction is likewise None when nothing was observed",
+      gone_tr.warning_frac(B) is None and good_tr.warning_frac(B) == 0.0)
+
+# And a real peak reduces headroom, so "always None" does not pass this part.
+good.record_block(_CB(B, LIVE_MAX_W * 0.9, None))
+print(f"    after one {LIVE_MAX_W * 0.9:.0f} W quarter: "
+      f"headroom {good_tr.headroom_w(B):.0f} W, "
+      f"warning {good_tr.warning_frac(B) * 100:.0f} % of the limit")
+check("a real observed peak gives a real headroom, so this part is not passed "
+      "by a store that answers None to everything",
+      near(good_tr.headroom_w(B), LIVE_MAX_W * 0.1, 1e-6))
+check(f"...and it is over §9.1's 80 % warning threshold",
+      good_tr.warning_frac(B) > 0.8)
+
+# A CORRUPT database file is the third way a store fails, and it must land in
+# NOT_OBSERVED too rather than raising into the control loop.
+corrupt_path = TMP / "corrupt.db"
+corrupt_path.write_bytes(b"this is not a database" * 64)
+corrupt = PeakStore(str(corrupt_path))
+c_r = PeakTracker(corrupt, cap_w=LIVE_MAX_W).peak(B)
+print(f"    a corrupt database file -> {c_r.state}")
+check("a corrupt database reads NOT_OBSERVED and does not raise into the "
+      "control loop (§6 fail-open)", c_r.state == NOT_OBSERVED)
+
+
+# ==============================================================================
+print()
+print("6. the timezone fallback, graded against zoneinfo")
+
+_zi = None
+try:
+    from zoneinfo import ZoneInfo
+    _zi = ZoneInfo("Europe/Brussels")
+except Exception as err:                      # noqa: BLE001
+    print(f"    zoneinfo unavailable here ({err}) - the fallback IS the tz")
+
+if _zi is None:
+    check("zoneinfo is absent, so the encoded rule cannot be graded here - "
+          "reported, not silently passed", True)
+else:
+    fb = _EUTimezone()
+    # ⚠️ HOURLY, NOT 3-HOURLY, ACROSS THE TRANSITION DAYS. Both EU transitions
+    # happen at 01:00 UTC, so a rule that is wrong BY AN HOUR differs from the
+    # right one only between 01:00 and 02:00 UTC. A 3-hourly sweep steps over
+    # that window entirely and grades nothing - measured: a mutation moving the
+    # UTC threshold from 01:00 to 02:00 survived the whole file at 3-hourly.
+    probes = [datetime(2026, 1, 1, 12, tzinfo=timezone.utc)]
+    probes += [datetime(2026, m, d, h, mi, tzinfo=timezone.utc)
+               for m in (3, 10) for d in (28, 29, 30, 31)
+               for h in range(24) for mi in (0, 30)]
+    probes += [datetime(2026, m, 1, 0, 30, tzinfo=timezone.utc) for m in range(1, 13)]
+    # ⚠️ COMPARE THE CONVERTED WALL CLOCK, NOT ITS utcoffset(). `astimezone`
+    # goes through `fromutc`, but the RESULT carries local wall values, so
+    # asking it for `.utcoffset()` routes straight back into the LOCAL arm and
+    # never grades `fromutc` at all. Measured: a mutation moving the UTC
+    # threshold by an hour survived 397 offset-comparing probes and dies
+    # immediately on the wall clock they produce.
+    def _wallclock(t, tz):
+        return t.astimezone(tz).replace(tzinfo=None)
+
+    bad = [t for t in probes if _wallclock(t, fb) != _wallclock(t, _zi)]
+    print(f"    {len(probes)} probes across both DST transitions and every "
+          f"month boundary: {len(bad)} disagreement(s) in the LOCAL WALL CLOCK "
+          f"each one converts to")
+    check("the encoded EU rule converts every probe to the same local wall "
+          "clock as zoneinfo, including the two transition weekends", not bad)
+    # ...and the probes are not all the same offset, or the check is vacuous.
+    offsets = {t.astimezone(_zi).utcoffset() for t in probes}
+    check(f"...and the probe set spans BOTH offsets ({sorted(str(o) for o in offsets)}), "
+          f"so agreeing is not free", len(offsets) == 2)
+    check(f"BILLING_TZ resolved to zoneinfo on this host, not the fallback",
+          not isinstance(BILLING_TZ, _EUTimezone))
+
+    # ⚠️ THE PROBES ABOVE ONLY EXERCISE `fromutc()`. `astimezone` on a UTC
+    # instant never calls `utcoffset()` with a local wall time, so the local
+    # arm of the rule was ungraded - a mutation that moved it by an hour
+    # survived the whole file. These probes drive it directly. Noon is used
+    # because it is unambiguous on every day of the year, including the two
+    # transition days where 02:00-03:00 local is missing or repeated.
+    #
+    # ⚠️ AND THE LOCAL PROBES MUST INCLUDE 03:00-03:59 ON THE OCTOBER SUNDAY.
+    # That hour is where a local rule that ends DST an hour late still claims
+    # CEST while zoneinfo has already returned to CET; at noon both answers
+    # agree and the probe is worth nothing. Measured: at noon-only, a mutation
+    # moving the local thresholds from 02:00/03:00 to 03:00/04:00 survived.
+    #
+    # The MARCH gap (02:00-02:59 local, which does not exist) is deliberately
+    # NOT probed: Python hands a nonexistent local time to `utcoffset` as an
+    # ordinary value and any answer is defensible, so grading it would pin an
+    # arbitrary choice. It cannot move a month boundary - it is the last Sunday
+    # of March, never the 1st of a month - which is the only thing this tz is
+    # used for.
+    wall = [datetime(2026, m, d, 12) for m, d in
+            [(3, 27), (3, 28), (3, 29), (3, 30), (10, 24), (10, 25),
+             (10, 26), (10, 27)]]
+    wall += [datetime(2026, 10, 25, h, mi) for h in range(0, 6) for mi in (0, 30)
+             if h != 2]                       # 02:00 local is the ambiguous fold
+    wall += [datetime(2026, 3, 29, h, mi) for h in (0, 1, 3, 4, 5) for mi in (0, 30)]
+    wall += [datetime(2026, m, 1, 12) for m in range(1, 13)]
+    bad_w = [w for w in wall
+             if w.replace(tzinfo=fb).utcoffset() != w.replace(tzinfo=_zi).utcoffset()]
+    w_offsets = {w.replace(tzinfo=_zi).utcoffset() for w in wall}
+    print(f"    {len(wall)} LOCAL-wall probes through utcoffset(): "
+          f"{len(bad_w)} disagreement(s), spanning "
+          f"{sorted(str(o) for o in w_offsets)}")
+    check("utcoffset() on local wall time matches zoneinfo across both "
+          "transition weekends - the arm astimezone() never reaches", not bad_w)
+    check("...and those probes span both offsets too", len(w_offsets) == 2)
+    bad_n = [w for w in wall
+             if w.replace(tzinfo=fb).tzname() != w.replace(tzinfo=_zi).tzname()]
+    check("...and tzname() agrees with zoneinfo at every one of them (CET/CEST)",
+          not bad_n)
+
+
+# ==============================================================================
+print()
+print("7. the per-phase reduction, on an UNBALANCED three-phase load (§17)")
+
+# One phase exporting is what separates the three policies. On a balanced load
+# they all give the same number, which is why this fixture is not balanced.
+PH = (3000.0, 500.0, -200.0)
+NET = sum(PH)
+u = QuarterAverager(phases=3, max_hold_s=MAX_HOLD_S)
+u_closed = []
+for i in range(0, QUARTER_S + 1, 5):
+    u_closed += u.add(sample(B + timedelta(seconds=i), NET, phases=3, phase_net=PH))
+blk = u_closed[0]
+vals = {p: billed_w(blk, p) for p in (POLICY_NET, POLICY_SUM, POLICY_MAX)}
+print(f"    phases {PH} (net {NET:+.0f} W) -> "
+      + ", ".join(f"{k}={v:.0f} W" for k, v in vals.items()))
+check(f"the NET policy bills the connection's net offtake ({NET:.0f} W)",
+      near(vals[POLICY_NET], NET, 1e-6))
+check(f"the SUM policy clips each phase first, so the exporting phase does not "
+      f"net off ({sum(max(v, 0.0) for v in PH):.0f} W)",
+      near(vals[POLICY_SUM], sum(max(v, 0.0) for v in PH), 1e-6))
+check(f"the MAX policy bills the worst single phase ({max(PH):.0f} W)",
+      near(vals[POLICY_MAX], max(PH), 1e-6))
+check("...and on THIS fixture all three are different numbers - which is the "
+      "whole reason the reduction is a named policy and not an assumption",
+      len({round(v, 6) for v in vals.values()}) == 3)
+check("the shipped default is NET, the meter's own billed register",
+      billed_w(blk) == vals[POLICY_NET])
+
+bal = QuarterAverager(phases=3, max_hold_s=MAX_HOLD_S)
+b_closed = []
+for i in range(0, QUARTER_S + 1, 5):
+    b_closed += bal.add(sample(B + timedelta(seconds=i), 3000.0, phases=3,
+                               phase_net=(1000.0, 1000.0, 1000.0)))
+b_vals = {p: billed_w(b_closed[0], p) for p in (POLICY_NET, POLICY_SUM, POLICY_MAX)}
+check(f"...and on a BALANCED load NET and SUM coincide ({b_vals[POLICY_NET]:.0f} W), "
+      f"so a balanced fixture could not have told them apart",
+      near(b_vals[POLICY_NET], b_vals[POLICY_SUM], 1e-6))
+
+
+# ==============================================================================
+print()
+print("8. monthly_peak is DERIVED, and provably has not diverged")
+
+st8 = fresh_store("derive")
+QUARTERS = [(0, 1200.0), (1, 4998.0), (2, 3357.0), (3, 800.0), (4, 4832.0)]
+for q, w in QUARTERS:
+    st8.record_block(_CB(B + timedelta(seconds=q * QUARTER_S), w, None))
+MAXQ = max(w for _, w in QUARTERS)
+stored = st8.peak(month=month_key(B))
+derived = st8.recompute_month(month_key(B))
+print(f"    {len(QUARTERS)} quarters banked; stored peak {stored.peak_w:.0f} W, "
+      f"recomputed from quarter_blocks {derived.peak_w:.0f} W")
+check(f"the stored monthly peak is the largest quarter ({MAXQ:.0f} W - "
+      f"specs.md:583's own figure)",
+      stored.is_observed and near(stored.peak_w, MAXQ))
+check("...and re-deriving it from the 15-min tier gives the same number and "
+      "the same quarter, so the two records are proven equal rather than "
+      "assumed to be",
+      derived.is_observed and near(derived.peak_w, stored.peak_w)
+      and derived.quarter_start == stored.quarter_start)
+check("...and the two measured regressions from §9.1 land on DIFFERENT peaks - "
+      f"the sustained {MAXQ:.0f} W quarter, not the oscillating 3357 W one",
+      not near(stored.peak_w, 3357.0))
+# A quarter arriving LATER and lower must not lower the month.
+st8.record_block(_CB(B + timedelta(seconds=9 * QUARTER_S), 100.0, None))
+check("a later, smaller quarter does not lower the month's peak",
+      near(st8.peak(month=month_key(B)).peak_w, MAXQ))
+check("...and the recompute agrees with it after that write, too",
+      near(st8.recompute_month(month_key(B)).peak_w, MAXQ))
+# No pruning: §15 says these two tiers are indefinite / permanent.
+src = (HERE / "app" / "tariff.py").read_text(encoding="utf-8")
+check("§15's retention is structural: no DELETE against quarter_blocks or "
+      "monthly_peak exists anywhere in tariff.py",
+      "DELETE FROM quarter_blocks" not in src
+      and "DELETE FROM monthly_peak" not in src
+      and "DROP TABLE" not in src)
+
+
+# ==============================================================================
+print()
+print("9. AC 3, on the replay data that actually exists")
+
+REPLAY = sorted((HERE / "scenarios").glob("p1-net-*.jsonl.gz"))
+print(f"    replay fixtures found: {len(REPLAY)} "
+      f"({', '.join(p.name for p in REPLAY) or 'none'})")
+check("the committed replay fixtures are present - a regression fixture CI "
+      "cannot see is not a regression fixture", len(REPLAY) >= 2)
+
+# ⚠️ `peak_cap_w:` appears TWICE in config.yaml - once under `options:` with the
+# default, once under `schema:` with `int(500,15000)`. Taking the last match
+# would blow up on the schema line, and taking any match that parses would be
+# luck; the FIRST is the options block, which is the number an install lands on.
+SHIPPED_CAP_W = None
+for line in (HERE / "config.yaml").read_text(encoding="utf-8").splitlines():
+    if line.strip().startswith("peak_cap_w:"):
+        try:
+            SHIPPED_CAP_W = float(line.split(":", 1)[1].strip())
+        except ValueError:
+            continue
+        break
+check("config.yaml's shipped peak_cap_w was read out of the file rather than "
+      "typed here", SHIPPED_CAP_W is not None)
+
+replay_days = 0
+total_q = 0
+under = 0
+for path in REPLAY:
+    st9 = fresh_store("replay-" + path.stem)
+    ing = P1Ingest(phases=1, max_age_s=MAX_HOLD_S)
+    tr9 = PeakTracker(st9, cap_w=SHIPPED_CAP_W or LIVE_MAX_W)
+    first = last = None
+    with gzip.open(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            row = json.loads(line)
+            t = datetime.fromisoformat(row["t"])
+            first = first or t
+            last = t
+            ing.submit(sample(t, float(row["w"])))
+    tr9.sync(ing)
+    months = {month_key(b.start) for b in ing.blocks}
+    span_h = (last - first).total_seconds() / 3600.0
+    qs = [w for _, w in st9.blocks_in(sorted(months)[0])] if months else []
+    peak = max(qs) if qs else 0.0
+    ok_q = sum(1 for w in qs if w <= (SHIPPED_CAP_W or LIVE_MAX_W))
+    total_q += len(qs)
+    under += ok_q
+    replay_days += span_h / 24.0
+    print(f"    {path.name}: {span_h:.1f} h, {len(qs)} closed quarters, "
+          f"month peak {peak:.0f} W, "
+          f"{ok_q}/{len(qs)} = {100.0 * ok_q / max(len(qs), 1):.1f} % under the "
+          f"{SHIPPED_CAP_W:.0f} W soft limit")
+    check(f"{path.name}: the month's peak equals its own largest quarter",
+          near(st9.peak(month=sorted(months)[0]).peak_w, peak, 1e-9))
+    check(f"{path.name}: a full day of real telegrams produces ~96 quarters, "
+          f"got {len(qs)}", 90 <= len(qs) <= 96)
+
+PCT = 100.0 * under / max(total_q, 1)
+print()
+print(f"    AC 3 MEASURED: {under}/{total_q} quarters = {PCT:.1f} % under the "
+      f"{SHIPPED_CAP_W:.0f} W soft limit, over {replay_days:.1f} DAYS of "
+      f"replay, UNCONTROLLED (no peak shaving was running on either day).")
+print(f"    AC 3 ASKS FOR 30 DAYS. {replay_days:.1f} days exist. "
+      f"AC 3 IS NOT MET and this run does not claim it is - see the module "
+      f"docstring. The figure above is the BASELINE SAFETY-07 has to improve.")
+check("the replay produced a measurable number over a stated sample size, "
+      "rather than a criterion quietly redefined to fit the data",
+      total_q > 100 and replay_days < 30)
+
+
+# ==============================================================================
+print()
+print("10. the wiring: the real Controller, and what its status page says")
+
+
+class _Store:
+    data = {}
+
+    def set(self, *a):
+        pass
+
+    def get_time(self, *a):
+        return None
+
+
+class _Pub:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+class _Hass:
+    async def limits(self, entity):
+        return (-LIVE_MAX_W, LIVE_MAX_W, 1.0)
+
+    async def number(self, entity, invert=False):
+        return None
+
+    async def set_number(self, entity, value):
+        return True
+
+    async def call(self, domain, service, data):
+        return True
+
+
+def built(db_path, opts=None):
+    return Controller(dict(
+        {"setpoint_entity": "number.sp", "meter_source": "ha_signed",
+         "p1_net_entity": "sensor.net", "meter_phases": 1,
+         "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}, **(opts or {})),
+        _Hass(), _Store(), _Pub(), stop=asyncio.Event(),
+        peak_db_path=str(db_path))
+
+
+c = built(TMP / "wired.db")
+check(f"a Controller built with peak_cap_w ABSENT takes the SHIPPED "
+      f"{SHIPPED_CAP_W:.0f} W, so config.yaml and main.py's fallback cannot "
+      f"drift apart unnoticed", c.peak.cap_w == SHIPPED_CAP_W)
+
+# Drive one real quarter through the real ingest, then the real cycle's sync.
+for i in range(0, QUARTER_S + 1, 5):
+    c.p1.submit(sample(B + timedelta(seconds=i), 4998.0))
+n = c.peak.sync(c.p1)
+wr = c.peak.peak(B)
+print(f"    after one 4998 W quarter through the real ingest: "
+      f"{n} banked, {wr.explain()}")
+check("the closed quarter reached SQLite through the tracker the cycle calls",
+      n == 1 and wr.is_observed and near(wr.peak_w, 4998.0, 1e-6))
+
+# ⚠️ `cycle()` calls sync() ONCE A SECOND against a `blocks` list that keeps a
+# closed quarter for a DAY. Without a dedupe that is ~86 000 re-banks of the
+# same row per block, and `recorded` - the number the status page prints as
+# "quarters banked" - would be a count of loop iterations rather than of
+# quarters. The database stays correct either way, which is exactly why this
+# needs its own check instead of being caught by the peak.
+again = c.peak.sync(c.p1)
+third = c.peak.sync(c.p1)
+print(f"    sync() called three times over the same closed quarter: "
+      f"{n}, {again}, {third} newly banked; tracker reports "
+      f"{c.peak.recorded} quarter(s)")
+check("...and syncing the same quarter again banks nothing new, so the count "
+      "the status page shows is quarters and not cycles",
+      again == 0 and third == 0 and c.peak.recorded == 1)
+check("...and the peak is unchanged by the repeat",
+      near(c.peak.peak(B).peak_w, 4998.0, 1e-6))
+
+rows = [r for r in c.checks() if "capacity-tariff" in r["text"] or "peak" in r["text"]]
+peak_rows = [r for r in rows if "peak" in r["text"] and "quarter(s) banked" in r["text"]]
+print("    status row: " + (peak_rows[0]["text"] if peak_rows else "(none)"))
+check("the status page carries exactly one capacity-tariff peak row",
+      len(peak_rows) == 1)
+check("...naming the peak, the soft limit and the quarters banked, all derived "
+      "from the controller that was actually built",
+      bool(peak_rows) and "4998 W" in peak_rows[0]["text"]
+      and f"{SHIPPED_CAP_W:.0f} W soft limit" in peak_rows[0]["text"]
+      and "1 quarter(s) banked" in peak_rows[0]["text"])
+check("...and it is FLAGGED, because 4998 W is over §9.1's 80 % warning point "
+      f"on a {SHIPPED_CAP_W:.0f} W limit",
+      bool(peak_rows) and not peak_rows[0]["ok"] and peak_rows[0]["warn"])
+
+# The half that matters: the same page with a store that cannot answer.
+c2 = built(TMP / "no-such-dir" / "nope.db")
+u_rows = [r for r in c2.checks() if "capacity-tariff peak" in r["text"]]
+print("    status row (unreadable store): "
+      + (u_rows[0]["text"] if u_rows else "(none)"))
+check("an unreadable store gets its OWN row, saying UNREADABLE", len(u_rows) == 1)
+check("...and it does NOT read as a quiet month at 0 W - without this, a broken "
+      "instrument looks exactly like a month with no peak",
+      bool(u_rows) and "UNREADABLE" in u_rows[0]["text"]
+      and "0 %" not in u_rows[0]["text"] and u_rows[0]["warn"])
+check("...and the healthy row and the unreadable row are different text",
+      bool(u_rows) and bool(peak_rows)
+      and u_rows[0]["text"] != peak_rows[0]["text"])
+
+# THE MEASUREMENT IS OF DELIVERED POWER (SAFETY-20). Graded on the parsed
+# SYNTAX, not on the text: the module docstring argues this at length and names
+# every forbidden word while doing so, so a grep over the source would be
+# satisfied by deleting the explanation and would fail on writing one. What must
+# be true is that no NAME the code evaluates refers to a command.
+import ast as _ast
+
+_tree = _ast.parse(src)
+_names = {n.id for n in _ast.walk(_tree) if isinstance(n, _ast.Name)}
+_names |= {n.attr for n in _ast.walk(_tree) if isinstance(n, _ast.Attribute)}
+_names |= {n.name for n in _ast.walk(_tree)
+           if isinstance(n, (_ast.FunctionDef, _ast.ClassDef))}
+_FORBIDDEN = {"setpoint", "write_setpoint", "target", "Decision", "i_clamped",
+              "clamped", "Claim", "resolve", "P_PEAK", "arbiter"}
+_found = sorted(_names & _FORBIDDEN)
+_imports = sorted(m.module or "" for m in _ast.walk(_tree)
+                  if isinstance(m, _ast.ImportFrom))
+print(f"    tariff.py evaluates {len(_names)} distinct names and imports "
+      f"from {_imports or ['(stdlib only)']}")
+check(f"none of them is a command-side name {sorted(_FORBIDDEN)} - the utility "
+      f"bills what FLOWED, so this reads the meter and nothing else"
+      + (f"; found {_found}" if _found else ""), not _found)
+check("...and it imports nothing from arbiter, clamp or control: it files no "
+      "claim, applies no clamp, and commands nothing - SAFETY-07's job",
+      not [m for m in _imports if m in ("arbiter", "clamp", "control",
+                                        ".arbiter", ".clamp", ".control")])
+# ...and the guard is not vacuous: the same grader run over main.py, which DOES
+# command, must light up.
+_main = {n.attr for n in _ast.walk(
+    _ast.parse((HERE / "app" / "main.py").read_text(encoding="utf-8")))
+    if isinstance(n, _ast.Attribute)}
+check(f"the same grader over main.py finds {sorted(_main & _FORBIDDEN)}, so it "
+      f"is capable of failing", bool(_main & _FORBIDDEN))
+
+
+# ==============================================================================
+print()
+shutil.rmtree(TMP, ignore_errors=True)
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_validate.py

@@ -0,0 +1,574 @@
+"""Runnable check for the startup gate.  `python3 test_validate.py`
+
+Two halves, and the second is the one that matters. The first asserts that the
+three refusable configurations are refused. The second asserts that everything
+on validate.py's "deliberately not refused" list still STARTS - because the way
+a validator dies is not by missing a fault, it is by refusing something harmless
+until somebody deletes the call.
+"""
+
+import asyncio
+import sys
+
+from app.validate import (
+    ACTUATOR_WRITE_KEYS, FIRMWARE_INGEST_VETO_S, ConfigRefused, refuse,
+    validate_startup_config,
+)
+
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def base(**over):
+    """A configuration that must start. Everything else is this, spoilt."""
+    # ⚠️ The maintenance rates are named EXPLICITLY, at the values config.yaml
+    # ships (MAINT-04). They are not decoration: with the key absent, rule 6
+    # falls back to main.py's 2500 W, which against this 2000 W ceiling is a
+    # genuine refusal - so a base() without them would be a config that does
+    # not start, and every check below would be measuring the wrong thing.
+    o = {"setpoint_entity": "number.goodwe_setpoint", "max_w": 2000,
+         "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+         "meter_source": "off",
+         "maintenance_charge_w": 2000, "maintenance_discharge_w": 2000}
+    o.update(over)
+    return o
+
+
+def why(problems, needle):
+    return any(needle in p for p in problems)
+
+
+# --------------------------------------------------------------------------- #
+print("the baseline must start, or nothing below means anything")
+check("a good config with a 5000 W device is accepted",
+      validate_startup_config(base(), -5000, 5000) == [])
+check("...and with no device reachable yet, too",
+      validate_startup_config(base(), None, None) == [])
+
+# --------------------------------------------------------------------------- #
+print("1. max_w against the device's own rating")
+# ⚠️ THE ORIGINAL BUG. main.py used to log 'the device wins' and run anyway,
+# with write_setpoint() clamping, so the configured ceiling was never the real
+# one and the only evidence had scrolled off the log.
+p = validate_startup_config(base(max_w=8000), -5000, 5000)
+check("max_w above the device maximum is refused", len(p) == 1)
+check("...and the message names the configured value", why(p, "8000"))
+check("...and the device's value", why(p, "5000"))
+check("...and says which one wins", why(p, "THE DEVICE WINS"))
+check("max_w exactly at the device maximum is fine",
+      validate_startup_config(base(max_w=5000), -5000, 5000) == [])
+check("max_w under it is fine",
+      validate_startup_config(base(max_w=2000), -5000, 5000) == [])
+# The charge side is a separate rail and an asymmetric device is legal.
+p = validate_startup_config(base(max_w=4000), -2500, 5000)
+check("a max_w the device cannot take on the CHARGE side is refused too",
+      len(p) == 1 and why(p, "charge side"))
+check("...naming the device's floor", why(p, "-2500"))
+# ⚠️ Not guessed at: the entity may simply not have booted yet. run_control()
+# re-runs this the moment the real rating arrives.
+check("an unreachable device skips the range check rather than assuming",
+      validate_startup_config(base(max_w=8000), None, None) == [])
+check("a non-numeric max_w is refused",
+      why(validate_startup_config(base(max_w="lots"), -5000, 5000), "not a number"))
+
+# --------------------------------------------------------------------------- #
+print("2. an actuator to write to")
+# A controller with no actuator: write_setpoint() returns on the blank entity,
+# so no rating is read, no heartbeat is sent, layer 1 pins the inverter at 0 W,
+# and the add-on looks perfectly healthy the whole time.
+for blank in ("", "   ", None):
+    p = validate_startup_config(base(setpoint_entity=blank), None, None)
+    check(f"setpoint_entity {blank!r} is refused", len(p) == 1)
+check("...and the message says why it is dangerous rather than untidy",
+      why(validate_startup_config(base(setpoint_entity=""), None, None),
+          "heartbeat"))
+# specs §1.5: two writers on one actuator is not expressible in this schema.
+check("there is exactly one way to reach the actuator",
+      ACTUATOR_WRITE_KEYS == ("setpoint_entity",))
+
+# --------------------------------------------------------------------------- #
+print("3. a meter that can never read")
+# ⚠️ These predicates belong to p1.validate_meter_options(), which build_source()
+# also uses. Asserted here to prove the gate actually consults it - one entry
+# point, not two.
+check("meter_source off asks nothing of the P1 keys",
+      validate_startup_config(base(meter_source="off"), -5000, 5000) == [])
+check("homewizard_local with no p1_host is refused",
+      why(validate_startup_config(base(meter_source="homewizard_local"),
+                                  -5000, 5000), "p1_host"))
+check("...and with a host it is accepted",
+      validate_startup_config(base(meter_source="homewizard_local",
+                                   p1_host="192.168.2.250"), -5000, 5000) == [])
+check("a poll cadence at meter_max_age_s is refused at STARTUP, not just disabled",
+      why(validate_startup_config(base(meter_source="homewizard_local",
+                                       p1_host="m", meter_poll_s=30,
+                                       meter_max_age_s=30), -5000, 5000),
+          "meter_max_age_s"))
+check("ha_signed with no p1_net_entity is refused",
+      why(validate_startup_config(base(meter_source="ha_signed"), -5000, 5000),
+          "p1_net_entity"))
+check("a phase list disagreeing with meter_phases is refused",
+      why(validate_startup_config(base(meter_source="ha_signed",
+                                       p1_net_entity="sensor.n", meter_phases=3,
+                                       p1_phase_net_entities=["a", "b"]),
+                                  -5000, 5000), "phase-count"))
+check("mqtt_p1 with no topic is refused",
+      why(validate_startup_config(base(meter_source="mqtt_p1"), -5000, 5000),
+          "meter_mqtt_topic"))
+check("ha_dsmr with only half its entities is refused",
+      why(validate_startup_config(base(meter_source="ha_dsmr",
+                                       p1_import_entity="sensor.i"), -5000, 5000),
+          "p1_export_entity"))
+check("a misspelt meter_source is refused rather than silently ignored",
+      why(validate_startup_config(base(meter_source="ha_signd"), -5000, 5000),
+          "is not one of"))
+
+# --------------------------------------------------------------------------- #
+print("4. meter_max_age_s against the firmware's compile-time veto")
+# ⚠️ The schema allows int(5,300); the firmware's threshold is baked in at 30 s
+# and wins silently. Same shape as the max_w case: a configured bound overridden
+# by a lower layer, with nothing saying so.
+hw = dict(meter_source="homewizard_local", p1_host="m")
+p = validate_startup_config(base(**hw, meter_max_age_s=120), -5000, 5000)
+check("a meter_max_age_s above the firmware veto is refused", len(p) == 1)
+check("...naming the configured value", why(p, "120"))
+check("...naming the firmware's value", why(p, "30"))
+check("...and saying which one wins", why(p, "THE FIRMWARE WINS"))
+check("the tested pair 30/30 is accepted",
+      validate_startup_config(base(**hw, meter_max_age_s=30), -5000, 5000) == [])
+check("one second above it is refused",
+      validate_startup_config(base(**hw, meter_max_age_s=31), -5000, 5000) != [])
+# Below the veto the add-on gives up FIRST, which is fail-safe and visible on
+# its own status page. Only above is the silent case.
+check("below the veto is fine - the add-on being stricter is not a conflict",
+      validate_startup_config(base(**hw, meter_max_age_s=10,
+                                   meter_poll_s=4), -5000, 5000) == [])
+# ⚠️ Scope: meter_max_age_s is read by nothing but P1Ingest, and the veto keys
+# off a sensor only published when ingestion runs. With the meter off it governs
+# nothing, so refusing would be pure trivia.
+check("with meter_source off the number governs nothing and is not refused",
+      validate_startup_config(base(meter_source="off", meter_max_age_s=300),
+                              -5000, 5000) == [])
+check("the constant is the firmware's, not a rounded guess",
+      FIRMWARE_INGEST_VETO_S == 30.0)
+
+# --------------------------------------------------------------------------- #
+print("6. a maintenance charge the ceiling can actually accommodate (MAINT-04)")
+# ⚠️ THE SHIPPED BUG. config.yaml shipped max_w 2000 against
+# maintenance_charge_w 2500, so the cheap-window shaping asked for hi=-2500
+# against the supervised lo=-2000 - lo > hi, arbiter clause 3, 0 W. Maintenance
+# silently never charged in a cheap window on a default install.
+p = validate_startup_config(base(max_w=2000, maintenance_charge_w=2500),
+                            -5000, 5000)
+check("maintenance_charge_w above max_w is refused", len(p) == 1)
+check("...and the message names the charge rate", why(p, "2500"))
+check("...and the ceiling", why(p, "2000"))
+check("...and says which one wins", why(p, "THE CEILING WINS"))
+# ⚠️ Equality is REACHABLE, not a near miss: lo=-2000, hi=-2000 is the single
+# point -2000 W. Refusing it would be exactly the trivia that gets a validator
+# deleted, and it is the boundary the rule is written `>` for.
+check("maintenance_charge_w exactly at max_w starts",
+      validate_startup_config(base(max_w=2000, maintenance_charge_w=2000),
+                              -5000, 5000) == [])
+check("below it starts",
+      validate_startup_config(base(max_w=2000, maintenance_charge_w=1500),
+                              -5000, 5000) == [])
+# Not scoped to maintenance_enabled: the pair is contradictory either way, and
+# scoping would leave the trap armed for the one action - ticking the box - that
+# cannot be expected to change what a charge rate means.
+check("...and it is refused with maintenance_enabled off, as shipped",
+      why(validate_startup_config(
+          base(max_w=2000, maintenance_charge_w=2500,
+               maintenance_enabled=False), -5000, 5000), "THE CEILING WINS"))
+
+# ⚠️ THE SIBLING, CHECKED RATHER THAN ASSUMED. The shaping is NOT symmetric:
+# drain files Claim.set at P_MAINTENANCE and owns the actuator, so the ceiling
+# CLAMPS it (+2000 W) instead of contradicting it, and the arbiter's explain()
+# names the clamp every cycle. Loud, and it still moves energy - so warned, not
+# refused. If someone later "fixes the asymmetry" by making this a refusal,
+# this check goes red and they have to justify it.
+check("maintenance_discharge_w above max_w WARNS but starts",
+      validate_startup_config(base(max_w=2000, maintenance_discharge_w=2500),
+                              -5000, 5000) == [])
+
+# The demonstration the rule is derived from, asserted rather than described.
+from app.arbiter import (                   # noqa: E402
+    Claim, P_LOOP, P_MAINTENANCE, P_MAINT_SHAPE, P_SAFETY, resolve,
+)
+
+def _charge(max_w, charge_w):
+    return resolve([Claim.limit("supervised", P_SAFETY, -max_w, max_w, "max_w"),
+                    Claim.limit("maintenance", P_MAINT_SHAPE, hi=-charge_w,
+                                reason="cheap-window charge"),
+                    Claim.set("loop", P_LOOP, 500.0, "grid")])
+
+def _drain(max_w, disch_w):
+    return resolve([Claim.limit("supervised", P_SAFETY, -max_w, max_w, "max_w"),
+                    Claim.set("maintenance", P_MAINTENANCE, disch_w, "drain"),
+                    Claim.set("loop", P_LOOP, 500.0, "grid")])
+
+r = _charge(2000, 2500)
+check("arbiter: the refused pair really does emit 0 W",
+      r.target_w == 0.0 and r.contradiction)
+r = _charge(2000, 2000)
+check("arbiter: the permitted equality really does charge",
+      r.target_w == -2000.0 and not r.contradiction)
+r = _charge(3000, 2500)
+check("arbiter: raising max_w above the rate charges at the rate",
+      r.target_w == -2500.0 and not r.contradiction)
+r = _drain(2000, 2500)
+check("arbiter: the drain SET is clamped, not contradicted",
+      r.target_w == 2000.0 and not r.contradiction)
+check("...and the clamp names itself, which is why it is not refused",
+      "supervised" in (r.bound_by or "") and "limited by" in r.explain())
+
+# --------------------------------------------------------------------------- #
+print("the SHIPPED defaults must pass the rule they are governed by (AC3)")
+# ⚠️ Shipping a default the validator refuses would be worse than the bug it
+# refuses. Read config.yaml itself rather than a transcription of it - a
+# transcription is what lets the two drift apart silently. Regex, not PyYAML:
+# the add-on image has no PyYAML (Dockerfile installs py3-aiohttp/py3-paho-mqtt
+# only) and a check that skips on ImportError is not a check.
+import os                                   # noqa: E402
+import re                                   # noqa: E402
+
+_CFG = os.path.join(os.path.dirname(os.path.abspath(__file__)), "config.yaml")
+with open(_CFG, encoding="utf-8") as _fh:
+    _txt = _fh.read()
+_shipped = {k: float(v) for k, v in re.findall(
+    r"^  (max_w|maintenance_charge_w|maintenance_discharge_w|sign_disagree_w): "
+    r"(-?\d+(?:\.\d+)?)\s*$", _txt, re.M)}
+check("config.yaml really was read (all four defaults found)",
+      set(_shipped) == {"max_w", "maintenance_charge_w",
+                        "maintenance_discharge_w", "sign_disagree_w"})
+check(f"the shipped defaults are accepted {_shipped}",
+      validate_startup_config(base(**_shipped), -5000, 5000) == [])
+check("...and the shipped charge rate is at or under the shipped ceiling",
+      _shipped["maintenance_charge_w"] <= _shipped["max_w"])
+check("...and the shipped discharge rate too, so it warns about nothing",
+      _shipped["maintenance_discharge_w"] <= _shipped["max_w"])
+
+# --------------------------------------------------------------------------- #
+print("the shipped meter_freeze_s, pinned (TEST-06 / AC3)")
+# ⚠️ WHY A NUMBER GETS ITS OWN CHECK. `meter_freeze_s: 300` is the threshold
+# SAFETY-18's entire argument is about, and before this it was pinned NOWHERE:
+# 300 -> 3600 left test_freeze.py AND this file green, because the schema
+# accepts int(60,3600) and no check ever read the shipped value. The schema
+# bounds what is CONFIGURABLE; this pins what is SHIPPED, which is a different
+# question and the one the docs answer.
+#
+# Read by regex like _shipped above, for the same reason: no PyYAML in the
+# image, and a check that skips on ImportError is not a check.
+_freeze_s = [float(v) for v in re.findall(
+    r"^  meter_freeze_s: (\d+(?:\.\d+)?)\s*$", _txt, re.M)]
+_freeze_schema = re.findall(r"^  meter_freeze_s: int\((\d+),(\d+)\)\s*$",
+                            _txt, re.M)
+check(f"config.yaml carries exactly one meter_freeze_s default {_freeze_s}",
+      len(_freeze_s) == 1)
+check("...and exactly one schema range for it", len(_freeze_schema) == 1)
+_hold_s = _freeze_s[0] if _freeze_s else None
+_lo, _hi = ((float(_freeze_schema[0][0]), float(_freeze_schema[0][1]))
+            if _freeze_schema else (None, None))
+check("the shipped meter_freeze_s is still the measured 300 s that freeze.py, "
+      "config.yaml's own comment and test_freeze.py are all written at",
+      _hold_s == 300.0)
+check(f"...and it is inside its own schema range ({_lo}-{_hi} s)",
+      None not in (_lo, _hi, _hold_s) and _lo <= _hold_s <= _hi)
+
+# The two properties the number has to have, DERIVED rather than restated - so
+# they go red on a value that is merely schema-legal. Both come straight from
+# config.yaml's own comment on the key.
+#
+#   upper: the alert must land inside the 900 s quarter that bills the capacity
+#          tariff, or the notification arrives after the money is spent;
+#   lower: the slowest a HEALTHY meter can tick a 1 Wh register and still look
+#          unchanged for hold_s is 3600/hold_s W, and that must stay inside the
+#          deadband or the conjunction's two terms stop being mutually
+#          exclusive (freeze.py, "WHERE hold_s COMES FROM").
+_QUARTER_S = 900.0
+_shipped_deadband = [float(v) for v in re.findall(
+    r"^  deadband_w: (\d+(?:\.\d+)?)\s*$", _txt, re.M)]
+check(f"config.yaml carries exactly one deadband_w default {_shipped_deadband}",
+      len(_shipped_deadband) == 1)
+_db = _shipped_deadband[0] if _shipped_deadband else None
+_slowest_healthy_w = 3600.0 / _hold_s if _hold_s else None
+print(f"    shipped meter_freeze_s {_hold_s} s: alert inside the "
+      f"{_QUARTER_S:.0f} s billing quarter, and a healthy meter slow enough to "
+      f"look unchanged for it is {_slowest_healthy_w} W against a "
+      f"{_db} W deadband")
+check(f"...the alarm still lands inside the {_QUARTER_S:.0f} s billing quarter",
+      _hold_s is not None and _hold_s < _QUARTER_S)
+check("...and a healthy meter that looks unchanged for it is still inside the "
+      "deadband, so the two terms stay mutually exclusive",
+      _slowest_healthy_w is not None and _db is not None
+      and _slowest_healthy_w < _db)
+
+# ⚠️ AND THE RANGE'S OWN BOUNDS. "300 sits inside the range" is worth nothing
+# while the range itself is unpinned: widened to `int(1,86400)` an operator can
+# configure `meter_freeze_s: 86400` and the guard is dead for a day at a time,
+# with every check in this repo still green. That mutation survived the first
+# cut of this PR and is what this block closes. Both numbers are argued for in
+# config.yaml's own comment and in freeze.py, and each is re-derived here:
+#
+#   60 s   the floor freeze.py calls NOT A RECOMMENDATION - there a healthy
+#          meter can look unchanged at 60 W, four times the shipped deadband, so
+#          the conjunction's two terms stop being mutually exclusive and only
+#          the margin is left;
+#   3600 s the ceiling - already four times the billing quarter, so the top of
+#          the range has given up detecting a freeze inside the quarter that
+#          bills it. It is the last bound between a supported configuration and
+#          a disabled guard, and moving it is a decision rather than a tidy-up.
+print(f"    schema range {_lo}-{_hi} s: at the floor a healthy meter that looks "
+      f"unchanged is "
+      + (f"{3600.0 / _lo:.0f} W" if _lo else "?")
+      + f" against a {_db} W deadband; the ceiling is "
+      + (f"{_hi / _QUARTER_S:.1f}x" if _hi else "?")
+      + " the billing quarter")
+check(f"the schema range itself is still the argued 60-3600 s (found "
+      f"{_lo}-{_hi})", (_lo, _hi) == (60.0, 3600.0))
+check("...a floor that gives up the mutual exclusion and keeps only the "
+      "margin, which is why config.yaml calls it not a recommendation",
+      None not in (_lo, _db) and 3600.0 / _lo > _db)
+check("...and a ceiling already past the billing quarter, so no value the "
+      "schema still accepts can alarm inside the quarter that bills it",
+      _hi is not None and _hi > _QUARTER_S)
+
+# --------------------------------------------------------------------------- #
+print("the KNOWN cross-file default divergence, pinned rather than commented")
+# ⚠️ WHAT THIS GUARDS, AND WHY IT ASSERTS THE BUG RATHER THAN THE FIX.
+# config.yaml and validate.py now default maintenance_charge_w to 2000, while
+# main.py's two `opts.get(..., 2500)` fallbacks and MaintConfig's dataclass
+# default still say 2500. So an options dict with the key ABSENT is ACCEPTED by
+# rule 6 at 2000 and then built by main.py at 2500 - which is a contradiction:
+#
+#     validate_startup_config -> []            (accepted)
+#     MaintConfig().charge_w  -> 2500.0
+#     arbiter                 -> 0.0 W, contradiction=True
+#
+# That is the bug rule 6 exists to catch, passing rule 6. It is unreachable on a
+# Supervisor install (every key is always supplied from config.yaml) but fully
+# reachable from sim/inject.py and from tests - which is exactly where anyone
+# debugging maintenance works.
+#
+# The fix is ONE SOURCE OF TRUTH for option defaults. That is a bigger change
+# than this ticket and it lands in main.py, which another ticket is live in - so
+# the divergence is RECORDED here instead of closed. The check therefore passes
+# on the mismatch and FAILS when either side moves, in EITHER direction:
+#
+#   - config.yaml moves           -> FAIL: re-decide what the fallback should be
+#   - main.py is fixed to match   -> FAIL: the divergence is gone, DELETE this
+#                                    check and the ⚠️ block in validate.py
+#
+# A comment cannot do that, and "a comment where a check belonged" is this
+# repo's most repeated defect.
+_APP = os.path.join(os.path.dirname(os.path.abspath(__file__)), "app")
+
+def _read(*parts):
+    with open(os.path.join(*parts), encoding="utf-8") as fh:
+        return fh.read()
+
+# Every literal fallback for this key in main.py, whatever the call shape.
+_main_falls = [float(m) for m in re.findall(
+    r'\.get\(\s*"maintenance_charge_w"\s*,\s*(-?\d+(?:\.\d+)?)\s*\)',
+    _read(_APP, "main.py"))]
+# ...and MaintConfig's own dataclass default, which is the one that bites when
+# main.py is bypassed entirely (a Maintenance built straight from defaults).
+_dc_falls = [float(m) for m in re.findall(
+    r"^\s*charge_w:\s*float\s*=\s*(-?\d+(?:\.\d+)?)\s*$",
+    _read(_APP, "maintenance.py"), re.M)]
+
+check(f"main.py's fallbacks are still found and still 2500 {_main_falls}",
+      len(_main_falls) == 2 and set(_main_falls) == {2500.0})
+check(f"MaintConfig's default is still found and still 2500 {_dc_falls}",
+      len(_dc_falls) == 1 and set(_dc_falls) == {2500.0})
+check(f"...and config.yaml still ships 2000, so the divergence is UNCHANGED "
+      f"(shipped {_shipped['maintenance_charge_w']:.0f}, code 2500)",
+      _shipped["maintenance_charge_w"] == 2000.0)
+
+# ⚠️ And the consequence itself, through the REAL code rather than through the
+# numbers above - so that if someone "fixes" this by changing a literal without
+# understanding it, the thing that goes red is the behaviour, not the transcript.
+from app.maintenance import MaintConfig      # noqa: E402
+
+_absent = {k: v for k, v in base().items() if k != "maintenance_charge_w"}
+_built = MaintConfig().charge_w
+check("with the key ABSENT the validator accepts...",
+      validate_startup_config(_absent, -5000, 5000) == [])
+check(f"...while the code would build {_built:.0f} W against a "
+      f"{_absent['max_w']:.0f} W ceiling...", _built > _absent["max_w"])
+_r = _charge(_absent["max_w"], _built)
+check("...which the arbiter resolves to 0 W as a contradiction - the hole, "
+      "asserted so it cannot widen unnoticed",
+      _r.target_w == 0.0 and _r.contradiction)
+
+# --------------------------------------------------------------------------- #
+print("max_w must be a positive magnitude")
+# Schema-blocked on a real install, but validate_startup_config() is also
+# sim/inject.py's entry point and can be handed any dict at all.
+for bad in (0, -1, -2000):
+    p = validate_startup_config(base(max_w=bad), -5000, 5000)
+    check(f"max_w {bad} is refused", len(p) == 1 and why(p, "must be positive"))
+check("...and the message explains it would read as a trip, not a mistake",
+      why(validate_startup_config(base(max_w=0), -5000, 5000), "contradiction"))
+# ⚠️ SAFETY-02 changed what this case has to say, and the change is real rather
+# than bookkeeping: with a 1 W ceiling the default 300 W sign-disagreement
+# threshold is unreachable, so rule 5 refuses - correctly, because the watchdog
+# would report itself armed while being incapable of firing. What this check is
+# FOR is "a positive max_w is not itself a refusal", so it now names a sign
+# threshold the ceiling can actually reach, and the interaction gets its own
+# check below.
+check("the smallest sane max_w still starts",
+      validate_startup_config(base(max_w=1, sign_disagree_w=0.5,
+                                   maintenance_charge_w=1), -5000, 5000) == [])
+check("...but that same 1 W ceiling with the DEFAULT sign threshold is refused",
+      why(validate_startup_config(base(max_w=1), -5000, 5000), "never fire"))
+
+# --------------------------------------------------------------------------- #
+print("what must NOT be refused - a validator that fires on trivia gets deleted")
+# DOCS.md: the arbiter's `supervised` limit still binds the wire to +-max_w, so
+# the only cost of the extra headroom is unwind latency after saturation.
+check("integrator_max_w above max_w warns but starts",
+      validate_startup_config(base(max_w=2000, integrator_max_w=9000),
+                              -5000, 5000) == [])
+check("integrator_max_w 0 (follow max_w) starts",
+      validate_startup_config(base(integrator_max_w=0), -5000, 5000) == [])
+# Fail-safe AND already a red NOT READY banner naming the entity: a refusal on
+# top of that adds nothing an operator can act on.
+check("a missing soc_entity is left to the readiness banner",
+      validate_startup_config(base(soc_entity=""), -5000, 5000) == [])
+check("a missing batt_entity likewise",
+      validate_startup_config(base(batt_entity=""), -5000, 5000) == [])
+# The transient case. ESPHome is routinely not up when the add-on boots, and
+# refusing here would turn a device that arrives late into a restart loop.
+check("a setpoint entity that is configured but not yet found starts",
+      validate_startup_config(base(), None, None) == [])
+check("meter_poll_s with thin but non-zero headroom starts",
+      validate_startup_config(base(meter_source="homewizard_local", p1_host="m",
+                                   meter_poll_s=20, meter_max_age_s=30),
+                              -5000, 5000) == [])
+
+# --------------------------------------------------------------------------- #
+print("the refusal must be legible as a refusal, not as a crash")
+p = validate_startup_config(base(max_w=8000, setpoint_entity=""), -5000, 5000)
+check("several problems are all reported, not just the first", len(p) >= 1)
+refuse(p)   # prints the banner; the eye is the assertion for its wording
+err = ConfigRefused(p)
+check("ConfigRefused carries every problem", err.problems == p)
+check("...and str() names one of them", str(err) == p[0])
+
+# --------------------------------------------------------------------------- #
+print("the LATE refusal, when the device only shows up after the gate has run")
+# ⚠️ This path had no test at all and no live demonstration - the review's
+# catch. ESPHome is routinely not up when the add-on boots, so hass.limits()
+# returns (None, None), the range checks are skipped, and run_control() is the
+# first place the device's real rating is ever known. Everything below is about
+# what happens when it turns out to conflict.
+from app.main import Controller            # noqa: E402
+
+
+class _LateHass:
+    """Reports the range only run_control() gets to see."""
+
+    def __init__(self, lo, hi):
+        self.lo, self.hi = lo, hi
+        self.writes = []
+
+    async def limits(self, entity):
+        return (self.lo, self.hi, 1.0)
+
+    async def number(self, *a, **k):
+        return 0.0
+
+    async def set_number(self, entity, value):
+        self.writes.append(value)
+        return True
+
+
+class _Store2:
+    data = {}
+
+    def set(self, *a):
+        pass
+
+
+class _Pub2:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+def late(opts_over, lo, hi):
+    """Drive run_control() against a device that only reports (lo, hi) now.
+
+    ⚠️ Returns whether run_control() EXITED ON ITS OWN. That is the assertion
+    that matters: on a refusal it must return without entering the while loop,
+    and on a clean config it must not return at all. So the clean case is stopped
+    from outside after it has had time to write, rather than waited on - a
+    wait_for() here would just time out, which is the correct behaviour dressed
+    up as a failure.
+    """
+    async def go():
+        stop = asyncio.Event()
+        hass = _LateHass(lo, hi)
+        # A device narrower than the shipped 5000 W schema ceiling is exactly
+        # the case that cannot be reached through the Supervisor on the live
+        # install, so it is reached here instead.
+        c = Controller(base(**opts_over), hass, _Store2(), _Pub2(), stop=stop)
+        c.auto = True
+        task = asyncio.create_task(c.run_control())
+        for _ in range(30):                    # up to ~3 s
+            if task.done():
+                break
+            await asyncio.sleep(0.1)
+        exited = task.done()
+        if not exited:
+            c.stopping = True
+        await asyncio.wait_for(task, timeout=5)
+        return c, stop, hass, exited
+    return asyncio.run(go())
+
+c, stop, hass, exited = late({"max_w": 5000}, -3600.0, 3600.0)
+check("a device narrower than max_w, discovered late, is refused",
+      c.refused is not None and len(c.refused) == 1)
+check("...naming both values", why(c.refused, "5000") and why(c.refused, "3600"))
+check("...signalling amain to wind down", stop.is_set())
+check("...and returning instead of looping forever", exited)
+# The whole point: run_control() must not fall through into the while loop. A
+# single write here would mean it commanded the inverter under a config it had
+# just declared unusable.
+check("...having never entered the control loop, so it wrote nothing",
+      hass.writes == [])
+check("...and it is recorded in the event log an operator reads",
+      any("REFUSED" in e for e in c.events))
+
+# The same path when there is no conflict: it must NOT refuse, and it must
+# actually regulate - asserted by a write reaching the device, not by absence.
+c2, stop2, hass2, exited2 = late({"max_w": 2000}, -5000.0, 5000.0)
+check("a late device that agrees does not trip the re-check", c2.refused is None)
+check("...and the control loop runs, writing to the device", hass2.writes != [])
+check("...and does not signal a shutdown", not stop2.is_set() and not exited2)
+
+# ⚠️ THE FOOTGUN THE REVIEW FOUND. `stop` used to default to None, so this
+# construction was legal and the refusal path then returned into a live process
+# with no control loop, no exit and no further output.
+try:
+    Controller(base(), _LateHass(-5000.0, 5000.0), _Store2(), _Pub2())
+    check("a Controller with no stop Event is rejected at construction", False)
+except TypeError:
+    check("a Controller with no stop Event is rejected at construction", True)
+
+# --------------------------------------------------------------------------- #
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + "; ".join(fails))
+    sys.exit(1)
+print("all checks passed")

goodwe_controller/test_watchdog.py

@@ -0,0 +1,505 @@
+"""Runnable check for the sign-disagreement watchdog.  `python3 test_watchdog.py`
+
+Every case here is either a fault this must catch or a piece of NORMAL behaviour
+it must not mistake for one. The second list is the longer one on purpose: an
+alarm that fires on ordinary operation is worse than no alarm, because the next
+person switches it off.
+
+The headline validation is not here - it is `sim/replay_sign.py` in the infra
+repo, which drives this module over the two captured bus days. This file is the
+table-driven half: boundaries, timers, the latch, and the arming gate.
+"""
+
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app.watchdog import (
+    SignWatchdog, SignWatchdogConfig, loop_is_following,
+)
+
+fails = []
+T0 = datetime(2026, 8, 20, 15, 0, 0, tzinfo=timezone.utc)
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def drive(samples, cfg=None, following=True):
+    """Feed (offset_s, commanded_w, grid_w) tuples. Returns (wd, trip_offset)."""
+    wd = SignWatchdog(cfg)
+    trip_at = None
+    for item in samples:
+        offset, cmd, grid = item[0], item[1], item[2]
+        f = item[3] if len(item) > 3 else following
+        if wd.evaluate(cmd, grid, f, T0 + timedelta(seconds=offset)) and trip_at is None:
+            trip_at = offset
+    return wd, trip_at
+
+
+def opposed(duration_s, step=5, cmd=-1000, grid=1500, following=True, start=0):
+    return [(start + t, cmd, grid, following)
+            for t in range(0, int(duration_s) + 1, step)]
+
+
+print("the fault it exists to catch")
+wd, at = drive(opposed(300))
+check("charging into an importing house trips", wd.tripped)
+check("and trips at 180 s, not before", at == 180)
+check("the reason names both signals", "-1000" in wd.reason and "+1500" in wd.reason)
+print(f"       e.g. {wd.reason!r}")
+
+wd, at = drive(opposed(300, cmd=2000, grid=-2000))
+check("discharging into an exporting house trips too", wd.tripped and at == 180)
+
+print()
+print("the boundaries")
+wd, _ = drive(opposed(600, cmd=-300, grid=1500))
+check("300 W exactly does NOT qualify (strictly greater)", not wd.tripped)
+wd, _ = drive(opposed(600, cmd=-301, grid=1500))
+check("301 W does", wd.tripped)
+wd, _ = drive(opposed(600, cmd=-1000, grid=300))
+check("a 300 W meter does not qualify either", not wd.tripped)
+wd, _ = drive(opposed(175))
+check("175 s of disagreement does not trip", not wd.tripped)
+wd, _ = drive(opposed(180))
+check("180 s does (>= hold_s)", wd.tripped)
+
+print()
+print("continuity - the rule that produced zero false positives on real data")
+broken = opposed(175) + [(180, -1000, -1500)] + opposed(175, start=185)
+wd, _ = drive(broken)
+check("179 s, one agreeing sample, then 175 s more: no trip", not wd.tripped)
+check("and the window really was reset", wd.disagree_since is not None)
+long_enough = broken + opposed(200, start=365)
+wd, _ = drive(long_enough)
+check("but a full 180 s after the reset does trip", wd.tripped)
+
+print()
+print("things that are NOT faults")
+# The load-step transient. Measured on the healthy capture: longest 30 s.
+wd, _ = drive(opposed(30) + [(35 + t, 800, 900) for t in range(0, 300, 5)])
+check("a 30 s load-step crossover does not trip", not wd.tripped)
+
+# SoC 10 %, Standby, declining a 1350 W discharge. The battery does nothing, so
+# the meter stays where it was and the command agrees with it.
+wd, _ = drive([(t, 1350, 1350) for t in range(0, 900, 5)])
+check("a battery refusing a discharge command cannot trip it", not wd.tripped)
+
+# A frozen meter drives command and reading into agreement, not disagreement.
+wd, _ = drive([(t, 800, 800) for t in range(0, 900, 5)])
+check("a frozen meter cannot trip it", not wd.tripped)
+
+# Maintenance grid charge: 2500 W of charge against an importing house, for
+# hours. Opposed, both huge - and entirely correct.
+wd, _ = drive(opposed(7200, cmd=-2500, grid=3000, following=False))
+check("two hours of maintenance grid charge does not trip", not wd.tripped)
+check("and the timer never even started", wd.disagree_since is None)
+
+wd, _ = drive([(t, -1000, None) for t in range(0, 900, 5)])
+check("a missing meter reading does not trip", not wd.tripped)
+wd, _ = drive(opposed(175) + [(180, -1000, None)] + opposed(600, start=185))
+check("a missing reading mid-window RESETS it rather than accumulating",
+      wd.tripped and wd.disagree_since is not None)
+wd, at = drive(opposed(175) + [(180, -1000, None)] + opposed(600, start=185))
+check("...so the trip lands 180 s after the gap, not after 180 s total",
+      at == 365)
+
+wd, _ = drive([(t, 0.0, 3000) for t in range(0, 900, 5)])
+check("a 0 W command is not a wrong-direction command", not wd.tripped)
+
+print()
+print("the latch")
+wd, _ = drive(opposed(200))
+check("tripped after the fault", wd.tripped)
+# The trip commands 0 W, which removes the command side of the comparison.
+for t in range(200, 900, 5):
+    wd.evaluate(0.0, 3000, True, T0 + timedelta(seconds=t))
+check("stays tripped once the command is zeroed", wd.tripped)
+for t in range(900, 1500, 5):
+    wd.evaluate(1000, 1000, True, T0 + timedelta(seconds=t))
+check("stays tripped even once everything looks healthy again", wd.tripped)
+wd.reset()
+check("reset() is the only way out", not wd.tripped and wd.disagree_since is None)
+check("and the reason is cleared with it", wd.reason == "")
+
+print()
+print("the thresholds are configuration, not constants")
+cfg = SignWatchdogConfig(min_w=800.0, hold_s=60.0)
+wd, at = drive(opposed(300, cmd=-1000, grid=1500), cfg=cfg)
+check("a 60 s hold trips at 60 s", wd.tripped and at == 60)
+wd, _ = drive(opposed(600, cmd=-700, grid=1500), cfg=cfg)
+check("an 800 W gate ignores a 700 W command", not wd.tripped)
+
+print()
+print("the configuration that would disarm it is refused")
+from app.validate import validate_startup_config  # noqa: E402
+
+base = {"setpoint_entity": "number.sp", "meter_source": "off",
+        "meter_phases": 1, "meter_max_age_s": 30}
+p = validate_startup_config({**base, "max_w": 2000, "sign_disagree_w": 300},
+                            -5000, 5000)
+check("300 W under a 2000 W ceiling is accepted", p == [])
+p = validate_startup_config({**base, "max_w": 2000, "sign_disagree_w": 2000},
+                            -5000, 5000)
+check("a threshold AT max_w is refused", len(p) == 1 and "never fire" in p[0])
+# ⚠️ maintenance_charge_w is named here only to keep this case about the SIGN
+# rule. MAINT-04 added a second rule against the same ceiling, and a 500 W
+# max_w is also below the 2000 W shipped maintenance charge - so without this
+# the dict is refused twice, for two correct but different reasons, and the
+# `len(p) == 1` below would be measuring the interaction rather than this rule.
+p = validate_startup_config({**base, "max_w": 500, "sign_disagree_w": 3000,
+                             "maintenance_charge_w": 500}, -5000, 5000)
+check("a threshold above max_w is refused", len(p) == 1 and "never fire" in p[0])
+p = validate_startup_config({**base, "max_w": 2000, "sign_disagree_w": 1999},
+                            -5000, 5000)
+check("one watt under the ceiling is reachable, so accepted", p == [])
+
+print()
+print("the arming gate, derived from the REAL arbiter")
+# ⚠️ THIS IS THE DECISION THE WHOLE TICKET TURNS ON, and until now it was
+# asserted in three comment blocks and verified by nothing: every other case in
+# this file passes `following` in as a literal. What has to hold is that the
+# expression in main.py - loop won AND the emitted value points the way the loop
+# asked AND is no larger - is never True for a resolution the loop did not
+# actually get. So run real claims through the real resolve() and derive it.
+from app.arbiter import (  # noqa: E402
+    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_PEAK, P_SAFETY, Claim, resolve,
+)
+
+
+def following_from(claims, asked):
+    """THE SHIPPED gate, not a copy of it.
+
+    ⚠️ This used to transcribe main.py's expression with a comment saying
+    "keep the two in step", which is exactly the arrangement that does not keep
+    two things in step. Measured: editing the shipped gate alone to
+    `winner in ("loop", "peak")` left this suite - including the P_PEAK row below,
+    whose entire job is to catch that edit - completely green, while the watchdog
+    went blind for the duration of every peak event. Import it or the P_PEAK
+    assertion is decoration.
+    """
+    r = resolve(claims)
+    return r, loop_is_following(r, asked)
+
+
+MAXW = Claim.limit("supervised", P_SAFETY, -2000, 2000, "max_w")
+DEV = Claim.limit("device", P_SAFETY, -5000, 5000, "rating")
+
+# name, claims, what the loop asked, expected `following`
+TABLE = [
+    ("the loop alone, unopposed",
+     [Claim.set("loop", P_LOOP, 900)], 900, True),
+    ("the loop bound by max_w - reduced, not redirected",
+     [Claim.set("loop", P_LOOP, 4000), MAXW], 4000, True),
+    ("charging, bound by max_w on the other side",
+     [Claim.set("loop", P_LOOP, -4000), MAXW], -4000, True),
+    ("maintenance owns the setpoint outright",
+     [Claim.set("loop", P_LOOP, 900),
+      Claim.set("maintenance", P_MAINTENANCE, -2500, "charge"), MAXW], 900, False),
+    ("maintenance charge-only clamps the loop to 0 W",
+     [Claim.set("loop", P_LOOP, 900),
+      Claim.limit("maintenance", P_MAINT_SHAPE, hi=0.0, reason="charge-only"),
+      MAXW], 900, False),
+    # ⚠️ THE CASE `winner == \"loop\"` ALONE WOULD HAVE GOT WRONG. 1500 W, not
+    # the default 2500 W: at max_w 2000 a -2500 hi against a -2000 lo is an
+    # arbiter contradiction, not a charge - see main.py.
+    ("cheap-window charge REDIRECTS the loop while it still 'wins'",
+     [Claim.set("loop", P_LOOP, 500),
+      Claim.limit("maintenance", P_MAINT_SHAPE, hi=-1500, reason="cheap-window"),
+      MAXW], 500, False),
+    ("...and the contradiction at the shipped defaults is not following either",
+     [Claim.set("loop", P_LOOP, 500),
+      Claim.limit("maintenance", P_MAINT_SHAPE, hi=-2500, reason="cheap-window"),
+      MAXW], 500, False),
+    ("a lo limit RAISES the magnitude without flipping the sign",
+     [Claim.set("loop", P_LOOP, 200),
+      Claim.limit("floor", P_SAFETY, lo=800), MAXW], 200, False),
+    ("a safety stop wins outright",
+     [Claim.set("loop", P_LOOP, 900),
+      Claim.set("safety", P_SAFETY, 0.0, "stopped"), MAXW], 900, False),
+    ("no claims at all - the arbiter's own failsafe",
+     [MAXW, DEV], None, False),
+    ("the loop asked for zero",
+     [Claim.set("loop", P_LOOP, 0.0), MAXW], 0.0, False),
+    # The forward hazard, asserted as it stands TODAY rather than as it should
+    # be. When peak shaving lands, these expectations are what have to change.
+    ("peak shaving at P_PEAK disarms the gate (loop_is_following's forward hazard)",
+     [Claim.set("loop", P_LOOP, 900),
+      Claim.set("peak", P_PEAK, 1800, "shaving"), MAXW], 900, False),
+    # ⚠️ AND THE ROW ABOVE CANNOT DETECT A WIDENED GATE ON ITS OWN, which was
+    # found by trying it: with the shipped gate edited to
+    # `winner in ("loop", "peak")` that case STILL comes out False, because peak
+    # shaving asked for MORE than the loop and the magnitude term rejects it
+    # anyway. The winner term is masked. This row isolates it - a peak claim
+    # smaller than the loop's ask and pointing the same way, so `winner` is the
+    # only term that can decide - and it is what actually turns red if the gate
+    # is widened without anyone revisiting the hazard.
+    ("...and with peak BELOW the loop's ask, only the winner term separates them",
+     [Claim.set("loop", P_LOOP, 1800),
+      Claim.set("peak", P_PEAK, 900, "shaving"), MAXW], 1800, False),
+]
+for name, claims, asked, expect in TABLE:
+    r, got = following_from(claims, asked)
+    check(f"{name} -> following={expect}", got is expect)
+    if got is not expect:
+        print(f"       resolution was {r.explain()!r}")
+
+# And the gate is never True when the loop did not win, whatever else is going on.
+check("no configuration above arms the gate without the loop winning",
+      all(not following_from(c, a)[1]
+          for _, c, a, _ in TABLE if following_from(c, a)[0].winner != "loop"))
+
+print()
+print("end to end: the trip is COMMAND ZERO, not alarm-only")
+# ⚠️ THE FAULT INJECTED HERE IS A NEGATIVE GAIN, and that is not a contrivance -
+# it is the minimal faithful model of what this watchdog is for. The check
+# compares the loop's OUTPUT DIRECTION against the INPUT STATE it was regulating,
+# so what it detects is a loop whose two ends have become decoupled in sign: a
+# gain, a claim or a strategy with its polarity inverted, or an integrator so far
+# wound up that unwinding takes minutes. (Illusmart's was the last one: it
+# reached -14 768 W against a +-5000 W rail while writing once every 20-60 s, and
+# that arithmetic alone is 5-15 minutes of wrong-direction command.)
+#
+# `gain` is float(0.05,1.0) in the schema, so this is not a reachable
+# configuration - it is a stand-in for a code regression, which is the case a
+# unit test can actually hold the line on.
+import asyncio  # noqa: E402
+
+from app.main import Controller  # noqa: E402
+
+
+class _Hass:
+    def __init__(self):
+        self.writes = []
+        self.calls = []
+
+    # ⚠️ ADDED FOR SAFETY-03, AND THE REASON IS WORTH READING. The e2e below
+    # runs a DELIBERATELY INVERTED loop (gain -0.6) into a steady 2000 W import,
+    # which is a loop that winds straight into the rail - so the output-clamp
+    # alarm fires here, and the stub not having `call` is how that was
+    # discovered. This scenario is now a second, independent witness that the
+    # clamp alarm sees a real winding loop; test_clamp.py asserts it explicitly.
+    async def call(self, domain, service, data):
+        self.calls.append((domain, service, data))
+
+    async def limits(self, entity):
+        return (-5000.0, 5000.0, 1.0)
+
+    async def number(self, entity, invert=False):
+        # A house importing 2000 W, steadily, whatever the battery does.
+        return {"sensor.grid": 2000.0, "sensor.soc": 50.0,
+                "sensor.batt": 0.0}.get(entity)
+
+    async def set_number(self, entity, value):
+        self.writes.append(float(value))
+        return True
+
+
+class _S:
+    data = {}
+
+    def set(self, *a):
+        pass
+
+    def get_time(self, *a):
+        return None
+
+
+class _P:
+    enabled = False
+
+    def publish(self, *a, **k):
+        pass
+
+    def close(self):
+        pass
+
+
+async def _e2e():
+    hass = _Hass()
+    opts = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+            "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+            "meter_source": "off", "max_w": 2000, "gain": -0.6,
+            "sign_disagree_w": 300, "sign_disagree_s": 1, "auto_start": True}
+    c = Controller(opts, hass, _S(), _P(), stop=asyncio.Event())
+    c.auto = True
+    c.dev_min, c.dev_max = -5000.0, 5000.0
+    seen_wrong_way = False
+    for _ in range(12):
+        await c.read_inputs()
+        await c.cycle()
+        if c.target < -300 and not c.sign_wd.tripped:
+            seen_wrong_way = True
+        await asyncio.sleep(0.25)
+    return c, hass, seen_wrong_way
+
+
+ctrl, hass, wrong_way = asyncio.run(_e2e())
+check("the broken loop really did command charge into an import first", wrong_way)
+check("the watchdog tripped", ctrl.sign_wd.tripped)
+check("the commanded value is 0 W", ctrl.target == 0.0)
+check("0 W actually reached the device", 0.0 in hass.writes)
+check("and it got there through the failsafe claim, not by accident",
+      "failsafe" in ctrl.reason)
+print(f"       status line: {ctrl.reason!r}")
+check("the status page says so in words",
+      any("SIGN-DISAGREEMENT FAILSAFE" in c["text"] for c in ctrl.checks()))
+check("the banner leads with it",
+      "FAILSAFE" in ctrl.status_payload()["banner"])
+check("it stays at 0 W on later cycles too",
+      hass.writes[-1] == 0.0 and hass.writes.count(0.0) >= 1)
+
+# ⚠️ THIS USED TO BE `check("MQTT reports the failsafe state", ctrl.sign_wd.tripped)`
+# which restates the assertion three lines above and never touches the payload.
+# The `status: "failsafe"` value was shipped untested. Capture what publish()
+# actually hands the broker.
+published = {}
+ctrl.mqtt = type("P", (), {"enabled": True,
+                           "publish": lambda _s, v: published.update(v),
+                           "close": lambda _s: None})()
+ctrl.publish()
+check("MQTT's controller-status sensor reports 'failsafe'",
+      published.get("status") == "failsafe")
+ctrl.sign_wd.reset()
+ctrl.publish()
+check("...and goes back to 'running' once cleared",
+      published.get("status") == "running")
+
+
+print()
+print("the latch survives a restart - it is the only thing between a tripped")
+print("controller and the first thing an operator will try")
+# ⚠️ THE BLOCKER THIS FILE MISSED FIRST TIME ROUND. `auto` is persisted and
+# `tripped` was not, so reconstructing a Controller against the same Store -
+# which is exactly what a container restart does - came back armed, into the
+# fault, with no operator involved: tripped=False, banner NOT READY, and it
+# resumed commanding -1000 then -2000 W before re-tripping 180 s later.
+
+
+class _MemStore:
+    """A Store that keeps its dict across "restarts", like the real file does."""
+
+    def __init__(self):
+        self.data = {"phase": "idle", "sign_tripped": False, "sign_reason": ""}
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def get_time(self, *a):
+        return None
+
+
+async def _restart():
+    shared = _MemStore()
+    hass1 = _Hass()
+    opts = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+            "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+            "meter_source": "off", "max_w": 2000, "gain": -0.6,
+            "sign_disagree_w": 300, "sign_disagree_s": 1, "auto_start": True}
+    a = Controller(opts, hass1, shared, _P(), stop=asyncio.Event())
+    a.auto = True
+    a.dev_min, a.dev_max = -5000.0, 5000.0
+    for _ in range(12):
+        await a.read_inputs()
+        await a.cycle()
+        await asyncio.sleep(0.25)
+
+    # The restart. Same options, same store, brand new Controller and Hass.
+    hass2 = _Hass()
+    b = Controller(opts, hass2, shared, _P(), stop=asyncio.Event())
+    b.auto = True
+    b.dev_min, b.dev_max = -5000.0, 5000.0
+    for _ in range(6):
+        await b.read_inputs()
+        await b.cycle()
+        await asyncio.sleep(0.05)
+    return a, b, shared, hass2
+
+
+pre, post, store, hass2 = asyncio.run(_restart())
+check("it tripped before the restart", pre.sign_wd.tripped)
+check("the trip reached the store", store.data["sign_tripped"] is True)
+check("...with the reason beside it, so the operator is told why",
+      "SIGN_DISAGREEMENT" in store.data["sign_reason"])
+check("the new Controller comes back TRIPPED", post.sign_wd.tripped)
+check("...and says why, restored rather than re-detected",
+      "SIGN_DISAGREEMENT" in post.sign_wd.reason)
+check("...commands 0 W from its very first cycle", post.target == 0.0)
+check("...and never commanded anything else after the restart",
+      hass2.writes != [] and set(hass2.writes) == {0.0})
+check("the banner still leads with the failsafe",
+      "FAILSAFE" in post.status_payload()["banner"])
+# ⚠️ TWO PRESSES, and the first one must NOT clear it. `auto` is True while
+# tripped, so the first press stops control; only the transition back to True
+# clears. That is the documented behaviour and it is worth an assertion, because
+# a one-press clear would be reachable by an operator who never read the banner.
+asyncio.run(post.handle_action("auto_toggle"))          # -> stopped
+check("pressing stop does not clear the failsafe",
+      post.sign_wd.tripped and store.data["sign_tripped"] is True)
+asyncio.run(post.handle_action("auto_toggle"))          # -> started
+check("pressing start DOES clear it, and clears the store with it",
+      not post.sign_wd.tripped and store.data["sign_tripped"] is False
+      and store.data["sign_reason"] == "")
+# One more restart from the cleared store, to prove the clear persisted too.
+fresh = Controller({"setpoint_entity": "number.sp", "meter_source": "off"},
+                   _Hass(), store, _P(), stop=asyncio.Event())
+check("...so the next restart comes back armed and untripped, as it should",
+      not fresh.sign_wd.tripped)
+
+# ⚠️ THE WRITE ORDERING IS AN INVARIANT, SO IT GETS AN ASSERTION. main.py writes
+# `sign_reason` and THEN `sign_tripped`, each one its own `save()`, so that a
+# process that dies between the two leaves a reason nothing reads - harmless -
+# rather than a latch with no explanation for the operator who has to decide
+# whether to clear it. Documented reasoning is not enforcement: swapping those two
+# lines used to pass every check in this file.
+#
+# The death is modelled as the second write raising. In the field it is a power
+# cut or a container kill (Store.save() swallows OSError rather than raising), so
+# what is asserted here is the PROPERTY - what survives on disk - not the
+# mechanism.
+
+
+class _CrashOnFlag(_MemStore):
+    def set(self, k, v):
+        if k == "sign_tripped" and v:
+            raise RuntimeError("power cut, mid-trip")
+        super().set(k, v)
+
+
+async def _crash_mid_write():
+    store = _CrashOnFlag()
+    hass = _Hass()
+    opts = {"setpoint_entity": "number.sp", "meter_entity": "sensor.grid",
+            "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+            "meter_source": "off", "max_w": 2000, "gain": -0.6,
+            "sign_disagree_w": 300, "sign_disagree_s": 1, "auto_start": True}
+    c = Controller(opts, hass, store, _P(), stop=asyncio.Event())
+    c.auto = True
+    c.dev_min, c.dev_max = -5000.0, 5000.0
+    died = False
+    for _ in range(12):
+        try:
+            await c.read_inputs()
+            await c.cycle()
+        except RuntimeError:
+            died = True
+            break
+        await asyncio.sleep(0.25)
+    return store, died
+
+
+crashed_store, died = asyncio.run(_crash_mid_write())
+check("the second write is the one that sets the flag", died)
+check("a crash between the two writes leaves the REASON on disk",
+      "SIGN_DISAGREEMENT" in crashed_store.data.get("sign_reason", ""))
+check("...and never a latch with nothing to explain it",
+      not crashed_store.data.get("sign_tripped"))
+
+print()
+if fails:
+    print(f"{len(fails)} FAILED: {', '.join(fails)}")
+    sys.exit(1)
+print("all checks passed")