SAFETY-03: alarm when a computed setpoint exceeds the rating, do not just clip it

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 pinned at
the 5 kW rail; clipped silently that is a flat, legal-looking 5000 W hold and
nothing says the loop asked for three times it.

write_setpoint() - the one path every write takes - now clamps to the VALIDATED
max_w and reports whether the raw value differed; check_output_clamp() raises
OUTPUT_CLAMP as a notification, an ERROR, an event row and a red status banner.
Not a trip: the clamped value is written and the loop keeps running.

The rating is max_w and nothing is min()ed at runtime - CFG-01 already refuses a
max_w outside the device range at startup. The device range is applied second as
defence in depth; it cannot bite after a successful validation, so if it ever
does it alarms too and names the bound. No new config key.

Decision grew i_clamped / clamped booleans, and that is the load-bearing part:
`reason` is one string that slew-limiting and the saturation freeze overwrite,
so an alarm keyed on it is silent on exactly the cycles a winding loop produces.
Mutating main.py back onto the string drops the 10.3 replay from 2 engagements
to 0.

Distinct from saturation by construction - no shared reason code, notification
id, status row or counter - and checked in the negative, after first asserting
the saturation freeze really did engage.

Two things found by running it rather than by reading it: a row per engagement
flushed the 40-row event log and evicted SAFETY-18's own METER FROZEN? row (now
coalesced per episode with an exact count), and a naive clamp turns a nan into a
command at the full rating because every comparison against nan is False.

test_clamp.py is new: assert-based, no framework. Six author mutations
reproduced red, including "clamp kept, alarm deleted". Two of the check's own
hypotheses about the freeze/clamp interaction were refused by its sweep and
rewritten to what it measured.

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

goodwe_controller/DOCS.md

@@ -474,6 +474,61 @@ today is 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 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