7 Commits

Include renames

Author	SHA1	Message	Date
glenn schrooyenandClaude Opus 5	3527c8a04c	SAFETY-41: escalate a sustained engagement, so a runaway is never held ... Review found the case I asked it to construct, and it is not a corner case. The rate limit alone DELAYS A RUNAWAY: a benign one-cycle clamp that spends the budget, then a continuous §10.3-shaped runaway, held the runaway's first notification for up to 140 s - one REASSERT_S minus a cycle. On the live install, where ordinary railing spends the budget essentially all the time, a runaway arriving during normal operation would be delayed with near-certainty. That is the "benign noise suppresses the bug signal" shape this module's docstring is written against, and the family the first attempt at this card died of. THE ESCALATION. An episode that has not yet spoken because an EARLIER, unrelated episode spent the budget speaks anyway once it has engaged SUSTAINED_CYCLES = 3 times in a row. The discriminator is run length and the two populations genuinely differ: the live flood was runs of length ONE (engage, de-assert, engage), while a runaway engages every cycle. Measured, and it costs nothing it was protecting: live scatter flood (305 cycles, 1-in-6) 11 -> 11 notifications chatter 1-engaged/3-clean over 8000 s 50 -> 50 notifications pinned 900 s quarter (floor is 5) 6 -> 6 alarms runaway delay after a benign episode 140 s -> 10 s ⚠️ MY COUNTERFACTUAL CHECK COULD NOT FAIL FOR THE DEFECT IT NAMED, and review caught that too. It read `ClampWatchdog().note(True, ...) is True` - a FRESH object, which only exercises the `last_alarm is None` branch, the trivially-true one. A fresh watchdog has no earlier episode to be held back BY. It now SPENDS THE BUDGET FIRST: benign clamp, gap past CLEAR_CYCLES, then a continuous runaway, and asserts the delay is well under REASSERT_S. That is the third instance in this file of the family recorded at line 216 and at the 224 s sweep, and it was guarding the most safety-critical property in the change. Also pinned: `last_alarm` SURVIVING the de-assert. Review built the mutation - if the de-assert also refreshed it, chatter collapses from 50 notifications to 1 and the alarm never fires again, with the suite green. That is the "alarm that never fires" class, a different bug from one that fires later. Now caught. Both new checks verified against the mutations they name: removing the escalation -> 1 FAILED; refreshing last_alarm on de-assert -> 1 FAILED. Full suite: 21 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-05 18:13:09 +02:00
glenn schrooyenandClaude Opus 5	8790c4d38f	SAFETY-41: rate-limit the RISING EDGE, which is where the flood came from ... Review falsified the first version of this change, and the correction is the substance of it. Raising REASSERT_S 30 -> 150 removed NONE of the owner's notifications. The re-assert interval governs only the still-engaged path; the rising edge fired unconditionally. At the measured ~5 s cycle the live pattern - 48 engagements in ~25 minutes, about one cycle in six - leaves ~25 s of clean cycles between engagements, past CLEAR_CYCLES x 5 s = 15 s. So the alarm DE-ASSERTED between almost every engagement and each one returned as a fresh rising edge. Measured on the shipped class over that window: 48 episodes, 48 notifications at REASSERT_S = 30, and still 48 at 150. The interval now bounds the NOTIFICATION RATE rather than the repeat rate within one episode: `last_alarm` survives a de-assert, and a new episode speaks only if the interval has elapsed. Same window afterwards: 51 episodes, 51 engagements, 11 notifications. ⚠️ NOTHING IS DROPPED, AND THE TWO PROPERTIES THAT MATTER ARE PINNED: - a PINNED loop still speaks 6 times in the 900 s billing quarter, against a floor of 5 (part 2, unchanged); - a rising edge from a COLD watchdog still fires IMMEDIATELY, so a runaway beginning from quiet is never held back by a budget spent on an earlier, unrelated episode. That check is the counterfactual and it is the half that would go red if the limit ignored elapsed silence. Every engagement is still counted, every episode still increments, and the action-log row is still written on every engaged cycle. The budget is on notifications, never on evidence. The new pin is written in wall-clock seconds and in the shape the field produced, so it does not move when the constant does. Verified by reverting the rising edge to unconditional: 2 checks go RED naming it. Full suite: 21 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-05 17:06:29 +02:00
glenn schrooyenandClaude Opus 5	1d393ced22	SAFETY-41: correct the comment, and fix the check it cites ... Review found two false statements in the comment and one weak check. All three are fixed here; the constant itself is unchanged at 150 s and was never in question. 1. "That caps this constant at 900/5 = 180 s" was FALSE ABOUT THE CHECK IT CITED. test_clamp.py part 2 sweeps i = 0..899 and the rising edge at i=0 is free, so it measured `1 + floor(899/R)` - one alarm more than a real quarter earns. Measured: 224 s was GREEN across the whole suite. Anyone raising this to 200 s would have had a green board and a requirement quietly unmet - the same defect recorded at test_clamp.py:216, one notch weaker. The check now grades floor(QUARTER_S / REASSERT_S) directly, so it enforces the ceiling the comment claims for it. Verified: 150 PASS, 180 PASS, 181 FAIL, 224 FAIL. 180 is also the true requirement edge - on the worst sliding 900 s window 180 earns 5 alarms and 181 earns 4. 2. The "60 cycles of the §10.3 runaway" note was attributed to this module and truncated. It is main.py:2479 and reads "60 cycles of the §10.3 runaway produce 0 write-path engagements and 2 loop-side ones". Quoted in full, attributed correctly. 3. "48 engagements in 25 minutes" was left implying a pinned rail. It is roughly one cycle in six - real, and far above the 2-in-60 the guard was sized for, but not continuous. Restated, and labelled as a live-log reading rather than a measurement in this repo. Also recorded: the 1500 W tuning derivation is in the OTHER repo (admin/goodwe NOTES.md, "Simulated 2 kW load step (gain 0.6, clamp 1500)"), so this repo cannot corroborate it and a reader should not go looking here; and MIN_PER_QUARTER = 5 is a test-local integer, not a spec figure - the 900 s quarter is system-wide but the 5 is not, so the 180 s ceiling rests on one number a test author chose. Full suite: 20 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-05 16:53:46 +02:00
glenn schrooyenandClaude Opus 5	3516947b5e	SAFETY-41: raise the clamp alarm's re-assert 30 s -> 150 s ... The owner reported the OUTPUT_CLAMP notification as a persistent annoyance on the live install. It re-asserted every 30 s, all day. ⚠️ THIS IS A REGIME CHANGE, NOT A CHANGE OF MIND ABOUT THE ALARM. 30 s was chosen when a loop-side engagement was rare - clamp.py's own note records "60 cycles of the §10.3 runaway produce 2 loop-side engagements". The live install produced 48 IN 25 MINUTES of ordinary operation, because `max_w` is 5000 W where the loop's tuning was derived at a 1500 W clamp (SAFETY-39). The integrator therefore reaches its bound constantly and the alarm narrated it every 30 s. An alarm that speaks that often about the normal case is how an operator learns to ignore the one that matters, which is the exact failure clamp.py's docstring is written against. ⚠️ 150 s IS THE REQUIREMENT'S OWN EDGE WITH ONE STEP OF MARGIN, not a comfort choice. test_clamp.py part 2 pins the cadence in WALL-CLOCK terms rather than against this constant: a loop pinned on the rail must speak at least MIN_PER_QUARTER = 5 times inside the 900 s quarter that bills the capacity tariff. That caps the constant at 900/5 = 180 s. Measured: 180 s -> 5 alarms per quarter (exactly the required 5, no margin) 150 s -> 6 alarms per quarter 300 s -> 3, and the floor check goes RED 180 s would sit on the boundary, so any later change to the firing logic would tip it red for a reason unrelated to that change. The FLOOR is the thing that must not move, and it does not. ⚠️ WHAT THIS DOES NOT DO. It changes how often the alarm repeats. It does NOT make the alarm correct: the message still calls the integrator bound a BUG SIGNAL and still pairs a request from one moment with a `self.target` read at another. That is SAFETY-40. And it does not stop the loop railing in the first place; that is SAFETY-39. This is a stop-gap and says so at the line. Nothing was suppressed: every engagement is still counted, the action-log row is unchanged, and the §10.3 runaway still raises the alarm - an earlier attempt at this that split the alarm so only `clamped` notified was REVERTED because test_clamp.py:398 proved it would have disabled runaway detection entirely (a runaway presents as `i_clamped`, and control.py:78-81 says `clamped` is unreachable on a default install). Full suite: 20 passed, 0 failed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BwRLw7eKYj2byVdwB6kbjU	2026-09-05 16:53:46 +02:00
adminandClaude Opus 5	83911ed637	SAFETY-20: measure the freeze rail against the reachable ceiling, not max_w ... SAFETY-18's conjunction needs `abs(commanded_w) >= 0.95 * max_w`, but the emitted command is clipped to the setpoint device's own [dev_min, dev_max] range as well as to max_w - in clamp_to_rating()'s second stage and again as the arbiter's `device` P_SAFETY limit claim. Measured on the shipped predicate at the ticket's numbers, max_w 5000 on a +-4700 W inverter: looks_frozen(unchanged_s=3600, commanded_w=4700, max_w=5000) -> False The command is pinned at the hardware's rail, the meter has been frozen for an hour, and term 2 is unsatisfiable by construction because 4700 < 4750. Any device rating at or below 0.95 * max_w disarms the conjunction outright, and the status page then printed `armed (... command is over 4750 W)` - a guard that cannot fire, advertising that it can, which is the failure SAFETY-15, SAFETY-19 and validate.py rule 5 all exist to prevent. The rail is now measured against min(max_w, |dev_min|, |dev_max|), through a new `rail_ceiling_w()` threaded into looks_frozen(), FreezeWatchdog.evaluate() and both call sites in main.py. An unread rating leaves the old behaviour exactly, and correctly: hass.limits() returns None whenever ESPHome is not up, and on that path no device clamp is applied either, so max_w really is the ceiling. A rating larger than max_w cannot raise the rail - this is a min(), not a swap. THE DELIBERATE CHOICE, since SAFETY-03 has landed. The arithmetic was kept rather than substituting Decision.i_clamped / Decision.clamped. i_clamped is the integrator bound (control.py:208, `bounded != i_w`), not "the command is at the device rating", and `clamped` is the max_w output bound, unreachable on a default install - neither is the device rail. More decisively, both answer "did the LOOP ask for more than a bound", while the rail term asks "is the command standing at the ceiling", and those coincide only when the loop is the claimer that won. A maintenance SET or a peak-guard floor reaches the ceiling through arbiter LIMIT claims with no clamp engaging at all, so a boolean rail would go False exactly during a maintenance phase running against a frozen meter - which freeze.py's own docstring names as the same fault with a worse actuator behind it. The predicate is also public with two call sites that pass DIFFERENT command values (self.target, and `standing` = last_write); a per-cycle boolean cannot be passed per call site, so substituting it would have silently decided the pre-clamp-versus-wire question that PM recorded as still open. AC 1 governs, and it is satisfied literally. The smaller of the two device bounds, not a per-sign pair. A per-sign rail is tighter and is not wrong, but it is two rails needing two coverage verdicts on a status row that carries one number, and the only configuration that distinguishes them is refused at startup anyway. The symmetric ceiling can only lower the rail, which widens term 2 rather than disarming it; term 1 carries the whole no-false-positive argument and is untouched. A ceiling of 0 W is NOT COVERED, not "armed at 0 W". A device that can command nothing in one direction would make `abs(command) >= 0` true of every command including a parked one - term 2 degenerately TRUE, collapsing the conjunction into the bare unchanged_s > N threshold TEL-05 refused for false-tripping at this controller's own operating point. rail_unreachable() returns the reason, looks_frozen() stays silent, and the page uses the NOT COVERED row the unsupported-transport case already has - a second reason to use that surface, not a new mechanism. AC 4, decided rather than assumed: NO NEW validate.py RULE. The configuration is max_w above the device rating, which rule 2 (CFG-01) already refuses on the identical predicate, re-run by run_control() once the real rating is known: validate_startup_config({... max_w: 5000}, -4700, 4700) -> ['max_w is 5000 W but number.sp accepts at most 4700 W - THE DEVICE WINS ...'] A rail-specific rule would fire on a strict subset of that (0.95 * max_w > dev_max implies max_w > dev_max) and could never be the rule that stopped a start. The residue is the state where hass.limits() answered (None, None) - ESPHome not up at boot, range checks skipped rather than guessed at, rating never re-read - and there is nothing to refuse there by construction, which is why the answer is a runtime row. Recorded in validate.py's "deliberately not refused" list and pinned by four checks in test_validate.py, so the decision's premise goes red if rule 2 is ever softened back to a warning. HOW REACHABLE THIS IS, stated rather than glossed. Because rule 2 refuses the configuration whenever the rating is known, min(max_w, dev_max) IS max_w on every install that reaches the control loop with a rating it could read, and this change is arithmetically dead there. That is clamp.py's argument for its own second stage word for word: the case where it bites is the case where the startup gate did not run or no longer holds, and a guard that quietly assumes the gate ran is a guard that reports armed in exactly the state it cannot fire in. Verified by breaking it, per this project's rule. Reverting rail_w() to bare max_w fails nine checks; deleting the NOT COVERED handling fails five. The one that mattered: shipping the corrected predicate while NOT passing the rating from check_meter_frozen() left the entire suite green, because nothing graded the caller - so test_freeze.py part 5b now drives the real cycle() on a +-4700 W device and asserts on the notification that leaves the process, and the unwiring mutation fails three checks there. The peak-guard call site's wiring is still ungraded (behind p1_enabled, needs a fed averager for `frozen` to have any observable consequence) and that gap is named in the file rather than implied. Full suite: 15/15 in goodwe-addon-ci. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>	2026-09-01 02:14:07 +02:00
glenn schrooyenandClaude Opus 5	4e66583a52	SAFETY-03 review fixes: both clamp stages always run, and two checks that could not fail ... 1. BEHAVIOURAL, and a regression this PR introduced. clamp_to_rating() returned early from the max_w stage, so the device bound was applied only when the rating bound had NOT fired - the bigger the overshoot, the less the guard did. At max_w 5000 against a +-4000 device, +9999 emitted +5000 W, outside the device range, while +4500 was correctly held to +4000. It undid the pre-PR guarantee "never send a value the device will reject outright" and undercut this module's own case for max_w-not-min(), which rests on that stage catching a validation that did not run. Both stages now always run; the result names both bounds when both bite (max_w+device). Asserted over a 492-point sweep, because the defect was invisible to any single-value check sitting inside one stage. 2. The hysteresis check issued range(CLEAR_CYCLES - 1) clean cycles, which at CLEAR_CYCLES = 1 issues zero, passes, and prints "0 clean cycles do NOT clear it" - green for the chatter setting the constant exists to prevent. Now: ONE clean cycle must not clear the alarm, a literal that does not move with the constant, and the de-assert count is measured by looping until it clears. 3. The re-assert check stimulated at REASSERT_S + 9, green for any value including 3600 - the hour of silence the module promises not to produce. Now stated in wall-clock terms: a loop pinned across the 900 s capacity-tariff quarter must speak at least 5 times and on no more than 20% of cycles. Pinned in both directions. Red confirmed for each: the restored early return (3 checks), CLEAR_CYCLES = 1 (1), REASSERT_S = 3600 (1) and REASSERT_S = 0 (3). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015VXjA3LWccN1rJsk3okyPC	2026-08-30 15:52:09 +02:00
glenn schrooyenandClaude Opus 5	c040aac4b8	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	2026-08-30 15:22:22 +02:00