SAFETY-04: bound the integrator independently of the output

Evidence at sign-off: 55 checks in test_control.py (24 on release/1.0),
independently reproduced. 108,031 failsafe-release combinations swept across
both grid directions, 2,500 randomised carried-i_w trajectories at 200 ticks,
300 repeated-meter-value stall scenarios - zero anomalies. The historical
runaway regression uses the real 10.3 numbers and goes red when the protection
is removed.

Two rejections on the way. The first cut deadlocked the loop at small |i_w| and
let the accumulator run 50% past the rail, which ADDED windup this codebase
never had - the accumulator used to be the post-clamp command, so it could not
exceed max_w by construction. The second deadlocked at i_w == 0.0 in the export
direction, found by sweeping the boundary after three reviewers had each
covered the same half of it.

The finding worth keeping: deleting the integrator freeze outright failed 0 of
55 checks, because the integrator bound truncated to exactly the value the
fixture asserted. A neighbouring mechanism was standing in for the one under
test. The same pattern turned up again in the output clamp. test_control.py now
carries the audit table and its invariant - every mechanism in compute() must
be noticed by at least two checks when deleted.

Deliberately not met as literally written: the detector counts cycles, not the
10 s the AC specifies. compute() is clockless and cycle() runs only on a
changed meter reading, so there is no wall-clock window at all. Documented in
the code and in DOCS.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

goodwe_controller/DOCS.md

@@ -59,11 +59,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 |
 | `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

@@ -70,6 +70,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(
@@ -89,6 +94,8 @@ class Controller:
         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
@@ -231,17 +238,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:

goodwe_controller/config.yaml

@@ -48,6 +48,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
@@ -88,6 +89,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)