goodwe-addon/goodwe_controller/CHANGELOG.md

Changelog

Unreleased

Maintenance option defaults lived in three places that had already disagreed, and MAINT-04's tripwire was holding them apart rather than closing them (CFG-03). config.yaml shipped maintenance_charge_w: 2000, main.py carried two opts.get("maintenance_charge_w", 2500) fallbacks, and MaintConfig's dataclass carried a third 2500.0. An options dict with the key absent was therefore accepted by validate.py's rule 6 — which read 2000 — and then built by main.py at 2500, against a 2000 W ceiling. Demonstrated through the shipped code:

options dict with maintenance_charge_w ABSENT, max_w=2000
  validate_startup_config  ->  [] (ACCEPTED, no problems)
  MaintConfig().charge_w   ->  2500.0
  arbiter.resolve()        ->  0.0 W, contradiction=True

That is the bug rule 6 exists to refuse, passing rule 6. Unreachable through the Supervisor, which always supplies every key from config.yaml; fully reachable from sim/inject.py and from the test suite, which is where anyone debugging maintenance is.

maintenance_discharge_w had the identical divergence (config.yaml 2000, MaintConfig 2500) and the card named only the charge side. Closing one key and leaving its twin would have reproduced the defect one line down, so both are closed.

The single source of truth is config.yaml's options: block — the file the Supervisor reads and the operator edits. There is now exactly one in-code copy, maintenance.MAINT_OPTION_DEFAULTS, which is TARIFF-02's PRICE_OPTION_DEFAULTS and SAFETY-24's PEAK_OPTION_DEFAULTS pattern applied to the family that named the card. A mirror rather than a runtime read because the Dockerfile copies app/ and run.sh into the image and not config.yaml: the running add-on cannot open the file it is configured by. test_maintenance.py pins every entry by reading the shipped file, so a drift is a CI failure rather than a comment. Every other declaration site now derives from it or has ceased to exist:

• MaintConfig's eight dataclass defaults are indexed out of the mirror — no numeric literal survives in the class that held the third opinion;
• MaintConfig.from_options() is the only place in the add-on that reads a maintenance_* option. main.py's eight inline opts.get(key, <literal>) calls are gone;
• main.py's second fallback site (the cheap-window charge floor) reads self.maint.cfg.charge_w instead of re-opening the options dict, so the rate the shaping asks for and the rate the state machine drains at cannot be two numbers from one install;
• validate.py's rule 6 and its maintenance_discharge_w warning take their fallbacks from the mirror.

Where the RANGE lives is now stated and checked, so the next person does not add a fifth site. maintenance_charge_w: int(500,5000) in config.yaml's schema: block is a fourth declaration of a different kind — a bound, not a default. Bounds live in the schema block only: the Supervisor enforces them and reads only that file. test_maintenance.py asserts that every mirrored key has a schema entry (or the Supervisor silently drops the option and the add-on runs on the mirror instead of the operator's value) and that every shipped default lies inside its own range. What the schema grammar cannot express is a relation between keys — maintenance_charge_w against max_w — which is why rule 6 is written in Python and does not belong in the mirror either.

MAINT-04's tripwire in test_validate.py is DELETED, not left passing, as it and validate.py's ⚠️ block both instructed each other to do. Its passing condition was the bug. In its place, the same four consumers exercised the same way and now agreeing: the validator accepts a dict with every maintenance_* key missing, a real Controller built from that dict holds 2000 W, MaintConfig() answers 2000 W with no dict at all, and the real arbiter emits -2000 W, limited by supervised(max_w) instead of 0 W, contradiction=True.

Checked by breaking it, five ways, each observed red before being reverted: move config.yaml alone → the mirror pin fails; move config.yaml and the mirror to 1500 → every consumer follows together (MaintConfig() 1500 W, the Controller 1500 W, the arbiter -1500 W, limited by maintenance(cheap-window charge)) and both suites go green again; retype charge_w: float = 2500.0 into the dataclass → red; restore opts.get("maintenance_charge_w", 2500) in main.py → red; delete a key from config.yaml's options block → red.

Stale prose that asserted the closed divergence as current is corrected in app/watchdog.py, test_watchdog.py and test_peakguard.py.

peak_soc_floor reads like a pack-wide reserve and is not one, and on a sustained-load evening the grid-following loop discharges straight past it to the BMS cut-out (SAFETY-25). The gap has been written down four times without being filed — SAFETY-18's finding (freeze.py), SAFETY-24's module note, its PR body, and its honestly-uncaught 13th mutation — and never once measured. It is measured now, on the committed 2026-08-20 capture, driving the shipped control.compute(), peakguard.decide(), peakguard.claim() and the real arbiter.resolve():

19:00-22:00 UTC, 830 W mean, minimum 701 W, not one watt of export
reference pack (300 Ah x 51.2 V x DoD 90) started at 21 %, one point
above peak_soc_floor

  ends at 10.0 %  -  the bms_soc_floor cut-out
  1525 Wh delivered by the LOOP over 587 cycles
  549 cycles below peak_soc_floor, 343 of them still discharging
  0 cycles on which the peak guard filed any floor at all

And it is a behaviour, not a config value. The same evening ends at 9.9715 % at peak_soc_floor = 5, 11, 20 and 60 — the shipped value and both ends of the schema range — identical to four decimal places. The option an operator would reach for cannot move the number by any amount. On the same day's high-load block the two states coexist: 49 cycles reporting PEAK GUARD FLOOR-LIMITED and, on all 49, the arbiter simultaneously granting the loop up to 2000 W of discharge.

Why SAFETY-24 could not close it. The peak guard files a lo limit — a lower bound. That asymmetry is what makes it provably unable to lower a target, cap a discharge or contradict the arbiter, and it is therefore equally unable to stop a discharge the loop itself wants. A floor on the guard cannot become a floor on the pack by being raised.

What changed is the honesty, on four operator-facing surfaces, because that half is required whichever way the open question is answered and it is the actual misstatement on the live system today:

• config.yaml says next to the option that it bounds the peak guard only and is not a pack-wide reserve, with the replayed evening and the sweep;
• DOCS.md says it in the options table and in a new section carrying the figures above;
• the status-page row for a floor-limited guard carries the scope sentence — it is the one line a human reads at the moment the guard stops, and read alone it implies a reserve the replay shows does not exist;
• the persistent notification says what has stopped (the guard buying a lower bill) and what has not (the pack being spent).

peakguard.py and freeze.py carry the measurement beside the findings they already recorded.

The product decision is NOT taken here. Whether the loop gets a reserve floor of its own moves real energy on this house and belongs to the owner. DECISIONS/SAFETY-25-loop-soc-floor.md records the options, what each costs and protects, weighed against MAINT-01 and against the fact that this would be the fifth SoC key (OPT-04's arbitrage_soc_floor fired SAFETY-24's "revisit if a third floor appears" trigger unremarked), and a recommendation. It also records a trap found while writing it and now checked through the real arbiter: the obvious shape — a hi limit on the loop — crosses the peak guard's lo and resolves to a CONTRADICTION at 0 W, the battery parked in the quarter that sets the bill, unless bms_soc_floor < loop_soc_floor <= peak_soc_floor is enforced at startup.

test_peakguard.py part 10 is a tripwire, not a guarantee, and part 10f is what makes it one. The replay half records the defect; on its own it could not see the defect being FIXED, because replay_loop() hand-builds main.py's claim list and is therefore blind to any claim main.py adds — which is exactly where a loop-side floor would be built. PR #31's reviewer proved that by building the memo's own Option B in main.py and watching the whole suite stay green. 10f pins the claim-source set: every claims.append(...) in Controller.cycle() is read off its AST and must be one of eight named sources, and real Controller.cycle()s — spied at main.py's own resolve, swept over the whole 0–100 % state-of-charge range in both the idle and the floor-limited state — must hand the arbiter exactly {device, supervised, loop} and {device, supervised, loop, peak}. A ninth source, at any state of charge, in any configuration, takes part 10 red on the line it is written. A floor built inside control.compute() or the guard instead moves 10a–10c's replayed numbers, which the replay drives directly. So the exposure cannot change size under a green suite.

Nine mutations, re-run against the fixed tree, each against a freshly copied tree with no __pycache__ present at all, mounted :ro — the same structural immunity MUTATION.md records for CI. Six are the AC 3 and behaviour mutations already on this ticket's record (the status row's scope sentence, the notification's, config.yaml's, the memo deleted, the loop's gain zeroed, the guard's claim given a hi); two are the reviewer's, and are the ones that motivated 10f — the memo's own Option B at its recommended default, now three checks red where it was fully green, and an absurd always-binding 95 % reserve, six red; one is new, against the banner short form below. All nine are red, no survivors, and no byte delta is +0 B.

The gate has never once graded the content a pull request would land, and a run that never started reported as a test failure (CI-02). Both halves were measured on a deliberately conflicted throwaway pull request rather than read off the workflow, because the Actions log endpoints 404 on this Gitea and a step's own conclusion is the only channel out of a job.

Case 1, and the ticket's mechanism was wrong in a way that made it worse. CI-02 was filed saying a conflicted pull request loses its merge ref, so that git fetch $GITHUB_REF || git fetch $GITHUB_SHA falls through and grades the bare branch head. The symptom was real — PR #14 reported checks / unit -> success while mergeable: false — but the mechanism is not. On this server GITHUB_REF is refs/pull/<n>/head, GITHUB_SHA is the same commit, and git ls-remote origin 'refs/pull/*' advertises no /merge refs at all, for open and closed pull requests alike. The first fetch has always succeeded; the fallback has never fired once. So the gate did not lose merged content on conflicted pull requests — it has never had merged content, on any pull request in this repository's history. Green has meant "this branch passed on its own", which on a base that has moved is not what lands, and block_on_outdated_branch is off on release/1.0 so the base usually has moved.

The checkout now fetches the base tip and the pull request head, merges them, and refuses if the merge does not apply — as its own named step, so /actions/runs/<id>/jobs distinguishes "nothing was tested" from "the tests spoke". Verified by producing it: with the fix on a conflicted pull request the required context went failure in 2 s with the two test steps skipped. The --depth 1 is gone (a merge needs a merge base; a full fetch of this repository is 6.8 MB and 1.1 s), and the fallback survives only on the workflow_dispatch path, which has no pull request to merge and now says so in its output.

Case 2: concurrency: is gone, and cancel-in-progress was never the knob. Runs 531 and 533 on PR #14 were cancelled at 0 s each at the exact second the next run was created, having never started; a cancelled run posts failure on the required context, described Canceled after 0s, and branch protection compares state and not description — so "nothing ran" and "your tests are broken" arrive at the gate as the same red, wanting opposite responses. Three settings were measured with one run holding the single runner slot and two pushes behind it: with no block at all both queued runs survived and executed; with the group kept and cancel-in-progress: false the queued run was still cancelled at 0 s. A shared group cancels a run that has not started regardless of that flag. Having no group is the only configuration measured to leave a queued run alive, and it is what ships. The cost — a developer who pushes four times occupies the shared runner four times — is CI-01's own trade written the other way round: a delayed verdict, never a destroyed one.

test_ci_gate.py grades the gate by running it, not by reading it. It extracts the checkout and merge steps out of checks.yml and executes the shipped commands against two throwaway local repositories it builds — one whose pull request merges, one whose does not — and pins that the old one-liner exits 0 on the unmergeable one while the new steps refuse. It also pins the two tokens that assemble checks / unit (pull_request): renaming name: or the unit: job key would leave every open and future pull request waiting forever on a context that never arrives, with no error anywhere in that sequence. Seven mutations of checks.yml were each confirmed red. .gitea/ci/Dockerfile gains git for it.

What was NOT established, stated so nobody reads more into this. The original report that "no run was ever created for 0942228d" was already corrected on the card — run 533 was created and cancelled — and this work confirms that from the runs list and the per-commit status history. A commit that never had a run carries an empty /statuses/<sha> list; a queued one carries pending / Waiting to run within seconds, and a concurrency-held one pending / Blocked by required conditions. Those are distinguishable at the API. /actions/tasks, which is what was polled originally, lists only tasks that started, and cannot answer the question at all.

The NOT READY banner no longer repeats the row underneath it. status_payload() renders the first hard-failing check as the page headline, so the scope sentence above turned the loudest element on the page into a 550-character paragraph that the checks list then repeated verbatim. A row may now carry an optional short banner form; the floor-limited row does, and its headline is the guard's own line plus a 68-character scope tag. The row itself is unchanged — the checks list is where an operator reads what the floor does and does not bound, and shortening that would have been weakening AC 3. Rows without the key are unaffected, and the page still renders with textContent.

A setpoint device smaller than max_w silently disarmed the frozen-meter detector, and the status page reported it as armed (SAFETY-20). 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() 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 rating at or below 0.95 * max_w disarms the conjunction outright. The 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|) — freeze.rail_ceiling_w(), threaded through looks_frozen(), FreezeWatchdog.evaluate() and both call sites in main.py. An unread rating (hass.limits() returning None when ESPHome is not up) leaves the old behaviour exactly, and correctly: 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 status row prints the rail the predicate actually uses and names the device when the device is what capped it; the log line and the HA notification do the same, since they outlive the page.

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 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.

AC4, 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. A rail-specific rule would fire on a strict subset of what rule 2 refuses (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) and the range checks were skipped — there is nothing to refuse there, by construction, which is why the answer is a runtime row. Written into 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.

And it was verified by breaking it. Reverting rail_w() to bare max_w fails nine checks; deleting the NOT COVERED handling fails five; and — the one that mattered — shipping the corrected predicate while not passing the rating from check_meter_frozen() originally left the whole suite green, because nothing graded the caller. test_freeze.py part 5b now drives the real cycle() on a ±4700 W device and asserts on the notification that leaves the process; the unwiring mutation fails three checks there. The peak-guard call site's wiring is still ungraded — it sits behind p1_enabled and needs a fed averager to have any observable consequence — and that gap is named in the file rather than implied. A mutation run could grade code that was not there, and the fix is a purge rather than a flag (TEST-15). FCST-03's developer reverted self.provisional to here.provisional, re-ran, and reported a survivor; disassembly showed the source read here while the running code loaded self. CPython validates a .pyc on (source size, source mtime truncated to whole seconds), and a size-preserving edit reverted inside one second moves neither number, so the stale bytecode was reused. That does not make past results wrong - it made them unverified, and the distinction is the whole card.

Reproduced rather than reasoned about. test_bytecode.py builds a real package whose two return values are the same length, imports it in a real subprocess, rewrites it inside the same second and reads back which value ran. Part 1 shows the interpreter running SELF off a file that says HERE.

And it shows the two obvious mitigations do not work. python3 -B and PYTHONDONTWRITEBYTECODE=1 are write-side only: neither stops an EXISTING stale .pyc being read, and a mutation run always has one because the previous run wrote it. The advice already in test_control.py's coverage audit led with -B and is corrected here - the purge is the half that works, and -B earns its place by protecting the NEXT edit rather than this one. No sleep anywhere: one-second mtime resolution is the mechanism, and waiting it out would slow every run down while still only covering the edit somebody remembered to slow.

goodwe_controller/tools/mutation_run.sh is the harness the house adopts: it purges, prints a sha256/byte fingerprint of every app/*.py it is about to grade - so a mutation report can say WHICH source produced it - runs each suite under python3 -B, refuses a tree with no test_*.py (CI-01's rule), and fails if a cache appears during the run. It takes the tree as an argument so the infra repo's replay harnesses can call it.

MUTATION.md states the guarantee where a mutation gets written, and every one of the 16 suites now points at it from its docstring - a list test_bytecode.py derives from the tree, so a new suite joining without the pointer is red.

CI was already immune and is described that way rather than as a hole being closed: checks.yml mounts the checkout -v "$WS:/w:ro", and a read-only tree cannot take a __pycache__ at all - measured, and it fails silently, exit status 0 - while each job rm -rfs its workspace and clones afresh. PYTHONDONTWRITEBYTECODE=1 is added as belt and braces, because the :ro is one character wide. The shipped add-on was never affected: Dockerfile has set PYTHONDONTWRITEBYTECODE=1 since it was written.

The survey of this week's mutation claims is in MUTATION.md, scoped by the property rather than by re-running everything. The defect is one-directional - stale bytecode turns a red into a green survivor and never the reverse - so every "all red, no survivors" result in the window is not at risk, and the exposure is the recorded SURVIVORS from source-edit runs made before the purge discipline landed on 2026-08-31. Two of them were re-run here under the harness and both still stand (TARIFF-01's record_block() ignoring its policy argument; SAFETY-03's abs() on the clamp limit). The rest are labelled still-unverified rather than quietly assumed or noisily re-run.

Out of scope and recorded: the infra repo's sim/ replay harnesses import the add-on and write bytecode into both trees. Anyone mutating a module graded by a replay must purge both by hand until that repo adopts the harness.

release/1.0 went red at midnight on a commit nobody had touched (TEST-17). Controller.checks() read the capacity-tariff peak with self.peak.peak() - no argument - so tariff.py resolved the month from datetime.now(), while test_tariff.py section 10 banks its quarter at the fixed fixture 2026-08-30. From 1 September the page was correctly asked for September, correctly answered NO_RECORD, and the row read "no completed quarter recorded yet" - a string containing no "peak", which the section's filter required. Four checks failed. The suite had been a latent time bomb since TARIFF-01 merged on 2026-08-30 and every PR that ran it ran in August.

Isolated by holding the commit and the image constant and moving only the clock under libfaketime: green at 2026-08-30, four failures at 2026-09-01, identical at f4914a1, 04292c4~1 and 04292c4. The calendar, not a regression.

The product was right and the test was wrong, so the fix does not change what the live page says. checks() takes when: datetime | None = None and threads it into peak() and warning_frac() - the convention every other peak query in tariff.py already follows. The single production caller passes nothing and still means today. Section 10 now grades at its own fixture's month.

Three new checks make the defect detectable rather than seasonal: the same controller read at two different reference months must produce two different rows, which no clock can satisfy; the later month must read NO_RECORD and stay distinguishable from both an observed peak and an unreadable store; and calling checks() with no argument must still mean today. Verified by mutation - a checks() that drops when is now red at every clock tried, where the old section went green in August. Full suite green, 15 files, at the real clock and at faked clocks in four other months.

One thing left alone deliberately: only the UNREADABLE branch prefixes its row with capacity-tariff peak:. The NO_RECORD row carries neither that phrase nor the word peak, which is what made the original filter brittle and what broke the first draft of the new checks too. It is product text with other suites reading it, so it is noted here rather than changed.

Thirty days of the real meter, and the acceptance criterion three cards deferred is now a number (DATA-01). TARIFF-01 and SAFETY-07 both merged with AC 3 - "monthly peak held under the soft limit in >= 95 % of intervals over a 30-day simulation replay" - honestly unmet, on the belief that only two days of capture existed and nothing longer could be produced. That belief came from a true statement about the past being read as one about the future: HA's recorder still held the whole month. scenarios/p1-net-30d-2026-08/ is 2026-08-01 to 2026-08-30, 485,841 samples, 30/30 days read, 0 failed, 4.13 MB gzipped, in the same schema as the two days that were already there.

tools/export_p1_history.py is the exporter, committed and runnable - the 2026-08-25 one-off was not, and that is exactly why the data was thought unobtainable. It reads day-at-a-time, retries, and never lets a failed read look like an empty hour: a day whose read fails writes no file, is recorded as "read": "FAILED", and the run exits non-zero; the entity is proved to exist before any empty day is believed. Nothing is interpolated, so the month's 13 gaps (1291 s, 99.95 % covered) and its 3 unavailable samples stay visible. --verify re-fetches the two committed days by the same route and reproduces them byte for byte after decompression.

tools/replay_ac3.py runs the month. Over 30 days the criterion measures 98.89 % uncontrolled and 98.99 % guarded, so it is met on that reading - and the uncontrolled figure is the finding: a month with no controller at all passes it. On the other reading of the same sentence it is not met - the guard takes August's peak from 5029.8 W to 4107.3 W, still over the 3500 W soft limit, because once a month peak is set CEILING_MONTH_PEAK defends that peak rather than the cap. Neither number is hidden; both are in that directory's README.

The size decision is committed and measured, not absorbed: a git bundle of the whole history goes from 1.58 MB to 5.28 MB (+3.70 MB, x3.3), which a Home Assistant supervisor clones on every install. Downsampling was not available - meter_max_age_s is 30 s, so any coarser resample converts real coverage into modelled meter-gap and moves the number being measured.

The thirty files sit in a SUBDIRECTORY on purpose: test_tariff.py part 9 and test_peakguard.py part 6 glob scenarios/p1-net-*.jsonl.gz non-recursively, so CI keeps replaying the two small days and does not grow ~50 s per PR. Both files' honesty notes are corrected to point at the month.

OPT-04's AC4 is met: twelve months of real EPEX BE day-ahead prices are now in the repository, and the strategy has been replayed against them (DATA-02). AC4 asked for "net-positive across 12 months of replayed prices". OPT-04 shipped it as NOT MET and replayed a synthetic year instead, because scenarios/ held only P1 meter captures. That was the right call at the time and the wrong diagnosis of why: the criterion was being carried alongside a 30-day meter criterion as though both needed waiting, and EPEX BE day-ahead is public data, not a capture. It needed a fetch, not a month.

scenarios/epex-be-dayahead-2025-09-01_2026-09-01.json — 8760 hourly points, 2025-09-01 to 2026-09-01 Brussels-local, in §9.3's canonical three-field shape. scenarios/fetch_epex_be.py produced it and --verify re-derives every claim it makes about itself without touching the network.

Licensing was checked before anything was committed. The source is Fraunhofer ISE's Energy-Charts API, which publishes the BE zone under CC BY 4.0 from Bundesnetzagentur | SMARD.de and other zones under private-use-only terms — so this zone is redistributable with attribution and the data is committed rather than left as a script plus a checksum. The fetcher refuses to write a file whose per-response license_info stops saying CC BY 4.0. Cross-checked against the upstream: SMARD's own 4996/DE series matched this feed on all 96 quarter-hours of 2026-04-10, maximum difference 0.00 EUR/MWh.

The figures are raw wholesale and the file says so. "all_in": false, with the markup/tax assumption carried in provenance.all_in_assumption as numbers to apply rather than numbers already applied — TARIFF-02's double-counting trap in data form. test_arbitrage.py section 7B applies it in one visible place and asserts arithmetically that its two additive terms cancel out of every daily spread, so the trade counts depend on the VAT multiplier alone and not on the guessed markup. The same replay is run on raw wholesale as well, so how much of the answer rests on the guess is reported (110 trades all-in, 88 raw).

DST is handled by construction, not by a special case. The fetcher iterates in UTC and renders through price.brussels(), so 2025-10-26 comes out 25 points and 2026-03-29 comes out 23 — verified by counting per Brussels day rather than asserting 24, and by checking that October's 02:00 appears twice at +02:00 and +01:00 with two different prices while March's 02:00 does not appear at all. The window is bounded at local midnight: bounding it at 00:00 UTC produced a 22-hour first day, and a 24-hour day silently missing from the end, both of which the point-and-gap accounting caught.

The result, at the shipped default, whatever it is. At cycle_cost_threshold_eur 0.10 widened by FCST-03's no-weather 1.5× to a required 0.1500 EUR/kWh, the real year completes 110 round trips and is net-positive at +24.88 EUR of benefit net of the cycle cost (2 kWh a trade). Unwidened it completes 173. Nothing was tuned: the shipped default and the 2.5/1.5 factors are untouched, and every figure comes out of the same decide().

What the product owner's open decision now has under it. The four independent reports that a static day/night spread of ~0.0840 does not clear 0.10 all stand — a static-tariff site still never trades. What was missing was the other half: a dynamic site's daily spread clears the widened requirement on 121 of 365 days, median daily all-in spread 0.1130. The threshold at which a median day would clear is 0.0754, and at that value the same year completes 156 trips for +35.42 EUR. Both numbers are reported; neither is applied.

And the synthetic year stays, because the real one cannot grade §17. Not one of the 365 real days has a negative dearest hour — 372 negative wholesale hours and 0 days where the strategy would have sold into one — so "0 discharges into a negative-price hour" over real prices is a count of something that could not happen, and deleting the guard would not change it. Section 7B asserts that degeneracy instead of quietly reporting the zero; section 7's generator is still the only thing here that puts a negative price where the strategy would sell.

Size, measured rather than assumed. Plain JSON: 893 KB in the working tree but 74.6 KB as a git object, against 56.5 KB for a committed .json.gz. Git already compresses blobs, so gzipping saves 18 KB and costs a reviewer the ability to read the provenance block — including the licence claim they are meant to check — in the diff. Plain, and load() still accepts .gz for a future dataset that earns it.

Nothing is wired into the add-on. generic_dayahead remains the live fetch path; nothing under app/ imports the script, and the dataset is for replay.

The capacity-peak guard's forced discharge now has an EMS-side energy floor (SAFETY-24). SAFETY-07 can command a discharge to hold a billed quarter down, and nothing below it consulted the state of charge — soc_floor belongs to the maintenance cycle, and freeze.py already recorded that for the grid-following loop "the BMS is the sole energy backstop". On the 2026-08-20 replay the guard asks for 878 Wh in a day. Relying on the BMS is not absurd — it is a real floor and it works — but it is the pack's protection rather than the operator's, and a month of aggressive quarters leaves the battery repeatedly at that cut-out with no EMS-side record of why.

decide() now takes soc and soc_floor, both required and neither defaulted. Above the floor nothing changes. At or below it the guard files a 0 W floor instead of a sized one — one-directional, so charging stays blocked and no discharge is capped — and reports floor_limited with the reason it bound. It is not a trip: every stop in §11.2's table still outranks the claim, and the floor can never be negative, so §9.1's "discharge and export are never capped by the peak guard" survives as a property of the object (swept: 0 negative floors across 1296 combinations of load, elapsed, battery, SoC and floor).

Failing to shave is not silent. A floor-limited cycle raises one notification per episode (goodwe_peak_soc_floor), distinct from the saturation alarm because the two ask the operator for opposite things, and renders its own status row. An unreadable SoC is floor-limited, not a full battery — a full battery is exactly the value that would disarm the floor, and this project has shipped that defaulting once before (| float(100) in the stage-5 loop).

Verified by replay, not by argument. The 2026-08-20 capture is driven against a modelled pack sized from the day's own measured appetite, so it genuinely exhausts: without the floor it reaches the BMS cut-out and sits there for 1227 guard cycles; with it the pack stops at 20.0 % and never touches the BMS. The energy withheld equals the energy between the two floors to within one cycle at the rail. The honest half is reported too — the worst quarter goes from 4338 W to 5030 W, because a floor-limited guard shaves less on purpose.

Two new options, mirrored once. peak_soc_floor (20) and bms_soc_floor (10), whose defaults live in peakguard.PEAK_OPTION_DEFAULTS — TARIFF-02's pattern — imported by validate.py and main.py rather than typed as literals, and pinned to config.yaml by a check that reads the file. CFG-03 still tracks three places. validate.py rule 8 refuses peak_soc_floor <= bms_soc_floor at startup, in CFG-01/MAINT-04's manner. maintenance_soc_floor is deliberately not reused and deliberately not renamed: it is a drain target, not a spend limit, and the rename is recorded as a decision to revisit if a third floor ever appears.

Price arbitrage - the first strategy that trades on a price (OPT-04). Four cards built the price stack and nothing traded on it. app/arbitrage.py is §10.1's priority 3: charge in the cheapest published hour, discharge in the dearest, and only when the spread covers cycle_cost_threshold_eur. It is off by default (arbitrage_enabled: false) - it is the first strategy in this add-on that commands the battery against the meter on purpose.

It consumes the four cards rather than re-deciding anything. Whether a trade is permitted at all, on which two hours, and against which widened threshold is TariffPlan.arbitrage()'s answer (TARIFF-03), and that answer cannot be obtained without first stating whether the peak guard is holding. So §9.1's "give peak shaving priority over arbitrage" is honoured structurally: there is no code path to a tradeable spread that skips the question. And because the claim is filed at P_ARBITRAGE (30) while peakguard files its floor at P_PEAK (50), the arbiter clamps an arbitrage charge even if that interlock were bypassed. Two independent mechanisms, neither re-implemented here.

A guard that never ran is not a guard that is clear. On meter_source: off there is no telegram stream, so the peak guard is never evaluated. That third state is carried as None and it refuses: charging at the rail creates the billed quantity while nothing measures the quarter it lands in. validate.py refuses that configuration at startup too, along with arbitrage armed on a site with no price source at all, and a SoC floor at or above the ceiling.

§17: never export into a negative price. The guard is on the hour being sold into, not on the spread - a day priced -0.30 ... -0.05 has a 0.25 EUR/kWh spread that clears any shipped threshold and a dearest hour that is still negative. Buying in a negative hour stays allowed; being paid to charge is the right trade.

Prices are fetched in the background, never on the tick. resolve_tariff() may open an HTTPS connection, and the control tick is what feeds the ESP32 heartbeat - a supplier's TLS timeout there is a supplier able to push the add-on towards layer 1's 30 s veto. A separate task refreshes every 30 minutes; the tick reads an attribute and an age bound, and a plan whose refresh has stopped answering retires rather than standing as if it were current.

What is honestly not measured. The acceptance criterion asked for net-positivity across 12 months of replayed prices. This repository holds no price history - scenarios/ is P1 meter data - so that criterion is not met, and is not restated. What test_arbitrage.py section 7 does instead is replay a synthetic year and assert the property that does not need real prices: every executed round trip cleared its own widened requirement, on all of them, across a year containing 522 hours priced below zero and zero discharges into one. And at the shipped 0.10 EUR/kWh threshold a realistic Belgian day/night site does not trade at all - reported, not tuned. That number, and the widening factors beside it, are one product decision and it is open.

Provisional prices, and what may not rest on one (FCST-03). Day-ahead prices arrive once a day, around 14–16 h CET. Until they do, §8.3 says the unknown hours use yesterday's profile and are flagged provisional: true — and no irreversible action may be taken on a provisional price. app/price_forecast.py does the fill, and the whole module is shaped by one defect: a carried-forward point and a published one are the same three fields and a bool, so the natural line PricePoint(..., provisional=y.provisional) copies yesterday's False onto today's guess and produces stale data presented as current. That is the meter-side SAFETY-18 failure one layer up — the reading arrives on time, looks fresh, and is wrong.

So the flag is never passed through. Carried points are built by a constructor that has no provisional parameter at all (the literal True lives in one place, and there is nothing for a caller to forget or copy); published points are passed through by identity, so there is no copy that could lose a flag; and an audit re-derives the expected flag for every emitted point from the set of hours the feed actually published and raises rather than repairing one. A published point may itself be provisional — eneco_eddy's current-quarter imbalance print is — so the audit's rule for a published hour is "whatever the feed said", never "False".

The fill keys on the Brussels wall clock, not on t − 24 h. A 23-hour day has no 02:00 and a 25-hour day has two, so a fixed 24-hour subtraction shifts every carried hour by one across a transition and misprices a whole day with nothing to show for it. Re-running the fill after a late publication replaces the carried hours with the real print: the number and the flag move together because the series is rebuilt, never patched.

Arbitrage now drops provisional hours instead of refusing the whole day. The refusal that read "the plan is provisional" would have switched arbitrage off every morning on every dynamic site once carry-forward filling landed — a part-firm series is the normal state before the print. What §8.3 forbids is acting on a provisional price, so the provisional hours are dropped and the spread, the cheapest hour and the dearest hour are computed over the published ones only; fewer than two firm hours is still a refusal, which is where the §11.4 fallback (wholly provisional) lands. The permitting variant now refuses to be constructed around a provisional point at all. The cheap-window flag became per-hour for the same reason, so a site's maintenance charge floor does not go dark every morning.

Real-time / imbalance products get measurably wider thresholds. One widening path, driven by a set of active uncertainty sources: the product's own (§9.2 row 2, derived from the declared PriceProduct and never from a plugin id) and §11.4's "no weather data" row, which the spec widens by a different trigger and which is the same mechanism. The combination rule is max, not a product — two independent doubts must not compound into a threshold nothing can clear. The caller supplies the base round-trip cost threshold, so OPT-04 still owns what the number is; this owns only how much wider it gets and why, and the allowed verdict reports the threshold it cleared.

An irreversible action is a value, not a judgement call at each call site. Irreversible carries the hours an action commits — the maintenance drain's window is derived from maintenance.DRAIN_TIMEOUT_MIN rather than typed twice — and the gate looks at exactly those hours, blocking on a provisional one, on an hour the series does not cover, and on no price data at all: three different reasons, none of them an answer. ⚠️ It is the entry point for a start being justified by a price; the calendar path main.py runs today is untouched, because a gate that blocked on no_data would stop the monthly cycle on every default install — §12's opening sentence.

Zero new options. No config.yaml key, no new defaults dict, no o.get(k, X) in main.py: the module reads no options at all, so CFG-03 did not widen.

The grid-following loop is now capped against the month's billed capacity peak (SAFETY-07). New app/peakguard.py. TARIFF-01 measured the quarter; this is the consumer it was built for. Every cycle the guard projects the open quarter, compares it to a ceiling and files ONE arbiter claim: a lower bound on the setpoint at P_PEAK. That shape is both behaviours §10.1 asks for — a hard clamp on charging and pre-emptive discharge — and it cannot cap discharge or export, because a floor cannot. excess = 900 × (projected − ceiling) ÷ remaining, and the floor is the MEASURED battery power plus that: a floor built on the standing command winds itself to the rail whenever the inverter fails to follow, and one built on delivered power cannot.

It trips where SAFETY-18 only notifies, and the captures decided that. On the healthy reference day it engages on zero of 95 quarters; the action is level-triggered, unlatched and re-derived every cycle, so a false engagement costs one cycle of discharge rather than a parked battery. Replayed on 2026-08-20 the billed quarter goes from 5029.8 W — above the inverter's own 5000 W rating — to 3485 W, under the soft limit and without saturating. Quarters under the limit across both committed days: 189/190 → 190/190. Two days is not thirty; AC 3 is still TARIFF-01's open item and this does not claim it.

Blindness forbids importing, and it is checked before the projection is graded. A fresh averager projects a confident 0 W, which is under every ceiling there is; a meter gap longer than meter_max_age_s makes the projection read LOW; and a frozen meter reading export projects 0 W at full coverage. All three become a floor of 0 W, which is one-directional and cannot cost pack energy. That is the backstop SAFETY-18 could not be — its alarm arrives at 300 s of a 900 s quarter and commands nothing. The frozen term is freeze.looks_frozen() itself, evaluated on this cycle's standing command, not a second copy of the conjunction.

The ceiling is peak_cap_w, raised only by an OBSERVED reading. NO_RECORD and NOT_OBSERVED both leave it at the cap, so an unreadable peak store makes the guard STRICTER. The gate is the reading's STATE, not whether a number happens to be attached to it: today a peak_w is not None test behaves identically, and depending on that coincidence is how a future last-known-peak field would silently raise the ceiling off a read that failed. headroom_w() is deliberately not consumed — cap − peak turns a zero peak into FULL freedom.

Two defects found building it, both in the interaction rather than the arithmetic. A LIMIT does not out-vote another LIMIT — arbiter.resolve() applies every limit at or above the winner's priority and takes the most restrictive — so the peak floor (lo ≥ 0) and the maintenance charge-only shaping (hi ≤ 0) resolved to a CONTRADICTION and 0 W, parking the battery in the exact quarter it should shave. Fixed by suppression rather than priority: main.py drops the maintenance shaping while the guard is engaged, which is what that branch already did for the optional peak_forecast_entity — a key that is empty on a default install, so until now the suspension could not fire on the site that needed it. And thresholding excess > 0 released the claim the instant it started working, producing seventeen engage/release cycles in one 900 s quarter (§10.2's oscillation) and leaving that quarter 49 W over; the threshold is now the floor itself, which is the same arithmetic read as a level rather than as a switch.

PeakTracker.project() no longer reads a private name with a default. getattr(averager, "_last_net", 0.0) failed quiet AND in the disarming direction: a rename credits 0 W held, the projection reads low, and the money guard does not engage. QuarterAverager.held_net_w is now a documented public property, read without a default, and Projection carries it. TEST-13 item 4.

No new option, and no fourth defaults site. The ceiling is peak_cap_w, the coverage threshold is meter_max_age_s, the freeze predicate is meter_freeze_s, and the achievable discharge comes from max_w and the device rating. config.yaml and validate.py are untouched; §14's capacity_peak_limit_kw stays declined as the kW/W mismatch trap it is. On meter_source: off there are no telegrams, so the guard does not run at all and the status page says NOT COVERED — running it there would have blinded it permanently and stopped every legacy install from charging, which is what the first cut did until test_clamp.py's export case caught it.

Static day/night and fully-fixed tariffs, first-class (TARIFF-03). §9.2 puts a large share of the Belgian installed base on a static profile, and an EMS that only works under dynamic pricing is an EMS for a minority. A new static_profile option describes a two-period day/night tariff — or a single fixed price — as JSON, and app/static_tariff.py turns it into the same canonical {start, eur_per_kwh, provisional} series the fetched providers emit, so nothing downstream learns that a tariff can be static.

It is not a sixth provider plugin, and the reason is mechanical. PriceProvider.capabilities() is a classmethod, so a plugin's PriceProduct is fixed when the class is written — but §9.2 makes STATIC and FIXED two different products with two different required behaviours, and which one a site is on is a property of the operator's data, not of any class. StaticProfile.product derives it from the number of distinct prices instead. The second reason: the plugin framework exists to stop a fetched figure being marked up twice, and a number the operator typed as all-in has no publisher to disagree with.

So the profile sits where §11.4 already says it does — under the providers, as the fallback. The configured-product path and the feed-is-down path are the same generator differing in one flag: provisional. A static-tariff site runs that path every day, so the degradation path for a dynamic site cannot rot unused.

"No arbitrage" is a type, not a boolean somebody has to remember to check. TariffPlan.arbitrage() returns a variant: the allowed arm carries the spread and the cheapest and dearest hours, and the refused arm carries a reason and nothing else — .spread_eur_kwh on a refusal raises rather than answering 0.0. An optimiser cannot compute a trade from a refusal because it cannot get the inputs out of one. Four refusals, all derived: the peak guard is holding, there is no price data, the plan is provisional, or the series is flat. That last one is AC2 — a fully-fixed tariff disables arbitrage by arithmetic rather than by matching on an enum, and a dynamic feed that happens to print one price all day is refused for the same true reason.

Peak shaving outranks arbitrage, expressed so OPT-04 cannot skip it. arbitrage() takes peak_guard_active as a required keyword argument, so the spread is not obtainable without first answering whether §10.1's priority 2 is holding. §9.1's capacity tariff is a network cost charged whatever the energy product is.

Time-window shifting reaches the one shiftable load that exists. main.py's cheap-window flag — previously fed only by the price_now_entity / price_avg_entity pair — now falls back to the static profile, and the Web UI gained a Tariff row naming the window, the price, when it next changes and why it is or is not cheap. The rule is strictly below the seven-day mean: under a flat tariff <= would call every hour cheap and a fixed-tariff site would top up from the grid at any hour, which is the opposite of self-consumption only. Seven days rather than 48 hours because a 48 h mean taken on a Friday is two-thirds weekend, and the same Tuesday 09:00 would come out cheap or dear depending on when you asked.

A profile must tile every day type exactly once, checked at startup. A gap is refused with the uncovered range named rather than filled in — an invented price is one an optimiser would trade on — and an overlap is refused because otherwise one of two prices wins silently on list order. The trap this catches in practice: 22:00–07:00 mon-fri does not cover Saturday morning, because a window applies on the day the clock reads.

validate.py rule 7's stated reason expired, exactly as TARIFF-02 predicted. That ticket left a tripwire in test_price.py section 12 asserting that nothing in app/ consumed load_prices(), with instructions to fix the refusal's wording in the same commit when it went red. It went red naming static_tariff.py. The message now says what is true instead — the series is consumed, but main.py acts on the static side of it and not on a fetched one — and the tripwire is re-aimed rather than removed: the consumer set is pinned, so a second consumer (OPT-04) goes red again, and the expired phrase is asserted gone so a bad merge cannot restore it. Rule 7 also grew a second refusal: static_profile alongside the Home Assistant price pair is the same silent-loser conflict, and a live one.

No new place for an option default (CFG-03 is not widened). static_profile was added to app/price.py's PRICE_OPTION_DEFAULTS — the one in-code mirror TARIFF-02 created and pinned to config.yaml by a check — rather than to a defaults dict in the new module, which has none. main.py grew no o.get("static_profile", …) fallback. That is TARIFF-02's pattern, stated here so a reviewer does not have to infer it.

Measured, on the data that exists. test_static_tariff.py replays the two committed days of this house's real P1 meter (scenarios/p1-net-2026-08-{20,23}) priced under a Belgian day/night profile. 2026-08-20 is a Thursday: 15.220 kWh imported, 9.606 in the day window and 5.614 in the night one, EUR 4.7185 under day/night against EUR 4.6725 flat, and shifting the day-window energy into the night window saves EUR 0.8069 — which is 9.606 kWh x the 0.0840 spread, derived twice and required to agree. 2026-08-23 is a Sunday: 0.728 kWh, all of it night-priced, which is the weekend row proving itself on real data. §17 names six Belgian scenarios and a static-profile case is not among them; this is the seventh, and it is two captured days rather than a season — the file says so rather than implying an annual figure.

Also worth knowing before OPT-04: on realistic Belgian day/night numbers the whole-tariff spread is about 0.08 EUR/kWh, below the shipped cycle_cost_threshold_eur of 0.10. A correct optimiser will decline to cycle for the tariff alone on such a site. That is a product finding, not a defect.

Price provider plugins, and one canonical all-in price format (TARIFF-02). app/price.py ships five providers - generic_dayahead (wholesale EPEX BE), engie_dynamic, totalenergies_dynamic, eneco_eddy and the offline manual_csv - all emitting exactly {"prices": [{"start", "eur_per_kwh", "provisional"}]}, tz-aware at the Brussels offset, EUR/kWh, all-in. Nothing consumes it yet: this is the seam, landed first, so that the arbitrage work that follows never learns a supplier's name.

Double-counting the markup is refused rather than discouraged, given a correct declaration. A plugin does not return a price; it returns the figure its source published and declares which of {energy, markup, taxes} that figure contains. The framework adds the complement, once. Engie and TotalEnergies publish a retail figure with their margin already inside; adding the configured 3 c/kWh on top would make every future arbitrage decision wrong by that amount with nothing reporting it.

Two mechanisms, because one was not enough. PluginOptions raises on the framework-owned keys - and review of PR #16 then wrote a double-counting plugin three more ways, one of them touching nothing but PRICE_OPTION_DEFAULTS, a public dict in the module every plugin already imports. So register() now also refuses at import any plugin whose own code mentions a framework key (code_leaks(), docstrings stripped via ast so a plugin's mandated SOURCES: line does not false-positive). Honest wholesale baseline 0.188 EUR/kWh; every attack landed 0.219.

The guarantee's precise shape, stated because an overclaim is worse than no claim: the framework adds the complement exactly once given a correct sources declaration. A plugin that declares {energy} while its feed is really all-in still comes out one markup high while touching no framework name, and no code can catch that - the declaration is the plugin's unverifiable claim about somebody else's tariff. What is mechanised is reachability; what stays human is truthfulness.

The product type is declared, not inferred from the plugin's name. eneco_eddy is a real-time/imbalance product and gets widened arbitrage thresholds; that reaches a consumer through capabilities().product and volatility_regime(), never through a name comparison. test_price.py asserts mechanically that no plugin id appears anywhere in the framework's own code, and drives a sixth provider defined inside the test file to the correct regime with price.py untouched.

"No price data" is a type, not an empty list. Following the same rework sim/riglock.py took, a fetch returns PriceRead.series(...) or PriceRead.no_data(reason), and only the first carries fields. An empty series is not constructible; no_data has no .points to iterate, no .at(), and .get("points", []) raises rather than returning the default. A day of free electricity and a day with no prices are different instructions - arbitrage is pointless under the first and forbidden under the second - and an implementation that returns [] on a failed fetch cannot tell them apart. Every site-level failure returns no_data; nothing raises into the control tick.

What is not verified, and cannot be by an offline suite: every fixture is synthetic, so the five feed URLs and JSON shapes are checked against a belief about what those suppliers publish, not against the feeds. The parse layer is exercised; the contract with each supplier is not. Expect the first live fetch of each to need a shape fix, and note that a wrong shape degrades to no-price-data rather than to a wrong price.

manual_csv is the documented offline fallback and needs no network, no supplier account and no HTTP stack. See DOCS.md for the format. Its start column must carry a UTC offset - a bare local timestamp is refused, because one hour every October names two moments.

Injection is priced separately (export_price_eur_kwh), a scalar rather than a second series, and negative values are accepted. Consumption plugins cannot reach it.

price_provider may not be combined with price_now_entity / price_avg_entity - the add-on refuses to start on that pair. The Home Assistant sensors are the existing delegation of pricing to HA and still work alone; with both configured they would silently keep deciding while the status page named a supplier that decided nothing.

No timezone database is used. The shipped Alpine image has no tzdata, so Brussels offsets are computed from the EU rule and every instant is carried as UTC and rendered at the offset that applies to it. The checks drive both 2026 transitions - the 23-hour and 25-hour days - rather than a normal day, where a fixed 24-slot implementation and a correct one agree.

The capacity-tariff peak is now measured, banked and survives a restart (TARIFF-01). New app/tariff.py. The 15-minute block average itself was already built and unwired - p1.QuarterAverager computes clock-aligned 900 s blocks, time-weighted over irregular telegram spacing, offtake-only and per-phase - and P1Ingest.blocks was a 96-entry list a restart erased. This adds the SQLite behind it (/data/tariff.db): one row per completed quarter in the indefinite 15-min tier, one row per calendar month in the permanent peak tier, and no DELETE against either anywhere in the module.

Blocks, not a sliding window. The card says "rolling"; 9.1 bills "the highest 15-minute average offtake", stated per QUARTER. "Rolling" here means continuously updated, not a trailing-15-minutes window - a trailing window reports a peak the meter never bills, and reports it HIGH, because a burst straddling :15 fills it completely while contributing to two block averages at partial weight.

A restart mid-block resumes it, and a restart that outlives the block banks it. QuarterAverager grew snapshot()/restore(); the tracker checkpoints the open block every 15 s (worst case 1.7 % of one quarter) and clears the checkpoint in the same breath as a block close. The held sample keeps its ORIGINAL timestamp across the restart, so the outage is integrated under the same max_hold_s rule a running process would apply and uncovered seconds drag the closed block DOWN rather than being held forward. quarter_start is the primary key and a re-bank may only ever RAISE a figure, so a replay cannot double-count and a partial re-run cannot lower a quarter already measured.

An unreadable store is not a zero peak. peak() answers OBSERVED / NO_RECORD / NOT_OBSERVED and carries peak_w = None unless observed - the riglock.holder() fix applied to something that spends money. A peak read as 0 W hands SAFETY-07 maximum headroom and silently disarms the guard at the moment its own storage breaks, so there is no accessor that defaults it: a caller who forgets gets a TypeError, and the status page prints a different row for "no quarter yet" than for "the database did not answer".

Calendar months are LOCAL, blocks are UTC. A quarter starting 22:15 UTC on 31 August bills in September. Block alignment still needs no timezone.

No new option, and no second peak entity. The soft limit is the existing peak_cap_w; config.yaml and validate.py are untouched, so CFG-03 is not widened. peak_forecast_entity stays the input to maintenance_charge_floor()

• repointing that consumer changes what moves energy and belongs to SAFETY-07.

It measures and nothing else. No claim, no clamp, no command; graded on the parsed syntax in test_tariff.py, which also proves the same grader lights up on main.py. Per SAFETY-20, the quantity is DELIVERED power - tariff.py only ever sees P1Sample, the meter's own reading, never a setpoint.

AC 3 is not met and the check says so. It asks for 30 days of replay; two days of this house's real meter exist (2026-08-20, 2026-08-23), now committed as scenarios/p1-net-*.jsonl.gz. test_tariff.py part 9 replays them, reports the percentage under the shipped limit next to the sample size in days, and asserts nothing about the 95 % figure.

A computed setpoint over the rating now alarms instead of being clipped in silence (SAFETY-03). The clamp was never the missing half - specs.md 10.3 records an unclamped integrator climbing ~130 W per 4 s past 10 kW and reporting 14 768 W while pinned at the 5 kW rail, and a silent clamp turns exactly that into a flat, legal-looking 5000 W hold. write_setpoint() - the one path every write takes, cycle, heartbeat, operator button and shutdown alike - now clamps to the validated max_w and reports whether the raw value differed, and Controller.check_output_clamp() raises OUTPUT_CLAMP: a persistent notification (goodwe_output_clamp), an ERROR, an event row and a red status banner. Not a trip: the clamped value is written and the loop keeps running, per 11.2's "clamp and alarm".

The bound is max_w and nothing is min()ed at runtime. Section 14 requires the loop clamp and the driver's setpoint_limit_w to agree, validated at startup with a refusal on mismatch - which CFG-01 already ships. The device range is still applied second, as defence in depth; after a successful validation it cannot engage, so if it ever does, that is louder than the first stage and it alarms too, naming the bound. No new config key: the guard's limit is the one the operator already set, and its cadence is a module constant.

Decision grew i_clamped / clamped booleans, and that is the load-bearing part. reason is one string that later stages overwrite - a cycle that clamps the integrator and is then slew limited reports slew-limited, and one that clamps while saturated reports saturated-freeze. Both are the winding case, so an alarm keyed on the string is silent on exactly the cycles it exists for: mutating main.py back onto "clamp" in decision.reason drops the 10.3 replay from 2 engagements to 0. The flags are set where the clamp happens and are never overwritten. On a default install (integrator_max_w following max_w) the integrator bound is the one that bites and the output clamp is unreachable, so the integrator flag is the whole signal.

Distinct from the saturation freeze, and checked in the negative. A clamp is a software bug signal; saturation is the hardware failing to follow a legal command, and its action is to freeze the integrator, not to alarm. They share no reason code, notification id, status row or counter. test_clamp.py drives a loop that saturates for 10 consecutive cycles at 1.4 % of the rating and asserts zero clamp notifications, zero engagements, no log row and no status row - after first asserting that the saturation freeze really did engage, so the silence is an observation rather than a scenario that did nothing.

The action log is coalesced per episode, and that was a real bug. log_event() keeps 40 rows; one row per engagement flushed the entire ring within 40 cycles of a winding loop, and the first thing it evicted was SAFETY-18's own METER FROZEN? row - this guard silencing another guard's log. Caught by test_freeze.py going red, not by inspection. One row per episode now, carrying the exact engagement count read off the counter.

A non-finite setpoint is refused, and it was worse than passing one through. nan is loss of input (11.1 rule 1: command zero, keep commanding), not an out-of-range value. Measured: because every comparison against nan is False, a naive max(-limit, min(limit, nan)) keeps its first argument and turns a nan into a command at the full rating, then reports it as a clamp engagement.

Review fixes (PR #12). Three, and the first was a behavioural regression this PR introduced: clamp_to_rating() returned early from the max_w stage, so the device bound - the "applied second, defence in depth" half - was reached only when the rating bound had NOT fired. The bigger the overshoot, the less the guard did. At max_w 5000 against a +-4000 device, +9999 emitted +5000 W, outside the device range, while a mere +4500 was correctly held to +4000. That undid the pre-PR guarantee "never send a value the device will reject outright" and undercut this module's own case for clamping to max_w rather than a runtime min(), which rests entirely on that stage catching a validation that did not run. Both stages now always run, the result names both bounds when both bite (max_w+device), and the property is asserted over a 492-point sweep rather than on witness values - the defect was invisible to any single-value check that happened to sit inside one stage. No reachable production path was found for it (two validation gates and the arbiter bound sit in front), but latent is not harmless.

Two harness defects, both of the kind where a check cannot fail for the value it forbids: the hysteresis check issued range(CLEAR_CYCLES - 1) clean cycles, which at CLEAR_CYCLES = 1 issues zero and passes while printing "0 clean cycles do NOT clear it" - green for the chatter setting the constant exists to prevent. And the re-assert check stimulated at REASSERT_S + 9, green for any value including 3600, i.e. the hour of silence the module promises not to produce. Both are now written in wall-clock terms that do not move when the constant does: one clean cycle must not clear the alarm, and a loop pinned across the 900 s capacity-tariff quarter must speak at least 5 times and on no more than 20 % of cycles. CLEAR_CYCLES = 1, REASSERT_S = 3600 and REASSERT_S = 0 each go red.

test_clamp.py (new, assert-based, no framework) covers the clamp arithmetic and its boundaries - exactly +-max_w is not an engagement - the alarm's edge/re-assert/hysteresis cadence, the 10.3 runaway replayed through the real Controller.cycle() against an unclamped transcription, the saturation negative, and the direct-write path. Six author mutations reproduced red, including "clamp kept, alarm deleted" (the historical build) and "alarm keyed on reason". Two of the check's own hypotheses about how the freeze and the clamp interact were refused by the sweep and rewritten to what it measured: a frozen cycle can clamp, and does so exactly when the integrator reverses.

test_freeze.py's notification assertions now filter by notification_id rather than by service - the add-on raises more than one kind of notification, and its railing scenarios legitimately raise this one too.

Cheap-window maintenance charging was unreachable at the shipped defaults, and now the config that makes it unreachable is refused (MAINT-04). config.yaml shipped max_w: 2000 against maintenance_charge_w: 2500. The cheap-window shaping files Claim.limit(hi = -maintenance_charge_w) against the supervised SAFETY limit's lo = -max_w, so lo > hi — the arbiter's clause 3, correctly resolved to 0 W and logged as a CONTRADICTION. Maintenance silently never charged in a cheap window on a default install, and the only evidence read like a bug in the arbiter rather than like the two numbers an operator set. Measured against the real arbiter, loop asking +500 W:

max_w=2000  hi=-2500  ->     +0 W  contradiction=True
max_w=2500  hi=-2500  ->  -2500 W  limited by supervised(max_w)
max_w=3000  hi=-2500  ->  -2500 W  limited by maintenance(cheap-window charge)

validate_startup_config() now refuses maintenance_charge_w > max_w (rule 6), the same shape as CFG-01's sign_disagree_w >= max_w: a number the operator set, overridden by a layer they cannot see. Equality is reachable (-max_w is a single valid point) and deliberately not refused. Verified by starting the add-on on the pre-fix pair: exit 78, the refusal banner, no traceback.

maintenance_discharge_w was checked, not assumed, and it is NOT the same case. The shaping is not symmetric. The drain phase does not shape the loop, it OWNS the actuator — Claim.set(P_MAINTENANCE, +discharge_w) — and a SET is clamped by the limits above it rather than contradicted by them. 2500 against a 2000 W ceiling emits +2000 W, and the arbiter's own explain() prints maintenance -> 2000 W, limited by supervised(max_w) every cycle. Nothing is silent and energy still moves; the cycle completes slower (13.8 kWh usable at 2000 W is ~6.9 h against the 720 min drain timeout). Warned about, not refused.

The shipped defaults changed so the validator does not reject them. maintenance_charge_w and maintenance_discharge_w are now 2000, at the shipped max_w. max_w was deliberately NOT raised instead: it is the supervised safety ceiling and raising a default upward ships more power to every new install. Raising max_w (the reference install runs 5000) is what unlocks a faster maintenance cycle — raise it first, then these. test_validate.py now reads config.yaml itself and asserts the shipped numbers pass the rule, so a default that the validator refuses cannot ship again.

⚠️ Upgrading an existing default install: the add-on may refuse to start

An install still carrying maintenance_charge_w: 2500 against max_w: 2000 now meets rule 6 and exits 78 with the refusal banner instead of starting. That is the intended behaviour — the configuration was already broken, it was just silent about it — but an add-on that will not come back after an update needs the fix stated here rather than only in the log.

The fix, either way: set maintenance_charge_w to 2000 or lower, OR raise max_w to 2500 or higher (Settings → Add-ons → GoodWe RS485 Controller → Configuration), then start it. The banner in the log says the same thing and names both numbers.

Whether you hit this at all depends on whether the Supervisor kept the old value, and both cases are covered above because we did not verify which one applies here. The Supervisor merges an add-on's stored options over the defaults in config.yaml, so:

• A key the operator never edited re-derives from the new config.yaml and becomes 2000 on upgrade. Non-event, nothing to do.
• A key the operator did set persists at 2500 and the add-on refuses to start until it is changed. Note this includes anyone who used the Configuration page's YAML editor, which writes the whole options block back — so "I never touched that field" is not a guarantee the old value is gone.

⚠️ This is reasoned from the Supervisor's documented merge behaviour, not measured on the live install. The reference install's stored options could not be read (/api/hassio/ refuses a long-lived token) and probing it was out of scope — it regulates a real battery. It runs max_w: 5000 and is unaffected either way.

⚠️ Known, deliberately left, and worth a follow-up: main.py and maintenance.py still fall back to 2500 when the key is absent from the options dict, while config.yaml and validate.py now say 2000. Unreachable on a Supervisor install (every key is always supplied) and reachable only from tests/sim. The real fix is one source of truth for option defaults, which is bigger than this ticket and touches files another ticket is in.

0.5.2

A meter frozen at a wrong-but-fresh value now raises an alarm. It still is not stopped. (SAFETY-18)

A meter that answers 200 OK with a stale document forever is arriving on every poll, so every freshness mechanism in the stack reads it as healthy: meter_max_age_s is reset by each response, the firmware watchdog is fed by the heartbeat and by a sample age that never climbs, and the arbiter contributes only ±max_w. The loop integrates a constant error and rails — replaying the real compute() at 15 s cycles, in 150/60/30 s at max_w: 2000 for a meter frozen at 350/1000/≥3000 W, and 360/135/75 s at max_w: 5000. The live install runs max_w: 5000, which is both the schema maximum and the device rating.

The new detector (app/freeze.py) is a conjunction, not the bare unchanged_s threshold TEL-05 measured and rejected:

unchanged_s ≥ meter_freeze_s   AND   |command| within 5 % of max_w

Both terms already existed and were already on the status page. They fail for independent reasons: at the converged point the command is nowhere near the rail, and at the rail against a real load the kWh registers move within seconds. At the shipped 300 s there is also a structural relation, not just a margin — the slowest a healthy 1 Wh register can tick and still look unchanged is 12 W, which is inside the 15 W deadband, so the command there is parked at 0 W and the two halves cannot both be true.

Notification only, deliberately. An HA persistent notification (fixed notification_id, so a repeat replaces rather than stacks), an ERROR log line, a UI event and a red status banner. No claim, no latch, no 0 W: a false trip parks the battery and the operator's next move is to switch the guard off; a false notification costs an alert. The trip is a separate decision that needs data from a real install.

• New option meter_freeze_s (default 300, range 60–3600, no "off").
• Only meter_source: homewizard_local is covered — it is the only transport that sees the meter's own document. Everywhere else the status page says NOT COVERED rather than "armed".
• DOCS.md now states the capacity-tariff exposure this does not close: peak_cap_w caps maintenance charging and nothing caps the loop, so a lying meter can drive a 5 kW unattended import, and ≥15 minutes of that sets the month's billed peak (measured: one 4998 W quarter moved a monthly peak from 4832 → 5013 W). That cap is SAFETY-07.
• test_freeze.py grades it in both directions: silent over 40 minutes of the live house's real converged capture (committed as scenarios/p1-age-2026-08-26.jsonl.gz), silent over an hour of TEL-05's low-power case where a bare threshold is shown to fire, and alarming on a genuinely frozen meter driven over real HTTP through the real HomeWizardLocalSource — against the rig's own hwsim freeze fault when the infra repo is reachable, an equivalent stub otherwise. Its negative twin is the load-bearing one: the same railed command against a meter that is still moving must stay silent at the same threshold.

0.5.1

SAFETY-02's latch now survives an add-on restart, which is the difference between a latch and a pause. auto was persisted and sign_wd.tripped was not, so reconstructing the Controller against the same store — exactly what a container restart does — brought it back armed, into the same fault, with no operator involved: tripped=False, banner back to NOT READY, and it resumed commanding (measured: −1000 W, −2000 W) before re-tripping 180 s later. Under a Supervisor that restarts a crashed add-on that is a loop of three-minute wrong-direction bursts — and "restart the add-on" is the first thing an operator looking at a FAILSAFE banner and a 0 W inverter will try.

sign_tripped and sign_reason are now Store keys beside the maintenance state, written the moment the trip happens (reason first, flag second, so a crash between the two can never persist a latch with no explanation) and restored in Controller.__init__. Cleared only by the operator's start. DOCS.md said "it does not clear itself"; that was false across a restart and now is not.

Also in this release, all of it review follow-up rather than new behaviour:

• The arming gate is tested against the real arbiter. It was the decision the whole ticket turns on and it was asserted in three comment blocks and verified by nothing — every case passed following in as a literal. test_watchdog.py now derives it from resolve() across twelve claim configurations, including the redirect case winner == "loop" alone would have got wrong and the lo limit that raises magnitude without flipping sign.

• The MQTT status: "failsafe" value is tested. The check that claimed to cover it restated the assertion three lines above it and never touched the payload.

• A forward hazard written down where it will be read, and made to bite. winner == "loop" disarms the watchdog under any higher-priority SET claim. Today only maintenance and the safety stops emit one and neither follows the meter; a peak-shaving strategy at P_PEAK does, and would blind the watchdog for every peak event.

  The gate is now watchdog.loop_is_following(), called by both main.py and the test, for the same reason disagrees() was extracted: the test held a transcription of the shipped expression, so editing the shipped gate alone to winner in ("loop", "peak") left every suite green while the watchdog went blind. Two copies, and the one that drifts is the one doing the grading.

  ⚠️ Extracting it was not sufficient on its own. The realistic P_PEAK row — peak shaving asking for more than the loop — still could not detect the widened gate, because the magnitude term rejects it regardless and masks the winner term. A second row with peak asking for less isolates winner as the only deciding term, and that is the one that turns red.

• The worked example described a configuration that does not ship. At the defaults maintenance_charge_w (2500) exceeds max_w (2000), so that claim is an arbiter contradiction resolving to 0 W, not a −2500 W charge. The example is now written at 1500 W. (The contradiction is a real pre-existing bug — a default cheap-window maintenance charge silently never happens — filed separately, deliberately not fixed here.)

• disagrees() is public, so sim/replay_sign.py stops carrying its own copy of the predicate it grades.

• held_s takes the clock instead of reading one, restoring the pure-function property the module advertises.

• The sign_reason-before-sign_tripped write ordering is enforced, not just documented. Swapping the two lines used to pass every check. A store that fails the second write now proves the property the ordering exists for: what survives a crash mid-trip is a reason with no latch, never a latch with no explanation.

• Measured figures corrected throughout: 93.4 % / 4212 of 17280 (was 92.9 % / 4127 of 16349), per-cluster 0.3 / 0.9 / 10.5 / 0.0 %.

0.5.0

SAFETY-02 — the sign-disagreement watchdog. The add-on now watches whether the setpoint it is emitting and the grid figure it is regulating on point the same way. If they oppose each other, both over sign_disagree_w (300 W), for sign_disagree_s (180 s) continuously, it files a failsafe claim at P_SAFETY, commands 0 W, and latches there until an operator starts control again. New module app/watchdog.py; new options sign_disagree_w and sign_disagree_s.

This is the gap the existing failsafes leave open. The stale-input watchdog asks whether the meter is still talking, the saturation freeze asks whether the inverter can follow, the output clamp asks whether the number is too big — a loop can pass all three while charging the battery out of the grid, because the only thing wrong is the sign. On 2026-08-20 a commercial controller did exactly that four times in one day, for up to 77 minutes at a stretch, and reached a commanded −14 768 W against a ±5000 W inverter.

Validated against that day. sim/replay_sign.py in the infra repo drives this module over the committed RS485 captures of both 2026-08-20 (the four episodes) and 2026-08-23 (healthy): 18 trips on the fault day, every one inside a window NOTES.md §4.7 accounts for, and 0 on the healthy day. The four episodes do share one signature rather than merely resembling each other — sign agreement runs 0.3 / 0.9 / 10.5 / 0.0 % inside them against 93.4 % on the healthy day.

Three decisions worth knowing about:

• It is disarmed whenever the grid-following loop is not what is driving. Sign agreement is a property of a loop that follows the meter. A maintenance grid charge opposes the meter by design — 2500 W of charge into a house drawing 500 W is +3000 W on the meter against a −2500 W command, for hours — and armed unconditionally this would trip on every maintenance cycle. The gate tests the emitted number, not the winning claim's name: a limit claim can let the loop "win" and still replace its value with one pointing the other way.
• The trip latches. Commanding 0 W removes the command side of the comparison, so the disagreement always clears the moment the trip works. Un-latched, this would trip, clear, and hand the actuator back to the loop that was driving the wrong way, every three minutes forever.
• sign_disagree_w at or above max_w is refused at startup (validator rule 5). The arbiter never lets a command exceed max_w, so such a threshold makes the watchdog incapable of firing while the status page still reports it armed. A disarmed guard that advertises itself as armed is the failure mode this project keeps refusing to ship.

What it does not catch, stated so nobody assumes otherwise: an inverter that acts opposite to what it was told moves the meter further the same way, so command and meter agree while everything runs away. That is the saturation freeze's job, which compares the command against the battery's actual power.

test_validate.py's "the smallest sane max_w still starts" case now names a reachable sign threshold, because a 1 W ceiling genuinely does disarm the 300 W default and is now correctly refused.

0.4.0

CFG-01. The add-on now refuses to start on a configuration it cannot honour, instead of logging a line and carrying on. validate_startup_config() runs in amain() before the broker, the web server or any task exists, so a refusal cannot leave half a controller running behind a UI.

It refuses only where continuing produces one of two outcomes: (a) a stated limit is untrue - the operator configured a bound and a lower layer silently enforces a different one - or (b) the add-on is inert and indistinguishable from healthy. (b) is not a special case of (a): with no setpoint_entity, layer 1 pinning the inverter at 0 W is the failsafe working. The system does not become unsafe, it becomes a convincing impression of a working controller.

Four things qualify:

• max_w above (or below) the setpoint device's own rating. This is the one that changed behaviour. It used to warn the device wins and run anyway, with write_setpoint() silently clamping, so the configured ceiling was never the real one and the only evidence had scrolled off the log. The refusal names the configured value, the device's value, and which wins.
• No setpoint_entity. A controller with no actuator: every write is a no-op, the device rating is never read, and the ESP32 heartbeat that holds off the layer-1 failsafe never happens. It ran, looked healthy, and moved nothing.
• A meter_source that can never produce a reading - missing p1_host, missing p1_net_entity, a blank MQTT topic, a phase list disagreeing with meter_phases, an unknown source name, or a meter_poll_s at or past meter_max_age_s. These were already caught, but they only disabled ingestion, which leaves the grid reading None forever: permanent "inputs missing", 0 W, and a status page indistinguishable from a healthy meter nobody has sent anything to yet.
• meter_max_age_s above the firmware's ingest veto. The schema accepts int(5,300); the ESP32's threshold is a compile-time max_age_s: "30" and it trips layer 1 at p1_age_s >= 30. Set 120 and the add-on treats a 119 s reading as fresh and keeps commanding, while the firmware has already vetoed and is holding the inverter at 0 W - healthy meter, running controller, nothing moving, and no line anywhere saying the number you set was overruled. Structurally the same fault as the max_w case. Only above the veto is refused: below it the add-on gives up first, which is fail-safe and visible on its own status page. Mirrored as validate.FIRMWARE_INGEST_VETO_S - it cannot be imported from a compile-time YAML substitution, so it carries a note about the one direction in which it can go stale.

max_w at or below zero is refused too. Schema-blocked on a real install, but validate_startup_config() is now also the simulation suite's entry point, and a non-positive max_w inverts the arbiter's supervised bounds into a contradiction that resolves to 0 W - i.e. it would read as a safety trip rather than as the typo it is.

The predicates for the meter group still live in p1.validate_meter_options(), which build_source() also calls - one definition, two callers, not two competing validators. Two transports gained a check they never had: ha_dsmr with only one of its two entities, and mqtt_p1 with a blank topic, both of which previously built a transport that could never read.

Deliberately not refused, because it is untidy rather than unsafe: integrator_max_w above max_w (the arbiter still bounds the wire to ±max_w, so the cost is unwind latency, not amperage - warned), a missing soc_entity / batt_entity (fail-safe, and already a red NOT READY banner naming it), a setpoint_entity that has not appeared on the Core API yet (ESPHome is routinely late; refusing would make a slow boot need a human - re-checked once the real rating arrives), and a thin-but-nonzero meter_poll_s margin.

A refusal is legible as a refusal: a banner that says in words that this is a configuration problem and nothing is broken, the numbered problems, no traceback, and exit status 78 (EX_CONFIG).

SAFETY-12. The control loop now evaluates on a clock as well as on a change. run_control() ran cycle() only when the meter value differed from the previous poll, so a meter that repeated a value ran no control cycles at all - while the heartbeat went on re-emitting the last command and the firmware went on putting it on the wire every 2 s. Layer 1 stayed fed, every indicator read healthy, and a command computed from an old reading kept being executed through whatever the load did next. Measured on the rig during TEL-05: 70 s at a literally constant 350.0 W with 14 arrivals and zero cycles.

It was worse than a latency limit: it was a safety claim that could not fire. stale_input_s and the inputs missing -> 0 W claim both live inside cycle(). Pre-fix, if the meter value happened to be constant, cycle() was never called again - so that claim had no way to run. Constant meter, SoC entity dying at t=4 s, same binary:

pre-fix    writes: [(0.0, 220.0), (0.0, 220.0), (10.1, 220.0)]
           final target: 220.0 W   reason: 'loop -> 220 W'
post-fix   writes: [(0.0, 220.0), (0.0, 220.0), (3.0, 430.0), (9.1, 0.0), (10.1, 0.0)]
           final target: 0.0 W     reason: 'safety -> 0 W'

The pre-fix controller held 220 W through the entire input outage with its status line still reading loop -> 220 W, and layer 1 does not cover that case on a meter_source: off install: no P1 age sensor is published, so the firmware has nothing to veto on, while the heartbeat keeps its watchdog fed. So the old behaviour was not "holds a stale command safely" - it was a failsafe that a repeating meter switched off. test_loop.py asserts both halves.

cycle_floor_s (default 15 s) is a deadline on the gap between cycles, not a second scheduler: every cycle resets it, whichever trigger fired. On a healthy meter it never elapses, so the cycle rate, the write sequence and therefore the per-cycle gain the tuning was measured against are unchanged - asserted in test_loop.py by driving the real loop twice on one binary (a huge cycle_floor_s reproduces the old behaviour exactly) and comparing the commanded values.

The reset is not the only thing holding that up, and the other argument is the sturdier one: the combined cycle rate is max(arrival rate, 1/floor), never the sum. At 1/15 s the floor is strictly slower than the ~1/5 s arrival rate, so even a hypothetical floor racing the arrivals could not exceed the nominal healthy rate. The re-tune is unreachable by construction. ⚠️ That holds only while cycle_floor_s stays above the meter's update interval, and the schema minimum is 5 s - which is exactly the reference meter's interval. Nothing enforces the relationship; validate.py is the obvious home for it and does not have it yet.

Observed over six real minutes on the same rig, one binary, meter held at a literally constant 350.0 W: before, 1 cycle (at startup) and then nothing, the command stuck at 220 W against a 350 W import for the rest of the window. After, 24 cycles, worst gap 15.14 s, and the ordinary PI ramp doing its job - 220, 430, 650, 860, 1080, 1300, 1510, 1730, 1940, 2000 W, one step per cycle, rail at t=136 s and flat after. Three minutes with the meter parked at the target instead: 1 cycle before, 12 after, and 19 writes either way - the same 19. Three minutes on a normally-changing meter: 36 cycles and 49 writes on both sides, the same values in the same order. The heartbeat write count never moves; the only writes the fix adds are the ten the loop was supposed to be making all along.

15 s is bracketed, not round.

Below it, ~11 s, and it arises more routinely than a dropped poll. HomeWizardLocalSource polls at 5.0 s against a meter that updates every 4.97 s (NOTES.md:640). Two near-equal periods beat, so roughly once every ~14 minutes the poller steps over an update entirely - a ~10 s gap between changed values on a perfectly healthy meter, plus up to 1 s for the 1 s tick to notice. A failed HTTP poll (retried on the next tick, no backoff) adds another 5 s. The floor sits above the beat-skip so it does not fire on that alone; what it takes to reach 15 s is a beat-skip and a failed poll coinciding.

Above it, 30 s. meter_max_age_s is 30 s, past which there is no reading to evaluate, and the firmware's ingest veto is also 30 s - so the loop is guaranteed to have re-decided at least twice inside any window in which layer 1 might otherwise be the only thing deciding. ⚠️ The default is therefore not independently justified at 15: if the firmware's veto ever moves, this moves with it. Noted beside the constant in main.py.

It is also exactly stale_input_s, this system's existing answer to "how long may we hold without re-deciding".

A floor cycle runs the full law on the same inputs, integrator included. In P1 mode the freshness question is already answered upstream and answered harder

• past meter_max_age_s the reading is None, which is "inputs missing", which is a P_SAFETY 0 W claim - so a floor cycle there can only ever run on a reading this system already calls fresh. ⚠️ That is transport-conditional: with meter_source: off, read_inputs() takes the grid figure straight from hass.number() with no age gate at all, so a Home Assistant entity that has gone quiet reads as current on that path, with or without this change. Running the full law is still right there - the alternative is a degraded second law reasoning about an age nobody measured - but the floor does not make that path fresh. The integrator advances per cycle, not per second, so bounding the gap bounds the accumulation; integrator_max_w bounds it after that. A gentler second law for floor cycles would be a second set of dynamics nobody can test on this hardware.

⚠️ This is not a freeze detector, and TEL-05 established one cannot be built here: at the converged -10 W target a 1 Wh register needs ~6 minutes to move while the power figure legitimately repeats, so any threshold on unchanged_s false-trips at the exact operating point we run at. Nothing in this change decides whether a repeated reading is true. It stops "the number is the same" from meaning "do not think". The consequence, stated plainly: against a meter genuinely frozen at a wrong value the loop will now correct toward that wrong value rather than hold a stale command, bounded by max_w, the arbiter and the device rating. That was already what happened to a lying meter whose value merely jittered; bit-exact repetition was never a safety property.

DOCS.md's "Saturation is counted in cycles, not seconds" section documented the old behaviour as an accepted deviation. It is qualified, not deleted: the deviation survives (the window is still counted in cycles, and 3 x 15 s is still not the specification's 10 s) but it is now bounded at 45 s instead of open-ended, and the passage's second justification - "nothing accumulates while it is stalled" - is called out as having covered integrator windup and not staleness, which was the actual hazard. The same wrong argument in control.py's saturation comment is corrected too.

TEL-04. meter_source: ha_signed reads a single signed power entity, which is the shape a HomeWizard P1 publishes. Both transports 0.3.0 shipped require two unsigned registers and refuse negatives, so neither fits the meter installed here.

TEL-05. meter_source: homewizard_local polls the meter's own local API directly. This exists because of something the HA paths cannot do: Home Assistant fires no state change for a repeated reading and exposes no arrival signal at all, so sensor.p1_sample_age_s on those transports measures time since the value changed, not since the meter reported. Real captured data has gaps of 42 s and 97 s between changes on a perfectly healthy meter - long enough for a 30 s staleness threshold to command 0 W for no reason. Every HTTP response to the local API is a genuine arrival, so the age means what it says.

Verified on the rig against a literally constant 350.0 W for 70 s - the exact state where the HA path recorded zero samples in 45 s - with 14 arrivals and the age never exceeding the poll cadence.

Set p1_host to the meter's address and meter_poll_s (default 5 s, matching the meter's own ~5 s update). Still defaults to off; nothing changes for an install that does not opt in.

Freeze detection is separate and deliberately not thresholded: a meter answering 200 OK with a stale number is arriving, so no arrival stamp can flag it. The energy registers carry that as unchanged_s, surfaced on the status line for a human to read rather than alarmed on - at a converged -10 W a 1 Wh register needs about six minutes to move, so any threshold would false-trip at the target operating point.

Unreleased

TEL-05. A fourth meter_source, homewizard_local, which polls a HomeWizard P1's own local API (GET /api/v1/data) instead of watching a Home Assistant entity. Set p1_host to the meter's address; meter_poll_s (default 5 s, the meter's own update rate) sets the cadence.

✅ This is the first transport whose sensor.p1_sample_age_s measures when the meter reported, and therefore the first one a firmware watchdog may threshold. Every HTTP response is an arrival: the meter answered, now, with its current reading, and whether the number moved is not consulted. Home Assistant cannot express that at all — a repeated reading emits no state_changed, advances last_reported on neither serialiser, and state_reported is not subscribable ("Event filter is required"). On ha_signed that made a healthy meter under a flat load indistinguishable from a dead one, and our own capture of this house's meter goes 42.2 s and 97.0 s between changes — both past the default meter_max_age_s of 30, i.e. a false trip to 0 W on a meter that is fine. If you have a HomeWizard P1, move to this mode.

Everything TEL-01 established is reused, not re-implemented: ingest timestamping, meter_max_age_s, the clock-recomputed age, the plausibility bounds and the §20 unsigned-decode rejection, and the same split_signed sign convention ha_signed uses. A failed or timed-out poll submits nothing, so it is a missing reading — never 0 W — and it does not reset the age.

Verified on the ENV-01 rig against sim/hwsim.py, steady and with --fault freeze injected. Still defaults to off.

⚠️ An arrival stamp still cannot see a frozen meter, and no arrival detector can: a meter answering 200 OK forever with a stale number is arriving. The local API does expose what the HA path never had — the total_power_*_kwh registers stop advancing — and the transport tracks it as unchanged_s, but that is deliberately not folded into the age and not thresholded: this controller regulates grid power toward ~0 W, and at a converged −10 W the export register needs six minutes to move by its 1 Wh resolution while the power figure legitimately repeats. Thresholding it at 30 s would rebuild the false-trip limit cycle at the exact operating point we aim for. Freeze detection needs the low-power case solved first, separately. It is shown on the status page's P1 line instead — leaving it unthresholded only holds up if a human can read it, so now they can.

TEL-04. A third meter_source, ha_signed, reading one signed Home Assistant entity: positive = import, negative = export. That is the shape a HomeWizard P1 publishes (sensor.p1_meter_active_power), and it is the meter actually fitted here - which neither TEL-01 transport can read, because ha_dsmr needs two unsigned registers and refuses a negative one, i.e. every exporting telegram. Set p1_net_entity, and p1_phase_net_entities for the per-phase capacity-tariff figures on a three-phase connection.

Everything TEL-01 established is inherited rather than re-implemented - the new transport is a subclass of the ha_dsmr one overriding only which entities it wants and how they become a sample. So ingest timestamping, meter_max_age_s, sensor.p1_sample_age_s recomputed against the clock and republished once a second, the plausibility bounds, and unavailable / unknown treated as a missing reading and never 0 W all behave identically across the three sources.

Still defaults to off; an existing install is unaffected until it opts in.

⚠️ sensor.p1_sample_age_s is published on ha_signed, but must not yet be thresholded by the ESP32 stale-input watchdog. On the HA WebSocket paths the age is stamped from state_changed, so it measures time since the value changed, not since the meter reported - and Home Assistant exposes no arrival signal for a repeated reading (no state_changed, no last_reported movement on either serialiser, and state_reported is not subscribable over the WebSocket). Measured on the ENV-01 rig against the real HomeWizard integration. ha_dsmr mostly escapes it because a telegram moves several entities at once; ha_signed has one, so a healthy meter under a flat load is indistinguishable from a dead one. Our own capture has the house meter going 42.2 s and 97.0 s between changes. Raising meter_max_age_s does not fix that, it only chooses which error you get; the fix is an arrival stamp from the meter itself and is a separate ticket. Full detail in DOCS.md.

0.3.0

SAFETY-04. The control law's integrator is now an explicit accumulator, 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 holds any resting point inside it indefinitely, and the meter bills import and export on separate registers, so resting at +14 W import costs 0.34 kWh/day with the loop behaving perfectly. Biasing the target slightly negative moves that residue onto the export register. Configurable in the Configuration tab; see DOCS.md for the trade-off table.

Behaviour is unchanged at target_grid_w: 0.

0.2.0

Precedence between strategies is now a first-class object instead of an if/else ladder, ahead of there being more than three of them.

Every strategy returns a CLAIM each cycle - set ("I want X") or limit ("the result must stay within these bounds") - and arbiter.py resolves them by one rule:

1. Highest-priority set wins; no claim at all means 0 W.
2. Then every limit whose priority is >= that set's priority applies, most restrictive first.
3. Contradictory limits are a BUG: command 0 W and say so.

Clause 2 is why "money outranks maintenance" is now a consequence of the priorities rather than a special case in a Jinja template: the maintenance charge-only limit binds the loop, but will not bind a higher-priority peak shaving claim when one exists.

• Maintenance shaping (charge-only, cheap-window floor) moved out of the control law. control.py is once again only a controller that tracks the meter.
• The loop computes from the ARBITER's last output, not its own last wish. If something outranked it, that is what the hardware actually did, and tracking anything else makes it jump when it regains control.
• Every decision is explainable: "loop -> 0 W, limited by maintenance (charge-only)" now appears in the UI and the log, instead of a bare number.
• Safety limits (device rating, supervised max_w) bind every strategy including the highest, and are still enforced a second time at the point of writing.

0.1.6

Findings from installing this on a live system, replacing a working YAML implementation. Every one of these was silent - the add-on looked healthy while being completely unable to do its job.

• run.sh must use #!/usr/bin/with-contenv sh. The HA base images run s6-overlay, which starts services with a SANITISED environment. With a plain shebang, SUPERVISOR_TOKEN is simply absent and every Home Assistant call returns 401 - while homeassistant_api: true makes the permissions look correctly granted. Startup now logs the token length and probes the Core API, so the next person sees it in one line.
• Bump version: for every change. Supervisor keys the built image by version, so editing source and rebuilding silently reuses the old image. Two fixes appeared not to work because of this.
• Dependencies come from apk, not pip. Alpine is musl and there are no musl wheels for aiohttp; pip would compile it on the client's Pi.
• paho-mqtt 1.x and 2.x are both supported. Alpine ships 1.x, which has no CallbackAPIVersion; that raised and took the whole add-on down with it.
• MQTT can no longer take down control. Publisher construction is wrapped - observability must never stop the controller.
• MQTT discovery is published from on_connect. paho drops QoS-0 publishes issued before the CONNACK, so announcing straight after connect() published nothing at all while logging "MQTT connected".
• Repeated failures log at most once a minute. The control loop retries every second; unthrottled warnings rolled the log buffer and destroyed the startup diagnostics needed to debug the 401 above.
• auto_start works. The store's defaults supplied auto: False, so the fallback to the option could never fire.

Known issue: after deleting the MQTT entities from the registry during development, Home Assistant would not re-adopt them from retained discovery - not even after clearing the retained topics and reconnecting. The add-on publishes correct discovery and live state (verified on the broker); this is an HA-side adoption problem and affects status entities only, never control.

0.1.0

First packaged release. Ports the control loop and the monthly maintenance cycle from the reference Home Assistant implementation into an add-on.

• Grid-following control: gain/slew/clamp/deadband with anti-windup, all tuned against measured hardware behaviour (see FIELD-GUIDE.md §14).
• Saturation freeze with the duration term — three consecutive diverging cycles, not one. The instantaneous test fires on every large correction, because the plant itself needs 3-6 s to settle.
• Monthly maintenance cycle as an ownership state machine: drain / charge / hold, with exactly one writer of the setpoint at any moment.
• Capacity-tariff awareness: the maintenance charge is capped by quarter-hour peak headroom, and peak shaving outranks the maintenance schedule.
• Failsafe behaviour: commands 0 W on missing inputs, on stop, and on shutdown. Never replays a stale setpoint - the reference implementation did, and the hardware watchdog cannot catch that.
• Ingress UI with a commissioning checklist that names problems in words.
• Optional MQTT discovery for status entities.

Known limits:

• Home Assistant OS / Supervised only (add-ons cannot run on Container/Core).
• The inverter protocol is reverse-engineered; no vendor contract.
• Without the optional RS485 e-stop, nothing covers the host machine dying.