TEL-05 review follow-ups: show unchanged_s, name a timeout, keep the poll task alive

Four follow-ups on the reviewed and approved TEL-05 work. Additive; no shipped
behaviour changes except the two failure paths below.

1. unchanged_s had no operator surface. DOCS.md told a reader "the transport
   tracks it as unchanged_s" and there was nowhere to look: main.py built the
   transport, scheduled run(), and never read the object again. The status page
   now shows it on the healthy P1 line. Still NOT thresholded and NOT folded
   into the age - that refusal was reviewed and upheld, because at the converged
   -10 W this controller aims for a 1 Wh register needs ~6 minutes to move, so
   any limit false-trips at the target operating point. The whole argument for
   leaving it to a human requires the human being able to see it.

2. The "equivalent mutant" note on the content_type guard was wrong, and the
   comment is downgraded to say so. web.Response(text=...) defaults to
   text/plain, so the fake meter CAN serve valid JSON under the wrong mimetype.
   Test added; shipped behaviour was already correct.

3. A timed-out poll logged an empty reason: str(asyncio.TimeoutError()) is "",
   so the status page read "last error:" and then nothing, on a hung meter, at
   the moment the battery had just gone to 0 W. Falls back to the class name.
   Note str(err), not `err or ...` - an exception object is always truthy.

4. submit() sat outside the try in poll_once() and run() had no except, so a
   raise would kill the poll task permanently and SILENTLY - safe (the age
   climbs, the controller commands 0 W) but indistinguishable from a dead meter.
   Both wrapped; poll_s is already the retry cadence, so no backoff.

Also a comment at the parse_homewizard range(phases) slice: a 3-phase meter
configured as 1-phase understates the capacity-tariff figure. Filed separately,
not fixed here.

242 checks in test_p1.py (236 before, 6 new). test_control 55, test_arbiter 18,
test_maintenance 21, all untouched and green. Each new check proved non-vacuous:
six mutations, six named reds, no suite aborts, sources restored byte-identical.

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

.gitattributes

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

goodwe_controller/CHANGELOG.md

@@ -1,5 +1,115 @@
 # Changelog
 
+## 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,
+bounded independently of the output clamp instead of inheriting whatever
+headroom the clamp happened to leave. It also freezes while the inverter is
+not tracking, rather than continuing to wind up against a command nothing is
+acting on. `integrator_max_w` (default `0`) governs the bound; `0` means
+"follow `max_w`", which is the existing behaviour.
+
+Behaviour is unchanged at the defaults - a 4,928-case equivalence sweep
+against the previous control law confirms it decides identically at
+`integrator_max_w: 0`.
+
+**TEL-01.** P1 meter ingestion, so a Belgian P1's two unsigned registers
+(consumption, injection) no longer need a hand-written signed template
+sensor: the subtraction moves into the add-on, done once and tested. Two
+transports, chosen with the new `meter_source` option: `ha_dsmr` subscribes
+to the DSMR integration over the HA WebSocket, `mqtt_p1` reads a topic.
+Defaults to `off`, which keeps the existing `meter_entity` path untouched -
+nothing changes for an install that does not opt in.
+
+Enabling it publishes `sensor.p1_sample_age_s`: seconds since the newest
+accepted telegram, recomputed against the clock and republished roughly once
+a second rather than only when a telegram lands. That is deliberate - Home
+Assistant only pushes a state on change, so a meter sitting at a genuinely
+constant reading would otherwise look identical to a dead one. Watching the
+age instead means a frozen meter shows a climbing age, not a flat line. The
+firmware watchdog subscribes to this exact entity id.
+
+Known limits, both already in DOCS.md: on `mqtt_p1`, a bridge stuck
+republishing its last telegram still "arrives", so the age cannot detect
+that particular failure - prefer `ha_dsmr` where both are available. And a
+dead P1 meter takes 45 s to reach 0 W commanded (30 s for `meter_max_age_s`
+to call the reading stale, then 15 s of `stale_input_s` on top), which is
+`meter_max_age_s` and `stale_input_s` stacking, not either one alone.
+
 ## 0.2.1
 
 `target_grid_w` (default -10 W): what the meter should rest at. The deadband

goodwe_controller/DOCS.md

@@ -48,6 +48,219 @@ Use the ESP32's readings rather than the inverter's cloud or dongle sensors:
 those serve cached values, and a stale reading here ends the maintenance charge
 phase having charged nothing.
 
+### P1 meter ingestion
+
+`meter_entity` above expects one signed sensor, which usually means a template
+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; `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
+
+`meter_max_age_s` and `stale_input_s` **stack**. They are two different clocks
+and neither one is the whole answer:
+
+| step | option | default |
+|---|---|---|
+| telegrams stop, P1 sample goes stale, grid power starts reading *missing* | `meter_max_age_s` | 30 s |
+| inputs have been missing long enough for the loop to command 0 W | `stale_input_s` | 15 s |
+| **total, meter death → 0 W commanded by this add-on** | | **45 s** |
+
+So in P1 mode `stale_input_s` is *not* "how long inputs may be missing before
+commanding 0 W" measured from the meter dying — it is measured from the moment
+the P1 sample already went stale. Size the pair together: the ESP32's own
+watchdog commands 0 W after ~30 s of silence from this add-on regardless, and
+that layer is unaffected by either option.
+
+There is **no fallback to an inverter-side power figure**, deliberately. The
+inverter's own AC power tracks its battery almost perfectly and the real meter
+hardly at all, so a controller that failed over to it would be regulating
+against its own output while looking healthy.
+
+The `mqtt_p1` payload is one JSON object per telegram, and the schema is strict —
+a key it does not recognise is a telegram from something other than what was
+tested, and guessing a key here means guessing a kilowatt:
+
+```json
+{"import_w": 1234.0,
+ "export_w": 0.0,
+ "phases": [{"import_w": 500, "export_w": 0},
+            {"import_w": 400, "export_w": 0},
+            {"import_w": 334, "export_w": 0}],
+ "timestamp": "2026-08-24T18:00:05+02:00"}
+```
+
+`phases` and `timestamp` are optional; `timestamp` must carry a UTC offset. Where
+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
+newest accepted telegram**, refreshed every second rather than only when a
+telegram lands. The ESP32's stale-input watchdog subscribes to this exact entity
+id, so do not rename it.
+
+The reason it is recomputed against the clock is that Home Assistant only pushes
+a state when the state *changes*. A meter sitting at a genuinely constant reading
+emits nothing, which is indistinguishable — to anything watching the value — from
+a meter that has died. Watching the age instead separates the two: it climbs when
+telegrams stop and resets when they arrive, whatever the reading says.
+
+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`.** 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
 
 | option | default | meaning |
@@ -59,11 +272,35 @@ phase having charged nothing.
 | `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. **Do not set to 1** |
+| `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** |
+| `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 |
-| `stale_input_s` | 15 | How long inputs may be missing before commanding 0 W |
+| `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) |
 
+#### Saturation is counted in cycles, not seconds
+
+The specification states the saturation window as **"> 10 s"**. This add-on counts
+**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.
+
+Two reasons that is acceptable:
+
+- 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.
+
+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".
+
 #### Why `target_grid_w` is not zero
 
 The deadband is a one-way ratchet: any resting point inside it holds until

goodwe_controller/app/control.py

@@ -28,6 +28,22 @@ class Tuning:
     step_w: int = 10
     saturation_w: float = 500.0
     saturation_cycles: int = 3
+    # The integrator's own bound. None means "follow max_w", which is the
+    # default and the recommended setting.
+    #
+    # ⚠️ DO NOT RAISE THIS ABOVE max_w without a measurement to justify it.
+    # Every watt of integrator above the rail is a watt of wind that has to be
+    # burned off before the command can start moving the other way, i.e. extra
+    # cycles of discharge into an already-exporting meter after every
+    # saturation event. Measured on the closed-loop sim, 4000 W load dropped to
+    # 0: at integrator_max_w == max_w the command is 1000 W two cycles later; at
+    # 1.5x max_w it is 1800 W. The output clamp already bounds what reaches the
+    # wire, so headroom here buys nothing but unwind latency.
+    #
+    # It is a separate key because it has to be able to be SMALLER than max_w,
+    # which is the only direction that buys anything: it caps unwind latency
+    # below what the rail implies. Merging it into max_w would take that away.
+    integrator_max_w: float | None = None
     # What the meter should rest at, in W. Negative = a slight export.
     # ⚠️ The deadband is a one-way ratchet: any resting point inside it holds
     # forever, and the meter's IMPORT register counts every positive one with
@@ -44,6 +60,10 @@ class Decision:
     sat_count: int
     frozen: bool
     reason: str
+    # The integrator AFTER this cycle, before the output clamp, the slew limit
+    # 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
 
 
 def compute(
@@ -52,12 +72,14 @@ def compute(
     actual_w: float,
     tuning: Tuning,
     sat_count: int = 0,
+    i_w: float | None = None,
 ) -> Decision:
     """One control cycle. A cycle is one meter update (~5 s on a HomeWizard P1).
 
     `prev_w`   what we last commanded
     `grid_w`   net grid power, + = importing
     `actual_w` what the inverter reports it is doing, + = discharging
+    `i_w`      the carried integrator, or None to seed it from `prev_w`
     """
     reason = "tracking"
 
@@ -71,6 +93,21 @@ def compute(
     # on EVERY large correction, because the plant itself needs 3-6 s to settle
     # while a cycle is ~5 s. Requiring N consecutive saturated cycles is what
     # 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.
+    #
+    # 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.
     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
@@ -83,11 +120,82 @@ def compute(
     # 70 s" is how a healthy loop is recognised at a glance, and a command
     # frozen where it should not be is how two real bugs were caught.
     error = grid_w - tuning.target_grid_w
+
+    # --- the integrator ----------------------------------------------------
+    # This loop is in velocity form: the accumulator IS the commanded power, so
+    # "the integrator" and "the output" were one variable and could not be
+    # bounded apart. `i_w` is that accumulator made explicit; main.py carries it
+    # between cycles, which is what turns the two clamps into two limits.
+    #
+    # Passing i_w=None re-seeds it from the last command every cycle. With
+    # integrator_max_w following max_w that reduces this function to the exact
+    # velocity form it replaced, frozen branch included - asserted by an
+    # exhaustive comparison against a transcription of the old law in
+    # test_control.py, not by inspection. Break either the gate or the bound
+    # below and that test is what tells you the equivalence went with it.
+    if i_w is None:
+        i_w = float(prev_w)
+    limit = tuning.max_w if tuning.integrator_max_w is None else tuning.integrator_max_w
+
     if abs(error) < tuning.deadband_w:
-        want = prev_w
         reason = "deadband"
     else:
-        want = prev_w + tuning.gain * error
+        moved = i_w + tuning.gain * error
+        # ⚠️ Freeze means "may not wind FURTHER in the direction it is already
+        # pushing". It may fall, cross zero, or reverse outright.
+        #
+        # It must NOT be encoded as "only corrections that shrink |i_w|": that
+        # is unsatisfiable for BOTH signs of error whenever the correction is
+        # larger than twice the integrator, i.e. every time the integrator is
+        # near zero. The loop then sits at its last value forever, because what
+        # clears the freeze is the inverter tracking again and not-tracking is
+        # the definition of saturation. Measured on that encoding: 0 W held
+        # indefinitely into a 2 kW import, where this form recovers next cycle.
+        #
+        # This is the same asymmetric rule the output freeze uses below, which
+        # has been in service on real hardware. It is applied here as well
+        # because the requirement is that the INTEGRATOR stop accumulating, not
+        # only the command.
+        #
+        # ⚠️ EXACTLY ZERO IS ITS OWN CASE, and it must be handled explicitly
+        # rather than falling into one of the two branches. "May not wind
+        # further in the direction it is already pushing" has no referent at
+        # zero: nothing is wound, and neither direction is "further". Writing
+        # this as `if i_w > 0 ... else ...` silently files zero under
+        # rising-only and permanently blocks the first push toward charging -
+        # the same deadlock as the shrink-only encoding above, mirrored in sign,
+        # and reachable because main.py resets i_w to exactly 0.0 on every stop
+        # and every reseed. Measured before the fix: 12 800 of 25 920 frozen
+        # ticks at i_w == 0.0 held the integrator, 8 304 of them changing the
+        # emitted command, worst case abandoning a 2 kW charge into a 4 kW
+        # export.
+        #
+        # Freezing at zero would also be pointless: the freeze exists to stop
+        # accumulation running away, and a first step from zero is bounded by
+        # the gain, the output clamp and the slew limit like any other.
+        if not frozen or i_w == 0.0:
+            i_w = moved
+        elif i_w > 0:
+            i_w = min(moved, i_w)
+        else:
+            i_w = max(moved, i_w)
+
+    # ⚠️ Applied EVERY cycle, frozen or not: the freeze is conditional, this
+    # bound is not. It is what makes the worst-case unwind time finite and
+    # knowable instead of a function of how long the error happened to stand.
+    bounded = max(-limit, min(limit, i_w))
+    if bounded != i_w:
+        # ⚠️ 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
+        # then never exceed max_w, so "clamped" is unreachable on a default
+        # install - it survives only for a configuration that deliberately lets
+        # the integrator run above the rail. Two reasons rather than one
+        # because the two events want different alarms: "i-clamped" is the loop
+        # winding, "clamped" is a command that came out over the rating anyway.
+        reason = "i-clamped"
+    i_w = bounded
+    want = i_w
 
     # ⚠️ Maintenance shaping (charge-only, cheap-window floor) used to live
     # here. It now belongs to arbiter.py as limit claims, so that precedence
@@ -123,7 +231,7 @@ def compute(
     step = max(1, int(tuning.step_w))
     target = round(target / step) * step
 
-    return Decision(float(target), sat_count, frozen, reason)
+    return Decision(float(target), sat_count, frozen, reason, float(i_w))
 
 
 def maintenance_charge_floor(

goodwe_controller/app/main.py

@@ -39,6 +39,7 @@ from .control import Tuning, compute, maintenance_charge_floor, peak_at_risk
 from .hass import HomeAssistant
 from .maintenance import IDLE, MaintConfig, Maintenance
 from .mqtt import MqttPublisher
+from .p1 import P1Ingest, build_source, is_enabled
 from . import web
 
 OPTIONS_PATH = "/data/options.json"
@@ -70,6 +71,11 @@ class Controller:
             step_w=int(opts.get("step_w", 10)),
             saturation_w=float(opts.get("saturation_w", 500)),
             saturation_cycles=int(opts.get("saturation_cycles", 3)),
+            # 0 / unset means "follow max_w", which is the recommended
+            # value. Read the note in control.py before raising it above
+            # max_w: every watt above the rail is unwind latency.
+            integrator_max_w=(float(opts["integrator_max_w"])
+                              if opts.get("integrator_max_w") else None),
         )
         self.maint = Maintenance(
             MaintConfig(
@@ -85,10 +91,23 @@ class Controller:
             store,
         )
 
+        # P1 ingestion (TEL-01). `meter_source: off` keeps the original
+        # single-entity meter_entity path, so an existing install is unchanged
+        # until it opts in.
+        self.p1 = P1Ingest(phases=int(opts.get("meter_phases", 1)),
+                           max_age_s=float(opts.get("meter_max_age_s", 30)))
+        self.p1_enabled = is_enabled(opts)
+        # Set by amain() once the transport is built, so the status page can show
+        # what only the transport knows (homewizard_local's unchanged_s). Stays
+        # None when P1 is off, or under a transport that has no such counter.
+        self.p1_source = None
+
         # live state
         self.auto = bool(store.data.get("auto", opts.get("auto_start", False)))
         self.target = 0.0
         self.sat_count = 0
+        self.i_w = 0.0        # the loop's integrator, carried between cycles
+        self.loop_w = None    # what the loop asked for last cycle, or None
         self.reason = "starting"
         self.grid = self.soc = self.batt = None
         self.peak_fc = None
@@ -114,8 +133,18 @@ class Controller:
     # -- io ------------------------------------------------------------------
     async def read_inputs(self) -> None:
         o = self.o
-        self.grid = await self.hass.number(o.get("meter_entity", ""),
-                                           bool(o.get("meter_invert")))
+        if self.p1_enabled:
+            # ⚠️ P1 is the only authoritative measurement of what the utility
+            # sees (§5.1). When it is stale this is None, which falls into the
+            # existing "inputs missing -> command 0 W" path below. There is
+            # deliberately NO fallback to an inverter-side figure: the
+            # inverter's own AC power correlates 0.998 with battery power and
+            # 0.09 with the real meter, so a controller that failed over to it
+            # would be regulating against its own output.
+            self.grid = self.p1.net_w
+        else:
+            self.grid = await self.hass.number(o.get("meter_entity", ""),
+                                               bool(o.get("meter_invert")))
         self.soc = await self.hass.number(o.get("soc_entity", ""))
         self.batt = await self.hass.number(o.get("batt_entity", ""),
                                            bool(o.get("batt_invert")))
@@ -231,17 +260,36 @@ class Controller:
             # wish. If something outranked the loop, that is what the hardware
             # actually did, and the controller must track reality or it jumps
             # the moment it regains control.
+            #
+            # ⚠️ The integrator has to track the same reality, and it is no
+            # longer prev_w, so it needs saying out loud: if the arbiter did not
+            # give the loop what it asked for last cycle, the loop's
+            # accumulated error belongs to a command that never happened.
+            # Re-seed from what the hardware was actually told. This is the
+            # failsafe case too - every layer-1 stop resolves to 0 W, so
+            # entering failsafe re-seeds the integrator to zero and the first
+            # cycle after release starts from zero instead of dumping the whole
+            # stale period as power.
+            if self.loop_w is None or self.target != self.loop_w:
+                self.i_w = self.target
             decision = compute(
                 prev_w=self.target,
                 grid_w=self.grid,
                 actual_w=self.batt,
                 tuning=self.tuning,
                 sat_count=self.sat_count,
+                i_w=self.i_w,
             )
             if decision.frozen and self.sat_count < self.tuning.saturation_cycles:
                 self.log_event(f"saturation freeze ({self.target:.0f} W vs {self.batt:.0f} W)")
             self.sat_count = decision.sat_count
+            self.i_w = decision.i_w
+            self.loop_w = decision.target_w
             claims.append(Claim.set("loop", P_LOOP, decision.target_w, decision.reason))
+        else:
+            # Stopped or blind: no accumulation may survive the outage.
+            self.i_w = 0.0
+            self.loop_w = None
 
         resolution = resolve(claims)
         if resolution.contradiction:
@@ -280,14 +328,26 @@ class Controller:
             await asyncio.sleep(1)
 
     def publish(self) -> None:
-        self.mqtt.publish({
+        values = {
             "setpoint": self.target,
             "grid": self.grid,
             "battery": self.batt,
             "soc": self.soc,
             "phase": self.maint.phase,
             "status": "running" if self.auto else "stopped",
-        })
+        }
+        # ⚠️ ONLY when P1 ingestion is actually running. The ESP32's stale-input
+        # watchdog subscribes to sensor.p1_sample_age_s and forces the layer-1
+        # failsafe once it reaches max_age_s. With meter_source off there is no
+        # ingester feeding it, so published_age_s would be time-since-startup
+        # climbing without bound - i.e. every existing install would cross the
+        # threshold within 30 s and pin its inverter at 0 W forever. Publishing
+        # nothing leaves the entity non-existent, which is the status quo and
+        # what has_state() in the firmware is checking for.
+        if self.p1_enabled:
+            # Recomputed here, once a second, on purpose - see P1Ingest.
+            values["p1_age"] = round(self.p1.published_age_s, 1)
+        self.mqtt.publish(values)
 
     async def shutdown(self) -> None:
         """Deterministic wind-down. Do not skip this."""
@@ -300,11 +360,39 @@ class Controller:
     def checks(self) -> list:
         o = self.o
         out = []
-        for label, value, entity in (
-            ("grid power", self.grid, o.get("meter_entity")),
-            ("battery SoC", self.soc, o.get("soc_entity")),
-            ("battery power", self.batt, o.get("batt_entity")),
-        ):
+        if self.p1_enabled:
+            age = self.p1.published_age_s
+            if self.p1.stale:
+                out.append({"ok": False, "warn": False,
+                            "text": f"P1 meter ({o.get('meter_source')}): no reading for "
+                                    f"{age:.0f} s (limit {self.p1.max_age_s:.0f} s)"
+                                    + (f" - last error: {self.p1.last_error}"
+                                       if self.p1.last_error else "")})
+            else:
+                # ⚠️ unchanged_s is REPORTED, never thresholded and never folded
+                # into the age - see HomeWizardLocalSource.unchanged_s for why
+                # (at the converged -10 W this controller aims for, a 1 Wh
+                # register needs ~6 minutes to move, so any limit false-trips at
+                # the exact operating point we target). The whole argument for
+                # leaving it unthresholded is that a human interprets it, which
+                # requires a human being able to see it - so here it is. getattr:
+                # only homewizard_local has one, and p1_source is None until
+                # amain() builds the transport.
+                unchanged = getattr(self.p1_source, "unchanged_s", None)
+                out.append({"ok": True, "warn": False,
+                            "text": f"P1 meter ({o.get('meter_source')}): {self.p1.net_w:g} W, "
+                                    f"{age:.0f} s old, {self.p1.samples} telegrams, "
+                                    f"{self.p1.parse_errors} rejected"
+                                    + (f", measurement unchanged for {unchanged:.0f} s"
+                                       if unchanged is not None else "")})
+        rows = [("battery SoC", self.soc, o.get("soc_entity")),
+                ("battery power", self.batt, o.get("batt_entity"))]
+        if not self.p1_enabled:
+            # In P1 mode the check above replaces this one; leaving both in
+            # would report "no entity configured" for a meter_entity that is
+            # correctly unused, i.e. a permanent false NOT READY.
+            rows.insert(0, ("grid power", self.grid, o.get("meter_entity")))
+        for label, value, entity in rows:
             if not entity:
                 out.append({"ok": False, "warn": False, "text": f"{label}: no entity configured"})
             elif value is None:
@@ -431,6 +519,7 @@ async def amain() -> None:
         # observability, and the battery does not care. Caught broadly and on
         # purpose: this crashed the add-on once already (paho 1.x vs 2.x) and
         # took the control loop down with it.
+        broker = None
         try:
             broker = await hass.mqtt_service()
             pub = MqttPublisher(
@@ -438,6 +527,7 @@ async def amain() -> None:
                 broker.get("port", 1883) if broker else 1883,
                 broker.get("username") if broker else None,
                 broker.get("password") if broker else None,
+                omit=() if is_enabled(opts) else ("p1_age",),
             )
         except Exception as err:  # noqa: BLE001
             _LOG.warning("MQTT unavailable (%s) - continuing without status entities", err)
@@ -458,13 +548,25 @@ async def amain() -> None:
             with contextlib.suppress(NotImplementedError):
                 loop.add_signal_handler(sig, stop.set)
 
-        task = asyncio.create_task(controller.run_control())
+        tasks = [asyncio.create_task(controller.run_control())]
+
+        # P1 ingestion runs as its own long-lived task. ⚠️ It must not be driven
+        # off the control loop: telegrams arrive every ~5 s and the loop would
+        # decimate them, so the 15-minute average - the capacity-tariff billing
+        # unit - would be computed from a fraction of the data.
+        p1_source = build_source(opts, controller.p1, session, broker)
+        if p1_source is not None:
+            controller.p1_source = p1_source     # so checks() can report on it
+            tasks.append(asyncio.create_task(p1_source.run()))
+
         await stop.wait()
 
         await controller.shutdown()
-        task.cancel()
-        with contextlib.suppress(asyncio.CancelledError):
-            await task
+        for task in tasks:
+            task.cancel()
+        for task in tasks:
+            with contextlib.suppress(asyncio.CancelledError):
+                await task
         await runner.cleanup()
         _LOG.info("stopped")
 

goodwe_controller/app/mqtt.py

@@ -45,6 +45,14 @@ 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.
+    ("p1_age", "p1_sample_age_s", "P1 sample age", "s", "duration", "measurement", None),
 ]
 
 BASE = "goodwe_ctl"
@@ -52,7 +60,12 @@ AVAILABILITY = f"{BASE}/availability"
 
 
 class MqttPublisher:
-    def __init__(self, host, port, username=None, password=None):
+    def __init__(self, host, port, username=None, password=None, omit=()):
+        # `omit` drops sensor keys from discovery entirely. ⚠️ Announcing a
+        # sensor that nothing will ever publish to is not harmless here:
+        # p1_sample_age_s is a watchdog input, and an entity that exists but is
+        # never fed is a worse signal than one that does not exist at all.
+        self.omit = set(omit)
         self.enabled = mqtt is not None and bool(host)
         self.client = None
         if not self.enabled:
@@ -86,6 +99,8 @@ class MqttPublisher:
 
     def _announce(self) -> None:
         for key, object_id, name, unit, dev_class, state_class, icon in SENSORS:
+            if key in self.omit:
+                continue
             cfg = {
                 "name": name,
                 "object_id": object_id,

goodwe_controller/config.yaml

@@ -1,5 +1,5 @@
 name: GoodWe RS485 Controller
-version: "0.2.1"
+version: "0.3.0"
 slug: goodwe_controller
 description: >-
   Drives a GoodWe ES/BP battery inverter over RS485 by emulating its smart
@@ -39,6 +39,45 @@ options:
   batt_invert: false
   setpoint_entity: ""
 
+  # --- 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;
+  # 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: ""
+  p1_export_entity: ""
+  # Optional, in L1..L3 order. Required for the capacity-tariff peak on a
+  # 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
   gain: 0.6
@@ -48,6 +87,7 @@ options:
   step_w: 10
   saturation_w: 500
   saturation_cycles: 3
+  integrator_max_w: 0
   heartbeat_s: 10
   stale_input_s: 15
   auto_start: false
@@ -80,6 +120,26 @@ schema:
   batt_invert: bool
   setpoint_entity: str
 
+  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)
   slew_w: int(50,5000)
@@ -88,6 +148,7 @@ schema:
   step_w: int(1,100)
   saturation_w: int(100,2000)
   saturation_cycles: int(1,10)
+  integrator_max_w: int(0,15000)
   heartbeat_s: int(2,25)
   stale_input_s: int(5,120)
   auto_start: bool

goodwe_controller/test_control.py

@@ -24,6 +24,63 @@ def check(name, cond):
         fails.append(name)
 
 
+# ---------------------------------------------------------------------------
+# COVERAGE AUDIT - measured, not executed. Read this before adding a mechanism.
+#
+# THE INVARIANT: every mechanism in compute() must be noticed by AT LEAST TWO
+# checks when it is deleted. If you add a mechanism to compute(), re-run the
+# audit and add it to the table. If a figure here drops, a check has started
+# passing for a reason other than the one it names.
+#
+# THE TECHNIQUE, because there is no script to run: replace one mechanism in
+# control.py with a no-op, run this file, count the failures, restore. That is
+# the converse of the usual mutation - not "does a wrong value fail?" but "does
+# anyone notice when the mechanism is GONE?". It is kept as a comment rather
+# than as tooling on purpose: the only cheap way to automate it is to key on
+# source lines, which goes stale silently, and a green audit that has quietly
+# stopped testing anything is precisely the failure this ticket exists to fix.
+# A comment cannot go stale-green, because it never claims to be running.
+#
+# Measured at 389d9ec. Numbers are the lead's independent reproduction.
+#
+#   mechanism in compute()                     checks that fail when deleted
+#   ------------------------------------------ -----------------------------
+#   integrator freeze (AC 3)                                               2
+#   integrator clamp (AC 1)                                                6
+#   integrator bound follows max_w                                         4
+#   output clamp                                                           3
+#   slew limit                                                             4
+#   output freeze                                                          2
+#   deadband                                                               5
+#   quantisation                                                           2
+#   saturation detector, `saturated_now = False`                          11
+#   saturation duration (AC 2), fires instantly                            2
+#   sat counter reset on a good cycle                                      6
+#   target_grid_w bias                                                     3
+#   i_w=None seeding from prev_w                                           6
+#
+# The detector figure is for the `saturated_now = False` form specifically;
+# disabling it further down as `frozen = False` is a weaker mutation and gives
+# 10. Reproduce the same form or the number will not match.
+#
+# ⚠️ IT HAS FOUND A DEAD MECHANISM TWICE, BOTH THE SAME WAY: a clamp standing in
+# for the mechanism under test. Deleting the integrator freeze once failed
+# NOTHING, because the fixtures sat at max_w 2000 and the integrator bound
+# truncated a wound value back to exactly 2000 - the assertion passed on the
+# clamp. The output clamp was masked the same way by the integrator bound.
+# Hence: A FIXTURE MUST SIT CLEAR OF EVERY RAIL IT IS NOT TESTING. Where a test
+# names one mechanism, make that mechanism the binding one (see TCLAMP and TF).
+#
+# ⚠️ RUN MUTATIONS WITH `python -B` AND CLEAR app/__pycache__. CPython
+# invalidates a .pyc on (source mtime in whole seconds, source size), so a
+# same-second rewrite that also preserves the file size reuses stale bytecode
+# and the suite reports on code you are no longer running. It under-reported one
+# mutation here as 2 where the true figure is 6. The error is one-directional -
+# stale bytecode can only under-report - so every figure above is a lower bound
+# at worst, and the two zeros ever recorded were both confirmed by fixing them
+# and watching the count rise, which a caching artefact cannot do.
+# ---------------------------------------------------------------------------
+
 print("control law")
 
 # Deadband: inside meter noise, hold exactly - do not drift.
@@ -41,13 +98,22 @@ check("proportional step (gain 0.6)", d.target_w == 300)
 d = compute(prev_w=0, grid_w=-500, actual_w=0, tuning=T)
 check("export drives charging", d.target_w == -300)
 
-# Clamp
-d = compute(prev_w=1900, grid_w=1000, actual_w=1900, tuning=Tuning(max_w=2000, slew_w=5000))
+# Clamp.
+# ⚠️ integrator_max_w is lifted clear of max_w so that the OUTPUT clamp is the
+# mechanism under test. Left at the default the integrator bound truncates
+# first, these two assertions pass on that alone, and deleting the output clamp
+# fails nothing - the same masking that hid the integrator freeze.
+TCLAMP = Tuning(max_w=2000, slew_w=5000, integrator_max_w=5000)
+d = compute(prev_w=1900, grid_w=1000, actual_w=1900, tuning=TCLAMP)
 check("clamped to max_w", d.target_w == 2000)
 
 # Slew: from 0 with a huge error, no more than slew_w in one cycle.
 d = compute(prev_w=0, grid_w=5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
 check("slew limits one cycle", d.target_w == 1000)
+d = compute(prev_w=-1900, grid_w=-1000, actual_w=-1900, tuning=TCLAMP)
+check("clamped to -max_w", d.target_w == -2000)
+d = compute(prev_w=0, grid_w=-5000, actual_w=0, tuning=Tuning(max_w=5000, slew_w=1000))
+check("slew limits one cycle, charging", d.target_w == -1000)
 
 # Saturation needs DURATION: one diverging cycle must NOT freeze.
 t = Tuning(saturation_w=500, saturation_cycles=3)
@@ -73,6 +139,251 @@ check("freeze still allows magnitude to fall", d.target_w < 2000)
 d = compute(prev_w=0, grid_w=7, actual_w=0, tuning=Tuning(deadband_w=1, step_w=10))
 check("quantised to step_w", d.target_w % 10 == 0)
 
+print("SAFETY-04: the integrator is bounded apart from the output")
+
+# The historical runaway, with its real numbers. A commercial controller on
+# this site, with the inverter switched OFF, wound ~130 W every 4 s past 10 kW
+# and reported 14 768 W while its output clamp sat at 5 kW. At gain 0.6 that
+# rate is a standing error of 130/0.6 = 217 W that never resolves, because the
+# inverter is not there to resolve it. 150 cycles is past the ~113 it took to
+# reach 14 768 W at that rate.
+RUNAWAY_ERROR = 130.0 / 0.6
+RUNAWAY_CYCLES = 150
+HISTORICAL_W = 14768.0
+
+
+def runaway(tuning, sign=1):
+    """Inverter off: it reports 0 W forever, the error never clears."""
+    prev, i_w, sat = 0.0, 0.0, 0
+    worst_i, worst_cmd = 0.0, 0.0
+    for _ in range(RUNAWAY_CYCLES):
+        d = compute(prev_w=prev, grid_w=sign * RUNAWAY_ERROR, actual_w=0.0,
+                    tuning=tuning, sat_count=sat, i_w=i_w)
+        prev, i_w, sat = d.target_w, d.i_w, d.sat_count
+        worst_i = max(worst_i, abs(i_w))
+        worst_cmd = max(worst_cmd, abs(prev))
+    return worst_i, worst_cmd
+
+
+TR = Tuning(max_w=2000)          # integrator_max_w unset => follows max_w
+wi, wc = runaway(TR)
+check(f"runaway: integrator plateaus at {wi:.0f} W (<= 2000)", wi <= TR.max_w)
+check(f"runaway: emitted command peaks at {wc:.0f} W (<= 2000)", wc <= TR.max_w)
+check("runaway: nowhere near the historical 14 768 W", wc < HISTORICAL_W / 4)
+
+# ...and with the saturation detector deliberately defeated, so that only the
+# clamp is holding. Kill one mechanism, the other still bounds it.
+TD = Tuning(max_w=2000, saturation_w=1e9)
+wi, wc = runaway(TD)
+check(f"runaway with the detector defeated: integrator still bounded ({wi:.0f} W)",
+      wi <= TD.max_w)
+check("runaway with the detector defeated: command still <= max_w", wc <= TD.max_w)
+
+# The mirror: the same runaway driving the other way. An export that never
+# clears winds the integrator negative just as hard.
+wi, wc = runaway(Tuning(max_w=2000), sign=-1)
+check(f"runaway (export direction): integrator bounded at {wi:.0f} W", wi <= 2000)
+check("runaway (export direction): emitted command <= max_w", wc <= 2000)
+
+# The bound is a separate quantity, and the useful direction is BELOW max_w:
+# there it binds first and caps unwind latency tighter than the rail does.
+d = compute(prev_w=0, grid_w=6000, actual_w=0,
+            tuning=Tuning(max_w=2000, integrator_max_w=1000, slew_w=5000))
+check("integrator bound binds independently of the output clamp",
+      d.i_w == 1000 and d.target_w == 1000)
+
+# Freeze = may not wind further in the direction it is already pushing.
+# ⚠️ max_w is raised WELL above the fixtures on purpose. At the default 2000
+# the integrator bound truncates a wound value back to exactly 2000 and
+# satisfies these assertions on its own, so deleting the freeze outright
+# failed nothing - the clamp was standing in for the mechanism under test.
+# Any fixture here must sit clear of every rail, or it tests the rail.
+TF = Tuning(saturation_w=500, saturation_cycles=3, max_w=5000)
+f1 = compute(prev_w=2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
+check("frozen: integration does not wind further", f1.i_w == 2000.0 and f1.frozen)
+f2 = compute(prev_w=2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=2000.0)
+check("frozen: unwinding is still allowed", f2.i_w < 2000.0)
+# ...and the same two on the charging side. Every freeze rule in this file has
+# a mirror, because the one that did not is the defect that got through review.
+f3 = compute(prev_w=-2000, grid_w=-800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
+check("frozen (charging): integration does not wind further", f3.i_w == -2000.0)
+f4 = compute(prev_w=-2000, grid_w=800, actual_w=0, tuning=TF, sat_count=3, i_w=-2000.0)
+check("frozen (charging): unwinding is still allowed", f4.i_w > -2000.0)
+
+# ⚠️ REGRESSION, and the reason the first cut of SAFETY-04 was rejected. A
+# freeze encoded as "only corrections that shrink |i_w|" is unsatisfiable for
+# BOTH signs of error whenever |correction| > 2*|i_w|, so near zero the loop
+# stops moving forever - the freeze cannot clear, because clearing it needs the
+# inverter to track and not-tracking is what saturation means. Measured on that
+# encoding: 0 W held into a 2 kW import for as long as the sim ran.
+z = compute(prev_w=0, grid_w=2000, actual_w=600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0: a 2 kW import still moves the command",
+      z.frozen and z.target_w == 1000)
+# ...and the next cycle the inverter is inside saturation_w of the command, so
+# the freeze clears on its own. Deadlock would show up here as frozen=True.
+z2 = compute(prev_w=1000, grid_w=1000, actual_w=600, tuning=T,
+             sat_count=z.sat_count, i_w=z.i_w)
+check("frozen at i_w=0: the freeze then clears", not z2.frozen)
+# Same stranding on the other side: a small positive integrator against export.
+z3 = compute(prev_w=100, grid_w=-1000, actual_w=800, tuning=T, sat_count=3, i_w=100.0)
+check("frozen at i_w=+100: a 1 kW export still moves the command",
+      z3.frozen and z3.target_w < 0)
+z4 = compute(prev_w=-100, grid_w=1000, actual_w=-800, tuning=T, sat_count=3, i_w=-100.0)
+check("frozen at i_w=-100: a 1 kW import still moves the command",
+      z4.frozen and z4.target_w > 0)
+
+# ⚠️ EXACTLY ZERO, BOTH DIRECTIONS. This boundary has a history: the first cut
+# deadlocked here under import, and the fix for it deadlocked here under export
+# because `if i_w > 0 ... else ...` files 0.0 under rising-only. main.py resets
+# i_w to exactly 0.0 on every stop and every reseed, so it is a normal state,
+# not a corner.
+zi = compute(prev_w=0, grid_w=2000, actual_w=600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: an import push moves the integrator",
+      zi.frozen and zi.i_w > 0)
+ze = compute(prev_w=0, grid_w=-2000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: an export push moves the integrator",
+      ze.frozen and ze.i_w < 0)
+# The COMMAND still holds at 0 W in that second case, and that is release/1.0's
+# rule, not a leftover: at prev_w == 0 the output freeze forbids starting to
+# charge while saturated, because commanding 0 while the inverter reports
+# hundreds of watts means something else is driving the bus. Asserted so that
+# nobody "fixes" it by accident - the integrator moving is what this ticket
+# owns, the command rule belongs to the output freeze.
+check("frozen at i_w=0.0: the output freeze still blocks a charge from 0 W",
+      ze.target_w == 0.0)
+# Where prev_w is already charging the output freeze does NOT block, and there
+# the difference reaches the wire: held at 0.0 the integrator abandons the
+# charge mid-export.
+zc = compute(prev_w=-2000, grid_w=-4000, actual_w=-600, tuning=T, sat_count=3, i_w=0.0)
+check("frozen at i_w=0.0: a charge is not abandoned during heavy export",
+      zc.target_w == -2000.0)
+
+# The general property, rather than another handful of points: while frozen the
+# integrator may be held ONLY when the correction would push it further from
+# zero on the side it already sits. Any other hold is a deadlock.
+stuck = []
+for i0 in [x * 25.0 for x in range(-80, 81)]:
+    for g in [x * 100.0 for x in range(-40, 41)]:
+        err = g - T.target_grid_w
+        if abs(err) < T.deadband_w:
+            continue
+        dd = compute(prev_w=0.0, grid_w=g, actual_w=1500.0, tuning=T, sat_count=3, i_w=i0)
+        if dd.i_w == i0 and not ((i0 > 0 and err > 0) or (i0 < 0 and err < 0)):
+            stuck.append((i0, g))
+check(f"frozen integrator never deadlocks, over {161*81} states"
+      + (f" (e.g. {stuck[0]})" if stuck else ""), not stuck)
+
+# False-positive guard: a normal 2 kW load step must not trip the detector,
+# because the plant needs several cycles to catch up on every one of them.
+prev, actual, sat, i_w, froze = 0.0, 0.0, 0, 0.0, False
+for _ in range(12):
+    d = compute(prev, 2000.0 - actual, actual, T, sat, i_w)
+    prev, sat, i_w = d.target_w, d.sat_count, d.i_w
+    actual = actual + 0.94 * (prev - actual)
+    froze = froze or d.frozen
+check("a normal 2 kW load step does not trip the saturation freeze", not froze)
+
+# The convergence sim below runs WITHOUT a carried integrator. This is the same
+# 2 kW step in the configuration that actually ships, where main.py carries it.
+prev, actual, sat, i_w = 0.0, 0.0, 0, 0.0
+carried = 0
+for _ in range(12):
+    d = compute(prev, 2000.0 - actual, actual, T, sat, i_w)
+    prev, sat, i_w = d.target_w, d.sat_count, d.i_w
+    actual = actual + 0.94 * (prev - actual)
+    carried += 1
+    if abs(2000.0 - actual) < T.deadband_w:
+        break
+check(f"carried integrator converges in {carried} cycles (<=6)", carried <= 6)
+check("carried integrator does not overshoot the load", actual <= 2000.0 + T.deadband_w)
+
+# ⚠️ REGRESSION: an integrator allowed to wind past the rail buys nothing (the
+# output clamp already bounds the wire) and costs extra cycles of
+# wrong-direction power after every saturation event. 4000 W load held to
+# saturation, then dropped to 0; the figure is the command on the first cycle
+# after the drop. This is what makes the DOCS advice checkable.
+def unwind(t):
+    prev, actual, sat, i_w, load = 0.0, 0.0, 0, 0.0, 4000.0
+    for c in range(16):
+        if c == 15:
+            load = 0.0
+        d = compute(prev, load - actual, actual, t, sat, i_w)
+        prev, sat, i_w = d.target_w, d.sat_count, d.i_w
+        actual = actual + 0.94 * (prev - actual)
+    return prev
+
+
+tight, loose = unwind(Tuning(max_w=2000)), unwind(Tuning(max_w=2000, integrator_max_w=3000))
+check(f"after saturation ends the command is {tight:.0f} W (<= 1000)", tight <= 1000)
+check(f"headroom above max_w makes that worse ({loose:.0f} W) - hence the default",
+      loose > tight)
+
+print("SAFETY-04: the i_w=None path is still release/1.0, exactly")
+
+
+def legacy(prev, grid, actual, t, sat_count):
+    """release/1.0's control law, transcribed. Do not 'improve' this."""
+    reason = "tracking"
+    sc = min(sat_count + 1, 10) if abs(prev - actual) > t.saturation_w else 0
+    frozen = sc >= t.saturation_cycles
+    error = grid - t.target_grid_w
+    if abs(error) < t.deadband_w:
+        want, reason = prev, "deadband"
+    else:
+        want = prev + t.gain * error
+    target = max(-t.max_w, min(t.max_w, want))
+    if target != want:
+        reason = "clamped"
+    slewed = max(prev - t.slew_w, min(prev + t.slew_w, target))
+    if slewed != target:
+        reason = "slew-limited"
+    target = slewed
+    if frozen:
+        target = min(target, prev) if prev > 0 else max(target, prev)
+        reason = "saturated-freeze"
+    step = max(1, int(t.step_w))
+    return float(round(target / step) * step), sc, frozen, reason
+
+
+# ⚠️ Compare EVERYTHING observable, not just the number. A previous version of
+# this sweep compared (target_w, sat_count) only and passed 3024 cases while
+# `reason` had silently lost a value - which is the kind of thing a sweep this
+# broad exists to catch. `frozen` and `reason` are both in the tuple now.
+#
+# The one deliberate rename: what release/1.0 called "clamped" is now
+# "i-clamped", because the truncation happens on the integrator before the
+# command is derived from it. Aliased here rather than papered over - if any
+# OTHER reason ever diverges, this check goes red.
+ALIAS = {"i-clamped": "clamped"}
+diffs = []
+seen = set()
+for tune in (Tuning(), Tuning(target_grid_w=-10.0), Tuning(max_w=5000, slew_w=5000)):
+    for prev in (-2000.0, -500.0, -100.0, 0.0, 100.0, 500.0, 2000.0):
+        for grid in (-6000.0, -1000.0, -500.0, -14.0, 0.0, 14.0, 500.0, 1000.0, 6000.0):
+            for actual in (-2000.0, 0.0, 600.0, 2000.0):
+                for sc in (0, 2, 3, 9):
+                    d = compute(prev, grid, actual, tune, sc)   # i_w defaults to None
+                    seen.add(d.reason)
+                    got = (d.target_w, d.sat_count, d.frozen,
+                           ALIAS.get(d.reason, d.reason))
+                    if got != legacy(prev, grid, actual, tune, sc):
+                        diffs.append((prev, grid, actual, sc, got,
+                                      legacy(prev, grid, actual, tune, sc)))
+check(f"i_w=None reproduces release/1.0 over {3*7*9*4*4} cases, reason included"
+      + (f" (first diff {diffs[0]})" if diffs else ""), not diffs)
+
+# ...and the rename is not a quiet deletion: the signal SAFETY-03 alarms on has
+# to actually occur in that sweep, or its hook is dead.
+check("the integrator clamp reports itself as 'i-clamped'", "i-clamped" in seen)
+
+# "clamped" stays reachable, but only where the integrator is deliberately
+# allowed above the rail - then BOTH fire and the output clamp, which describes
+# the value actually emitted, is the one reported.
+dc = compute(prev_w=0, grid_w=6000, actual_w=0,
+             tuning=Tuning(max_w=2000, integrator_max_w=3000, slew_w=5000))
+check("the output clamp still reports 'clamped' when it is the binding one",
+      dc.reason == "clamped" and dc.i_w == 3000 and dc.target_w == 2000)
+
 print("capacity tariff")
 check("no forecast means no cap", maintenance_charge_floor(2500, None, 3500) == 2500)
 check("headroom caps the charge", maintenance_charge_floor(2500, 2000, 3500) == 1500)