DATA-01: thirty days of the real meter, and what AC 3 actually measures

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, because two days of capture existed and it was believed
nothing longer could be produced. That belief was a true statement about
the past read as a claim about the future: HA's recorder still held the
whole month, and the reason nobody found out is that the 2026-08-25
export was a one-off script that left no artefact.

So the exporter is committed and runnable now.
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 schema the
two committed days already fixed.

VERIFIED AGAINST THE DAYS THAT EXIST. `--verify` re-fetches 2026-08-20
and 2026-08-23 by this exact route and reproduces both committed files
BYTE FOR BYTE after decompression (865,024 B / 15,600 samples and
894,387 B / 16,351 samples). The gzip containers differ by design: this
exporter writes mtime 0 so its output is reproducible, where the one-off
wrote a wall clock.

A FAILED READ IS NOT AN OBSERVATION. A day whose read fails writes no
file, is recorded "read": "FAILED", and the run exits non-zero; the
entity is proved to exist through /api/states before any empty day is
believed, because a typo would otherwise answer 200 [] thirty times and
produce a consistent dataset of nothing. Nothing is interpolated, so the
month's 13 gaps (1291 s, 99.95 % covered) and its 3 `unavailable`
samples stay visible as holes.

SIZE: COMMITTED, DELIBERATELY, AND MEASURED. A git bundle of the whole
history goes from 1.58 MB (release/1.0 @ 86c43eb) to 5.28 MB - +3.70 MB,
x3.3 - and a Home Assistant supervisor clones that on every install.
Downsampling was not on the table: meter_max_age_s is 30 s, so any
coarser resample turns real coverage into modelled meter-gap and moves
the number being measured. "Outside the repo with a pointer" is what
already happened and is why this card exists. The files sit in a
SUBDIRECTORY so the non-recursive globs in test_tariff.py part 9 and
test_peakguard.py part 6 do not pick them up - CI keeps replaying the two
small days instead of growing ~50 s per PR.

AC 3, MEASURED OVER 30 DAYS (tools/replay_ac3.py, which must reproduce
test_peakguard part 6's 189/190 to be believed):

  uncontrolled  2847/2879 = 98.89 % of quarters at or under 3500 W
  guarded       2850/2879 = 98.99 %
  month peak    5029.8 W -> 4107.3 W

Met on the ">= 95 % of intervals" reading - and the uncontrolled figure
is the finding, because a month with no controller at all passes it. Not
met on the other reading of the same sentence: 4107.3 W is still over the
soft limit. The guard pulls 31 of the 32 over-cap quarters down but lands
only 3 under the cap, because CEILING_MONTH_PEAK defends the running
month peak rather than the cap once one is set. Both suites' honesty
notes are corrected to point at the month instead of at its absence.

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

goodwe_controller/CHANGELOG.md

@@ -2,6 +2,344 @@
 
 ## Unreleased
 
+**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

goodwe_controller/DOCS.md

@@ -420,7 +420,7 @@ help - see "Why the tuning is what it is".
 | `maintenance_start_hour` | 10 | Hour of day a due cycle begins |
 | `maintenance_discharge_w` | 2000 | Drain rate (exports the surplus). Above `max_w` it is **clamped** to `max_w` — the drain phase SETs the setpoint and the arbiter bounds it, saying so on the status page (`limited by supervised(max_w)`). Warned about, not refused: the cycle still completes, just slower |
 | `maintenance_charge_w` | 2000 | Charge ceiling, capped again by peak headroom. Must stay **at or below `max_w`** or the cheap-window shaping (`hi = -maintenance_charge_w`) contradicts the supervised limit (`lo = -max_w`), the arbiter resolves it to **0 W**, and maintenance silently never charges in a cheap window — **the add-on refuses to start** |
-| `maintenance_soc_floor` | 11 | Drain target — stay just above the inverter's own floor |
+| `maintenance_soc_floor` | 11 | Drain target — stay just above the inverter's own floor. ⚠️ **This is not `peak_soc_floor`.** It is the depth the monthly recalibration deliberately goes to, once, on purpose; `peak_soc_floor` is the depth a money-saving discharge may never reach on any day. The right values differ (11 vs 20 as shipped), which is why they are two keys |
 | `maintenance_soc_target` | 99 | Charge target |
 | `maintenance_hold_min` | 120 | Hold at full so the BMS can balance |
 
@@ -430,6 +430,8 @@ help - see "Why the tuning is what it is".
 |---|---|
 | `peak_forecast_entity` | Quarter-hour demand forecast, for capacity-tariff markets. Empty = no cap |
 | `peak_cap_w` | The site's capacity-tariff target |
+| `peak_soc_floor` (20) | **The percent below which the capacity-peak guard will not discharge the battery.** Not optional and not the same thing as `maintenance_soc_floor` — see below |
+| `bms_soc_floor` (10) | The pack's **own** cut-out percent, the number the BMS enforces whatever you set above. `peak_soc_floor` must be **strictly above** it or the add-on refuses to start |
 | `price_now_entity`, `price_avg_entity` | Dynamic tariff. Empty = never force a paid grid top-up |
 
 On a capacity-tariff site the maintenance charge is capped by the headroom left
@@ -439,6 +441,11 @@ maintenance schedule.
 
 #### Capacity-tariff exposure of the grid-following loop
 
+⚠️ **This section described the exposure BEFORE SAFETY-07. The loop is now
+capped — see "The capacity-peak guard" below — and what follows is kept because it
+is still the clearest statement of WHAT is being guarded and why the number is
+worth what it is.**
+
 ⚠️ **`peak_cap_w` caps MAINTENANCE charging. It does not cap the loop.** The
 grid-following loop is bounded by `max_w` and by the device rating, and by
 nothing else. That is deliberate — the loop exists to *reduce* what crosses the
@@ -463,16 +470,107 @@ What exists today, and what does not:
 |---|---|
 | `max_w` bounds the magnitude | ✅ — but the exposure IS the magnitude |
 | Maintenance charging capped under `peak_cap_w` | ✅ |
-| **Loop capped under `peak_cap_w`** | ❌ — not built. This is SAFETY-07 |
+| **Loop capped under `peak_cap_w`** | ✅ — SAFETY-07, on every `meter_source` but `off` |
 | Frozen meter detected | ✅ on `homewizard_local` only, **alarm only** |
-| Frozen meter *stopped* | ❌ — the alarm does not command anything |
+| Frozen meter *stopped* | ✅ — SAFETY-07 forbids importing while the meter is frozen |
 | SoC guard on the loop | ❌ — the BMS is the only energy backstop |
 
-So the frozen-meter alarm below **narrows the window; it does not close it.** On
-a capacity-tariff site where an unattended runaway is unacceptable, the mitigation
-today is operational: set `max_w` no higher than the loop actually needs (the
-tuning was measured at 2000 W and a 1.78 kW load step is tracked fine there), fit
-the e-stop, and watch for the alarm.
+On the legacy `meter_source: off` path there are no P1 telegrams, so there is no
+quarter-hour average to guard, and the status page says **NOT COVERED**. There
+the mitigation is still operational: set `max_w` no higher than the loop actually
+needs (the tuning was measured at 2000 W and a 1.78 kW load step is tracked fine
+there), fit the e-stop, and watch for the alarm.
+
+### The capacity-peak guard
+
+**What it does.** Every cycle the add-on projects the open quarter to its
+end-of-interval average — from P1 telegrams only, never from the command — and
+compares it to a ceiling. Over the ceiling it files one claim: a **lower bound on
+the setpoint**, at `P_PEAK`. That single shape is both behaviours §10.1 asks for:
+a hard clamp on charging while the bound sits above the standing charge, and
+pre-emptive discharge while it sits above zero. It can never cap discharge or
+export, because a floor cannot.
+
+**The number.** `excess = 900 × (projected − ceiling) ÷ seconds remaining`, and
+the floor is the **measured** battery power plus that. The 900/remaining factor
+is the design rather than an accident: it is 1.0 at the top of the quarter and
+grows, so the guard is gentlest when its projection rests on the least evidence
+and becomes aggressive only once the quarter is nearly measured.
+
+**The ceiling** is `peak_cap_w`, raised to the month's banked peak when that
+already stands higher — once a month's bill is set at 5013 W, holding later
+quarters to 3500 W buys nothing and costs real charging. **That relaxation is
+granted only by an OBSERVED reading:** a peak store that cannot be read leaves the
+ceiling at the cap, so a broken instrument makes the guard stricter, never looser.
+
+**When it cannot see, it forbids importing.** Three states are not evidence and
+are checked before the projection is graded: no open quarter (a fresh averager
+projects a confident 0 W, which is under every ceiling there is), a meter gap
+longer than `meter_max_age_s`, and SAFETY-18's frozen-meter conjunction. In all
+three the claim becomes a floor of **0 W**. That is the backstop for the frozen
+meter: the alarm arrives at `meter_freeze_s` (300 s) of a 900 s billing quarter
+and commands nothing, and this stops the import.
+
+**It trips, where the freeze detector only notifies,** and the captures are why.
+On the healthy reference day (2026-08-23) it engages on **zero** of 95 quarters.
+The action is level-triggered and unlatched — re-derived from a fresh projection
+every cycle, released the instant the projection drops back — so a false
+engagement costs one cycle of discharge rather than a parked battery. And it is a
+LIMIT, so every stop in the watchdog table still outranks it.
+
+**Replayed on 2026-08-20**, the day the vendor controller failed: the billed
+quarter measured **5029.8 W**, above the inverter's own 5000 W rating, and the
+guard brings it to **3485 W** — under the soft limit, without ever asking for more
+than the inverter can give. Across both committed days the quarters under the
+limit go from 189/190 to 190/190. Two days is not thirty and does not close AC 3;
+it is the comparison two days can support.
+
+**What it alarms on is saturation, not engagement.** An engagement is an ordinary
+control action and goes to the action log and the status page. A *saturated*
+guard — asking for everything the inverter has while the quarter is still
+projected over — raises one notification (`goodwe_peak_saturated`), because that
+is the one state where the money will be spent and shedding load is the only
+thing left that changes the bill.
+
+**No new option for the CEILING.** It is `peak_cap_w`, which already shipped. 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 — every one of them a key that already exists.
+
+#### The energy floor under the forced discharge (`peak_soc_floor`)
+
+The guard above can **command a discharge**, and until SAFETY-24 nothing in the
+add-on bounded how far down it took the pack — the BMS was the only backstop.
+On the 2026-08-20 replay the guard asks for **878 Wh in a day**.
+
+That is not absurd: the BMS floor is real and it works. But it is *the pack's*
+protection, not *yours*. A month of aggressive quarters can leave the battery
+repeatedly parked at that cut-out with no record on this side of why, and the
+first symptom — a battery that is never available when you want it — looks
+exactly like the SoC drift the monthly maintenance cycle exists to correct.
+
+- **`peak_soc_floor` (20 %)** is where the forced discharge stops. Below it the
+  guard files a **0 W** floor instead of a sized one: charging stays blocked
+  (that can only ever lower your offtake), and no further discharge is asked for.
+- **It does not stop the ordinary self-consumption loop.** That loop still has no
+  SoC guard of its own. This bounds what the *peak guard* spends for money.
+- **When it binds you are told**, once per episode, with notification
+  `goodwe_peak_soc_floor` and a status-page row reading `PEAK GUARD
+  FLOOR-LIMITED`: the quarter **will** go over the ceiling, so shedding load is
+  the only thing left that changes the bill. Failing to shave is never silent —
+  the euro figure is the whole point of the guard.
+- **An unreadable SoC is treated as floor-limited, not as a full battery.** A
+  full battery is exactly the value that would disarm this floor.
+- **`bms_soc_floor` (10 %)** is the pack's own cut-out — register `0x0560` on the
+  reference GW5000S-BP, consistent with DoD 90. It exists so the add-on can
+  **refuse to start** when `peak_soc_floor` is at or below it: such a floor can
+  never be the thing that stops the discharge, and a guard that advertises a
+  backstop it does not have is the one thing this project will not ship. Equal is
+  refused too — equal buys zero margin.
+
+Why 20 %: the reference pack is 13.8 kWh usable, so 10 points of margin over the
+BMS cut-out is about 1.6× the guard's worst measured day. If your pack is
+smaller, or your quarters are worse, raise it.
 
 ### The winding-loop alarm (the output clamp)
 
@@ -583,15 +681,16 @@ floor of 60 s that figure is 60 W and only the margin is left.
 
 ### Energy price providers
 
-> **No *fetched* price moves energy in 0.5.x.** This release ships the
-> *plumbing*: the five provider plugins, the canonical all-in format they emit,
-> and the config that selects one. Turning a provider on fetches, validates and
-> publishes prices and changes no charging decision; the arbitrage strategy that
-> would use it is a later ticket.
+> **A fetched price moves energy only when you switch arbitrage on.** This
+> release ships the five provider plugins, the canonical all-in format they
+> emit, the config that selects one, and — new in OPT-04 — a price-arbitrage
+> strategy that trades on them. With `arbitrage_enabled: false`, which is the
+> shipped default, turning a provider on still fetches, validates and publishes
+> prices and changes no charging decision.
 >
-> The one exception is `static_profile` below. A static day/night tariff needs
-> no network, so its cheap window is computed on every cycle and does reach the
-> maintenance cycle's grid top-up.
+> `static_profile` below needs no network at all, so its cheap window is
+> computed on every cycle and reaches the maintenance cycle's grid top-up
+> whether or not arbitrage is armed.
 
 | option | meaning |
 |---|---|
@@ -743,6 +842,50 @@ to, and the site simply has no tariff until the feed returns. It is not required
 — the add-on warns rather than refusing — but filling it in is what makes that
 fallback work.
 
+### Price arbitrage (`arbitrage_enabled`)
+
+§10.1 priority 3: charge in the cheapest published hour, discharge in the
+dearest, **and only when the spread covers what the round trip costs.** Off by
+default — this is the first strategy in the add-on that commands the battery
+*against* the meter on purpose, so it is armed deliberately or not at all.
+
+| option | meaning |
+|---|---|
+| `arbitrage_enabled` | `false` by default. Arms the strategy |
+| `cycle_cost_threshold_eur` | What one full round trip costs per kWh — pack wear plus conversion losses. A spread below this is not traded |
+| `arbitrage_soc_floor` | The reserve arbitrage may not spend, % |
+| `arbitrage_soc_ceiling` | The headroom it may not overfill, % |
+
+**What it needs, and what the add-on refuses.** Arbitrage requires a price
+source (`price_provider` or `static_profile`) and a P1 meter (`meter_source`).
+Without a price source there is nothing to tell cheap from expensive; without
+P1 the capacity-tariff peak guard never runs, and §9.1 puts peak shaving above
+arbitrage — a charge that nothing measures is exactly what that guard exists to
+prevent. Both combinations are **refused at startup** rather than left looking
+armed.
+
+**Peak shaving always wins.** The strategy cannot obtain a spread at all
+without first answering whether the peak guard is holding, and even if it
+could, the guard's floor is filed at a higher arbiter priority and clamps an
+arbitrage charge. Discharging is never capped by it — only offtake is billed.
+
+**It never exports into a negative price** (§17). A negative hour is the best
+possible hour to *charge* in and that is still allowed; selling into one gives
+energy away and pays for the privilege.
+
+**At the shipped threshold a static day/night site does not trade.** The
+realistic Belgian day/night spread is about 0.08 EUR/kWh and the default
+threshold is 0.10, so the honest answer on such a site is "no opportunity", and
+the status page says so with the numbers. Whether 0.10 is the right default is
+a product decision, not a bug: lower it only if you know what a cycle costs
+your pack.
+
+**The prices are fetched in the background**, never on the control tick — a
+supplier's TLS timeout on that path would be a supplier able to push the add-on
+towards the firmware's 30 s failsafe. The plan refreshes every 30 minutes and
+retires itself if the refresh stops answering, at which point arbitrage stops
+with it.
+
 ### Site
 
 | option | meaning |

goodwe_controller/app/arbiter.py

@@ -36,6 +36,15 @@ P_SAFETY = 100        # stopped, inputs missing, shutting down, device limits
 P_MAINTENANCE = 60    # maintenance owns the actuator outright (drain, hold)
 P_PEAK = 50           # capacity-tariff peak shaving - costs real money
 P_MAINT_SHAPE = 40    # maintenance shaping the loop (charge-only)
+# OPT-04. §10.1 priority 3 - price arbitrage. ⚠️ ITS POSITION IS THE SPEC, NOT A
+# preference: P_PEAK (50) is ABOVE it so clause 2 lets the capacity-tariff floor
+# clamp an arbitrage charge, which is §9.1's "give peak shaving priority over
+# arbitrage whenever the two conflict" expressed as arithmetic rather than as a
+# rule somebody has to remember. P_MAINT_SHAPE (40) is above it so a speculative
+# spread cannot override the pack's balancing cycle. P_LOOP (10) is below it
+# because trading against the meter is the entire point - the grid-following
+# loop would otherwise cancel every charge the moment it created import.
+P_ARBITRAGE = 30      # price arbitrage - trades against the meter on purpose
 P_LOOP = 10           # ordinary grid-following
 
 SET = "set"

goodwe_controller/app/arbitrage.py

@@ -0,0 +1,429 @@
+"""OPT-04 - §10.1 priority 3: charge cheap, discharge expensive, and only when
+the round trip is worth more than it costs.
+
+WHERE THIS LIVES, AND WHY IT IS NOT WHERE THE CARD SAYS. The functional notes
+on the Trello card reference specs.md §2.2's `ems/optimizer/...` layout. That
+module layout does not exist and is not being built; the product owner's
+decision of 2026-08-30 is that everything ships in `goodwe_controller/app/`,
+beside price.py, static_tariff.py, peakguard.py and arbiter.py. The BEHAVIOUR
+§10.1 / §9.1 / §8.3 / §17 describes is unchanged and still authoritative.
+
+
+WHAT THIS MODULE IS, AND - MORE IMPORTANTLY - WHAT IT IS NOT
+============================================================
+Four cards landed before this one and this one CONSUMES all four. Almost every
+question an arbitrage strategy has to answer is already answered somewhere
+else, by an object built for it, and the single biggest way to get this ticket
+wrong is to answer any of them again here:
+
+  price.py (TARIFF-02)          what a price IS, all-in, and what a product is.
+                                `Uncertainty`, `WIDEN_FACTOR`, `required_spread`.
+  static_tariff.py (TARIFF-03)  `TariffPlan.arbitrage()` - THE VERDICT. Whether
+                                a trade is permitted at all, on which two hours,
+                                against which widened threshold. Five refusal
+                                reasons live there, not here.
+  price_forecast.py (FCST-03)   provisional carrying, and the rule that no
+                                irreversible action rests on a provisional
+                                price (§8.3).
+  peakguard.py (SAFETY-07)      the capacity-tariff floor, filed as a `lo`
+                                LIMIT at P_PEAK on the arbiter.
+
+So what is left for this file is genuinely small, and that is the point:
+
+  * WHICH HOUR IS IT NOW - is this instant the buy hour, the sell hour, or
+    neither.
+  * MAY THE BATTERY DO IT - state of charge, and §17's negative-price rule.
+  * HOW HARD - one number, filed as one arbiter claim.
+
+Everything else is delegated, and delegated by CONSTRUCTION rather than by
+convention: `TariffPlan.arbitrage()` will not hand over a spread at all unless
+it is told whether the peak guard is holding, what a cycle costs, and what is
+uncertain. There is no code path here that can reach a tradeable number without
+having answered §10.1's priority ordering first.
+
+
+AC3 - PEAK SHAVING WINS, AND IT WINS TWICE
+==========================================
+§9.1: "Give peak shaving priority over arbitrage whenever the two conflict."
+That is honoured through the two mechanisms that already exist, and NEITHER of
+them is re-implemented here:
+
+  1. THE INTERLOCK. `plan.arbitrage(peak_guard_active=...)` is keyword-only and
+     REQUIRED. When the guard is engaged the verdict is a refusal carrying the
+     §10.1 wording, so `decide()` below never sees a spread at all. It is not
+     possible to write a caller here that skips the question - the argument has
+     no default and the spread is unreachable without it.
+
+  2. THE ARBITER. Even if (1) were somehow bypassed, `claim()` files a SET at
+     P_ARBITRAGE (30) and peakguard files a LIMIT at P_PEAK (50). arbiter.py
+     clause 2 applies every limit whose priority is >= the winning set's, most
+     restrictive wins - so the peak floor CLAMPS an arbitrage charge whatever
+     this module thinks. 50 >= 30 is what makes that true, and it is why the
+     priority below sits under P_PEAK rather than beside it.
+
+Two independent mechanisms for one rule is deliberate. The first is the one
+that reports honestly; the second is the one that holds when the first is
+wrong.
+
+⚠️ AND THE GUARD MUST BE ABLE TO SEE. On `meter_source: off` there is no
+telegram stream, so peakguard.decide() is never run and `peak_guard_active` is
+not FALSE - it is UNKNOWN. Charging a battery at max_w creates offtake, offtake
+is the billed quantity (§9.1), and doing it deliberately while nothing measures
+the quarter is the exact shape of failure §9.1 exists to prevent. So the third
+state is carried explicitly as `None` and it REFUSES. A failed read is not an
+observation, and "the guard did not run" is not "the guard is clear".
+
+
+§17's NEGATIVE-PRICE CASE, STATED ONCE
+======================================
+"Negative-price hours - arbitrage must not export." A negative price means the
+market pays the site to consume. Discharging the battery into such an hour
+gives away stored energy AND forgoes being paid to take more in; if the house
+load is covered it becomes export, which at a negative price is paid-for
+disposal. The buy side is untouched - a negative hour is the best possible hour
+to charge in, and this file's guard is deliberately asymmetric for that reason.
+
+⚠️ THE GUARD IS ON THE HOUR BEING SOLD INTO, NOT ON THE SPREAD. A series whose
+prices are -0.30 and -0.05 has a 0.25 EUR/kWh spread that clears any shipped
+threshold, and its DEAREST hour is still negative. A guard written as
+"spread > 0" or "the prices are not all negative" passes that case and exports.
+
+
+WHAT `cycle_cost_threshold_eur` IS, AND WHAT THIS FILE REFUSES TO DO WITH IT
+===========================================================================
+§10.1 gates arbitrage on "expected round-trip benefit exceeds
+`cycle_cost_threshold_eur`". It ships at 0.10 EUR/kWh. On realistic Belgian
+day/night numbers the static spread is about 0.08 EUR/kWh, and FCST-03's
+widening factors (2.5 real-time, 1.5 no-weather) are honest policy defaults
+with nothing to derive them from.
+
+⚠️ SO A STATIC-TARIFF SITE DOES NOT TRADE AT SHIPPED DEFAULTS, AND THAT IS
+REPORTED RATHER THAN TUNED AWAY. The threshold is a parameter here, the
+behaviour is correct at any value of it, and no number in this file was chosen
+to make a trade happen. Whether 0.10 is the right shipped default - and whether
+2.5/1.5 are - is one product decision and it belongs to the owner, not to this
+card. test_arbitrage.py section 7 reports what the shipped default does over a
+replayed year rather than adjusting anything so that it looks better.
+
+
+THE ACCOUNTING BASIS, AND THE TERM THAT IS DELIBERATELY ABSENT
+=============================================================
+The card's technical notes ask for `benefit = value_out(d) - cost_in(c)/η`, and
+then say of the round-trip efficiency: "η is NOT a §14 key - it needs one, or
+must be derived from measured charge/discharge energy in the state store. DO
+NOT HARDCODE IT." Both halves are honoured by not having the term at all:
+
+  * THE SELL SIDE IS PRICED AS DISPLACED IMPORT, NOT AS EXPORT. The two hours
+    compared are both all-in CONSUMPTION prices, which is the basis the notes
+    require ("credit displacement at all-in import prices, not at export price,
+    or the number flatters itself"). `export_price_eur_kwh` is therefore not
+    read here at all - §9.3's near-zero Belgian injection price is precisely
+    why the economically sound trade on this market is charge-cheap-to-
+    displace-expensive-import, and §17's guard below is the same fact stated as
+    a rule.
+
+  * AND THERE IS NO η, BECAUSE THERE IS NOTHING HONEST TO PUT IN IT. No config
+    key exists, the state store carries no measured charge/discharge energy
+    pair to derive one from, and a hardcoded 0.85 is exactly what the notes
+    forbid - it would also DOUBLE-COUNT, because `cycle_cost_threshold_eur` is
+    already defined as what a round trip costs per kWh and conversion loss is
+    part of that cost. When a measured η exists it belongs beside the threshold
+    as a second term, and this file's arithmetic is one subtraction, in one
+    place, ready for it.
+
+
+HYSTERESIS (§10.2)
+==================
+The switching decision is "which hour is it", and an hour is 60 minutes wide,
+so the action cannot chatter within one. The other two terms are monotone
+inside an hour in the only direction that matters: a charge raises SoC towards
+the ceiling and a discharge lowers it towards the floor, so each can stop once
+and cannot restart in the same hour. No timer is needed and none is invented.
+"""
+
+import logging
+import math
+from dataclasses import dataclass
+from datetime import datetime
+
+from .arbiter import P_ARBITRAGE, Claim
+from .price import Absence, price_option
+
+_LOG = logging.getLogger("goodwe.arbitrage")
+
+SOURCE = "arbitrage"
+
+# §10.2 reason codes. Written out because the action log is a user-facing
+# artefact and a code assembled from an f-string cannot be grepped for.
+CHARGE = "ARBITRAGE_CHARGE"
+DISCHARGE = "ARBITRAGE_DISCHARGE"
+
+# Why nothing was done. These are the reasons this MODULE owns; the five
+# refusals that belong to the verdict itself are carried through verbatim from
+# static_tariff.py rather than restated, so a refusal's wording has exactly one
+# author.
+IDLE_NO_PLAN = "no tariff plan has been resolved yet"
+IDLE_NOT_COVERED = (
+    "NOT COVERED: meter_source is off, so the capacity-tariff peak guard never "
+    "runs and nothing measures the quarter this charge would land in. §9.1 puts "
+    "peak shaving above arbitrage, and an unmeasured peak cannot be shaved - "
+    "so the honest answer is that arbitrage is not covered on this install, not "
+    "that the guard is clear")
+IDLE_NO_SOC = (
+    "state of charge is not being read, and a battery whose fill nobody knows "
+    "cannot be told to empty or to fill")
+IDLE_OFF_PEAK_HOUR = "this hour is neither the buy hour nor the sell hour"
+NEGATIVE_PRICE = (
+    "§17: the sell hour is priced BELOW ZERO, so discharging into it would give "
+    "energy away and pay for the privilege. Arbitrage must not export at a "
+    "negative price")
+
+
+@dataclass(frozen=True)
+class ArbitrageDecision:
+    """What the strategy concluded this cycle, with what it concluded it from.
+
+    ⚠️ NO FIELD HAS A DEFAULT, and that is TEST-14's rule rather than a style
+    choice: an outcome type's required field quietly gaining a default is a
+    mutation that survived review in three files in this repository. The
+    signature is scanned in test_price_forecast.py alongside `Gate`'s and
+    `Arbitrage`'s constructors, so a default added here later goes red without
+    anybody remembering to write a case for it.
+
+    `action` is None whenever nothing is to be done, and `power_w` is then None
+    too - not 0.0. Zero watts is a COMMAND (it parks the battery); "no claim"
+    is the absence of one, and the arbiter must be free to let the loop win.
+    """
+
+    action: str | None            # CHARGE | DISCHARGE | None
+    power_w: float | None         # signed: negative charges, positive discharges
+    reason: str
+    spread_eur_kwh: float | None
+    required_eur_kwh: float | None
+    price_now_eur_kwh: float | None
+
+    @property
+    def trading(self) -> bool:
+        return self.action is not None
+
+    def explain(self) -> str:
+        if not self.trading:
+            return f"arbitrage idle - {self.reason}"
+        return self.reason
+
+
+def _idle(reason, *, spread=None, required=None, price=None) -> ArbitrageDecision:
+    if not reason or not isinstance(reason, str):
+        raise ValueError(
+            "an idle arbitrage decision needs a reason a human can act on - "
+            "§10.2 requires every plan change to carry one, and 'arbitrage did "
+            "nothing' with no reason is indistinguishable from a bug.")
+    return ArbitrageDecision(action=None, power_w=None, reason=reason,
+                             spread_eur_kwh=spread, required_eur_kwh=required,
+                             price_now_eur_kwh=price)
+
+
+def enabled(opts: dict) -> bool:
+    """Is the strategy switched on at all? Off in the shipped configuration.
+
+    ⚠️ OFF BY DEFAULT ON PURPOSE. Every other card in this repository ships its
+    machinery inert and lets an operator arm it; this one MOVES ENERGY against
+    the meter on a real battery, so it is the last one that should be an
+    exception to that.
+    """
+    v = price_option(opts, "arbitrage_enabled")
+    return v is True or str(v).strip().lower() in ("true", "yes", "on", "1")
+
+
+def threshold_eur_kwh(opts: dict) -> float:
+    """§10.1's `cycle_cost_threshold_eur`, from the one place option defaults live."""
+    v = float(price_option(opts, "cycle_cost_threshold_eur"))
+    if not math.isfinite(v) or v < 0:
+        raise ValueError(
+            f"cycle_cost_threshold_eur is {v!r}. It is what a round trip COSTS, "
+            f"in EUR/kWh, so it is non-negative and finite - a negative "
+            f"threshold is one every spread clears, which is arbitrage with the "
+            f"brake removed.")
+    return v
+
+
+def soc_bounds(opts: dict) -> tuple:
+    """(floor, ceiling) in percent. The reserve arbitrage may not spend."""
+    return (float(price_option(opts, "arbitrage_soc_floor")),
+            float(price_option(opts, "arbitrage_soc_ceiling")))
+
+
+def guard_state(peak_decision):
+    """The peak guard's answer as the three-state `decide()` takes: T / F / None.
+
+    THE ONE PLACE THIS CONJUNCTION IS WRITTEN, and it is public for the reason
+    `peakguard.shaping_suspended()`, `watchdog.loop_is_following()` and
+    `freeze.looks_frozen()` are: the check that grades it has to assert on THE
+    SHIPPED EXPRESSION. A predicate transcribed into its own test is one copy
+    plus a future disagreement about what the check means, and the copy that
+    drifts is always the grading one - this repository has three separate
+    records of exactly that, one of which left every suite green while a
+    default install parked at 0 W in the quarter that sets the month's bill.
+
+    ⚠️ `None` IS NOT `False` AND COLLAPSING THE TWO IS THE WHOLE HAZARD. On
+    `meter_source: off` main.py never runs peakguard.decide() - there is no
+    telegram stream, so there is no open quarter to project - and the decision
+    it hands here is None. That is "the guard never ran", not "the guard is
+    clear", and answering False would arm a strategy whose charging creates the
+    billed quantity (§9.1) while nothing measures the quarter it lands in.
+    """
+    if peak_decision is None:
+        return None
+    return bool(peak_decision.engaged)
+
+
+def _point_at(plan, when: datetime):
+    """The price point covering `when`, or None when the series does not cover it.
+
+    ⚠️ None IS NOT A PRICE AND IS NOT ZERO. `TariffPlan` raises `Absence` here
+    rather than answering 0.0, for price.py's reason - "no data" becoming "free"
+    is the defect the whole outcome-type family exists to remove - and this
+    turns that into "do nothing", never into "it is cheap".
+    """
+    try:
+        return plan.read.match(series=lambda r: r.at(when),
+                               no_data=lambda _r: None)
+    except Absence:
+        return None
+
+
+def decide(plan, now: datetime, *, peak_guard_active, soc,
+           min_spread_eur_kwh, uncertainty, charge_w, discharge_w,
+           soc_floor_pct, soc_ceiling_pct) -> ArbitrageDecision:
+    """Should the battery trade this cycle, and how hard.
+
+    ⚠️ `peak_guard_active` IS A THREE-STATE ARGUMENT AND ALL THREE ARE REAL.
+    True (the guard is holding), False (it ran and is clear), and None (it never
+    ran, because nothing measures this install's quarter). See the module note:
+    None refuses, because the alternative is a strategy that creates the billed
+    quantity while the thing that would have limited it is switched off.
+
+    ⚠️ EVERY OTHER ARGUMENT IS KEYWORD-ONLY AND HAS NO DEFAULT, for
+    `TariffPlan.arbitrage()`'s reason. A defaulted `soc_floor_pct` is a reserve
+    floor this module asserted rather than one the operator configured, and the
+    first time it is wrong the battery is at 0 %.
+    """
+    if peak_guard_active is None:
+        return _idle(IDLE_NOT_COVERED)
+    if plan is None:
+        return _idle(IDLE_NO_PLAN)
+
+    verdict = plan.arbitrage(peak_guard_active=peak_guard_active,
+                             min_spread_eur_kwh=min_spread_eur_kwh,
+                             uncertainty=uncertainty)
+    return verdict.match(
+        refused=lambda v: _idle(v.reason),
+        allowed=lambda v: _act(plan, now, v, soc, charge_w, discharge_w,
+                               soc_floor_pct, soc_ceiling_pct))
+
+
+def _act(plan, now, v, soc, charge_w, discharge_w, floor_pct, ceiling_pct):
+    """The permitted case: which hour is this, and may the pack do it."""
+    here = _point_at(plan, now)
+    if here is None:
+        return _idle(
+            f"the series carries a tradeable spread but no price for this "
+            f"instant ({now.isoformat()}), which is §11.4 for this hour rather "
+            f"than a reason to reach for a neighbouring one",
+            spread=v.spread_eur_kwh, required=v.required_spread_eur_kwh)
+
+    price = here.eur_per_kwh
+    buying = here.start == v.cheapest.start
+    selling = here.start == v.dearest.start
+    if not (buying or selling):
+        return _idle(IDLE_OFF_PEAK_HOUR, spread=v.spread_eur_kwh,
+                     required=v.required_spread_eur_kwh, price=price)
+
+    # ⚠️ BELT AND BRACES ON §8.3, AND IT IS NOT DEAD CODE. `_firm_or_die` makes
+    # the two points on the verdict firm at construction, but the point matched
+    # HERE is whatever `at()` returned for this instant, and the identity of the
+    # two rests on the series being the one the verdict was built from. An hour
+    # that is provisional is one nobody published a price for, and no
+    # irreversible action may rest on it.
+    if here.provisional:
+        return _idle(
+            f"§8.3: the price for this hour ({here.start.isoformat()}) is "
+            f"CARRIED FORWARD, not published, and no irreversible action may be "
+            f"taken on a provisional price",
+            spread=v.spread_eur_kwh, required=v.required_spread_eur_kwh,
+            price=price)
+
+    if soc is None:
+        return _idle(IDLE_NO_SOC, spread=v.spread_eur_kwh,
+                     required=v.required_spread_eur_kwh, price=price)
+
+    common = dict(spread=v.spread_eur_kwh, required=v.required_spread_eur_kwh,
+                  price=price)
+
+    if selling:
+        # §17. THE NAMED REGRESSION CASE. Checked BEFORE the SoC question, so a
+        # negative price reports the reason that actually forbids the trade
+        # rather than one that happens to fire first on some other site.
+        if price < 0:
+            return _idle(f"{NEGATIVE_PRICE} - this hour is "
+                         f"{price:+.4f} EUR/kWh", **common)
+        if soc <= floor_pct:
+            return _idle(
+                f"the sell hour is here at {price:.4f} EUR/kWh but the pack is "
+                f"at {soc:g} %, at or under the {floor_pct:g} % reserve floor "
+                f"arbitrage may not spend (§10.1 priority 4)", **common)
+        return ArbitrageDecision(
+            action=DISCHARGE, power_w=abs(float(discharge_w)),
+            reason=(f"{DISCHARGE}: this is the dearest firm hour at "
+                    f"{price:.4f} EUR/kWh, {v.spread_eur_kwh:.4f} above the "
+                    f"cheapest and clear of the {v.required_spread_eur_kwh:.4f} "
+                    f"this cycle had to cover; discharging "
+                    f"{abs(float(discharge_w)):.0f} W from {soc:g} %"),
+            spread_eur_kwh=v.spread_eur_kwh,
+            required_eur_kwh=v.required_spread_eur_kwh,
+            price_now_eur_kwh=price)
+
+    if soc >= ceiling_pct:
+        return _idle(
+            f"the buy hour is here at {price:.4f} EUR/kWh but the pack is at "
+            f"{soc:g} %, at or over the {ceiling_pct:g} % ceiling - there is "
+            f"nowhere to put the cheap energy", **common)
+    return ArbitrageDecision(
+        action=CHARGE, power_w=-abs(float(charge_w)),
+        reason=(f"{CHARGE}: this is the cheapest firm hour at "
+                f"{price:.4f} EUR/kWh, {v.spread_eur_kwh:.4f} below the dearest "
+                f"and clear of the {v.required_spread_eur_kwh:.4f} this cycle "
+                f"had to cover; charging {abs(float(charge_w)):.0f} W from "
+                f"{soc:g} %"),
+        spread_eur_kwh=v.spread_eur_kwh,
+        required_eur_kwh=v.required_spread_eur_kwh,
+        price_now_eur_kwh=price)
+
+
+def claim(decision: ArbitrageDecision) -> Claim | None:
+    """The decision as one arbiter claim, or None when nothing is to be traded.
+
+    A SET at P_ARBITRAGE, and the priority is the whole §10.1 ordering:
+
+      P_PEAK 50        > this, so peakguard's `lo` floor CLAMPS an arbitrage
+                         charge (arbiter clause 2 applies every limit at or
+                         above the winner's priority). AC3, mechanically.
+      P_MAINT_SHAPE 40 > this, so a maintenance charge window's `hi` shaping is
+                         not overridden by a price opportunity. §12.4's "money
+                         outranks the schedule" is about the PEAK guard, which
+                         is measured and billed; a speculative spread is not
+                         that, and letting it out-rank the pack's balancing
+                         cycle would be this card quietly rewriting §12.
+      P_LOOP 10        < this, because trading against the meter is the point:
+                         the grid-following loop would otherwise cancel every
+                         charge the moment it created import.
+
+    ⚠️ NONE MEANS NO CLAIM, NOT A 0 W CLAIM. Filing `Claim.set(..., 0.0)` here
+    would out-rank the loop with a park order every cycle the strategy had
+    nothing to say, i.e. it would silently disable self-consumption on any site
+    that armed arbitrage.
+    """
+    if not decision.trading or decision.power_w is None:
+        return None
+    return Claim.set(SOURCE, P_ARBITRAGE, float(decision.power_w),
+                     decision.action)

goodwe_controller/app/main.py

@@ -28,24 +28,29 @@ import contextlib
 import json
 import logging
 import signal
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 
 import aiohttp
 
+from . import arbitrage
 from .arbiter import (
-    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_SAFETY, Claim, resolve,
+    P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_PEAK, P_SAFETY, Claim, resolve,
 )
 from .control import Tuning, compute, maintenance_charge_floor, peak_at_risk
 from .clamp import (
     REASON_CODE as CLAMP_REASON, ClampResult, ClampWatchdog, clamp_to_rating,
     is_commandable,
 )
-from .freeze import FreezeWatchdog, FreezeWatchdogConfig, rail_w
+from .freeze import (
+    FreezeWatchdog, FreezeWatchdogConfig, looks_frozen, rail_w,
+)
 from .hass import HomeAssistant
 from .maintenance import IDLE, MaintConfig, Maintenance
 from .mqtt import MqttPublisher
+from . import peakguard
 from .p1 import P1Ingest, build_source, is_enabled
-from .static_tariff import static_status
+from .price import Uncertainty, price_option
+from .static_tariff import resolve_tariff, static_status
 from .tariff import PeakStore, PeakTracker
 from .validate import ConfigRefused, refuse, validate_startup_config
 from .watchdog import SignWatchdog, SignWatchdogConfig, loop_is_following
@@ -54,6 +59,34 @@ from . import web
 OPTIONS_PATH = "/data/options.json"
 _LOG = logging.getLogger("goodwe")
 
+# --------------------------------------------------------------------------- #
+# OPT-04: THE BACKGROUND TARIFF REFRESH, AND WHY IT IS NOT OPTIONAL
+#
+# `static_tariff.resolve_tariff()` may perform an HTTPS fetch. The control tick
+# is what feeds the ESP32 heartbeat, and layer 1 commands 0 W if that heartbeat
+# stops for ~30 s - so a supplier's TLS timeout on the tick is a SUPPLIER able
+# to push this add-on into the failsafe. Every module in the price stack says
+# so in its own words (static_tariff.static_plan, resolve_tariff, main's
+# read_inputs) and this is the task those notes were waiting for.
+#
+# The tick therefore never awaits a fetch. It reads `self.tariff_plan`, an
+# attribute this task assigns, and nothing else.
+#
+# ⚠️ THE CADENCE IS NOT A GUESS AT HOW OFTEN PRICES CHANGE. A day-ahead feed
+# publishes ONCE, at 14-16 h CET, and §8.3's carried hours become firm at that
+# moment; 30 minutes is short enough that the switch is picked up inside the
+# hour it happens and long enough to be a polite 48 fetches a day. Nothing in
+# the control law depends on it.
+TARIFF_REFRESH_S = 1800.0
+# ⚠️ AND THE AGE BOUND IS NOT THE SAME QUESTION. A refresh that FAILS still
+# stores a plan - resolve_tariff() degrades to the §11.4 static fallback, which
+# is provisional and refuses arbitrage on its own. This bound covers the other
+# case: the refresh task itself dying, leaving a plan that was true hours ago
+# standing as if it were current. Three missed refreshes is the threshold, for
+# `p1.max_age_s`'s reason - one missed poll is not a fault, a run of them is.
+# A failed read is not an observation, and neither is a stale one.
+TARIFF_MAX_AGE_S = 3 * TARIFF_REFRESH_S
+
 
 def load_options() -> dict:
     try:
@@ -189,6 +222,33 @@ class Controller:
                                 cap_w=float(opts.get("peak_cap_w", 3500)))
         self.peak.restore(self.p1.averager)
         _LOG.info("capacity-tariff peak store: %s", self.peak.restore_state)
+
+        # SAFETY-07. The guard TARIFF-01 was built for. It is stateless by
+        # design (peakguard.py holds no history between calls), so the only
+        # state here is what an EDGE needs: what the last cycle concluded, so
+        # the action log and the notification fire on transitions rather than
+        # once per cycle for a quarter of an hour.
+        #
+        # ⚠️ THE CEILING HAS NO CONFIG OF ITS OWN, for the reason the clamp
+        # watchdog gives ~90 lines up and TARIFF-01 repeats: it is `peak_cap_w`,
+        # already shipped and already validated, and every other term of the
+        # projection is read off something the arbiter or the averager already
+        # owns.
+        #
+        # ⚠️ SAFETY-24'S FLOOR DOES HAVE ONE, AND IT COULD NOT NOT HAVE. How far
+        # down the guard may spend the pack for money is a number only the site
+        # knows, and refusing one set below the pack's own cut-out means knowing
+        # that cut-out too. So this card adds exactly two keys and reads their
+        # defaults from `peakguard.PEAK_OPTION_DEFAULTS` - TARIFF-02's mirror
+        # pattern - rather than typing literals here. THAT is what keeps CFG-03
+        # at three places: the divergence validate.py's rule 6 documents
+        # (`maintenance_charge_w` 2000 there, 2500 here) is exactly what a
+        # literal in this file would repeat.
+        self.peak_guard = None
+        self._peak_engaged = False
+        self._peak_saturated = False
+        self._peak_floor_limited = False
+        self._maint_shape_suspended = False
         # Set by amain() once the transport is built, so the status page can show
         # what only the transport knows (homewizard_local's unchanged_s). Stays
         # None when P1 is off, or under a transport that has no such counter.
@@ -213,6 +273,16 @@ class Controller:
         # window we are in and why it is or is not cheap - so "Cheap window:
         # no" is an evidenced answer rather than a bare no.
         self.tariff_words = "no static profile"
+
+        # OPT-04. The tariff plan the BACKGROUND task last resolved, and when.
+        # cycle() reads these two attributes and never awaits a fetch - see
+        # TARIFF_REFRESH_S. `None` means no refresh has completed yet, which is
+        # not "no prices" and certainly not "free": arbitrage.decide() reports
+        # it as its own reason and does nothing.
+        self.tariff_plan = None
+        self.tariff_at = None
+        self.arb = None
+        self._arb_action = None
         self.last_write = None
         self.last_write_at = None
         self.last_write_ok = None
@@ -424,6 +494,146 @@ class Controller:
                 self.log_event("inputs missing - commanding 0 W")
             claims.append(Claim.set("safety", P_SAFETY, 0.0, "inputs missing"))
 
+        # --- SAFETY-07: the quarter-peak projection guard --------------------
+        # ONE `lo` limit at P_PEAK, and peakguard.py carries the whole argument.
+        # What is decided HERE and nowhere else is what the guard is allowed to
+        # see and what it is allowed to ask for:
+        #
+        # ⚠️ `frozen` IS EVALUATED ON THIS CYCLE'S STANDING COMMAND, NOT ON
+        # `self.freeze_wd.active`. The watchdog object is advanced at the END of
+        # cycle() (check_meter_frozen), so reading its level here would grade
+        # this quarter against the PREVIOUS cycle's conjunction - one cycle of
+        # lag, in a guard whose entire job is to act inside a 900 s quarter.
+        # `standing` is the value SAFETY-02 already computed above for exactly
+        # this meaning: the command on the wire that this meter reading is a
+        # response to. The predicate itself is freeze.py's shipped
+        # `looks_frozen()`, not a copy of it - see loop_is_following() on what a
+        # transcribed safety predicate costs.
+        #
+        # ⚠️ `achievable_w` BOUNDS THE FLOOR SO THIS CLAIM CANNOT CONTRADICT THE
+        # SAFETY LIMITS ABOVE. `lo > hi` in the arbiter is a CONTRADICTION and
+        # resolves to 0 W - the battery parked, in the one minute of the month it
+        # should be discharging hardest. maintenance_charge_w had to learn the
+        # same lesson (config.yaml, validate.py rule 6); this claim is built so
+        # the config cannot express it.
+        #
+        # ⚠️ AND IT IS FILED EVERY CYCLE, unconditionally, like SAFETY-02's. A
+        # claim is not sticky. Filed once and skipped next cycle, the floor
+        # lapses and the actuator goes silently back to whatever was pushing the
+        # peak. Which of the higher-priority claims outranks it is arbiter.py's
+        # business, not this block's - and the answer is already right: a
+        # maintenance DRAIN or HOLD owns the setpoint at P_MAINTENANCE and
+        # commands discharge or zero, neither of which can create offtake, while
+        # a maintenance CHARGE is only ever a P_MAINT_SHAPE limit (40) and is
+        # therefore bound by this floor. That is §9.1's "money outranks the
+        # maintenance schedule", now as a consequence of the priorities.
+        #
+        # ⚠️ AND IT IS NOT RUN AT ALL WITHOUT P1. `meter_source: off` is the
+        # legacy single-entity path: there is no telegram stream, so
+        # `p1.averager` has no open block, so the guard would be BLIND on every
+        # cycle forever - and blind means "no charging". That is not a
+        # conservative default, it is a controller that silently stops charging
+        # on every install that has not opted in to P1 yet; test_clamp.py's
+        # export case caught it doing exactly that. The billed quantity simply
+        # is not measured on that path, and the honest report is NOT COVERED -
+        # the same answer, for the same reason, that the status page already
+        # gives for SAFETY-18 on a transport that cannot see `unchanged_s`.
+        dev_top = self.dev_max if self.dev_max is not None else max_w
+        self.peak_guard = None if not self.p1_enabled else peakguard.decide(
+            self.peak.project(self.p1.averager, now),
+            batt_w=self.batt,
+            cap_w=float(self.o.get("peak_cap_w", 3500)),
+            reading=self.peak.peak(now),
+            achievable_w=min(max_w, abs(float(dev_top))),
+            # ⚠️ SAFETY-24. `self.soc` IS THE MEASURED READING AND MAY BE None,
+            # and it is handed over as None rather than defaulted here. An early
+            # draft of the stage-5 loop read SoC as `| float(100)` and thereby
+            # invented a full battery (NOTES.md 4.4b); a full battery is
+            # precisely the value that disarms this floor. decide() treats None
+            # as floor-limited, which is the direction that costs a shave rather
+            # than the pack.
+            soc=self.soc,
+            soc_floor=float(self.o.get(
+                "peak_soc_floor",
+                peakguard.PEAK_OPTION_DEFAULTS["peak_soc_floor"])),
+            max_hold_s=self.p1.averager.max_hold_s,
+            frozen=looks_frozen(getattr(self.p1_source, "unchanged_s", None),
+                                standing, max_w, self.freeze_wd.cfg),
+        )
+        peak_claim = (peakguard.claim(self.peak_guard)
+                      if self.peak_guard is not None else None)
+        if peak_claim is not None:
+            claims.append(peak_claim)
+        # ⚠️ EDGE-LOGGED, not level-logged. The action log holds 40 lines; a
+        # guard that appended one every 15 s for a whole quarter would push the
+        # cause of the event off the end of the log that is meant to explain it.
+        # SAFETY-03 logs every engagement because a clamp engagement IS the
+        # count that matters there; here the count is the seconds, and the
+        # engagement's own reason line already carries them.
+        engaged_now = self.peak_guard is not None and self.peak_guard.engaged
+        if engaged_now != self._peak_engaged:
+            self._peak_engaged = engaged_now
+            if self.peak_guard is not None:
+                self.log_event(self.peak_guard.explain())
+
+        # --- OPT-04: price arbitrage (§10.1 priority 3) ----------------------
+        # ONE `set` claim at P_ARBITRAGE, and app/arbitrage.py carries the whole
+        # argument. What is decided HERE and nowhere else is what the strategy
+        # is allowed to see:
+        #
+        # ⚠️ IT IS PLACED AFTER THE PEAK BLOCK BECAUSE IT READS ITS CONCLUSION.
+        # `engaged_now` is this cycle's peak verdict, computed ~20 lines up.
+        # Evaluated before it, this would hand the strategy the PREVIOUS cycle's
+        # answer - one cycle of lag on the interlock that implements §9.1's
+        # "peak shaving outranks arbitrage", inside a 900 s quarter.
+        #
+        # ⚠️ AND THE THIRD STATE IS NOT A TIDINESS. Without P1 the guard is not
+        # CLEAR, it never RAN, and `None` says so. arbitrage.decide() refuses on
+        # it, because charging at max_w creates the billed quantity while
+        # nothing is measuring the quarter it lands in. `False` here would be
+        # this line asserting a measurement that was never taken - the defect
+        # `PeakReading` and `quarter_ceiling_w()` both exist to remove.
+        #
+        # ⚠️ THE THREE-STATE COLLAPSE LIVES IN arbitrage.guard_state(), NOT
+        # HERE, and that is not tidiness. It is the same lesson
+        # `shaping_suspended()` records: inline, this expression was reachable
+        # by no check, and mutating it back to a bare `engaged_now` left every
+        # suite in this repository green while a `meter_source: off` install
+        # traded blind. Read guard_state() before touching this line.
+        #
+        # ⚠️ NO FETCH ON THIS PATH. `fresh_tariff_plan()` is an attribute read
+        # and an age comparison; the HTTPS call lives in run_tariff_refresh().
+        # See TARIFF_REFRESH_S: a supplier's TLS timeout here would be a
+        # supplier able to push this add-on towards layer 1's 30 s veto.
+        #
+        # ⚠️ AND THE UNCERTAINTY SET IS NOT EMPTY BY DEFAULT. §11.4's
+        # no-weather row widens the threshold, and this add-on carries no
+        # weather forecast at all - §8.1's PV forecast is not built. Passing
+        # `frozenset()` would be main.py asserting a forecast is healthy when
+        # there is not one, which is exactly what static_tariff's `uncertainty`
+        # argument has no default in order to prevent.
+        self.arb = None
+        if arbitrage.enabled(self.o):
+            floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
+            self.arb = arbitrage.decide(
+                self.fresh_tariff_plan(now), now,
+                peak_guard_active=arbitrage.guard_state(self.peak_guard),
+                soc=self.soc,
+                min_spread_eur_kwh=arbitrage.threshold_eur_kwh(self.o),
+                uncertainty=frozenset({Uncertainty.NO_WEATHER}),
+                charge_w=max_w, discharge_w=max_w,
+                soc_floor_pct=floor_pct, soc_ceiling_pct=ceiling_pct)
+            arb_claim = arbitrage.claim(self.arb)
+            if arb_claim is not None:
+                claims.append(arb_claim)
+            # Edge-logged, for the peak guard's reason: the action log holds 40
+            # lines and a trade lasts a whole hour, so a line per cycle would
+            # flush the context that explains it. The transition is what an
+            # operator needs - "it started buying at 03:00", not 240 copies.
+            if self.arb.action != self._arb_action:
+                self._arb_action = self.arb.action
+                self.log_event(self.arb.explain())
+
         # --- maintenance -----------------------------------------------------
         if result.owns_setpoint:
             claims.append(Claim.set("maintenance", P_MAINTENANCE,
@@ -435,9 +645,44 @@ class Controller:
             # claimed, so the loop can discharge and shave the peak. When a
             # dedicated peak-shaving strategy arrives it will claim SET at
             # P_PEAK and outrank this limit without any code here changing.
-            if peak_at_risk(self.peak_fc, float(self.o.get("peak_cap_w", 3500))):
-                self.log_event("peak at risk - maintenance charge shaping suspended")
+            # ⚠️ AND SAFETY-07 IS THE OTHER HALF OF THIS CONDITION, NOT A
+            # SECOND MECHANISM. The shaping is `hi <= 0`; the peak guard's claim
+            # is `lo >= 0`. Both are limits, arbiter.py applies EVERY limit at or
+            # above the winner's priority, and most restrictive wins - so a peak
+            # event during a maintenance charge window files `lo > hi`, which is
+            # a CONTRADICTION and resolves to 0 W. The battery would park in the
+            # exact quarter it should be shaving. Priority does not save it:
+            # clause 2 has no notion of a higher-priority limit overriding a
+            # lower one, and it should not - "most restrictive" is what makes the
+            # safety bounds unconditional.
+            #
+            # So the higher-priority claimant SUPPRESSES the lower one rather
+            # than out-voting it, which is what this branch already did for
+            # `peak_forecast_entity`. That entity is optional and empty on a
+            # default install, so until now the suspension could not fire on the
+            # site that needed it. `self.peak_guard` is measured from the meter
+            # and is always there.
+            #
+            # ⚠️ THE CONJUNCTION LIVES IN peakguard.py, NOT HERE, and that is not
+            # tidiness. It was inline, and a reviewer mutated it back to its
+            # historical broken form - re-gated on `peak_forecast_entity` alone -
+            # and every suite in this repository stayed green while a default
+            # install parked at 0 W in the quarter that sets the month's bill.
+            # Read shaping_suspended() before touching this: both terms are
+            # there, and why neither is sufficient alone.
+            if peakguard.shaping_suspended(
+                    self.peak_guard, self.peak_fc,
+                    float(self.o.get("peak_cap_w", 3500))):
+                # Edge-logged: level-logging here would write one line per cycle
+                # for as long as the event lasts and flush the 40-line action log
+                # of the very context that explains it.
+                if not self._maint_shape_suspended:
+                    self._maint_shape_suspended = True
+                    self.log_event("peak at risk - maintenance charge shaping "
+                                   "suspended so the peak claim is not "
+                                   "contradicted")
             else:
+                self._maint_shape_suspended = False
                 hi = 0.0
                 reason = "charge-only"
                 if self.cheap:
@@ -552,6 +797,21 @@ class Controller:
         # is not, and test_freeze.py part 5 fails on exactly that.
         await self.check_meter_frozen()
 
+        # --- SAFETY-07's alarm, and it is NOT the engagement ------------------
+        # Its boundary is unconstrained: it grades `self.peak_guard`, which this
+        # method assigned above and nothing since has touched.
+        await self.check_peak_saturated()
+
+        # --- SAFETY-24's alarm, and it is the OTHER way the money gets spent --
+        # Same boundary argument as check_peak_saturated(): it grades
+        # `self.peak_guard`, which cycle() assigned above and nothing since has
+        # touched. Kept as its own method rather than folded into that one,
+        # because the two states are mutually exclusive and want OPPOSITE
+        # operator actions - saturation says "shed load, the inverter is already
+        # flat out"; this says "the pack is at its floor and this quarter is not
+        # being shaved at all".
+        await self.check_peak_floor_limited()
+
         # --- TARIFF-01, and it is LAST on purpose -----------------------------
         # Banking a quarter is bookkeeping about a moment that has already
         # happened; a slow SD card must never sit between the meter and the
@@ -643,6 +903,123 @@ class Controller:
                 f"for was itself out of range."),
         })
 
+    async def check_peak_saturated(self) -> None:
+        """SAFETY-07. Alarm ONLY when the guard has run out of inverter.
+
+        ⚠️ AN ENGAGEMENT IS NOT AN ALARM, AND THE DIFFERENCE IS §10.3's DOCTRINE
+        READ CAREFULLY. "Treat an out-of-range computed setpoint as a bug signal
+        - clamp it, then alarm" is SAFETY-03's rule and it is right there: the
+        loop computing 14 768 W is a WINDING INTEGRATOR, a defect, and clipping
+        it silently is what let it keep climbing behind a dashboard full of legal
+        numbers. A peak floor above the inverter's rating is not a defect. It is
+        a house load bigger than the inverter - 2026-08-20 15:45 ran ~5900 W
+        against a 5000 W unit - and alarming on the ordinary case is how an
+        operator learns to dismiss the notification that matters. So an
+        engagement is an ordinary control action: it goes to the §15 action log
+        and the status page, and no further.
+
+        What DOES earn the operator's attention is saturation: the guard asked
+        for more discharge than the inverter can give, so the quarter is going
+        over the ceiling anyway and the controller has already done everything
+        available to it. That is the one state where the money is going to be
+        spent and a human is the only remaining actuator.
+
+        Edge-triggered, and de-asserting arms it again - the same shape as
+        FreezeWatchdog's `evaluate()`, and for the same reason: one notification
+        per episode, not one per cycle.
+        """
+        g = self.peak_guard
+        saturated = bool(g is not None and g.saturated)
+        was, self._peak_saturated = self._peak_saturated, saturated
+        if not saturated or was:
+            return
+        self.log_event("PEAK GUARD SATURATED - " + g.reason)
+        _LOG.error(
+            "SAFETY-07 - %s. The guard is asking for everything the inverter "
+            "has and the quarter is still projected over the ceiling: this "
+            "quarter will set or raise the month's billed capacity peak. The "
+            "controller is STILL RUNNING and still shaving; there is nothing "
+            "further it can do. Shed load.", g.reason)
+        # A fixed notification_id, and a DIFFERENT one from every other alarm
+        # here - check_meter_frozen() gives the reasoning. A saturated peak guard
+        # is not a frozen meter and is not an out-of-range setpoint.
+        await self.hass.call("persistent_notification", "create", {
+            "notification_id": "goodwe_peak_saturated",
+            "title": "GoodWe: the capacity-peak guard has run out of inverter",
+            "message": (
+                f"{g.reason}.\n\nThe battery is being commanded to everything "
+                f"it can give and the quarter is STILL projected over the "
+                f"{g.ceiling_w:.0f} W ceiling, so this quarter will set or raise "
+                f"the month's billed capaciteitstarief peak. This is not a "
+                f"controller fault - the load is simply larger than the "
+                f"inverter. Shedding load in the next few minutes is the only "
+                f"thing that changes the bill."),
+        })
+
+    async def check_peak_floor_limited(self) -> None:
+        """SAFETY-24. Alarm when the EMS SoC floor stops the guard shaving.
+
+        ⚠️ FAILING TO SHAVE MUST NOT BE SILENT, AND THAT IS THE WHOLE POINT.
+        The guard exists for one euro figure - the capaciteitstarief bills the
+        month's single worst quarter - so a cycle in which it CHOSE not to shave
+        is a cycle in which money is being spent on purpose. Under-shaving
+        quietly would leave the operator with a bill and a status page full of
+        green.
+
+        The distinction from check_peak_saturated() is the operator's action,
+        which is why these are two notifications and not one:
+
+          saturated      the guard asked for everything the inverter has and it
+                         was not enough. SHED LOAD - the controller has already
+                         done all it can, and it is still discharging.
+          floor-limited  the guard asked for NOTHING, because the pack is at or
+                         under the EMS floor, or its SoC could not be read.
+                         Nothing is being discharged for this quarter at all.
+
+        They cannot both be true: peakguard.decide()'s floor-limited branch
+        returns before the `achievable_w` clamp that sets `saturated`.
+
+        Edge-triggered, and de-asserting arms it again - FreezeWatchdog's shape,
+        for FreezeWatchdog's reason: one notification per episode, not one per
+        cycle for a quarter of an hour.
+        """
+        g = self.peak_guard
+        limited = bool(g is not None and g.floor_limited)
+        was, self._peak_floor_limited = self._peak_floor_limited, limited
+        if not limited or was:
+            return
+        # No prefix: `reason` already opens with PEAK GUARD FLOOR-LIMITED, and
+        # a second copy is the kind of stutter that makes a 40-line action log
+        # read like boilerplate. The saturated path needs its prefix because its
+        # reason carries the word in the middle of a sentence, not at the front.
+        self.log_event(g.reason)
+        _LOG.error(
+            "SAFETY-24 - %s. The controller is STILL RUNNING and charging is "
+            "still blocked, but it is not discharging to hold this quarter, so "
+            "the quarter will set or raise the month's billed capacity peak. "
+            "Shed load, or lower peak_soc_floor if this pack can afford it.",
+            g.reason)
+        # A fixed notification_id, and a DIFFERENT one from every other alarm
+        # here - check_meter_frozen() gives the reasoning. A battery at its
+        # energy floor is not a saturated inverter and is not a frozen meter,
+        # and an operator who has to dismiss three identical-looking cards
+        # learns to dismiss the one that mattered.
+        await self.hass.call("persistent_notification", "create", {
+            "notification_id": "goodwe_peak_soc_floor",
+            "title": "GoodWe: the capacity-peak guard has run out of battery",
+            "message": (
+                f"{g.reason}.\n\nTHIS QUARTER WILL GO OVER THE "
+                f"{g.ceiling_w:.0f} W ceiling and will set or raise the "
+                f"month's billed capaciteitstarief peak, because the peak guard "
+                f"is not allowed to discharge any further: {g.soc_floor_reason}."
+                f" This is not a controller fault - it is the EMS-side energy "
+                f"floor (peak_soc_floor) doing what it is set to do, and it sits "
+                f"deliberately above the pack's own BMS cut-out. Charging stays "
+                f"blocked. Shedding load is the only thing that changes the bill "
+                f"now; if this pack can afford a deeper discharge, lower "
+                f"peak_soc_floor."),
+        })
+
     async def check_meter_frozen(self) -> None:
         """SAFETY-18. Alarm on a meter that answers forever without changing.
 
@@ -683,6 +1060,57 @@ class Controller:
         })
 
     # -- tasks ---------------------------------------------------------------
+    # -- OPT-04: the background tariff refresh -------------------------------
+    def fresh_tariff_plan(self, now):
+        """The stored plan if it is still current, else None. NEVER a stale one.
+
+        ⚠️ THIS IS THE ONE PLACE THE AGE IS JUDGED, and it is public for
+        `loop_is_following()`'s reason: a check has to be able to assert on the
+        shipped expression rather than on a transcription that drifts. Both
+        terms are required - a plan with no timestamp is one nothing stored, and
+        a timestamped plan older than TARIFF_MAX_AGE_S is a reading from a task
+        that has stopped answering.
+        """
+        if self.tariff_plan is None or self.tariff_at is None:
+            return None
+        if (now - self.tariff_at).total_seconds() > TARIFF_MAX_AGE_S:
+            return None
+        return self.tariff_plan
+
+    async def run_tariff_refresh(self) -> None:
+        """Resolve the tariff off the control path, forever. NEVER on the tick.
+
+        ⚠️ IT CATCHES EVERYTHING AND KEEPS GOING, for MqttPublisher's reason:
+        a supplier's outage, a certificate expiry, a malformed feed - all of it
+        is pricing, and the battery does not care. What it must never do is
+        raise out of here and take the task down, because then the plan freezes
+        at its last value and looks current forever. That is what
+        `fresh_tariff_plan()`'s age bound is the backstop for, and this is the
+        half that keeps the task alive so the bound rarely matters.
+
+        ⚠️ AND A FAILURE DOES NOT CLEAR THE PLAN. `resolve_tariff()` already has
+        a §11.4 answer for a dead feed - degrade to the static profile, mark it
+        provisional, arbitrage refuses - and that answer is better than the
+        absence of one. Zeroing the plan here would replace a coarse tariff with
+        no tariff, which is the opposite of what §11.4 asks for.
+        """
+        horizon = float(price_option(self.o, "price_horizon_h"))
+        while not self.stopping:
+            now = datetime.now(timezone.utc)
+            try:
+                plan = await resolve_tariff(
+                    self.o, now, now + timedelta(hours=horizon), now=now)
+                self.tariff_plan, self.tariff_at = plan, now
+                _LOG.info("tariff refreshed: %s", plan.words)
+            except Exception as err:                          # noqa: BLE001
+                _LOG.warning(
+                    "tariff refresh failed (%s); keeping the plan resolved at "
+                    "%s. It retires on its own after %.0f s and arbitrage "
+                    "stops with it.", err, self.tariff_at, TARIFF_MAX_AGE_S)
+            with contextlib.suppress(asyncio.TimeoutError):
+                await asyncio.wait_for(self.stop_event.wait(),
+                                       timeout=TARIFF_REFRESH_S)
+
     async def run_control(self) -> None:
         entity = self.o.get("setpoint_entity", "")
         if entity:
@@ -918,6 +1346,47 @@ class Controller:
                                       f"{self.peak.cap_w:.0f} W soft limit"
                                     + f"; {self.peak.recorded} quarter(s) banked"
                                     + f"; on start: {self.peak.restore_state}"})
+
+            # SAFETY-07. Three rows, not one, because "idle" and "cannot see"
+            # are opposite states and a page that spelled them the same way
+            # would show a green line over a guard that is switched off. `None`
+            # is a fourth state on purpose: before the first cycle the guard has
+            # concluded nothing, and saying "idle" then would be a claim about a
+            # decision that has not been taken.
+            _pg = self.peak_guard
+            if _pg is None:
+                out.append({"ok": True, "warn": True,
+                            "text": "peak guard: no decision yet - the first "
+                                    "control cycle has not run"})
+            elif _pg.saturated:
+                out.append({"ok": False, "warn": False,
+                            "text": "PEAK GUARD SATURATED - " + _pg.reason})
+            elif _pg.floor_limited:
+                # SAFETY-24. NOT ok, like saturation: in both states the money
+                # is going to be spent and a human is the only actuator left. A
+                # separate row from saturation because the two ask for opposite
+                # things - see check_peak_floor_limited().
+                out.append({"ok": False, "warn": False,
+                            "text": _pg.explain()})
+            elif _pg.blind:
+                out.append({"ok": False, "warn": True, "text": _pg.explain()})
+            else:
+                out.append({"ok": not _pg.engaged, "warn": _pg.engaged,
+                            "text": _pg.explain()})
+        else:
+            # ⚠️ OUTSIDE the `p1_enabled` block, and that placement is the point.
+            # SAFETY-07 is NOT COVERED on the legacy single-entity path - the
+            # quarter-hour average is measured from P1 telegrams and this path
+            # has none - and a row that only rendered where the guard runs would
+            # leave the one install that is unprotected showing nothing at all.
+            # Same answer, same reason, as the freeze detector's NOT COVERED row
+            # a few lines up.
+            out.append({"ok": False, "warn": True,
+                        "text": f"peak guard: NOT COVERED on meter_source "
+                                f"{o.get('meter_source')} - the quarter-hour "
+                                f"average is measured from P1 telegrams and this "
+                                f"path has none, so a runaway cannot be capped"})
+
         rows = [("battery SoC", self.soc, o.get("soc_entity")),
                 ("battery power", self.batt, o.get("batt_entity"))]
         if not self.p1_enabled:
@@ -1026,6 +1495,11 @@ class Controller:
             ("Maintenance due", "now" if next_due is None else next_due.strftime("%Y-%m-%d")),
             ("Cheap window", "yes" if self.cheap else "no"),
             ("Tariff", self.tariff_words),
+            # OPT-04. The strategy's own sentence, not a re-derivation of it -
+            # every refusal it can make already carries a reason a human can
+            # act on, and "Arbitrage: no" would throw all of them away.
+            ("Arbitrage", "off (arbitrage_enabled)" if self.arb is None
+             else self.arb.explain()),
         ]
         return {
             "banner": banner, "level": level, "rows": rows, "checks": checks,
@@ -1153,6 +1627,19 @@ async def amain() -> None:
 
         tasks = [asyncio.create_task(controller.run_control())]
 
+        # OPT-04. The tariff refresh runs as its OWN long-lived task, for the
+        # reason P1 ingestion does and then some: `resolve_tariff()` may open an
+        # HTTPS connection to a supplier, and the control tick is what feeds the
+        # ESP32 heartbeat. A fetch on that path is a supplier's TLS timeout able
+        # to push this add-on towards layer 1's 30 s veto. See TARIFF_REFRESH_S.
+        #
+        # ⚠️ STARTED ONLY WHEN ARBITRAGE IS ARMED. Nothing else in the add-on
+        # reads the resolved plan - `cheap` still comes from static_status() on
+        # the tick, which is pure - so on a default install this task would be
+        # network traffic in aid of an attribute nobody reads.
+        if arbitrage.enabled(opts):
+            tasks.append(asyncio.create_task(controller.run_tariff_refresh()))
+
         # P1 ingestion runs as its own long-lived task. ⚠️ It must not be driven
         # off the control loop: telegrams arrive every ~5 s and the loop would
         # decimate them, so the 15-minute average - the capacity-tariff billing

goodwe_controller/app/p1.py

@@ -286,6 +286,26 @@ class QuarterAverager:
         """Offtake watt-seconds accumulated in the open block so far."""
         return self._acc
 
+    @property
+    def held_net_w(self) -> float:
+        """The signed net power currently being held forward, in W.
+
+        PUBLIC BECAUSE SAFETY-07 DEPENDS ON IT, AND THAT IS THE WHOLE REASON.
+        `PeakTracker.project()` extrapolates the rest of the quarter from this
+        value and used to reach it as `getattr(averager, "_last_net", 0.0)`. A
+        default on a private name fails QUIET and fails in the DISARMING
+        direction: rename `_last_net` and every projection silently credits 0 W
+        held, which reads LOW, which puts the peak guard under the ceiling
+        exactly when the meter says it is over. Filed as TEST-13 item 4 and
+        fixed here rather than inherited - a money guard may not rest on a read
+        that can go wrong without a symptom.
+
+        Positive is offtake, matching `P1Sample.net_w`. It is the raw held
+        value, NOT floored at zero: the flooring is the accumulator's rule (only
+        offtake is billed) and belongs where it is applied, not here.
+        """
+        return self._last_net
+
     @property
     def offtake_avg_w(self) -> float:
         """Average offtake over the part of the open block seen so far."""

goodwe_controller/app/peakguard.py

@@ -0,0 +1,725 @@
+"""SAFETY-07 - the quarter-peak projection guard, and the only thing in this
+add-on that is allowed to spend the loop's freedom to save money.
+
+WHAT IT IS. TARIFF-01 built the INSTRUMENT: `tariff.py` measures the number the
+Belgian capaciteitstarief bills on - the highest 15-minute average offtake of the
+calendar month - and banks it where a restart cannot reach. It files no claim and
+commands nothing, and says so in its own first paragraph. This module is the
+CONSUMER it named. It turns that measurement into one arbiter claim and nothing
+else: no writes, no I/O, no clock, no state between calls. Given a projection and
+two measured numbers it returns a decision; `main.py` files it.
+
+------------------------------------------------------------------------------
+THE HAZARD, WITH THE EURO FIGURE
+
+specs.md:583 records a measured case: ONE 4998 W quarter moved a monthly peak
+from 4832 W to 5013 W and billed the whole month at it. The capacity tariff has
+no averaging and no forgiveness - the month's single worst quarter is the bill.
+
+SAFETY-18 shipped the ALARM for the way this system produces such a quarter by
+itself: a meter that answers 200 OK forever with a document that never changes,
+which every freshness mechanism in this stack reads as healthy while the loop
+integrates a constant error to the rail and holds it there. freeze.py's own
+table: at the live install's `max_w: 5000`, a meter frozen at >= 3000 W rails the
+command in 75 s. SAFETY-18 notifies at `meter_freeze_s` (300 s default), against
+a 900 s billing quarter. That is about nine minutes of human reaction time and
+nothing else - freeze.py says so in the words "THIS CUT DOES NOT CAP THAT."
+
+This is the cap. It is deliberately NOT a second freeze detector: it consumes
+freeze.py's shipped predicate rather than transcribing it.
+
+------------------------------------------------------------------------------
+THE MECHANISM: ONE `lo` LIMIT AT `P_PEAK`, AND WHY THAT SHAPE
+
+specs.md 10.1 row 2 asks for exactly two behaviours - "pre-emptive discharge as
+the projected quarter average approaches the soft limit; hard clamp on charging
+above it" - and 9.1 constrains the lever: "Discharge and export are never capped
+by the peak guard; only charging and import are."
+
+A LOWER BOUND on the setpoint is both of those in one object, and it is the only
+shape that is:
+
+  * incapable of capping discharge - a floor never stops the loop discharging
+    HARDER, so 9.1's asymmetry is structural here rather than remembered;
+  * incapable of capping export, for the same reason;
+  * a hard clamp on charging whenever the floor is above the standing charge;
+  * pre-emptive discharge whenever the floor is above zero.
+
+It is a LIMIT, not a SET, and that matters at both ends of the priority table.
+`P_PEAK` (50) is above `P_LOOP` (10), so it binds the grid-following loop. It is
+BELOW `P_MAINTENANCE` (60) and `P_SAFETY` (100), so a maintenance phase that owns
+the actuator and every layer-1 stop still outrank it: arbiter.py's clause 2 only
+applies limits whose priority is >= the WINNING SET's, so a P_SAFETY 0 W stop is
+not dragged off zero by this floor. That is the correct order - a controller
+pushing power the wrong way is wrong however much money it is trying to save.
+
+⚠️ AND A LIMIT DOES NOT OUT-VOTE ANOTHER LIMIT. This was assumed, and it is
+false: arbiter.py clause 2 applies EVERY limit at or above the winner's priority
+and takes the MOST RESTRICTIVE, with no notion of priority between them - which
+is exactly what makes the safety bounds unconditional and must not be changed.
+So this floor (`lo >= 0`) and the maintenance charge-only shaping (`hi <= 0`) do
+not resolve in P_PEAK's favour when both are filed. They resolve to `lo > hi`, a
+CONTRADICTION, which arbiter.py answers with 0 W - the battery parked in the one
+quarter of the month it should be shaving hardest. The rule for two limits that
+can cross is therefore SUPPRESSION, not priority: main.py drops the maintenance
+shaping for as long as this guard is engaged, which is the same thing that branch
+already did for `peak_forecast_entity` and is why 9.1's "money outranks the
+maintenance schedule" reads as a suppression there rather than as a priority
+here. The floor's clamp to `achievable_w` closes the only other pair that could
+cross - the P_SAFETY rating bounds.
+
+AND IT IS WHY OPT-04 NEEDS NO CHANGE HERE. 9.1 requires peak shaving to outrank
+arbitrage. Arbitrage does not exist yet, but it will arrive as a SET below
+P_PEAK, and arbiter.py clause 2 will bind it with this floor on the day it lands,
+with no edit to this file. Expressing the priority as a claim rather than as an
+if/else in main.py is the whole reason that holds.
+
+------------------------------------------------------------------------------
+THE FLOOR IS DERIVED, AND EVERY TERM OF IT IS MEASURED
+
+Let `ceiling_w` be the quarter average that must not be exceeded and `remaining`
+the seconds left in the open block. `project()` gives
+
+    projected = (acc + held * remaining) / 900
+
+so the held level that would land the quarter exactly on the ceiling is
+`held + 900 * (ceiling - projected) / remaining`, and the watts that must come
+off the meter are the difference between the two:
+
+    excess_w = 900 * (projected - ceiling) / remaining
+
+That single expression carries the whole control law, and two properties of it
+are the argument for this design:
+
+  1. THE CLAIM IS FILED WHILE THE FLOOR IS POSITIVE, NOT WHILE THE EXCESS IS.
+     `excess` is what must come off the METER, so it falls to zero the moment the
+     battery is already taking it - and a guard that disengaged there would hand
+     the actuator back, watch the offtake spring straight to the raw load, and
+     engage again next cycle. That is not a hypothetical: it is what the first
+     cut of this file did to 2026-08-20's billed quarter on replay - seventeen
+     engage/release cycles in 900 s, and the quarter still finished 49 W over the
+     limit it had spent a quarter of an hour holding. 10.2 names the cost
+     exactly: "an EMS that oscillates is worse than no EMS, both for hardware
+     wear and - per 9.1 - for the peak it is trying to avoid."
+
+     `batt_w + excess` IS the quantity to threshold: the offtake there would be
+     with the battery at zero, less the level this quarter can still afford. Read
+     as a LEVEL rather than as a switch, the same arithmetic gives a claim that
+     is filed for as long as a positive floor is needed and decays continuously
+     to nothing as the load falls. So there is still no hysteresis constant in
+     this file - not because oscillation was ruled out by argument, but because
+     the thresholded quantity is the one that does not oscillate.
+
+  2. THE GAIN IS 900/remaining, WHICH IS 1.0 AT THE START OF THE QUARTER AND
+     GROWS. This is the answer to the degeneracy at the top of a block, where the
+     projection is an extrapolation from almost no evidence: the guard is at its
+     GENTLEST exactly when its evidence is weakest, and becomes aggressive only
+     once most of the quarter is behind it and the projection is nearly a
+     measurement. The formula supplies that; no minimum-evidence threshold was
+     invented, because inventing one would delay the guard in the case it exists
+     for - a sustained rail from second zero.
+
+The floor itself is then
+
+    floor_w = batt_w + excess_w
+
+`batt_w` IS THE MEASURED BATTERY POWER, NOT THE STANDING COMMAND. Both were
+available. The measured one is right for two independent reasons. First, 9.1's
+settled constraint is that the utility bills what FLOWED - the arithmetic
+`grid = load - batt` is true of delivered power and false of intent. Second, and
+concretely: when the inverter cannot follow (the saturation case control.py
+already freezes the integrator for), a floor built on the command asks for
+`command + excess` every cycle while the command never arrives, and winds itself
+to the rail; a floor built on the measurement asks for `delivered + excess`,
+which stops rising the moment delivery stops rising. The delivered form cannot
+wind up. The intent form can.
+
+------------------------------------------------------------------------------
+THE CEILING IS `peak_cap_w`, RAISED ONLY BY AN OBSERVATION
+
+11.2's row is "Quarter peak | Projected quarter average approaches THE MONTHLY
+PEAK | Clamp the command", and 9.1's soft limit is `peak_cap_w`. Both matter,
+because the money is spent on `max(month's peak so far, this quarter)`:
+
+    ceiling_w = max(peak_cap_w, the month's banked peak)
+
+Once a month's peak already stands at 5013 W, holding every later quarter to
+3500 W buys nothing - the bill for that month is already 5013 W - while the
+holding itself costs real charging the site wanted. Raising the ceiling to a peak
+that has already been paid for is what stops one bad quarter from parking the
+battery's charging for three weeks.
+
+AND THAT RELAXATION IS GRANTED ONLY BY AN `OBSERVED` READING. `NO_RECORD` and
+`NOT_OBSERVED` both leave the ceiling at `peak_cap_w`, the tighter of the two, so
+a peak store that cannot be read makes this guard STRICTER and never looser. That
+direction is the whole point: tariff.py's `PeakReading` exists because a database
+that did not answer must not become a number, and the number it would have become
+here - a zero peak - is exactly the one that reads as "no peak recorded, full
+freedom". It is also why this module does NOT consume `headroom_w()`, whose
+disarming failure it would otherwise inherit: a peak read as 0 W returns FULL
+headroom, and full headroom is a guard that is not there.
+
+------------------------------------------------------------------------------
+BLINDNESS COMES FIRST, AND IT IS A DIFFERENT ACTION
+
+A projection is evidence only if the quantity under it was actually measured.
+Three ways it is not, all of them checked BEFORE the projection is graded,
+because grading a stimulus where the quantity it grades is degenerate is how a
+guard passes its own tests while being switched off:
+
+  * NO OPEN BLOCK. `project()` answers a fresh averager with
+    `Projection(0.0, 0.0, 0.0, 0.0, False, None, 0.0)` - a ZERO projection, which
+    compares as comfortably under any ceiling. That is not "the quarter is fine",
+    it is "there is no quarter". Graded as a number it silently disarms the guard
+    on exactly the startup path where nothing else is watching.
+
+  * COVERAGE. A meter gap longer than one `max_hold_s` window leaves seconds that
+    `QuarterAverager` deliberately does not accumulate (p1.py: holding a dead
+    meter's last value forward is how a fabricated peak gets onto a permanent
+    record). Those seconds make the projection read LOW, which is the
+    under-guarding direction. The threshold is `max_hold_s` itself - the point
+    p1.py already stops trusting a held sample - not a new number.
+
+  * FROZEN. SAFETY-18's conjunction, evaluated through `freeze.looks_frozen()`
+    rather than re-written here. A frozen meter is the worst case of all: the
+    samples keep ARRIVING, so coverage stays perfect and the projection is
+    confident - and if the stuck value is an export, the projection is a
+    confident ZERO while the real meter runs at the rail. This is the case
+    SAFETY-07 exists to backstop, and it is the case a projection cannot see.
+
+THE BLIND ACTION IS `floor_w = 0.0`: the battery may not IMPORT while the billed
+quantity is unobservable. It is the minimal action that closes the hazard, and it
+is one-directional - forbidding charging can only ever lower delivered offtake,
+never raise it - so a false blindness costs a charge the site wanted and cannot
+cost energy the pack did not want to give. Contrast the graded branch, which can
+force discharge; blindness deliberately does not earn that, because there is by
+definition no measurement to size it from.
+
+------------------------------------------------------------------------------
+WHY THIS ONE TRIPS WHERE SAFETY-18 ONLY NOTIFIES
+
+SAFETY-18 shipped notification-first, and config.yaml says why in one line: "A
+false trip parks the battery; a false alarm costs an alert." That reasoning is
+right for a DETECTOR whose negative case had to be established on a rig run. It
+does not carry to this guard, and the two committed captures say so:
+
+  * MEASURED FALSE-ENGAGEMENT RATE ON THE HEALTHY DAY: zero. 2026-08-23's worst
+    quarter is a few hundred watts against a 3500 W ceiling and nothing in its 95
+    quarters comes near engaging. test_peakguard.py re-measures that every run
+    from the committed capture rather than quoting it here.
+  * THE ACTION IS LEVEL-TRIGGERED AND UNLATCHED. It is re-derived from a fresh
+    projection every cycle and releases the instant the projection drops back
+    under the ceiling. There is no state to clear and no operator to wake. A
+    false engagement costs one cycle of discharge, not a parked battery - which
+    is precisely the cost SAFETY-18 could not bound and this one can.
+  * THE ACTION IS A LIMIT, NOT A SET. Every safety stop in 11.2's table outranks
+    it, so the worst thing a bug in this file can do is fail to relax a floor -
+    and a floor is bounded above by `achievable_w`, which main.py takes from the
+    same `max_w` and device rating the arbiter already enforces.
+
+So it trips. It is also the only guard here whose trigger IS the billed quantity
+itself, measured from parsed P1 telegrams, rather than a proxy for it.
+
+------------------------------------------------------------------------------
+SATURATION IS REPORTED, NOT ALARMED AS A BUG
+
+10.3's doctrine - "treat an out-of-range computed setpoint as a bug signal, clamp
+it AND alarm" - is SAFETY-03's, and it is right there: a loop computing 14 768 W
+is a winding integrator, i.e. a defect. A peak floor above the inverter's rating
+is NOT a defect. It is the ordinary physics of a 5900 W house load on a 5000 W
+inverter, which is literally what 2026-08-20 15:45 was. So the floor is clamped
+to `achievable_w` and the decision carries `saturated`, and main.py raises ONE
+notification on that - not because the controller is broken, but because it is
+the one case where the money WILL be spent and the controller has already done
+everything it can. An engagement that is not saturated is an ordinary control
+action and goes to the action log, like the clamp's engagements do.
+
+------------------------------------------------------------------------------
+NO NEW OPTION. CFG-03 STILL TRACKS THREE PLACES.
+
+`peak_cap_w` already ships, is already validated `int(500,15000)`, and is already
+read by `control.peak_at_risk()`. `max_hold_s` comes off the averager the caller
+already owns; `achievable_w` off `max_w` and the device rating the arbiter
+already enforces; the freeze predicate off `meter_freeze_s`. config.yaml and
+validate.py are untouched by this ticket, exactly as TARIFF-01 left them, and
+14's `capacity_peak_limit_kw` stays declined - a kW key beside a W key is the
+mismatch trap 14's own warning box describes.
+
+------------------------------------------------------------------------------
+SAFETY-24: THE ENERGY BACKSTOP THIS GUARD SHIPPED WITHOUT
+
+SAFETY-07 left this file saying, in its own words, that the graded branch can
+FORCE DISCHARGE and that nothing below it consults the state of charge - "the
+BMS is the sole energy backstop" (freeze.py). On the 2026-08-20 replay the guard
+asks for 878 Wh in a day, and it keeps asking for as long as the meter says the
+quarter is over the ceiling. That is the behaviour working as designed, and it
+is unbounded from below by anything in the EMS.
+
+⚠️ STATE THE RISK FAIRLY, because overstating it is how a real one gets ignored.
+Relying on the BMS is not absurd: it is a genuine floor and it works. But it is
+THE PACK's protection, not the OPERATOR's. A month of aggressive quarters can
+leave the battery repeatedly parked at that floor with no EMS-side record of
+why, and the first symptom - a pack that is never available when it is wanted -
+is indistinguishable from the SoC drift MAINT-01 exists to correct.
+
+So `decide()` now takes `soc` and `soc_floor`, and `discharge_permitted()` is
+the one place the question is answered. Four things about the shape of it:
+
+  1. IT IS NOT A TRIP, AND IT MUST NOT BECOME ONE. SAFETY-07's claim is a LIMIT
+     and every stop in 11.2's table still outranks it. This floor is about
+     ENERGY - how far down the guard may spend the pack for money - not about
+     last-resort safety. The action when it binds is therefore to stop ASKING
+     for more discharge, not to command anything.
+
+  2. THE ACTION IS `floor_w = 0.0`, WHICH IS THE BLIND BRANCH'S ACTION FOR THE
+     BLIND BRANCH'S REASON. Zero is one-directional: it forbids CHARGING, which
+     can only ever lower delivered offtake, and it forbids nothing else. It
+     cannot pull the loop off a discharge it is already doing, because a `lo`
+     limit structurally cannot cap discharge - the property this module's whole
+     shape rests on, and one a NEGATIVE floor would destroy. Nothing here can
+     produce a negative floor: the only two values `floor_w` ever takes are 0.0
+     and `min(wanted, achievable)` with `wanted > 0` already established.
+
+     ⚠️ AND IT DOES NOT BOUND THE LOOP. Self-consumption may still drain the
+     pack past this floor, exactly as SAFETY-18 recorded. That is not fixed
+     here and must not be claimed: this card bounds THE PEAK GUARD's OWN forced
+     discharge, which is the thing SAFETY-07 introduced. A loop-side SoC guard
+     is a different lever with a different right value.
+
+  3. IT IS GRADED ONLY WHERE IT IS NOT DEGENERATE. The SoC question is asked
+     AFTER `wanted > 0` is established - i.e. only where a forced discharge is
+     actually being asked for. Asked earlier it would grade a quantity that
+     governs nothing, and would report "floor-limited" on a quiet afternoon
+     where the guard was never going to discharge anyway.
+
+  4. AN UNREADABLE SoC IS NOT A FULL BATTERY. `soc=None` is floor-limited, not
+     permitted. This is `PeakReading`'s lesson in the one place it bites
+     hardest: a full battery is exactly the value that would disarm this floor,
+     so a failed read defaulting to one would silently restore the unbounded
+     discharge this card exists to remove. Both new arguments are REQUIRED
+     keyword-only and neither has a default, which is TEST-14 read as a rule
+     rather than as a story: a required field that gains a default is how three
+     separate files in this repo shipped a quiet fallback.
+
+AND FAILING TO SHAVE MUST NOT BE SILENT. The whole point of the guard is the
+euro figure, so a floor-limited cycle carries `floor_limited=True` and main.py
+raises ONE notification on the edge, saying the quarter will be exceeded - the
+same shape, and the same argument, as `saturated`. The two are mutually
+exclusive by construction: a floor-limited decision asks for nothing, so it
+cannot have run out of inverter.
+
+------------------------------------------------------------------------------
+CFG-03: TWO NEW OPTIONS, MIRRORED ONCE, AND WHY BOTH ARE NEEDED
+
+SAFETY-07 added none and said so. This card cannot: an EMS-side floor is a
+number only the site knows, and refusing one set below the pack's own cut-out
+means knowing that cut-out too.
+
+  * `peak_soc_floor` - the EMS floor. ⚠️ NOT `maintenance_soc_floor`. That is
+    the maintenance cycle's DRAIN TARGET: the depth a monthly recalibration
+    deliberately goes to, once, under supervision. This is the depth a
+    money-saving discharge may never reach, on any day of the month. Sharing
+    one key would couple two features whose right values differ and would widen
+    CFG-03 rather than narrow it.
+  * `bms_soc_floor` - the pack's own cut-out (register 0x0560 on the reference
+    unit, 10 %). It is here so validate.py rule 8 can REFUSE a `peak_soc_floor`
+    at or below it. That configuration is CFG-01 rule (a): the operator states
+    a floor, the BMS enforces a different one, and the status page reports an
+    energy backstop that can never bind.
+
+Both defaults are mirrored ONCE, in `PEAK_OPTION_DEFAULTS` below, which is
+TARIFF-02's `PRICE_OPTION_DEFAULTS` pattern - imported by validate.py and by
+main.py, pinned to config.yaml by test_peakguard.py rather than transcribed.
+This module still reads no option itself: `decide()` takes both as ARGUMENTS,
+makes no `.get()` call, and the mirror is a default table, not a read.
+
+⚠️ A DECISION RECORDED, NOT A RENAME DONE. Now that a second SoC floor exists,
+`maintenance_soc_floor` is the ambiguous name of the two - it reads like "the
+SoC floor" and is not. Renaming it is an option migration on a live install for
+a clarity gain, so the decision recorded here is: KEEP IT, and carry the
+distinction in DOCS.md and in this comment. Revisit if a THIRD floor appears -
+a loop-side guard would be the third - at which point the migration buys enough
+to be worth its cost.
+
+------------------------------------------------------------------------------
+AND IT READS NO PER-PHASE QUANTITY, ON PURPOSE
+
+The sum/max/net reduction is an open product question with the owner. TARIFF-01
+put it behind `billed_w()` and defaulted to NET. Everything this module consumes
+- `PeakReading.peak_w`, `Projection.projected_w` - is already reduced by that one
+function, so whichever way the owner answers, this file does not change and does
+not need re-testing. Nothing here indexes a phase.
+"""
+
+from dataclasses import dataclass
+
+from .arbiter import P_PEAK, Claim
+from .control import peak_at_risk
+from .tariff import QUARTER_S
+
+# Why the projection may not be graded. Reasons, not booleans: the status page
+# and the action log both have to say WHICH, and "blind" alone is unactionable.
+BLIND_NO_BLOCK = "no open quarter - the meter has produced no sample yet"
+BLIND_COVERAGE = "meter gap"
+BLIND_FROZEN = "SAFETY-18: the meter is answering without changing"
+
+# Where the ceiling came from. Only the second is a relaxation, and only an
+# OBSERVED reading may produce it.
+CEILING_CAP = "peak_cap_w"
+CEILING_MONTH_PEAK = "the month's banked peak"
+
+# SAFETY-24. Why the forced discharge may not be sized. Reasons, not booleans,
+# for BLIND_*'s reason: the status page, the action log and the operator
+# notification all have to say WHICH, and "floor-limited" alone is unactionable.
+FLOOR_SOC_UNREADABLE = ("the battery state of charge was not measured this "
+                        "cycle, and an unreadable SoC is not a full battery")
+FLOOR_AT_SOC_FLOOR = "state of charge is at or below the peak guard's SoC floor"
+
+SOURCE = "peak"
+
+# ⚠️ CFG-03. THE ONE IN-CODE MIRROR OF config.yaml FOR THIS CARD'S OPTIONS, and
+# it is TARIFF-02's `PRICE_OPTION_DEFAULTS` pattern for TARIFF-02's reason: the
+# add-on already carries option defaults in three places (config.yaml's
+# `options:`, config.yaml's `schema:`, and main.py's literal `.get()`
+# fallbacks), and a fourth is the open ticket. validate.py and main.py both
+# import THIS dict rather than typing a literal, and test_peakguard.py pins it
+# to config.yaml by READING the file - so a drift goes red instead of shipping.
+#
+# ⚠️ NOT A READ. `decide()` takes both values as arguments and this module makes
+# no `.get()` call at all; the dict is a default table for its two callers.
+PEAK_OPTION_DEFAULTS = {
+    # The EMS-side floor on SAFETY-07's forced discharge, in percent.
+    #
+    # 20 is DERIVED from the two numbers this repository already has, not
+    # chosen. The reference pack is 300 Ah at 51.2 V with DoD 90 - 13.8 kWh
+    # usable, the figure validate.py's rule 6 note already quotes - and the
+    # 2026-08-20 replay models 878 Wh of guard discharge in a day, which is
+    # 6.4 % of that. A floor 10 points above the pack's own 10 % cut-out
+    # therefore leaves the guard roughly 1.6 of its worst observed days of room
+    # before it stops, which is the smallest margin that lets the guard do its
+    # job on a bad day and still never reach the BMS.
+    "peak_soc_floor": 20,
+    # The pack's OWN cut-out, in percent: what the BMS enforces regardless of
+    # anything here. On the reference unit this is register 0x0560, read as 10,
+    # and it is consistent with DoD 90 on a full pack. It exists so validate.py
+    # rule 8 can refuse a `peak_soc_floor` at or below it - see that rule.
+    "bms_soc_floor": 10,
+}
+
+
+@dataclass(frozen=True)
+class PeakDecision:
+    """What the guard concluded this cycle, with everything it concluded it from.
+
+    Every field is derived from a measurement taken in the same cycle. There is
+    no `floor_w_or(default)` and there must not be one, for `PeakReading`'s
+    reason: an accessor that turns "not measured" into a number re-creates the
+    defect the type exists to remove.
+    """
+
+    engaged: bool
+    floor_w: float | None            # the `lo` the claim carries; None = no claim
+    ceiling_w: float
+    ceiling_from: str
+    blind: str | None = None
+    projected_w: float | None = None
+    excess_w: float = 0.0
+    wanted_w: float | None = None    # the floor before `achievable_w` clamped it
+    saturated: bool = False
+    # SAFETY-24. True when a forced discharge WAS wanted and the EMS-side SoC
+    # floor refused to size it. Mutually exclusive with `saturated` by
+    # construction: this branch asks for nothing, so it cannot have run out of
+    # inverter. `soc_floor_reason` says WHICH of the two ways it bound.
+    floor_limited: bool = False
+    soc: float | None = None
+    soc_floor: float | None = None
+    soc_floor_reason: str | None = None
+    reason: str = ""
+
+    def explain(self) -> str:
+        if self.floor_limited:
+            return self.reason
+        if not self.engaged:
+            if self.projected_w is None:
+                return f"peak guard idle - {self.reason}"
+            return (f"peak guard idle - quarter projects "
+                    f"{self.projected_w:.0f} W under a {self.ceiling_w:.0f} W "
+                    f"ceiling ({self.ceiling_from})")
+        return self.reason
+
+
+def quarter_ceiling_w(cap_w, reading) -> tuple[float, str]:
+    """The average this quarter may not exceed, and where the number came from.
+
+    ONLY an OBSERVED reading may raise it. `NO_RECORD` (the store answered, this
+    month has nothing yet) and `NOT_OBSERVED` (the store did not answer) both
+    return the cap, which is the tighter answer. A failed read therefore makes
+    the guard stricter, never looser - see the module note.
+    """
+    cap = float(cap_w)
+    if (reading is not None and getattr(reading, "is_observed", False)
+            and reading.peak_w is not None and float(reading.peak_w) > cap):
+        return float(reading.peak_w), CEILING_MONTH_PEAK
+    return cap, CEILING_CAP
+
+
+def excess_w(projection, ceiling_w) -> float:
+    """Watts that must come off the meter NOW to land the quarter on the ceiling.
+
+    The whole control law, and the only place it is written down:
+
+        excess = 900 * (projected - ceiling) / remaining
+
+    Positive means the quarter is projected over; zero or negative means it is
+    not. `remaining <= 0` is not a large number, it is an undefined one - a
+    quarter with no seconds left cannot be influenced - so it answers 0.0 rather
+    than dividing.
+    """
+    remaining = QUARTER_S - float(projection.elapsed_s)
+    if remaining <= 0.0:
+        return 0.0
+    return QUARTER_S * (float(projection.projected_w) - float(ceiling_w)) / remaining
+
+
+def uncovered_s(projection) -> float:
+    """Seconds of the open block the meter did not actually cover.
+
+    Derived from what `Projection` already carries rather than re-measured:
+    `covered_frac` is `elapsed / elapsed_wall`, and `elapsed_s` IS that wall.
+    """
+    return max(0.0, float(projection.elapsed_s)
+               * (1.0 - float(projection.covered_frac)))
+
+
+def blindness(projection, max_hold_s, frozen: bool) -> str | None:
+    """Why this projection may not be graded, or None if it may be.
+
+    Evaluated BEFORE the projection is compared to anything. Each of the three is
+    a way for the projected number to be confident and wrong, and the first - a
+    fresh averager's all-zero `Projection` - is confident, wrong AND under every
+    ceiling there is.
+    """
+    if frozen:
+        return BLIND_FROZEN
+    if projection.block_start is None:
+        return BLIND_NO_BLOCK
+    gap = uncovered_s(projection)
+    if max_hold_s is not None and gap > float(max_hold_s):
+        return (f"{BLIND_COVERAGE}: {gap:.0f} s of this quarter uncovered, past "
+                f"the {float(max_hold_s):.0f} s the averager will hold a sample")
+    return None
+
+
+def discharge_permitted(soc, soc_floor) -> str | None:
+    """SAFETY-24. May the guard size a forced discharge, or why may it not?
+
+    Returns None when it may, and otherwise the REASON it may not - which the
+    decision, the status page, the action log and the operator notification all
+    carry, because "floor-limited" on its own tells nobody what to do.
+
+    THE ONE PLACE THIS QUESTION IS ANSWERED, and it is public for the reason
+    `freeze.looks_frozen()`, `watchdog.loop_is_following()` and
+    `shaping_suspended()` are: a safety predicate transcribed into its own check
+    is one copy plus a future disagreement about what the check means, and the
+    copy that drifts is always the grading one.
+
+    ⚠️ `soc is None` IS NOT PERMISSION. A failed read is not an observation, and
+    a FULL BATTERY is exactly the value that would disarm this floor - so a
+    `float(soc or 100)` here would restore the unbounded discharge this card
+    removes, silently, on the one install whose SoC sensor is misnamed. There is
+    deliberately no default argument on either parameter.
+
+    ⚠️ AND `soc_floor is None` IS NOT PERMISSION EITHER, for the same reason one
+    step further out: a caller that has no floor configured has not thereby been
+    granted an unbounded one.
+
+    Boundary: `<=`, not `<`. A pack sitting exactly ON the floor has already
+    spent everything this guard was allowed to spend; permitting one more cycle
+    there would make the floor mean "one cycle below the floor".
+    """
+    if soc is None:
+        return FLOOR_SOC_UNREADABLE
+    if soc_floor is None:
+        return ("no peak guard SoC floor is configured, so there is nothing to "
+                "bound a forced discharge with")
+    if float(soc) <= float(soc_floor):
+        return FLOOR_AT_SOC_FLOOR
+    return None
+
+
+def decide(projection, *, batt_w, cap_w, reading, achievable_w, soc, soc_floor,
+           max_hold_s=None, frozen: bool = False) -> PeakDecision:
+    """The whole guard. Pure: no clock, no I/O, no state carried between calls.
+
+    `batt_w`       MEASURED battery power, positive = discharge. None when the
+                   sensor for it is missing - and then there is nothing to size a
+                   floor from, so no floor is invented.
+    `achievable_w` the largest discharge the arbiter could actually grant
+                   (`min(max_w, device max)`). The floor is clamped to it so this
+                   claim can NEVER produce `lo > hi` in the resolver - a
+                   contradiction there resolves to 0 W, which would park the
+                   battery in the exact minute it should be discharging hardest.
+    `soc`          SAFETY-24. MEASURED state of charge, percent. None when the
+                   sensor for it did not answer - which is floor-limited, not
+                   permission.
+    `soc_floor`    SAFETY-24. The percent below which this guard may not spend
+                   the pack for money. REQUIRED, and deliberately without a
+                   default: a default here would be CFG-03's fourth defaults
+                   site and TEST-14's quiet fallback in one line.
+    """
+    ceiling, from_where = quarter_ceiling_w(cap_w, reading)
+    ceil_top = abs(float(achievable_w))
+
+    blind = blindness(projection, max_hold_s, frozen)
+    if blind is not None:
+        # 0.0, not a sized floor. There is no trustworthy measurement to size one
+        # from; the claim that remains is "do not add to the offtake you cannot
+        # see", which is one-directional and cannot cost pack energy.
+        return PeakDecision(
+            engaged=True, floor_w=0.0, ceiling_w=ceiling, ceiling_from=from_where,
+            blind=blind, projected_w=None,
+            reason=(f"PEAK GUARD BLIND ({blind}) - the battery may not import "
+                    f"while the billed quarter cannot be measured; commanding no "
+                    f"charging (floor 0 W)"))
+
+    projected = float(projection.projected_w)
+    if batt_w is None:
+        # main.py's P_SAFETY stop already owns a cycle with a missing input, at
+        # 0 W. Filing nothing is the honest answer: a floor sized from a
+        # measurement that is not there is a made-up number.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected,
+            reason="no battery measurement to size a floor from")
+    if QUARTER_S - float(projection.elapsed_s) <= 0.0:
+        # A block with no seconds left cannot be influenced. This is degenerate
+        # rather than urgent - `excess_w` answers 0.0 there and a floor equal to
+        # the battery's own current output would be a claim that says nothing.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected,
+            reason="the quarter has no seconds left to influence")
+
+    ex = excess_w(projection, ceiling)
+    wanted = float(batt_w) + ex
+    if wanted <= 0.0:
+        # ⚠️ THE TEST IS ON THE FLOOR, NOT ON `excess > 0`, AND THE REPLAY IS WHY.
+        # `excess` is the watts that must come off the METER, so it goes to zero
+        # as soon as the battery is already removing them - and a guard that
+        # disengaged there handed the actuator straight back, the offtake sprang
+        # back to the raw load, and the next cycle engaged again. On 2026-08-20's
+        # billed quarter that bang-bang cycled 17 times in 900 s and left the
+        # quarter 49 W over the limit it had just spent a quarter of an hour
+        # holding. §10.2: "an EMS that oscillates is worse than no EMS, both for
+        # hardware wear and - per §9.1 - for the peak it is trying to avoid."
+        #
+        # `batt_w + excess` is the offtake that would exist with the battery at
+        # zero, minus the level the quarter can afford. Testing THAT is the same
+        # arithmetic read as a level rather than as a switch: the claim is filed
+        # for as long as a positive floor is needed and decays continuously to
+        # nothing as the load falls, so there is still no hysteresis constant -
+        # the quantity being thresholded is simply the right one.
+        return PeakDecision(
+            engaged=False, floor_w=None, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            wanted_w=wanted,
+            reason="the load is under the level this quarter can afford")
+
+    # SAFETY-24 - AND ONLY HERE. `wanted > 0` is now established, so a forced
+    # discharge really is being asked for and the SoC is the quantity that
+    # decides whether it may be sized. Asked one line earlier it would grade a
+    # number that governs nothing on every quiet cycle of the day, and would
+    # report "floor-limited" over a guard that was never going to discharge.
+    denied = discharge_permitted(soc, soc_floor)
+    if denied is not None:
+        # 0.0, not `wanted`, and not a negative number. Zero forbids CHARGING -
+        # one-directional, cannot cost pack energy - and forbids nothing else;
+        # a `lo` limit structurally cannot cap the discharge the loop is already
+        # doing. See the module note: this bounds THE GUARD's forced discharge,
+        # not the grid-following loop, which still has no SoC guard.
+        return PeakDecision(
+            engaged=True, floor_w=0.0, ceiling_w=ceiling,
+            ceiling_from=from_where, projected_w=projected, excess_w=ex,
+            wanted_w=wanted, floor_limited=True, soc=soc, soc_floor=soc_floor,
+            soc_floor_reason=denied,
+            reason=(
+                f"PEAK GUARD FLOOR-LIMITED: the quarter projects "
+                f"{projected:.0f} W against a {ceiling:.0f} W ceiling "
+                f"({from_where}) and {wanted:+.0f} W of discharge would hold "
+                f"it, but {denied}"
+                + ("" if soc is None else f" ({float(soc):.0f} %")
+                + ("" if soc is None or soc_floor is None
+                   else f" vs {float(soc_floor):.0f} %")
+                + ("" if soc is None else ")")
+                + " - commanding no forced discharge, so THIS QUARTER WILL GO "
+                  "OVER THE CEILING. Charging stays blocked (floor 0 W)"))
+
+    floor = min(wanted, ceil_top)
+    saturated = floor < wanted
+    return PeakDecision(
+        engaged=True, floor_w=floor, ceiling_w=ceiling, ceiling_from=from_where,
+        blind=None, projected_w=projected, excess_w=ex, wanted_w=wanted,
+        saturated=saturated, soc=soc, soc_floor=soc_floor,
+        reason=(
+            f"PEAK GUARD: quarter projects {projected:.0f} W against a "
+            f"{ceiling:.0f} W ceiling ({from_where}) with "
+            f"{QUARTER_S - projection.elapsed_s:.0f} s left, so {ex:.0f} W must "
+            f"come off the meter; battery measured {float(batt_w):+.0f} W, "
+            f"floor {floor:+.0f} W"
+            + (f" - SATURATED, {wanted:+.0f} W was needed and the inverter can "
+               f"only give {ceil_top:.0f} W" if saturated else "")))
+
+
+def shaping_suspended(decision, peak_forecast_w, cap_w) -> bool:
+    """Must the maintenance charge-only shaping stand down this cycle?
+
+    THE ONE PLACE THIS CONJUNCTION IS WRITTEN, and it is public for the reason
+    `watchdog.loop_is_following()` and `freeze.looks_frozen()` are: the check
+    that grades it has to assert on THE SHIPPED EXPRESSION. A safety predicate
+    transcribed into its own test is one copy plus a future disagreement about
+    what the check means, and the copy that drifts is always the grading one.
+    It was inline in `main.py` and nothing could reach it; a reviewer mutated it
+    back to its historical broken form and all twelve suites stayed green.
+
+    ⚠️ WHY SUPPRESSION AND NOT PRIORITY. The shaping is a LIMIT (`hi <= 0`) and
+    the peak guard's claim is a LIMIT (`lo >= 0`). arbiter.py clause 2 applies
+    EVERY limit at or above the winner's priority and takes the MOST RESTRICTIVE,
+    with no notion of one limit outranking another - which is precisely what
+    makes the safety bounds unconditional and must not be changed. Two crossing
+    limits are therefore a CONTRADICTION, which resolves to 0 W: the battery
+    PARKED, in the one quarter of the month that sets the bill. P_PEAK 50 >
+    P_MAINT_SHAPE 40 does not save it and never could.
+
+    ⚠️ AND THE FIRST TERM IS NOT ENOUGH ON ITS OWN. `peak_forecast_entity` is
+    OPTIONAL and is empty on a default install, so `peak_forecast_w` is None
+    there and `peak_at_risk()` answers False forever. Before this card the
+    suspension therefore could not fire on the very site that needed it. The
+    second term is the MEASURED guard, which is always present wherever P1 is.
+    Deleting either term - or re-gating the whole thing on the forecast - parks
+    a default install at 0 W, silently, in the billed quarter. test_peakguard.py
+    part 7 drives the real cycle with each of those mutations in place.
+    """
+    if peak_at_risk(peak_forecast_w, float(cap_w)):
+        return True
+    return decision is not None and decision.engaged
+
+
+def claim(decision: PeakDecision) -> Claim | None:
+    """The decision as one arbiter claim, or None when the guard is idle.
+
+    A LIMIT with only `lo` set. `hi` stays `+inf`, which is 9.1's "discharge and
+    export are never capped by the peak guard" expressed as a fact about the
+    object rather than as a rule somebody has to remember.
+    """
+    if not decision.engaged or decision.floor_w is None:
+        return None
+    # Three reasons, not two. A `lo = 0 W` claim reaches the arbiter from THREE
+    # different states now - blind, floor-limited, and a genuine floor that
+    # happens to be zero - and the arbiter's explain() is what an operator reads
+    # when the battery stops charging. Spelling them the same way would make the
+    # SAFETY-24 case indistinguishable from the SAFETY-18 one on the one line
+    # that gets read.
+    return Claim.limit(SOURCE, P_PEAK, lo=float(decision.floor_w),
+                       reason=("blind" if decision.blind
+                               else "SoC floor" if decision.floor_limited
+                               else "quarter peak"))

goodwe_controller/app/price.py

@@ -282,6 +282,87 @@ def volatility_regime(product: PriceProduct) -> str:
     return "wide" if product in _WIDE else "normal"
 
 
+# --------------------------------------------------------------------------- #
+# FCST-03: ONE widening path, driven by a SET of active uncertainty sources.
+#
+# Two spec rows widen the same number by two different triggers:
+#
+#   §9.2 / §8.3  real-time / imbalance product   -> "arbitrage thresholds widen"
+#   §11.4        no weather data                 -> "widen arbitrage thresholds"
+#
+# They are one mechanism reached twice, not two mechanisms, so there is one
+# function and a set of reasons. ⚠️ THE COMBINATION RULE IS `max`, NOT A
+# PRODUCT: multiplying 2.5 by 1.5 would make two independent doubts compound
+# into a threshold nothing on a Belgian tariff can ever clear, and an arbitrage
+# strategy that can never fire is indistinguishable from one that is switched
+# off. The widest single reason wins.
+#
+# ⚠️ HONEST ABOUT WHERE THE NUMBERS COME FROM. specs.md says thresholds widen
+# and does not say by how much; there is no capture to derive a factor from,
+# because no arbitrage strategy has ever run here. These are POLICY DEFAULTS,
+# chosen so that (a) a real-time product needs a materially larger spread than
+# a settled day-ahead one before a cycle is worth its wear, and (b) the two
+# factors DIFFER, so `max`, `sum` and `product` are three distinguishable
+# answers rather than the same number - a check that grades a combination rule
+# where all the candidates agree grades nothing. When OPT-04 lands
+# `cycle_cost_threshold_eur` (§10.1/§14) these become the natural second option
+# beside it, in PRICE_OPTION_DEFAULTS and nowhere else (CFG-03).
+class Uncertainty(Enum):
+    """Why an arbitrage threshold is currently wider than the tariff alone says."""
+    REALTIME_PRODUCT = "realtime_product"    # §9.2 row 2, §8.3
+    NO_WEATHER = "no_weather"                # §11.4 "no weather data"
+
+
+WIDEN_FACTOR = {
+    Uncertainty.REALTIME_PRODUCT: 2.5,
+    Uncertainty.NO_WEATHER: 1.5,
+}
+
+
+def uncertainty_of(product: PriceProduct) -> frozenset:
+    """The uncertainty a PRODUCT contributes on its own (§9.2 row 2).
+
+    Derived from the declared product, never from a plugin id - the same rule
+    `volatility_regime()` exists for. A sixth supplier declaring
+    `PriceProduct.REALTIME` is widened without anyone editing this file.
+    """
+    if not isinstance(product, PriceProduct):
+        raise TypeError(f"uncertainty_of() takes a PriceProduct, not "
+                        f"{product!r} - a plugin name is what §9.3 forbids.")
+    return (frozenset({Uncertainty.REALTIME_PRODUCT})
+            if product in _WIDE else frozenset())
+
+
+def widen_factor(sources) -> float:
+    """The multiplier the widest active source asks for. 1.0 when there are none.
+
+    ⚠️ A STRING IS REFUSED. `widen_factor({"realtime"})` would otherwise be a
+    silent 1.0 - a widening that reports itself as applied and is not, which is
+    the shape of defect this repo keeps finding.
+    """
+    srcs = frozenset(sources)
+    bad = [s for s in srcs if not isinstance(s, Uncertainty)]
+    if bad:
+        raise TypeError(f"widen_factor() takes Uncertainty members, not {bad!r}. "
+                        f"A string here would widen by 1.0 and say it widened.")
+    return max((WIDEN_FACTOR[s] for s in srcs), default=1.0)
+
+
+def required_spread(base_eur_kwh: float, sources) -> float:
+    """The spread an arbitrage cycle must clear, given what is uncertain (§8.3).
+
+    `base_eur_kwh` is the caller's own round-trip cost threshold - OPT-04 owns
+    that number (§10.1's `cycle_cost_threshold_eur`), this owns only how much
+    wider it gets and why.
+    """
+    if isinstance(base_eur_kwh, bool) or             not isinstance(base_eur_kwh, (int, float)) or             not math.isfinite(base_eur_kwh) or base_eur_kwh < 0:
+        raise ValueError(
+            f"required_spread() takes a non-negative, finite base threshold in "
+            f"EUR/kWh, not {base_eur_kwh!r}. A negative or NaN base makes every "
+            f"spread clear it, which is arbitrage with the brake removed.")
+    return round(float(base_eur_kwh) * widen_factor(sources), 6)
+
+
 @dataclass(frozen=True)
 class PricePoint:
     """One canonical point. THREE FIELDS. §9.3 lists three; this has three."""
@@ -526,6 +607,26 @@ PRICE_OPTION_DEFAULTS = {
     # test_price.py section 1. A second defaults dict in the new module would be
     # a fourth place option defaults live, which is exactly the open ticket.
     "static_profile": "",
+    # OPT-04. §10.1 priority 3, and §14's `optimizer.cycle_cost_threshold_eur`.
+    #
+    # ⚠️ THEY LIVE HERE FOR CFG-03's SAKE, exactly as `static_profile` does, and
+    # FCST-03's note above `WIDEN_FACTOR` names this as the place they would
+    # land. `arbitrage_soc_floor` / `arbitrage_soc_ceiling` are the reserve
+    # arbitrage may not spend and the headroom it may not overfill; they are
+    # NOT the maintenance SoC keys, which describe a balancing cycle rather
+    # than a trading reserve and would silently couple two unrelated policies.
+    #
+    # ⚠️ AND `cycle_cost_threshold_eur` IS 0.10 BECAUSE §10.1's NAME FOR IT SAYS
+    # SO, NOT BECAUSE IT MAKES ANYTHING TRADE. On realistic Belgian day/night
+    # numbers the static spread is ~0.08 EUR/kWh, so a static-tariff site does
+    # NOT trade at this default. That is a reported result (test_arbitrage.py
+    # section 7), and whether 0.10 - or FCST-03's 2.5/1.5 - is right is one
+    # product decision that belongs to the owner. No number here was chosen to
+    # make arbitrage happen.
+    "arbitrage_enabled": False,
+    "cycle_cost_threshold_eur": 0.10,
+    "arbitrage_soc_floor": 20,
+    "arbitrage_soc_ceiling": 95,
 }
 
 # ⚠️ The keys the FRAMEWORK owns. A plugin that reads one of these is a plugin

goodwe_controller/app/price_forecast.py

@@ -0,0 +1,465 @@
+"""FCST-03 - the hours the feed has not published yet, and what may not rest on them.
+
+WHERE THIS LIVES. specs.md §2.2 puts price ingest under `ems/ingest/prices/`.
+That layout does not exist and is not being built; the product owner's decision
+of 2026-08-30 is that everything ships in `goodwe_controller/app/`. The
+BEHAVIOUR §8.3 describes is unchanged and still authoritative - only the path
+moved. Read `ems/...` as `app/...`.
+
+§8.3, in full, because every line below is one clause of it:
+
+    "Day-ahead prices arrive once daily. Until they do, unknown hours use
+     yesterday's profile and are flagged `provisional: true` - and NO
+     IRREVERSIBLE ACTION MAY BE TAKEN ON A PROVISIONAL PRICE. Real-time /
+     imbalance products are treated as high-volatility: arbitrage thresholds
+     widen."
+
+Three separate things, and this module owns the first two. The third - the
+widening arithmetic - lives in price.py beside the product enum it is derived
+from (`Uncertainty`, `widen_factor`, `required_spread`), and is spent by
+`static_tariff.TariffPlan.arbitrage()`, because that is where the verdict this
+repo already refuses to hand out casually is produced. FCST-03 added a refusal
+to that existing ladder rather than a second mechanism beside it.
+
+
+THE DEFECT THIS MODULE IS SHAPED BY: A COPY THAT KEEPS THE WRONG FLAG
+=====================================================================
+A point filled from yesterday and a point published this morning are the SAME
+SHAPE. Three floats and a bool; only the bool tells them apart. And the natural
+way to write a carry-forward fill is:
+
+    PricePoint(start=t, eur_per_kwh=y.eur_per_kwh, provisional=y.provisional)
+                                                                ^^^^^^^^^^^^^
+
+which copies yesterday's `False` onto today's guess and produces exactly the
+thing the ticket exists to prevent: STALE DATA PRESENTED AS CURRENT. It reads
+fine, it type-checks, it round-trips through §9.3's JSON, and every price on
+the status page looks like a price. This is the meter-side SAFETY-18 defect one
+layer up: the reading arrives on time, looks fresh, and is wrong - and a
+freshness check that only asks "did something arrive" cannot see it.
+
+So the flag is not passed through anywhere in this file:
+
+  * A CARRIED POINT IS BUILT BY `_carried()`, WHICH HAS NO PARAMETER FOR THE
+    FLAG. `provisional=True` is a literal in one place. There is no argument a
+    caller can pass, no keyword to forget, and no variable that could hold
+    yesterday's value at the moment the point is constructed.
+  * A PUBLISHED POINT IS NEVER COPIED AT ALL. It is passed through BY IDENTITY -
+    the object the provider produced is the object in the output series - so
+    there is no copy that could lose or gain a flag. `filled.points[i] is
+    fetched.points[j]` is a checkable property, and test_price_forecast.py
+    checks it.
+  * `_audit()` RE-DERIVES the expected flag for every output point from the set
+    of hours the feed actually published, and RAISES if any point disagrees.
+    It is a post-condition, not a filter: it never fixes a flag, because a
+    module that quietly corrects its own provenance is one whose provenance
+    cannot be trusted.
+  * and test_price_forecast.py walks THIS FILE'S AST and fails if any
+    `PricePoint(...)` in it passes anything but a literal for `provisional`, so
+    the pass-through idiom cannot come back in a later edit and pass review by
+    looking ordinary.
+
+⚠️ "PUBLISHED" DOES NOT MEAN "FIRM". `eneco_eddy` is an imbalance product whose
+current-quarter print is genuinely provisional and says so per point (§9.2,
+TARIFF-02). Such a point is published AND provisional, and the audit's rule for
+a published point is "the flag is whatever the feed said", never "False". A
+provenance check that forced published points to False would be a bug that
+looks like a guarantee.
+
+
+THE FILL, AND WHY IT KEYS ON THE WALL CLOCK
+===========================================
+For every whole hour in the requested horizon that the feed has not published,
+take yesterday's value for THE SAME BRUSSELS WALL-CLOCK HOUR - not `t - 86400
+s`. On the two days a year that matter those are different instants, and the
+difference is not academic: a 23-hour day has no 02:00 at all and a 25-hour day
+has two, so a fill that subtracts a fixed 24 h shifts every carried hour by one
+across a transition and misprices the whole day in a way nothing reports.
+
+On the 25-hour day the two 02:00 hours - `02:00+02:00` and `02:00+01:00` - both
+key to local hour 2 and are BOTH filled from yesterday's single 02:00 value.
+That is deliberate: they are both guesses, they are both flagged, and nothing
+irreversible may rest on either. If yesterday itself was a 25-hour day, the
+first of its two 02:00 points is the one used, deterministically.
+
+An hour with no published price AND no yesterday value is LEFT OUT of the
+series. It is not filled with a neighbour, a mean, or a zero. §11.4 applies to
+that hour - `_Series.at()` raises `Absence` for it - and the caller that wanted
+a tariff for the whole horizon falls back to the static profile (TARIFF-03),
+which is the row the spec actually writes for "no price data". If NOTHING can
+be produced, the result is `PriceRead.no_data(reason)` and not an empty series,
+because an empty series is not constructible on purpose (price.py trap 3).
+
+
+AC2: THE IRREVERSIBLE-ACTION GATE
+=================================
+"The distinction should be an explicit property of the action, not a judgement
+call at each call site" - so an irreversible action is a value, `Irreversible`,
+carrying the number of hours it COMMITS. `price_permits()` looks at exactly
+those hours and answers with a `Gate` variant that carries the evidence on the
+permitting arm and a reason on the blocking one, the `_Outcome` shape price.py
+borrowed from `sim/riglock.py`.
+
+The shipped example is the maintenance drain (§12): starting one commits hours
+of forced discharge that cannot be undone if the price turns out to have been
+yesterday's. Its commitment window is DERIVED from `maintenance.DRAIN_TIMEOUT_MIN`
+rather than typed here, so the gate and the phase machine cannot drift apart.
+
+⚠️ WHAT DOES NOT GO THROUGH THIS GATE, AND WHY THAT MATTERS MORE THAN WHAT
+DOES. The maintenance cycle is a CALENDAR obligation (§12.2: a cycle that
+silently never fires is indistinguishable from one that is not due yet), and a
+site with `price_provider: off` - the shipped default - has no price series at
+all. Routing every maintenance start through a gate that blocks on `no_data`
+would stop the monthly cycle on every default install, permanently and
+silently: the exact failure §12 opens by naming. So `begin_phase()` is the
+entry point for a start that is being JUSTIFIED BY A PRICE, main.py's existing
+calendar path is untouched by this ticket, and OPT-04/MAINT-05 own the decision
+of which one a site runs. Nothing here disables anything that runs today.
+
+Reversible actions - ordinary self-consumption modulation, the loop that
+actually holds the grid at zero - are not gated at all and cannot be: §6 says
+absent machinery must not disable the loop.
+"""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+
+from .maintenance import CHARGE_TIMEOUT_MIN, DRAIN_TIMEOUT_MIN
+from .price import PricePoint, PriceRead, _Outcome, brussels
+
+_LOG = logging.getLogger("goodwe.price.forecast")
+
+
+class Provenance(Enum):
+    """Where a point in a filled series came from. INTERNAL - §9.3's wire format
+    carries the boolean and nothing else, so this never leaves the module.
+
+    It exists so `_audit()` has a vocabulary to state its post-condition in, and
+    so the two cases have names in the log rather than being "the ones with the
+    flag" and "the others".
+    """
+    PUBLISHED = "published"    # the provider printed this hour. Flag: the
+                               # feed's own - an imbalance print may be
+                               # published AND provisional (§9.2).
+    CARRIED = "carried"        # yesterday's same-wall-clock hour (§8.3).
+                               # Flag: ALWAYS True, by construction.
+
+
+# --------------------------------------------------------------------------- #
+# The fill
+# --------------------------------------------------------------------------- #
+
+def _utc_hour(instant: datetime) -> datetime:
+    u = instant.astimezone(timezone.utc)
+    return u.replace(minute=0, second=0, microsecond=0)
+
+
+def _carried(start_utc: datetime, eur_per_kwh: float) -> PricePoint:
+    """A point filled from yesterday's profile. §8.3: ALWAYS provisional.
+
+    ⚠️ THERE IS NO `provisional` PARAMETER, AND THAT IS THE MECHANISM. This is
+    the only constructor of a carried point, the flag is a literal, and no
+    caller - including a future one editing in a hurry - has anything to pass,
+    default, or copy from the point being carried.
+    """
+    return PricePoint(start=brussels(start_utc),
+                      eur_per_kwh=round(float(eur_per_kwh), 6),
+                      provisional=True)
+
+
+def _audit(points, published) -> None:
+    """Post-condition: every flag matches the point's TRUE provenance (AC1).
+
+    `published` maps a UTC hour to the point the provider produced for it.
+
+    ⚠️ RAISES, NEVER REPAIRS. A module that silently corrects its own
+    provenance is one whose provenance means nothing; the only safe response to
+    "this point's flag disagrees with where it came from" is to refuse to emit
+    the series at all.
+    """
+    seen = set()
+    for p in points:
+        u = _utc_hour(p.start)
+        if u in seen:
+            raise ValueError(f"the filled series repeats {u.isoformat()}; a "
+                             f"duplicated hour is how a DST day gets mispriced")
+        seen.add(u)
+        src = published.get(u)
+        prov = Provenance.CARRIED if src is None else Provenance.PUBLISHED
+        if src is None:
+            if p.provisional is not True:
+                raise ValueError(
+                    f"{u.isoformat()} is {prov.value} and is flagged "
+                    f"provisional={p.provisional!r}. §8.3: an hour filled from "
+                    f"yesterday's profile is provisional whether or not the "
+                    f"number turns out to be right - the flag is a claim about "
+                    f"PROVENANCE, not about accuracy.")
+        else:
+            if p is not src:
+                raise ValueError(
+                    f"{u.isoformat()} is {prov.value} but the series carries a "
+                    f"COPY of that point rather than the point itself. A copy "
+                    f"is where the provisional flag gets lost; published points "
+                    f"pass through by identity.")
+
+
+def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
+                        since: datetime, until: datetime,
+                        stamp: datetime) -> PriceRead:
+    """§8.3: fill the hours the feed has not published with yesterday's profile.
+
+    Every argument is required and keyword-only past the first. In particular
+    `yesterday` has NO DEFAULT: a fill with no yesterday to fill from is a
+    different situation from a fill that found nothing useful in one, and a
+    default `None` would make the two arrive looking identical.
+
+    Returns a `PriceRead`:
+
+      * a series, whose points are the provider's own objects for the hours it
+        published and `_carried()` points for the rest, ordered by instant;
+      * `no_data` when neither source can produce a single hour - never an
+        empty series, which is not constructible (price.py trap 3).
+
+    ⚠️ IDEMPOTENT AND RE-RUNNABLE, WHICH IS THE §5.4 LATE-PUBLICATION CONTRACT.
+    Day-ahead publication at 14-16 h CET can be late or fail, so the fetcher
+    retries and this runs again against the fresher read. Published hours always
+    win over carried ones, so a re-run REPLACES a carried point with the real
+    print and the hour becomes firm - the flag and the number move together
+    because the whole series is rebuilt rather than patched in place.
+    """
+    for name, value in (("since", since), ("until", until), ("stamp", stamp)):
+        if value.tzinfo is None or value.utcoffset() is None:
+            raise ValueError(f"{name} must be tz-aware; a naive instant is "
+                             f"ambiguous for one hour every October")
+
+    published = read.match(
+        series=lambda r: {_utc_hour(p.start): p for p in r.points},
+        no_data=lambda _r: {})
+
+    # Yesterday's profile, keyed by BRUSSELS WALL-CLOCK HOUR. First point wins
+    # when yesterday itself was a 25-hour day and printed local hour 2 twice.
+    by_local_hour = {}
+    yesterday.match(
+        series=lambda r: [by_local_hour.setdefault(brussels(p.start).hour, p)
+                          for p in r.points],
+        no_data=lambda _r: [])
+
+    out = []
+    u = _utc_hour(since)
+    end = until.astimezone(timezone.utc)
+    while u < end:
+        if u in published:
+            out.append(published[u])                    # BY IDENTITY. No copy.
+        else:
+            src = by_local_hour.get(brussels(u).hour)
+            if src is not None:
+                out.append(_carried(u, src.eur_per_kwh))
+        u += timedelta(hours=1)
+
+    if not out:
+        reason = read.match(
+            series=lambda r: (f"the {len(r.points)} published hours all fall "
+                              f"outside {since.isoformat()}..{until.isoformat()}"),
+            no_data=lambda r: r.reason)
+        return PriceRead.no_data(
+            f"§8.3 carry-forward produced no hours: {reason}, and yesterday's "
+            f"profile has nothing to fill them with either. §11.4 applies: "
+            f"static profile, plan provisional, no arbitrage")
+
+    _audit(out, published)
+    carried = sum(1 for p in out if _utc_hour(p.start) not in published)
+    if carried:
+        _LOG.info("§8.3: %d of %d hours carried forward from yesterday's "
+                  "profile and flagged provisional; %d published",
+                  carried, len(out), len(out) - carried)
+
+    product = read.match(series=lambda r: r.product,
+                         no_data=lambda _r: yesterday.product)
+    provider = read.match(series=lambda r: r.provider,
+                          no_data=lambda r: yesterday.provider)
+    return PriceRead.series(out, product, provider, stamp)
+
+
+# --------------------------------------------------------------------------- #
+# AC2: irreversibility as a property of the ACTION, and the gate that reads it
+# --------------------------------------------------------------------------- #
+
+@dataclass(frozen=True)
+class Irreversible:
+    """An action that cannot be undone once started, and how far it commits.
+
+    `commits_h` is the horizon the action ties up - the hours whose prices must
+    therefore be firm before it may be justified by a price at all.
+    """
+
+    name: str            # the §10.2 reason code
+    commits_h: float
+
+    def __post_init__(self):
+        if not self.name or not isinstance(self.name, str):
+            raise ValueError("an irreversible action needs a reason code (§10.2)")
+        if isinstance(self.commits_h, bool) or \
+                not isinstance(self.commits_h, (int, float)) or \
+                not self.commits_h > 0:
+            raise ValueError(
+                f"commits_h must be a positive number of hours, not "
+                f"{self.commits_h!r}. An action that commits nothing is a "
+                f"reversible one and does not belong here.")
+
+
+# ⚠️ DERIVED FROM THE PHASE MACHINE'S OWN BOUNDS, NOT TYPED HERE. maintenance.py
+# already states how long each phase may run before it is a fault; a second copy
+# of those numbers here would be a place for them to drift apart, and the drift
+# would show up as a gate that checked the wrong hours.
+MAINTENANCE_DRAIN = Irreversible("MAINTENANCE_DRAIN", DRAIN_TIMEOUT_MIN / 60.0)
+MAINTENANCE_CHARGE = Irreversible("MAINTENANCE_CHARGE", CHARGE_TIMEOUT_MIN / 60.0)
+
+
+class Gate(_Outcome):
+    """May an irreversible action proceed on the price evidence available?
+
+      * `permitted` - carries `.action` and `.hours`, the firm points that were
+                      actually checked. The evidence exists only on this arm.
+      * `blocked`   - carries `.reason`. Nothing else; `.hours` raises `Absence`.
+
+    No `__bool__`, both `match()` arms required and keyword-only, for the reason
+    price.py's `_Outcome` gives: `if gate:` must not look like a guard while
+    being none.
+    """
+
+    def match(self, *, permitted, blocked):
+        return {"permitted": permitted, "blocked": blocked}[self.kind](self)
+
+    @staticmethod
+    def permit(action, hours):
+        return _Permitted(action, hours)
+
+    @staticmethod
+    def block(reason):
+        if not reason or not isinstance(reason, str):
+            raise ValueError(
+                "Gate.block() takes a reason a human can act on. §6 requires "
+                "every decision to explain itself, and 'the maintenance cycle "
+                "did not start' with no reason is indistinguishable from a bug.")
+        return _Blocked(reason)
+
+
+class _Permitted(Gate):
+    kind = "permitted"
+
+    def __init__(self, action, hours):
+        if not isinstance(action, Irreversible):
+            raise TypeError(f"action must be an Irreversible, not {action!r}")
+        pts = tuple(hours)
+        if not pts:
+            raise ValueError(
+                "a permission granted over ZERO checked hours is a permission "
+                "granted on no evidence - the shape this whole file exists to "
+                "refuse. Block instead.")
+        if any(p.provisional for p in pts):
+            raise ValueError(
+                "a permitted gate cannot carry a provisional hour: §8.3 is the "
+                "one rule this type has.")
+        self.action = action
+        self.hours = pts
+        self.words = (f"{action.name} permitted on {len(pts)} firm hours "
+                      f"({pts[0].start.isoformat()} ..)")
+
+
+class _Blocked(Gate):
+    kind = "blocked"
+
+    def __init__(self, reason):
+        self.reason = reason
+        self.words = f"blocked - {reason}"
+
+
+def committed_hours(now: datetime, action: Irreversible) -> tuple:
+    """The whole hours `action` started at `now` would run through.
+
+    Split out because the gate and its caller must agree on what "the hours it
+    commits" means, and because a window that quietly excluded the last hour
+    would be a gate that permits an action on an hour it never looked at.
+    """
+    if not isinstance(action, Irreversible):
+        raise TypeError(f"action must be an Irreversible, not {action!r}")
+    if now.tzinfo is None or now.utcoffset() is None:
+        raise ValueError("now must be tz-aware")
+    out = []
+    u = _utc_hour(now)
+    end = now.astimezone(timezone.utc) + timedelta(hours=action.commits_h)
+    while u < end:
+        out.append(u)
+        u += timedelta(hours=1)
+    return tuple(out)
+
+
+def price_permits(read: PriceRead, now: datetime,
+                  action: Irreversible) -> Gate:
+    """§8.3's rule, as a value: may this irreversible action rest on this price?
+
+    Blocks when the read observed nothing (§11.4 - an action justified by a
+    price nobody has is an action justified by nothing), when any hour it
+    commits has no price at all, and when any of those hours is provisional.
+    Names the offending hour, so an operator reading the log knows which one.
+    """
+    hours = committed_hours(now, action)
+    return read.match(
+        series=lambda r: _walk(r, hours, action),
+        no_data=lambda r: Gate.block(
+            f"{action.name} is gated on a price and there is no price data: "
+            f"{r.reason}. §11.4 - and a missing price is not a cheap one"))
+
+
+def _walk(series, hours, action) -> Gate:
+    pts = []
+    for u in hours:
+        if not series.covers(u):
+            return Gate.block(
+                f"{action.name} commits {action.commits_h:g} h from "
+                f"{hours[0].isoformat()} and no price covers "
+                f"{u.isoformat()}. An hour outside the series is an hour with "
+                f"no price (§11.4 for that hour), not a free one")
+        p = series.at(u)
+        if p.provisional:
+            return Gate.block(
+                f"{action.name} commits {action.commits_h:g} h from "
+                f"{hours[0].isoformat()} and {u.isoformat()} is PROVISIONAL - "
+                f"carried from yesterday's profile or standing in for a dead "
+                f"feed. §8.3: no irreversible action may be taken on a "
+                f"provisional price. It becomes available when the day-ahead "
+                f"print lands (~14-16 h CET, §5.4)")
+        pts.append(p)
+    return Gate.permit(action, pts)
+
+
+def begin_phase(maint, now: datetime, read: PriceRead,
+                action: Irreversible) -> Gate:
+    """Start a maintenance phase BECAUSE OF A PRICE, or refuse and say why.
+
+    The AC2 example made real: `maint.force_start(now)` - the call that moves
+    the phase machine out of `idle` and commits the pack to hours of forced
+    discharge - happens on the permitting arm and cannot happen on the other
+    one, because the blocking arm has no code path to it.
+
+    ⚠️ READ THE MODULE DOCSTRING'S LAST WARNING BEFORE WIRING THIS IN. This is
+    the price-justified entry point, not the calendar one; a site with no price
+    provider must keep starting its monthly cycle the way it does today, or
+    §12's opening sentence comes true - a cycle that silently never fires.
+    """
+    gate = price_permits(read, now, action)
+    return gate.match(permitted=lambda g: _go(maint, now, g),
+                      blocked=lambda g: _no(g))
+
+
+def _go(maint, now, gate) -> Gate:
+    maint.force_start(now)
+    _LOG.info("%s: %s", gate.action.name, gate.words)
+    return gate
+
+
+def _no(gate) -> Gate:
+    _LOG.warning("irreversible action refused - %s", gate.reason)
+    return gate

goodwe_controller/app/static_tariff.py

@@ -77,25 +77,49 @@ price.py borrowed from `sim/riglock.py`. An optimiser cannot compute a trade
 from a refusal, because it cannot get the inputs out of one.
 
 And the verdict is only obtainable from `TariffPlan.arbitrage(...)`, which takes
-`peak_guard_active` as a REQUIRED KEYWORD ARGUMENT. §9.1 and §10.1 put peak
+`peak_guard_active`, `min_spread_eur_kwh` and `uncertainty` as REQUIRED KEYWORD
+ARGUMENTS, none of them defaulted. §9.1 and §10.1 put peak
 shaving (priority 2) above price arbitrage (priority 3) - the capacity tariff is
 a network cost charged whatever the energy product is - and the way that
 ordering is made to survive OPT-04 landing is that OPT-04 cannot obtain a spread
 without first stating whether the peak guard is holding. It is not free to
 forget the question; the call does not compile without an answer.
 
-⚠️ FOUR REFUSALS, IN THIS ORDER, EACH DERIVED FROM SOMETHING MEASURED:
+⚠️ FIVE REFUSALS, IN THIS ORDER, EACH DERIVED FROM SOMETHING MEASURED:
 
   1. the peak guard is active           §10.1: priority 2 outranks priority 3
   2. no price data at all               §11.4, and no static_profile to fall to
-  3. the plan is provisional            §11.4 fallback / §8.3 unknown hours
-  4. the series is FLAT                 max - min == 0, so there is nothing to
-                                        arbitrage. THIS is AC2: a fully-fixed
-                                        tariff disables arbitrage by ARITHMETIC,
-                                        not by a special case keyed on
-                                        `PriceProduct.FIXED`. A dynamic feed
+  3. fewer than TWO FIRM HOURS          §8.3. FCST-03 rewrote this one: it used
+                                        to be "any point in the series is
+                                        provisional", which would have switched
+                                        arbitrage off every morning on every
+                                        dynamic site once carry-forward filling
+                                        landed (a series is part-firm and
+                                        part-carried until the 14-16 h CET
+                                        publication). What §8.3 forbids is
+                                        acting ON a provisional price, so the
+                                        provisional hours are DROPPED and
+                                        everything below is computed over the
+                                        firm ones. A wholly provisional series -
+                                        the §11.4 fallback - still has no firm
+                                        pair and is still refused.
+  4. the FIRM series is FLAT            max - min == 0, so there is nothing to
+                                        arbitrage. THIS is TARIFF-03's AC2: a
+                                        fully-fixed tariff disables arbitrage by
+                                        ARITHMETIC, not by a special case keyed
+                                        on `PriceProduct.FIXED`. A dynamic feed
                                         that happens to print one price all day
                                         gets refused for the same true reason.
+  5. the spread does not clear the      §8.3/§9.2/§11.4, new in FCST-03. The
+     WIDENED threshold                  caller states its round-trip cost
+                                        threshold; this widens it by the widest
+                                        active uncertainty source - a real-time
+                                        / imbalance PRODUCT (derived from the
+                                        declared `PriceProduct`, never from a
+                                        plugin id) or the caller's own
+                                        `NO_WEATHER`. See price.py's
+                                        `required_spread()`; the combination
+                                        rule is `max`, not a product.
 
 Nothing here decides a trade. The spread is handed over; OPT-04 owns
 `cycle_cost_threshold_eur` (§10.1/§14) and what to do about it. ⚠️ Worth knowing
@@ -182,7 +206,8 @@ from datetime import datetime, timedelta, timezone
 
 from .price import (
     MAX_PLAUSIBLE_EUR_KWH, Absence, PricePoint, PriceProduct, PriceRead,
-    _Outcome, brussels, load_prices, price_option,
+    Uncertainty, _Outcome, brussels, load_prices, price_option,
+    required_spread, uncertainty_of, widen_factor,
 )
 
 _LOG = logging.getLogger("goodwe.tariff.static")
@@ -619,8 +644,9 @@ class Arbitrage(_Outcome):
         return {"allowed": allowed, "refused": refused}[self.kind](self)
 
     @staticmethod
-    def allow(spread, cheapest, dearest, regime, product):
-        return _Allowed(spread, cheapest, dearest, regime, product)
+    def allow(spread, cheapest, dearest, regime, product, required, sources):
+        return _Allowed(spread, cheapest, dearest, regime, product, required,
+                        sources)
 
     @staticmethod
     def refuse(reason):
@@ -632,17 +658,43 @@ class Arbitrage(_Outcome):
         return _Refused(reason)
 
 
+# ⚠️ FIRM BY CONSTRUCTION, ASSERTED RATHER THAN TRUSTED (FCST-03). §8.3 forbids
+# an irreversible action on a provisional price, and the two points on the
+# permitting variant ARE the action: they are the hours a strategy buys and
+# sells in. A provisional point reaching this far is a defect in the refusal
+# ladder above, and it fails loudly at the moment of construction rather than
+# quietly at the meter a day later.
+def _firm_or_die(cheapest, dearest):
+    for role, pt in (("cheapest", cheapest), ("dearest", dearest)):
+        if getattr(pt, "provisional", True):
+            raise ValueError(
+                f"the {role} hour handed to an arbitrage strategy is "
+                f"PROVISIONAL ({getattr(pt, 'start', '?')}). §8.3: no "
+                f"irreversible action may be taken on a provisional price - "
+                f"an ALLOWED verdict cannot be built out of one.")
+
+
 class _Allowed(Arbitrage):
     kind = "allowed"
 
-    def __init__(self, spread, cheapest, dearest, regime, product):
+    def __init__(self, spread, cheapest, dearest, regime, product, required,
+                 sources):
+        _firm_or_die(cheapest, dearest)
         self.spread_eur_kwh = spread
         self.cheapest = cheapest          # the PricePoint at the low end
         self.dearest = dearest            # the PricePoint at the high end
         self.regime = regime              # §8.3 "wide" | "normal"
         self.product = product
+        # FCST-03. The threshold this spread actually cleared, and why it was
+        # the size it was. An optimiser that wants to know how much margin it
+        # has does not get to re-derive it from a product enum.
+        self.required_spread_eur_kwh = required
+        self.uncertainty = frozenset(sources)
         self.words = (f"spread {spread:.4f} EUR/kWh over "
-                      f"{product.value} ({regime} thresholds)")
+                      f"{product.value} ({regime} thresholds, cleared "
+                      f"{required:.4f} EUR/kWh)")
+
+
 
 
 class _Refused(Arbitrage):
@@ -724,36 +776,100 @@ class TariffPlan:
             no_data=lambda r: _absent(r.reason))
 
     # -- the two things a consumer is allowed to act on ----------------------
+    def firm_points(self) -> tuple:
+        """The points that carry a PUBLISHED price for their own hour (§8.3).
+
+        The complement of the carried-forward fill FCST-03 adds. Empty on a
+        §11.4 fallback plan and on a `no_data` read - and empty is honest here,
+        because it is a count of observations, not a value invented in place of
+        one. Never used to answer "what does this hour cost"; only to answer
+        "may something irreversible rest on it".
+        """
+        return self.read.match(
+            series=lambda r: tuple(p for p in r.points if not p.provisional),
+            no_data=lambda _r: ())
+
     def cheap_now(self, instant: datetime) -> bool:
         """Is now a cheap window? STRICTLY below the mean - see the docstring.
 
-        False on a provisional plan: §8.3 forbids an irreversible action on a
-        provisional price, and a grid top-up of a battery is about as
-        irreversible as this add-on gets. False when there is no price at all,
-        which is the §11.4 row and also main.py's long-standing "fixed-tariff
-        site: never force a paid grid top-up, wait for sun".
+        ⚠️ FALSE ON A PROVISIONAL HOUR, AND IT IS THIS HOUR THAT DECIDES
+        (FCST-03). §8.3 forbids an irreversible action on a provisional price
+        and a paid grid top-up of a battery is about as irreversible as this
+        add-on gets - but the price that would be paid is THIS hour's, so a
+        firm hour does not stop being cheap because tomorrow's hours have not
+        been published yet. Before FCST-03 the whole plan had to be firm, which
+        was the same answer for the only two series that existed then (all firm,
+        or all provisional) and would have switched the cheap window off every
+        morning once carry-forward filling landed.
+
+        The mean is taken over the FIRM hours for the same reason: yesterday's
+        carried values are not observations of what today costs, and a
+        comparison basis half-built out of them grades this hour against a
+        number nobody published. On an all-firm series - every series that
+        existed before FCST-03 - it is the same mean to the last digit.
+
+        False when there is no price at all, which is the §11.4 row and also
+        main.py's long-standing "fixed-tariff site: never force a paid grid
+        top-up, wait for sun".
         """
-        if not self.has_prices or self.provisional:
+        firm = self.firm_points()
+        if not firm:
             return False
         try:
-            return self.price_at(instant) < self.mean_eur_kwh()
+            here = self.read.match(series=lambda r: r.at(instant),
+                                   no_data=lambda r: _absent(r.reason))
         except Absence:
             # An instant outside the series is an hour with no price (§11.4 for
             # that hour), not a cheap one.
             return False
+        if here.provisional:
+            return False
+        return here.eur_per_kwh < (sum(p.eur_per_kwh for p in firm) / len(firm))
 
-    def arbitrage(self, *, peak_guard_active: bool) -> Arbitrage:
+    def arbitrage(self, *, peak_guard_active: bool, min_spread_eur_kwh,
+                  uncertainty) -> Arbitrage:
         """May OPT-04 trade, and on what numbers. See the module docstring.
 
-        ⚠️ `peak_guard_active` IS REQUIRED AND KEYWORD-ONLY. §9.1/§10.1 put peak
-        shaving above arbitrage, and this is how that ordering survives a
-        strategy that has not been written yet: the spread is not obtainable
-        without answering the question.
+        ⚠️ ALL THREE ARGUMENTS ARE REQUIRED AND KEYWORD-ONLY, for one reason
+        each, and none of them has a default:
+
+          `peak_guard_active`   §9.1/§10.1 put peak shaving above arbitrage,
+                                and this is how that ordering survives a
+                                strategy that has not been written yet: the
+                                spread is not obtainable without answering the
+                                question.
+          `min_spread_eur_kwh`  the caller's own round-trip cost threshold
+                                (§10.1's `cycle_cost_threshold_eur`). A verdict
+                                that says "allowed" without being told what
+                                would make a cycle worth doing is a verdict
+                                about arithmetic, not about money. Pass 0.0 to
+                                mean "any positive spread", explicitly.
+          `uncertainty`         the §11.4 doubts the CALLER can see and this
+                                object cannot - today that is
+                                `Uncertainty.NO_WEATHER`. Defaulting it to the
+                                empty set would be this module asserting the
+                                weather forecast is healthy, which is a fact it
+                                has no way to observe. The product's own
+                                real-time uncertainty (§9.2 row 2) is derived
+                                here and unioned in, so AC3 cannot be forgotten
+                                by a caller who passes an empty set.
         """
         if not isinstance(peak_guard_active, bool):
             raise TypeError(
                 f"peak_guard_active must be a bool, not {peak_guard_active!r}. "
                 f"A truthy 'unknown' is how §10.1's priority 2 gets skipped.")
+        if isinstance(min_spread_eur_kwh, bool) or                 not isinstance(min_spread_eur_kwh, (int, float)) or                 not math.isfinite(min_spread_eur_kwh) or                 min_spread_eur_kwh < 0:
+            raise TypeError(
+                f"min_spread_eur_kwh must be a finite, non-negative number of "
+                f"EUR/kWh, not {min_spread_eur_kwh!r}. A negative threshold is "
+                f"one every spread clears.")
+        caller_sources = frozenset(uncertainty)
+        if any(not isinstance(u, Uncertainty) for u in caller_sources):
+            raise TypeError(
+                f"uncertainty must be Uncertainty members, not "
+                f"{sorted(map(repr, caller_sources))} - a string widens by "
+                f"nothing while reporting that it widened.")
+
         if peak_guard_active:
             return Arbitrage.refuse(
                 "the capacity-tariff peak guard is holding, and §10.1 puts peak "
@@ -765,26 +881,64 @@ class TariffPlan:
                 f"§11.4: {self.read.reason}. No series exists, so no spread "
                 f"exists; self-consumption, peak shaving and reserve management "
                 f"(§10.1 priorities 1, 2 and 4) are unaffected")
-        if self.provisional:
+
+        # ⚠️ REFUSAL 3, REWRITTEN BY FCST-03 FROM "ANY POINT IS PROVISIONAL" TO
+        # "THE FIRM POINTS ARE NOT ENOUGH TO TRADE ON", and the difference is
+        # the whole ticket. §8.3 fills the hours a day-ahead feed has not
+        # published yet with yesterday's profile and flags them - so from
+        # midnight until the 14-16 h CET publication, a normal healthy site has
+        # a series that is PART firm and PART carried. Refusing on "any point
+        # provisional" would switch arbitrage off every morning of every day on
+        # every dynamic site, which is not what §8.3 says and is a behaviour
+        # nothing would ever report. What §8.3 forbids is acting ON a
+        # provisional price - so the provisional hours are DROPPED from the
+        # trade set and everything below is computed over the firm ones only.
+        # A fully provisional series (the §11.4 fallback, or a pre-publication
+        # day with no fetch at all) has no firm pair left and is refused, which
+        # is the previous behaviour arrived at by a truer route.
+        pts = self.read.points
+        firm = tuple(p for p in pts if not p.provisional)
+        if len(firm) < 2:
             return Arbitrage.refuse(
-                f"§11.4: the plan is provisional (origin {self.origin!r}), and "
-                f"§8.3 forbids an irreversible action on a provisional price. "
-                f"Load shifting and peak shaving continue")
-        spread = self.spread_eur_kwh()
+                f"§8.3: only {len(firm)} of {len(pts)} hours carry a published "
+                f"price - the rest are provisional (origin {self.origin!r}), "
+                f"and no irreversible action may be taken on a provisional "
+                f"price. A buy hour and a sell hour must BOTH be firm before a "
+                f"cycle can be committed. Load shifting, self-consumption and "
+                f"peak shaving continue")
+
+        spread = round(max(p.eur_per_kwh for p in firm)
+                       - min(p.eur_per_kwh for p in firm), 6)
         if spread == 0.0:
             return Arbitrage.refuse(
-                f"the tariff is flat - every one of the "
-                f"{len(self.read.points)} hours costs "
-                f"{self.read.points[0].eur_per_kwh:.4f} EUR/kWh, so buying low "
-                f"and selling high is arithmetically impossible. §9.2: a fully "
+                f"the tariff is flat - every one of the {len(firm)} firm hours "
+                f"costs {firm[0].eur_per_kwh:.4f} EUR/kWh, so buying low and "
+                f"selling high is arithmetically impossible. §9.2: a fully "
                 f"fixed product is self-consumption only")
-        pts = self.read.points
+
+        # REFUSAL 5, NEW IN FCST-03 (AC3). One widening path, driven by the set
+        # of active uncertainty sources: the product's own (§9.2 row 2, derived
+        # from the DECLARED product and never from a plugin id) unioned with
+        # whatever the caller can see (§11.4's no-weather row).
+        sources = uncertainty_of(self.read.product) | caller_sources
+        need = required_spread(min_spread_eur_kwh, sources)
+        if spread < need:
+            return Arbitrage.refuse(
+                f"the firm spread is {spread:.4f} EUR/kWh and this cycle needs "
+                f"{need:.4f} - {min_spread_eur_kwh:.4f} widened by "
+                f"{widen_factor(sources):.2f}x because "
+                f"{', '.join(sorted(u.value for u in sources)) or 'nothing'} "
+                f"is uncertain (§8.3, §9.2, §11.4). A cycle whose spread does "
+                f"not cover its own round-trip cost costs money and pack life")
+
         return Arbitrage.allow(
             spread=spread,
-            cheapest=min(pts, key=lambda p: p.eur_per_kwh),
-            dearest=max(pts, key=lambda p: p.eur_per_kwh),
+            cheapest=min(firm, key=lambda p: p.eur_per_kwh),
+            dearest=max(firm, key=lambda p: p.eur_per_kwh),
             regime=self.read.regime,
-            product=self.read.product)
+            product=self.read.product,
+            required=need,
+            sources=sources)
 
     @property
     def words(self) -> str:

goodwe_controller/app/tariff.py

@@ -522,6 +522,7 @@ class Projection:
     covered_frac: float
     complete: bool
     block_start: datetime | None
+    held_w: float
 
     def explain(self) -> str:
         return (f"quarter projects {self.projected_w:.0f} W "
@@ -657,19 +658,38 @@ class PeakTracker:
         """
         start = averager.block_start
         if start is None:
-            return Projection(0.0, 0.0, 0.0, 0.0, False, None)
+            # ⚠️ A ZERO PROJECTION, AND IT IS NOT "THE QUARTER IS FINE". It is
+            # "there is no quarter". `block_start is None` is the flag that says
+            # which, and SAFETY-07 grades that flag BEFORE it grades the number -
+            # see peakguard.blindness(). A consumer that reads only
+            # `projected_w` here reads 0 W, which is under every ceiling there
+            # is, on exactly the startup path where nothing else is watching.
+            return Projection(0.0, 0.0, 0.0, 0.0, False, None, 0.0)
         elapsed_wall = max(0.0, (now - start).total_seconds())
         elapsed = averager.elapsed_s
         acc = averager.partial_ws
         remaining = max(0.0, QUARTER_S - elapsed_wall)
-        held = max(getattr(averager, "_last_net", 0.0), 0.0)
+        # ⚠️ NO `getattr` DEFAULT, AND THAT IS THE FIX, NOT A TIDY-UP. This read
+        # was `getattr(averager, "_last_net", 0.0)`: a private name with a
+        # fallback, so renaming the attribute would have kept every projection
+        # green while crediting 0 W held - a projection that reads LOW, which is
+        # the UNDER-GUARDING direction for SAFETY-07's floor. TEST-13 item 4.
+        # `held_net_w` is now a documented public property on QuarterAverager and
+        # is read without a default, so the same rename raises AttributeError on
+        # the first cycle instead of quietly disarming the money guard.
+        held = max(averager.held_net_w, 0.0)
         return Projection(
             projected_w=(acc + held * remaining) / QUARTER_S,
             elapsed_w=(acc / elapsed) if elapsed > 0 else 0.0,
             elapsed_s=elapsed_wall,
             covered_frac=(elapsed / elapsed_wall) if elapsed_wall > 0 else 0.0,
             complete=elapsed_wall <= 0 or elapsed >= elapsed_wall - 1e-9,
-            block_start=start)
+            block_start=start,
+            # Carried so a consumer can see WHAT was extrapolated, not only the
+            # extrapolation. It is the signed held value; `projected_w` uses the
+            # offtake-only form above, and the two differ whenever the site is
+            # exporting - which is the healthy operating point here.
+            held_w=averager.held_net_w)
 
 
 @dataclass(frozen=True)

goodwe_controller/app/validate.py

@@ -131,6 +131,25 @@ NOT READY banner already names the problem, (b) does not apply.
      installed base is on a fixed or static tariff. Refusing to start without a
      price feed would lock those sites out of the add-on entirely.
 
+  8. `peak_soc_floor` at or below `bms_soc_floor`.  [(a)]
+     SAFETY-24, and the same shape as 1, 4, 5 and 6. The peak guard can COMMAND
+     a discharge to hold a billed quarter down (SAFETY-07), and `peak_soc_floor`
+     is the EMS-side bound on how far down it may take the pack. The BMS has its
+     own cut-out and enforces it regardless. Set the EMS floor at or below that
+     cut-out and THE BMS WINS: the EMS bound can never be the thing that stops
+     the discharge, so the add-on carries an energy backstop that is incapable
+     of binding while its status page reports one - rule 5's "a disarmed guard
+     that advertises itself as armed", on the guard whose failure mode is a pack
+     that is quietly never available when it is wanted.
+
+     ⚠️ `<=`, NOT `<`, and the equality case is the interesting one. At exactly
+     equal, the EMS floor and the pack's cut-out act at the same percent, so the
+     EMS floor buys ZERO margin - it can never prevent the pack reaching the BMS
+     limit, which is the entire thing this option exists to prevent. That is not
+     "close to the rail", it is the disarmed case with an extra step. Rule 6
+     permits equality because equality there leaves one reachable point that
+     works; here it leaves none.
+
 WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
   - `integrator_max_w` above `max_w`. DOCS.md is right that the only thing the
@@ -151,12 +170,18 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
   - `maintenance_discharge_w` above `max_w`. Clamped, not contradicted, and the
     clamp names itself in the arbiter's explain() - see rule 6. Warned about,
     not refused.
+  - `peak_soc_floor` below `maintenance_soc_floor`, or above it. They are
+    DIFFERENT QUANTITIES (SAFETY-24: a drain target versus a spend limit) and
+    every ordering of the two is a legitimate site configuration. Refusing on
+    an ordering would be inventing a relationship the system does not have.
 """
 
 import logging
 
+from .arbitrage import enabled as arbitrage_on
 from .p1 import is_enabled, validate_meter_options
-from .price import PROVIDERS
+from .peakguard import PEAK_OPTION_DEFAULTS
+from .price import PRICE_OPTION_DEFAULTS, PROVIDERS
 from .static_tariff import ProfileInvalid, parse_static_profile
 
 _LOG = logging.getLogger("goodwe.config")
@@ -369,6 +394,36 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     # --- 7. two price sources on one site ------------------------------------
     problems.extend(_price_problems(opts))
 
+    # --- 8. an EMS energy floor the BMS does not already enforce -------------
+    # ⚠️ THE FALLBACKS ARE peakguard.PEAK_OPTION_DEFAULTS, NOT LITERALS, and
+    # that is CFG-03 read as a rule rather than as a complaint. Rule 6's own
+    # comment documents a LIVE divergence in this repo caused by typing 2000
+    # here and 2500 in main.py; this card refuses to add a second instance of
+    # it. The dict is the single in-code mirror, pinned to config.yaml by
+    # test_peakguard.py, and main.py reads the same one.
+    soc_floor = _number(opts, "peak_soc_floor",
+                        PEAK_OPTION_DEFAULTS["peak_soc_floor"])
+    bms_floor = _number(opts, "bms_soc_floor",
+                        PEAK_OPTION_DEFAULTS["bms_soc_floor"])
+    if soc_floor is None or bms_floor is None:
+        problems.append(
+            "peak_soc_floor and bms_soc_floor must both be numbers (got "
+            f"{opts.get('peak_soc_floor')!r} / {opts.get('bms_soc_floor')!r})")
+    elif soc_floor <= bms_floor:
+        problems.append(
+            f"peak_soc_floor is {soc_floor:.0f} % but the pack's own cut-out "
+            f"(bms_soc_floor) is {bms_floor:.0f} %, so SAFETY-07's forced "
+            "discharge has no EMS-side bound at all - THE BMS WINS, and it is "
+            "the pack's protection rather than yours. The guard would report a "
+            "SoC floor on its status page while being incapable of ever being "
+            "the thing that stops the discharge, and the symptom of that is a "
+            "battery repeatedly sitting at the BMS limit with no record of why "
+            f"- which looks exactly like the SoC drift the maintenance cycle "
+            f"exists to correct. Raise peak_soc_floor above {bms_floor:.0f} % "
+            f"(the shipped default is "
+            f"{PEAK_OPTION_DEFAULTS['peak_soc_floor']:.0f} %), or correct "
+            "bms_soc_floor if it does not match this pack.")
+
     # --- warnings: real, but not worth refusing over -------------------------
     integ = opts.get("integrator_max_w")
     integ_w = None if not integ else _number(opts, "integrator_max_w", None)
@@ -453,14 +508,21 @@ def _price_problems(opts: dict) -> list[str]:
     #     arbitrage verdict, so the seam is no longer inert.
     #   * main.py reads the STATIC side of that module every cycle
     #     (static_status()), which makes static_profile a real writer of `cheap`.
-    #   * main.py does NOT yet call resolve_tariff() on the control tick, and
-    #     that is deliberate: a provider fetch is network I/O and the tick is
-    #     what feeds the ESP32 heartbeat. So a configured PROVIDER still shapes
-    #     no energy decision on its own; a configured STATIC PROFILE does.
+    #   * main.py does NOT call resolve_tariff() on the control tick, and that
+    #     is still deliberate: a provider fetch is network I/O and the tick is
+    #     what feeds the ESP32 heartbeat. OPT-04 put it on a BACKGROUND REFRESH
+    #     instead (Controller.run_tariff_refresh), and the tick reads the plan
+    #     that task last stored - an attribute read, with nothing to block on.
+    #   * so a configured PROVIDER now DOES shape an energy decision, but only
+    #     through app/arbitrage.py and only while `arbitrage_enabled` is on.
+    #     With it off - the shipped configuration - the series is still fetched,
+    #     validated and published, and still moves nothing.
     #
-    # Hence two refusals below rather than one, and neither claims more than
-    # that list. When OPT-04 puts resolve_tariff() on a background refresh, the
-    # first message's middle clause is what changes - not the rule.
+    # Hence three refusals below rather than two, and none of them claims more
+    # than that list. ⚠️ THE MIDDLE CLAUSE OF THE FIRST MESSAGE IS WHAT OPT-04
+    # CHANGED, exactly as the note it replaced predicted - the RULE is
+    # untouched, because the reason it exists (main.py reads the Home Assistant
+    # pair FIRST and the other source is silent) is unchanged.
     ha_price = [k for k in ("price_now_entity", "price_avg_entity")
                 if str(opts.get(k, "") or "").strip()]
     if pid != "off" and ha_price:
@@ -469,10 +531,12 @@ def _price_problems(opts: dict) -> list[str]:
             f"{'is' if len(ha_price) == 1 else 'are'} set, which is two price "
             "sources on one site. THE HOME ASSISTANT ENTITIES WIN: they are "
             "what main.py reduces to the `cheap` flag the maintenance cycle "
-            "reads. The provider series IS consumed now - app/static_tariff.py "
-            "builds a tariff plan and an arbitrage verdict from it - but it is "
-            "not what main.py acts on, so the supplier you configured would "
-            "shape no energy decision while the status page named it. Clear "
+            "reads, and read_inputs() never looks at the other source once "
+            "they are set. The provider series is consumed - "
+            "app/static_tariff.py builds a tariff plan and an arbitrage "
+            "verdict, and app/arbitrage.py trades on it off a background "
+            "refresh - but the `cheap` flag those entities own is a separate "
+            "decision they would silently keep. Clear "
             "price_now_entity and price_avg_entity to use the "
             f"{pid!r} plugin, or set price_provider to 'off' to keep the "
             "Home Assistant sensors.")
@@ -528,6 +592,67 @@ def _price_problems(opts: dict) -> list[str]:
             "with no tariff at all rather than with a coarse one. Not refused, "
             "but filling it in is what makes that row work.", pid)
 
+    # ⚠️ OPT-04. THE THREE WAYS `arbitrage_enabled: true` CAN BE A LIE, refused
+    # rather than logged, because a strategy that is armed in the UI and cannot
+    # fire is indistinguishable from one that fires and finds no opportunity -
+    # which is the §14 warning box's case exactly. None of these can break an
+    # existing install: the option is new and ships `false`.
+    # ⚠️ CHECKED WHETHER OR NOT ARBITRAGE IS ARMED. A threshold that is not a
+    # non-negative number is a configuration error the moment it is typed, and
+    # deferring the complaint until somebody turns the strategy on would report
+    # it at the worst possible moment - the one where energy starts moving.
+    thresh = _number(opts, "cycle_cost_threshold_eur",
+                     PRICE_OPTION_DEFAULTS["cycle_cost_threshold_eur"])
+    if thresh is None or thresh < 0:
+        problems.append(
+            f"cycle_cost_threshold_eur is "
+            f"{opts.get('cycle_cost_threshold_eur')!r} and must be a "
+            f"non-negative number of EUR/kWh - it is what one round trip COSTS "
+            f"(§10.1). A negative threshold is one that every spread clears, "
+            f"including a spread of nothing, which is arbitrage with the brake "
+            f"removed rather than arbitrage tuned aggressively.")
+
+    if arbitrage_on(opts):
+        if pid == "off" and not str(opts.get("static_profile", "") or "").strip():
+            problems.append(
+                "arbitrage_enabled is on but price_provider is 'off' and "
+                "static_profile is empty, so this site has NO PRICES AT ALL. "
+                "§10.1's priority 3 is 'charge cheap, discharge expensive' and "
+                "there is nothing here to tell cheap from expensive, so the "
+                "strategy would refuse on every cycle forever while the "
+                "configuration said it was running. Configure a price_provider "
+                "or a static_profile, or turn arbitrage_enabled off.")
+        if not is_enabled(opts):
+            problems.append(
+                "arbitrage_enabled is on but meter_source is 'off', so there "
+                "is no P1 telegram stream, the capacity-tariff peak guard "
+                "never runs, and nothing measures the 15-minute average this "
+                "strategy's charging would land in. §9.1 gives peak shaving "
+                "priority over arbitrage; an unmeasured peak cannot be shaved, "
+                "so arbitrage would be deliberately creating the billed "
+                "quantity with the one guard that limits it switched off. "
+                "app/arbitrage.py refuses to trade in that state anyway - this "
+                "refuses the configuration that asks it to. Set meter_source, "
+                "or turn arbitrage_enabled off.")
+        floor = _number(opts, "arbitrage_soc_floor",
+                        PRICE_OPTION_DEFAULTS["arbitrage_soc_floor"])
+        ceiling = _number(opts, "arbitrage_soc_ceiling",
+                          PRICE_OPTION_DEFAULTS["arbitrage_soc_ceiling"])
+        if floor is None or ceiling is None:
+            problems.append(
+                f"arbitrage_soc_floor {opts.get('arbitrage_soc_floor')!r} and "
+                f"arbitrage_soc_ceiling {opts.get('arbitrage_soc_ceiling')!r} "
+                f"must both be numbers - they are percentages of pack charge.")
+        elif floor >= ceiling:
+            problems.append(
+                f"arbitrage_soc_floor is {floor:g} % and arbitrage_soc_ceiling "
+                f"is {ceiling:g} %, so there is no band left between them: "
+                f"every state of charge is either at or under the floor (no "
+                f"discharge) or at or over the ceiling (no charge), and the "
+                f"strategy can never act. The floor is the reserve it may not "
+                f"spend and the ceiling is the headroom it may not overfill, "
+                f"so the floor must be the SMALLER number.")
+
     if pid == "manual_csv" and not str(opts.get("price_csv_path", "") or "").strip():
         problems.append(
             "price_provider is 'manual_csv' but price_csv_path is empty, so "

goodwe_controller/config.yaml

@@ -163,6 +163,37 @@ options:
   peak_forecast_entity: ""
   peak_cap_w: 3500
 
+  # --- SAFETY-24: the energy backstop under SAFETY-07's forced discharge -----
+  # The peak guard can COMMAND a discharge to hold a billed quarter under
+  # peak_cap_w. Until this card it was bounded from below by nothing but the
+  # pack's own BMS cut-out - a real floor, but the PACK's protection rather than
+  # the OPERATOR's. On the 2026-08-20 replay the guard asks for 878 Wh in a day.
+  #
+  # peak_soc_floor is the percent below which that discharge is not sized. When
+  # it binds the guard reports FLOOR-LIMITED, keeps charging blocked (a 0 W
+  # floor), and the add-on raises ONE notification saying the quarter will be
+  # exceeded - failing to shave is never silent, because the euro figure is the
+  # whole point of the guard.
+  #
+  # ⚠️ THIS IS NOT maintenance_soc_floor AND MUST NOT BE MERGED WITH IT.
+  # maintenance_soc_floor is the DRAIN TARGET of the monthly recalibration: the
+  # depth the cycle deliberately goes to, once a month, on purpose. This is the
+  # depth a money-saving discharge may never reach on any day. The right values
+  # differ, and sharing one key would couple two features that want to move
+  # independently.
+  #
+  # ⚠️ 20 IS DERIVED, NOT PICKED. The reference pack is 13.8 kWh usable and the
+  # worst modelled guard day is 878 Wh, i.e. 6.4 % - so 10 points above the
+  # pack's own cut-out leaves the guard ~1.6 of its worst observed days of room
+  # and still never reaches the BMS.
+  peak_soc_floor: 20
+  # The pack's OWN cut-out percent - what the BMS enforces whatever is set
+  # above. Register 0x0560 reads 10 on the reference GW5000S-BP, consistent with
+  # DoD 90. It is here so validate.py can REFUSE a peak_soc_floor at or below
+  # it: such a floor can never bind, the BMS wins, and the status page would
+  # report an energy backstop that does not exist.
+  bms_soc_floor: 10
+
   # ⚠️ THE OLD PRICE PATH, AND IT IS NOT DEAD YET. These two entities are the
   # add-on delegating the whole price question to Home Assistant: main.py reads
   # both and derives ONE BOOLEAN, `cheap = now <= avg`, which is consumed by
@@ -240,6 +271,38 @@ options:
   # a second series: no shipped supplier publishes a dynamic injection curve.
   export_price_eur_kwh: 0.04
 
+  # --- price arbitrage (OPT-04, specs §10.1 priority 3 / §17) ---------------
+  # Charge in the cheapest published hour, discharge in the dearest, and ONLY
+  # when the spread covers what the round trip costs. Off in the shipped
+  # configuration: this is the first strategy in the add-on that moves energy
+  # against the meter on purpose, so it is armed deliberately or not at all.
+  #
+  # ⚠️ IT NEEDS A PRICE SOURCE AND A P1 METER, and validate.py refuses the
+  # combinations that cannot work rather than letting them look armed. With
+  # `price_provider: off` and no `static_profile` there is no series to trade
+  # on; with `meter_source: off` the capacity-tariff peak guard never runs, and
+  # §9.1 puts peak shaving above arbitrage - a charge nothing measures is the
+  # exact failure that guard exists to prevent.
+  #
+  # ⚠️ AT THE SHIPPED THRESHOLD A STATIC DAY/NIGHT SITE DOES NOT TRADE. The
+  # realistic Belgian day/night spread is about 0.08 EUR/kWh and the threshold
+  # below is 0.10, so the verdict is "the firm spread does not cover this
+  # cycle's cost" and nothing happens - correctly. That is a product decision
+  # (this number, and app/price.py's widening factors) and it is open with the
+  # owner; the code is correct at any value and no number was picked to make a
+  # trade appear.
+  arbitrage_enabled: false
+  # §10.1's `cycle_cost_threshold_eur`: what one full round trip costs per kWh
+  # - the wear on the pack plus the conversion losses. A spread below this is
+  # a cycle that loses money and pack life, so it is not taken.
+  cycle_cost_threshold_eur: 0.10
+  # The reserve arbitrage may not spend, and the headroom it may not overfill.
+  # Deliberately NOT the maintenance_soc_* keys: those describe a monthly
+  # balancing cycle, and pointing a trading strategy at them would couple two
+  # unrelated policies through one number.
+  arbitrage_soc_floor: 20
+  arbitrage_soc_ceiling: 95
+
   # --- site ------------------------------------------------------------------
   estop_fitted: false
   log_level: info
@@ -311,6 +374,12 @@ schema:
 
   peak_forecast_entity: str?
   peak_cap_w: int(500,15000)
+  # SAFETY-24. No "off" value: a guard that can command a discharge does not get
+  # a supported way to have no energy bound at all. The ranges OVERLAP on
+  # purpose - the schema cannot express "above bms_soc_floor", so validate.py
+  # rule 8 is what refuses the pair, with a message naming both numbers.
+  peak_soc_floor: int(5,60)
+  bms_soc_floor: int(0,50)
   price_now_entity: str?
   price_avg_entity: str?
 
@@ -337,5 +406,15 @@ schema:
   # bottoms out at 0 would make that site inexpressible.
   export_price_eur_kwh: float(-1,1)
 
+  # OPT-04. ⚠️ The threshold's lower bound is 0 and not negative: it is a COST,
+  # and a negative one is a threshold every spread clears - arbitrage with the
+  # brake removed. app/arbitrage.py refuses it in code too, because
+  # validate_startup_config() is also sim/inject.py's entry point and can be
+  # handed any dict at all.
+  arbitrage_enabled: bool
+  cycle_cost_threshold_eur: float(0,1)
+  arbitrage_soc_floor: int(5,95)
+  arbitrage_soc_ceiling: int(10,100)
+
   estop_fitted: bool
   log_level: list(trace|debug|info|warning|error)

goodwe_controller/scenarios/fetch_epex_be.py

@@ -0,0 +1,551 @@
+#!/usr/bin/env python3
+"""DATA-02: fetch 12 months of EPEX BE day-ahead prices, in §9.3's shape.
+
+    python3 scenarios/fetch_epex_be.py --start 2025-09-01 --end 2026-09-01 \
+        --out scenarios/epex-be-dayahead-2025-09-01_2026-09-01.json
+
+Run from `goodwe_controller/`. Rewrites the output file from scratch; the
+committed dataset is exactly what this produces, and `--verify` re-derives every
+claim the file makes about itself without going to the network.
+
+
+WHAT THIS IS NOT
+================
+NOT wired into the add-on, and it must never be. `price.py`'s `GenericDayAhead`
+is the live path and it has its own egress check; this is a one-shot archival
+fetch that produces a file for REPLAY, run by hand by a developer. Nothing under
+`app/` imports it.
+
+
+THE SOURCE, AND WHY THIS ONE
+============================
+`https://api.energy-charts.info/price?bzn=BE` - Fraunhofer ISE's Energy-Charts
+API. No key, no registration.
+
+⚠️ THE LICENCE WAS CHECKED BEFORE ANY DATA WAS COMMITTED, because for this
+source it is NOT uniform across bidding zones. The API's own OpenAPI document
+(`https://api.energy-charts.info/openapi.json`, /price) splits the zones in two:
+
+    "The data for the following bidding zones is licensed as CC BY 4.0 from
+     Bundesnetzagentur | SMARD.de and is published without changes:
+     AT, BE (Belgium), CH, CZ, DE-LU, ..."
+
+    "The data for the other bidding zones is for private and internal use only.
+     The utilization of any data, whether in its raw or derived form, for
+     external or commercial purposes is expressly prohibited. Should you require
+     licensing for market-related data, please direct your inquiries to the
+     original data providers, including but not limited to EPEX SPOT SE."
+
+BE is in the FIRST list, so redistribution is permitted with attribution and the
+dataset is committed rather than left as a fetch script and a checksum. Every
+response also carries the licence per-response in `license_info`, and this
+script REFUSES to write a file if that field ever stops saying CC BY 4.0 - a
+licence checked once by a human and assumed forever is a licence that changes
+silently. Had BE been in the second list, the correct output of this card would
+have been this script and a checksum and no data.
+
+Attribution, carried in the dataset's own `provenance` block and reproduced
+here: data CC BY 4.0, Bundesnetzagentur | SMARD.de, retrieved via Energy-Charts
+(Fraunhofer ISE), https://energy-charts.info, published without changes.
+
+Cross-checked against the upstream on 2026-08-31: SMARD's own chart_data series
+`4996/DE` over 2026-04-10 matched this API's BE series on all 96 quarter-hours
+with a maximum absolute difference of 0.00 EUR/MWh. "Published without changes"
+is a claim worth checking once; `--verify` does not repeat it, because it is a
+claim about the SOURCE and not about the file.
+
+
+RAW WHOLESALE, AND THE ASSUMPTION THAT IS NOT BAKED IN
+======================================================
+⚠️ WHAT COMES BACK IS RAW WHOLESALE, EUR/MWh, DAY-AHEAD AUCTION CLEARING PRICE.
+It is NOT all-in: no supplier markup, no distribution or transmission tariff, no
+levies, no VAT. §9.3's canonical point is all-in, and TARIFF-02's whole trap is
+a figure that already contains a component being handed to something that adds
+it again.
+
+So this file does NOT add one. `eur_per_kwh` in the output is the wholesale
+figure converted from EUR/MWh, `provenance.all_in` is `false` beside it, and the
+markup/tax assumption a consumer needs lives in `provenance.all_in_assumption`
+as NUMBERS TO APPLY rather than numbers already applied. test_arbitrage.py
+section 7 applies them where a reader can watch it happen.
+
+The assumption's SHAPE is the part that is not arbitrary, and it decides which
+conclusions depend on the guessed numbers at all:
+
+    all_in(h) = (wholesale(h) + markup + network_and_levies) * (1 + vat)
+
+  * The two ADDITIVE terms cancel out of a spread: max - min is unchanged by
+    them. So how often a day clears `cycle_cost_threshold_eur` does NOT depend
+    on the markup guess - only on the VAT multiplier.
+  * They do NOT cancel out of §17's negative-price guard, which compares ONE
+    hour's all-in price against zero. A wholesale hour at -0.02 EUR/kWh is
+    comfortably positive all-in once ~0.12 of fixed charges is added.
+
+Both are asserted arithmetically in section 7 rather than believed, and the
+trade count is reported on the raw spread as well, so a reader can see exactly
+how much of the answer rests on the guess.
+
+The numbers themselves (2026 Belgian residential dynamic contract, order of
+magnitude) are a STATED GUESS, labelled as one everywhere they appear. They are
+not a measurement and this card had nothing to measure them with.
+
+
+HOURS, QUARTER-HOURS, AND THE SEAM IN THE MIDDLE OF THE YEAR
+============================================================
+⚠️ THE SOURCE CHANGES RESOLUTION PART-WAY THROUGH ANY RECENT 12 MONTHS. EPEX
+day-ahead moved to a 15-minute market time unit in October 2025 and the feed
+follows: 2025-09-10 comes back as 24 hourly points, 2025-12-10 as 96
+quarter-hourly ones. An importer that assumed either one silently loses three
+quarters of the year, or reads a quarter as an hour.
+
+The canonical format is hourly, so quarter-hours are aggregated: an hour's price
+is the unweighted mean of its four quarters. That is a STATED APPROXIMATION of
+the hourly product, not the hourly product, and it errs in the direction that
+matters here - averaging discards intra-hour variation, so the observed spread
+is a LOWER bound on what a 15-minute strategy would see.
+`provenance.resolution` records how many hours came from each source shape.
+
+⚠️ AND A PARTIAL HOUR IS DROPPED, NOT AVERAGED OVER WHAT ARRIVED. An hour with
+three of four quarters is an hour nobody published a complete price for; the
+mean of three would be an invented number carrying no flag. Dropped hours are
+listed in `provenance.gaps` with their timestamps, because a missing hour in a
+feed is not a zero price, and a zero price is exactly the value that would make
+everything look free.
+
+
+SIZE: WHY THIS IS PLAIN JSON AND NOT A `.gz`, MEASURED
+======================================================
+The directory's existing captures are gzipped, so the default would have been to
+gzip this too. Measured on the committed file instead of assumed:
+
+    working tree, plain JSON                             893 171 bytes
+    what GIT actually stores for it (zlib, loose object)  74 590 bytes
+    what git would store for a committed `.json.gz`       56 504 bytes
+
+⚠️ GIT ALREADY COMPRESSES BLOBS, so gzipping buys 18 KB - 24 % of an object
+that is already 75 KB, in a repository whose three existing P1 captures cost
+27 KB, 136 KB and 140 KB. Eighteen kilobytes is not worth making the provenance
+block unreadable in a pull request, and the licence claim in that block is
+precisely the thing a reviewer of this card has to read and check. Plain JSON
+also greps, diffs line-by-line when a future refetch changes something, and is
+what `--verify` opens. `load()` still handles `.gz` for a future dataset large
+enough to want it; this one is not.
+
+The P1 captures are gzipped for the opposite reason and it is not an
+inconsistency: they are hundreds of thousands of telegram lines that no human
+reads, and there is no metadata in them to review.
+
+
+TIME
+====
+Every instant is carried as UTC and rendered with `app.price.brussels()`, the
+module that already owns the EU DST rule without a tz database. There is no
+second answer to that question here and there must not be: the point of
+`brussels()` is that the 02:00-03:00 hour which happens twice in October is two
+instants, and a 24-slot local-hour importer collapses them.
+
+So a year is 8760 hours only if it contains no transition, or contains both and
+they cancel - 25 in October, 23 in March. `--verify` therefore asserts the
+PER-DAY counts, not the total, because the total is exactly the number a broken
+importer also produces.
+"""
+
+import argparse
+import gzip
+import hashlib
+import json
+import os
+import sys
+import time
+import urllib.error
+import urllib.request
+from collections import Counter, defaultdict
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from app.price import brussels                                   # noqa: E402
+
+API = "https://api.energy-charts.info/price"
+BZN = "BE"
+LICENCE_MUST_CONTAIN = "CC BY 4.0"
+UTC = timezone.utc
+
+ATTRIBUTION = ("Data licensed CC BY 4.0 by Bundesnetzagentur | SMARD.de, "
+               "retrieved via the Energy-Charts API (Fraunhofer ISE), "
+               "https://energy-charts.info. Published without changes.")
+
+# ⚠️ A GUESS, LABELLED AS ONE, AND APPLIED BY THE CONSUMER - NOT HERE.
+# Order-of-magnitude 2026 Belgian residential dynamic contract. Nothing in this
+# repository measured any part of it.
+ALL_IN_ASSUMPTION = {
+    "form": "all_in = (wholesale + markup + network_and_levies) * (1 + vat)",
+    "markup_eur_per_kwh": 0.020,
+    "network_and_levies_eur_per_kwh": 0.100,
+    "vat_fraction": 0.06,
+    "status": "ASSUMPTION, NOT MEASURED. Stated so a consumer applies it "
+              "deliberately; the committed eur_per_kwh has none of it applied.",
+    "note": "The two additive terms cancel out of any spread, so an arbitrage "
+            "trade count depends on vat_fraction only. They do NOT cancel out "
+            "of the negative-price guard (17), which compares one hour's "
+            "all-in price against zero.",
+}
+
+
+PACE_S = 3.0            # between chunks, unconditionally
+RETRIES = 6
+
+
+def _get(url: str) -> dict:
+    """One GET, backing off on 429 and 5xx.
+
+    ⚠️ THIS IS A FREE PUBLIC SERVICE AND IT RATE-LIMITS. The first run of this
+    script was refused with 429 on its fifth chunk. Backing off is the polite
+    behaviour; it is also the correct one, because the alternative - catching
+    the error and carrying on - would produce a file that is silently missing a
+    month and says nothing about it. A refused request is not an empty month.
+    """
+    req = urllib.request.Request(
+        url,
+        headers={"User-Agent": "goodwe-addon/DATA-02 (one-shot archival fetch)"})
+    wait = 5.0
+    for attempt in range(1, RETRIES + 1):
+        try:
+            with urllib.request.urlopen(req, timeout=90) as r:
+                return json.loads(r.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            if e.code not in (429, 500, 502, 503, 504) or attempt == RETRIES:
+                raise
+            print(f"    HTTP {e.code}; backing off {wait:.0f}s "
+                  f"(attempt {attempt}/{RETRIES})", file=sys.stderr)
+            time.sleep(wait)
+            wait *= 2
+    raise SystemExit(f"unreachable: {url}")
+
+
+def local_midnight_utc(day: str) -> datetime:
+    """The INSTANT at which Brussels midnight begins on `day` (YYYY-MM-DD).
+
+    ⚠️ THE WINDOW IS LOCAL, NOT UTC, AND THE FIRST RUN OF THIS SCRIPT PROVED WHY.
+    Bounding it at 00:00 UTC starts the year at 02:00 CEST, which makes the first
+    Brussels day 22 hours long - and 22 is not one of the two lengths a
+    transition produces, so `report()` refused the file. A dataset whose first
+    day is short is a dataset whose "days per year" arithmetic is quietly wrong
+    everywhere downstream.
+
+    Derived from `brussels()` by trying the only two offsets Belgium has and
+    keeping the one that round-trips, rather than by restating the EU rule here.
+    """
+    for hours in (1, 2):
+        guess = datetime.fromisoformat(f"{day}T00:00:00").replace(
+            tzinfo=timezone(timedelta(hours=hours))).astimezone(UTC)
+        if brussels(guess).isoformat() == f"{day}T00:00:00+0{hours}:00":
+            return guess
+    raise SystemExit(f"no Brussels midnight for {day!r} - brussels() disagrees "
+                     f"with itself, which is a bug in price.py, not here.")
+
+
+def _months(start: datetime, end: datetime):
+    """[start, end) in month-sized chunks, so a bad chunk names its own window."""
+    a = start
+    while a < end:
+        b = min(end, (a.replace(day=1) + timedelta(days=32)).replace(day=1))
+        yield a, b
+        a = b
+
+
+def fetch(start: datetime, end: datetime):
+    """Raw {unix_second: EUR/MWh} over [start, end), deduplicated.
+
+    ⚠️ A `null` price is DROPPED, never coerced. The API returns null for an
+    interval it holds no result for, and `or 0.0` is the version of this line
+    that ships a year of free electricity.
+    """
+    seen, licences, nulls = {}, Counter(), 0
+    for a, b in _months(start, end):
+        # ⚠️ THE API'S `end` IS AN INCLUSIVE LOCAL DAY, AND THE WINDOW'S IS AN
+        # EXCLUSIVE INSTANT. Ask for the day containing the LAST hour of the
+        # chunk, derived from the instant rather than by subtracting a calendar
+        # day from the bound: `b - 1 day` drops the final local day whenever the
+        # window ends at local midnight, which is exactly how this window ends.
+        # The first run lost 2026-08-31 that way, silently - 8736 points instead
+        # of 8760 - and the points-plus-gaps accounting in report() is what
+        # noticed. A day nobody asked for is not a day with no prices.
+        first = brussels(a).date().isoformat()
+        last = brussels(b - timedelta(hours=1)).date().isoformat()
+        url = f"{API}?bzn={BZN}&start={first}&end={last}"
+        d = _get(url)
+        lic = str(d.get("license_info", ""))
+        licences[lic] += 1
+        if LICENCE_MUST_CONTAIN not in lic:
+            raise SystemExit(
+                f"REFUSING TO WRITE. {url} came back under licence {lic!r}, "
+                f"which does not say {LICENCE_MUST_CONTAIN!r}. The BE zone was "
+                f"redistributable when this card ran; if that has changed, the "
+                f"right output is this script and a checksum, not the data.")
+        unit = str(d.get("unit", ""))
+        if "MWh" not in unit:
+            raise SystemExit(
+                f"REFUSING TO WRITE. {url} reports unit {unit!r}, not EUR/MWh. "
+                f"A silent unit change is a factor of 1000 on every price.")
+        for t, p in zip(d["unix_seconds"], d["price"]):
+            if p is None:
+                nulls += 1
+                continue
+            if start.timestamp() <= t < end.timestamp():
+                seen[int(t)] = float(p)
+        print(f"  {a.date()} .. {b.date()}  {len(d['price']):5d} intervals",
+              file=sys.stderr)
+        time.sleep(PACE_S)
+    return seen, licences, nulls
+
+
+def to_hourly(raw: dict):
+    """Hourly means keyed by UTC hour. Returns (hours, gaps, shape_counts).
+
+    An hour is emitted only when every interval the source used for it arrived:
+    1 of 1 where the source was hourly, 4 of 4 where it was quarter-hourly.
+    Anything else is a gap and is named as one.
+    """
+    buckets = defaultdict(dict)
+    for t, p in raw.items():
+        buckets[t - (t % 3600)][t % 3600] = p
+
+    hours, gaps, shapes = {}, [], Counter()
+    for h in sorted(buckets):
+        got = buckets[h]
+        if set(got) == {0}:
+            shapes["hourly"] += 1
+            hours[h] = got[0]
+        elif set(got) == {0, 900, 1800, 2700}:
+            shapes["quarter_hourly_mean"] += 1
+            hours[h] = sum(got.values()) / 4.0
+        else:
+            gaps.append({
+                "hour_utc": datetime.fromtimestamp(h, UTC).isoformat(),
+                "intervals_present": sorted(got),
+                "why": "incomplete hour - dropped rather than averaged over "
+                       "what arrived; a partial read is not an observation",
+            })
+    return hours, gaps, shapes
+
+
+def canonical(hours: dict) -> list:
+    """9.3 points. THREE FIELDS, rendered at the Brussels offset for the instant."""
+    return [{"start": brussels(datetime.fromtimestamp(h, UTC)).isoformat(),
+             "eur_per_kwh": round(hours[h] / 1000.0, 6) + 0.0,
+             "provisional": False}
+            for h in sorted(hours)]
+
+
+def expected_hours(start: datetime, end: datetime) -> int:
+    """Whole hours in the window. Derived, rather than 8760 typed in."""
+    return int((end - start).total_seconds() // 3600)
+
+
+def per_local_day(points) -> Counter:
+    """Points per BRUSSELS calendar day - the count that exposes a DST bug."""
+    n = Counter()
+    for p in points:
+        n[p["start"][:10]] += 1
+    return n
+
+
+def digest(points) -> str:
+    """A checksum over the POINTS, so reformatting the envelope does not move it."""
+    h = hashlib.sha256()
+    for p in points:
+        h.update(f"{p['start']}|{p['eur_per_kwh']:.6f}|{int(p['provisional'])}\n"
+                 .encode())
+    return h.hexdigest()
+
+
+def load(path: str) -> dict:
+    op = gzip.open if path.endswith(".gz") else open
+    with op(path, "rt", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def report(doc, *, start=None, end=None) -> int:
+    """Re-derive every claim the file makes about itself. Returns failures."""
+    pts = doc["prices"]
+    prov = doc["provenance"]
+    bad = 0
+
+    def ck(name, cond):
+        nonlocal bad
+        print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+        if not cond:
+            bad += 1
+
+    ck(f"the checksum over the {len(pts)} points matches the recorded one "
+       f"({prov['sha256_of_points'][:16]}...)",
+       digest(pts) == prov["sha256_of_points"])
+    ck("every point has exactly the three canonical fields and nothing else",
+       all(set(p) == {"start", "eur_per_kwh", "provisional"} for p in pts))
+    ck("every start carries a UTC offset, and it is +01:00 or +02:00 - a naive "
+       "timestamp here is a wall clock plus an assumption",
+       bool(pts) and all(p["start"][-6:] in ("+01:00", "+02:00") for p in pts))
+    ck("the series is strictly increasing in time, so no instant is duplicated",
+       all(datetime.fromisoformat(a["start"]) < datetime.fromisoformat(b["start"])
+           for a, b in zip(pts, pts[1:])))
+    ck("consecutive points are exactly one hour apart AS INSTANTS, so the two "
+       "02:00s of the October day are two hours rather than one",
+       all((datetime.fromisoformat(b["start"])
+            - datetime.fromisoformat(a["start"])) == timedelta(hours=1)
+           for a, b in zip(pts, pts[1:])))
+
+    days = per_local_day(pts)
+    odd = {d: n for d, n in days.items() if n != 24}
+    ck(f"exactly two Brussels days are not 24 hours long, and they are the "
+       f"transitions: {sorted(odd.items())}",
+       sorted(odd.values()) == [23, 25] and len(odd) == 2)
+    spring = [d for d, n in odd.items() if n == 23]
+    autumn = [d for d, n in odd.items() if n == 25]
+    ck(f"the 23-hour day {spring} is in March and the 25-hour day {autumn} is "
+       f"in October, which is the direction the EU rule actually runs",
+       len(spring) == 1 and len(autumn) == 1
+       and spring[0][5:7] == "03" and autumn[0][5:7] == "10")
+    if autumn:
+        twice = [p["start"] for p in pts
+                 if p["start"].startswith(autumn[0] + "T02")]
+        ck(f"...and 02:00 on {autumn[0]} occurs TWICE at two different offsets "
+           f"{twice} - exactly the case a 24-slot local-hour array collapses",
+           len(twice) == 2 and twice[0][-6:] == "+02:00"
+           and twice[1][-6:] == "+01:00")
+        ck(f"...and the two carry DIFFERENT prices, so the 25th hour is a real "
+           f"observation and not the same one written down twice",
+           len({p["eur_per_kwh"] for p in pts
+                if p["start"].startswith(autumn[0] + "T02")}) == 2)
+    if spring:
+        ck(f"...and 02:00 on {spring[0]} does not occur at all, because that "
+           f"wall clock reading never happened in Belgium",
+           not any(p["start"].startswith(spring[0] + "T02") for p in pts))
+
+    if start and end:
+        want = expected_hours(start, end)
+        ck(f"{len(pts)} points for a window of {want} whole hours, and the "
+           f"{len(prov['gaps'])} recorded gaps account for the difference "
+           f"exactly", len(pts) + len(prov["gaps"]) == want)
+
+    # ⚠️ A ZERO IS NOT AUTOMATICALLY A DEFECT HERE, AND SAYING IT WAS WOULD BE
+    # THE WRONG LESSON. The Belgian market really does clear at 0.00 EUR/MWh in
+    # solar-glut hours; this window contains such hours. What must be impossible
+    # is a zero that arrived by COERCION - a dropped read turned into a free
+    # hour. That is excluded structurally rather than by outlawing the value:
+    # nulls are dropped, incomplete hours become gaps, and the accounting above
+    # shows points + gaps covering every hour of the window, so every emitted
+    # point stands for intervals the source actually published.
+    zeros = [p["start"] for p in pts if p["eur_per_kwh"] == 0.0]
+    ck(f"the {len(zeros)} hours priced at exactly zero match the count recorded "
+       f"at build time, so no zero appeared between the fetch and the file",
+       len(zeros) == prov["exact_zero_hours"])
+    ck("...and none of them is a coerced read: every emitted hour is backed by "
+       "published intervals, which is what the points-plus-gaps accounting "
+       "above establishes",
+       len(prov["gaps"]) == 0 or all("intervals_present" in g
+                                     for g in prov["gaps"]))
+    ck("the figures are declared RAW WHOLESALE, and the all-in assumption is "
+       "recorded as an assumption rather than applied",
+       prov["all_in"] is False
+       and "ASSUMPTION" in prov["all_in_assumption"]["status"])
+    return bad
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--start", default="2025-09-01")
+    ap.add_argument("--end", default="2026-09-01",
+                    help="exclusive; both bounds are BRUSSELS-local midnights")
+    ap.add_argument("--out", default=None)
+    ap.add_argument("--verify", default=None,
+                    help="re-derive the claims of an existing file; no network")
+    a = ap.parse_args()
+
+    if a.verify:
+        doc = load(a.verify)
+        print(f"verifying {a.verify}")
+        s = datetime.fromisoformat(doc["provenance"]["window_utc"]["start"])
+        e = datetime.fromisoformat(doc["provenance"]["window_utc"]["end"])
+        bad = report(doc, start=s, end=e)
+        print("OK" if not bad else f"{bad} FAILED")
+        return 1 if bad else 0
+
+    start = local_midnight_utc(a.start)
+    end = local_midnight_utc(a.end)
+    out = a.out or f"scenarios/epex-be-dayahead-{a.start}_{a.end}.json"
+
+    print(f"fetching {BZN} day-ahead {start.date()} .. {end.date()}",
+          file=sys.stderr)
+    raw, licences, nulls = fetch(start, end)
+    hours, gaps, shapes = to_hourly(raw)
+    pts = canonical(hours)
+
+    doc = {
+        "provenance": {
+            "card": "DATA-02",
+            "what": "EPEX BE day-ahead auction clearing prices, hourly",
+            "source": f"{API}?bzn={BZN} (Energy-Charts API, Fraunhofer ISE)",
+            "upstream": "Bundesnetzagentur | SMARD.de",
+            "licence": "CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)",
+            "licence_checked": "before committing anything; the API's OpenAPI "
+                               "document lists BE among the CC BY 4.0 zones and "
+                               "the remaining zones as private/internal use "
+                               "only, so redistribution of THIS zone is "
+                               "permitted with attribution",
+            "licence_as_returned": sorted(licences),
+            "attribution": ATTRIBUTION,
+            "cross_check": "SMARD chart_data 4996/DE over 2026-04-10 matched "
+                           "this feed on all 96 quarter-hours, max abs "
+                           "difference 0.00 EUR/MWh (2026-08-31)",
+            "retrieved_utc": datetime.now(UTC).replace(microsecond=0).isoformat(),
+            "fetched_by": "scenarios/fetch_epex_be.py",
+            "window_utc": {"start": start.isoformat(), "end": end.isoformat()},
+            "unit": "EUR per kWh (source publishes EUR/MWh; divided by 1000)",
+            "all_in": False,
+            "all_in_note": "RAW WHOLESALE. No supplier markup, no network or "
+                           "transmission tariff, no levies, no VAT. 9.3's "
+                           "canonical point is all-in and this is NOT; the "
+                           "consumer applies the assumption below, visibly.",
+            "all_in_assumption": ALL_IN_ASSUMPTION,
+            "resolution": {
+                "note": "EPEX day-ahead moved to a 15-minute market time unit "
+                        "in Oct 2025, part-way through this window.",
+                "hours_from_hourly_source": shapes["hourly"],
+                "hours_from_quarter_hourly_mean": shapes["quarter_hourly_mean"],
+                "aggregation": "unweighted mean of the four quarters; a stated "
+                               "approximation of the hourly product, and a "
+                               "LOWER bound on the spread a 15-minute strategy "
+                               "would have seen",
+            },
+            "timezone": "starts rendered at the Brussels offset by "
+                        "app.price.brussels(); instants carried in UTC, so the "
+                        "transition days come out 23 and 25 points by "
+                        "construction rather than by a special case",
+            "nulls_dropped": nulls,
+            "gaps": gaps,
+            "gaps_note": "hours the source did not publish completely. Dropped, "
+                         "never zero-filled: a missing hour is not a free hour.",
+            "points": len(pts),
+            "exact_zero_hours": sum(1 for p in pts if p["eur_per_kwh"] == 0.0),
+            "negative_hours": sum(1 for p in pts if p["eur_per_kwh"] < 0),
+            "zero_note": "REAL CLEARINGS AT 0.00 EUR/MWh, not dropped reads. "
+                         "Nulls are dropped and incomplete hours become gaps, "
+                         "so points + gaps == hours in the window and no point "
+                         "stands in for something that failed to arrive.",
+            "sha256_of_points": digest(pts),
+        },
+        "prices": pts,
+    }
+
+    with open(out, "w", encoding="utf-8", newline="\n") as f:
+        json.dump(doc, f, indent=1, ensure_ascii=False)
+        f.write("\n")
+    print(f"wrote {out}  {len(pts)} points  {os.path.getsize(out)} bytes",
+          file=sys.stderr)
+    print(f"verifying {out}")
+    return 1 if report(doc, start=start, end=end) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

goodwe_controller/scenarios/p1-net-30d-2026-08/README.md

@@ -0,0 +1,167 @@
+# 30 days of P1 net power — 2026-08-01 … 2026-08-30
+
+`sensor.p1_meter_active_power` out of Home Assistant's recorder, one gzipped
+JSONL file per **local** day (Europe/Brussels), same schema as the two files one
+directory up:
+
+    {"t": "2026-08-22T22:00:00+00:00", "w": -25.0}
+
+**485,841 samples, 30/30 days read, 0 days failed, 4.13 MB gzipped.**
+Produced by `tools/export_p1_history.py`; `manifest.json` here carries the
+per-day counts, sha256 of every file, and every gap.
+
+    python3 tools/export_p1_history.py --days 30 --end-date 2026-08-30 \
+        --out-dir scenarios/p1-net-30d-2026-08
+
+## Why this exists
+
+[[TARIFF-01]] AC 3 and [[SAFETY-07]] AC 3 both ask for *"monthly peak held under
+the soft limit in >= 95 % of intervals over a 30-day simulation replay"*, and
+both were merged with the criterion honestly unmet because only two days of
+capture existed. `test_tariff.py`'s docstring still recorded the reason as
+"nothing longer was ever captured" — which was true about the past and was
+quietly read as a statement about the future. It was not one. Probed on
+2026-08-31, HA's recorder answered a 20-minute window with 230 samples at 30
+days back and 0 at 45, so the whole month was still there and was exported the
+same day. **The window rolls: 2026-08-01 leaves the recorder around 2026-09-15.**
+
+## The size decision — COMMITTED, deliberately, at 4.13 MB
+
+Three options were on the table. This one was taken and the cost is stated
+rather than absorbed, and it is measured rather than estimated - a
+`git bundle` of the whole history before and after this commit:
+
+    release/1.0 @ 86c43eb   1.58 MB
+    DATA-01                 5.28 MB      +3.70 MB, x3.3
+
+A full clone of this repository therefore more than triples, and a Home
+Assistant supervisor clones it on every add-on install and update. That is the
+price; the paragraphs below are why it was judged worth paying rather than
+avoided by making the data worse or making it disappear.
+
+* **Downsampling is not available.** It is not a matter of taste: the shipped
+  `meter_max_age_s` is **30 s**, which is the age past which the controller's
+  own ingest stops counting a held reading as coverage. Any resample coarser
+  than 30 s therefore converts real coverage into modelled meter-gap and changes
+  the very number AC 3 measures. Resampling at or under 30 s saves almost
+  nothing against a 5 s cadence.
+* **"Outside the repo with a pointer" is what already happened, and it is why
+  this card exists.** The two committed days came from the infra repo's private
+  `sim/scenarios/`, the one-off export script was thrown away, and three cards
+  then deferred an acceptance criterion on the belief that the data could not be
+  produced again. `test_tariff.py` states the general rule verbatim: *a
+  regression fixture CI cannot see is not a regression fixture.* CI's token is
+  minted for this repository only.
+* **So: committed** — but in a SUBDIRECTORY, which is load-bearing. Both
+  `test_tariff.py` part 9 and `test_peakguard.py` part 6 do
+  `(HERE / "scenarios").glob("p1-net-*.jsonl.gz")`, which does not recurse. Drop
+  these thirty files beside the two and CI grows sixty full-day
+  replays - about 50 s of pure compute - on every PR forever, `test_tariff.py`'s
+  `check(... replay_days < 30)` starts failing, and both files' honesty notes
+  become false. In `p1-net-30d-2026-08/` they are visible to CI, invisible to
+  the globs, and the two committed days keep their job as the small fixtures the
+  suites grade against.
+
+They are also written once and never edited, so git stores one already-deflated
+blob per day with no delta churn.
+
+## Gaps are visible, never interpolated
+
+Nothing is filled, carried forward or resampled. A hole in the recorder is a
+hole here — consecutive `t` values further apart than the cadence — which is
+exactly what the controller's freshness rule already reads as *no coverage*, so
+a missing hour replays as a missing hour rather than as an hour of whatever the
+last sample said.
+
+**13 gaps over 30 s, 1291 s in total: 99.950 % of the month is covered.**
+All of them are listed in `manifest.json` and by
+`python3 tools/replay_ac3.py <dir> --report-gaps`. The longest is 263 s on
+2026-08-11.
+
+Three samples in the month carried the state `unavailable` rather than a number
+(2026-08-18 02:03:54Z and 04:10:41Z, 2026-08-25 01:52:02Z). There is no float to
+write and the committed schema has no slot for a non-number, so they are absent
+from the series and recorded individually in `manifest.json` under
+`non_numeric_states`. Each one sits inside a gap that is already listed, which
+is the honest rendering: the meter was not reporting a power then.
+
+**A failed read is never an empty hour.** If a day's read fails, the exporter
+writes NO FILE, records `"read": "FAILED"` with the error, and exits non-zero —
+so a missing day is unreadable-and-known rather than silently zero. The entity
+is also proved to exist through `/api/states` before any day is trusted, because
+a typo would otherwise answer `200 []` thirty times and produce a beautifully
+consistent dataset of nothing. On this run: 30 read, 0 failed, 0 empty.
+
+## AC 3, measured
+
+    cd goodwe_controller
+    python3 tools/replay_ac3.py scenarios/p1-net-30d-2026-08
+
+    485841 samples, 2879 closed quarters (30.0 days' worth)
+    month 2026-08: peak 5029.8 W uncontrolled -> 4107.3 W guarded
+
+    TARIFF-01 AC 3 (UNCONTROLLED): 2847/2879 = 98.89 % of quarters at or under 3500 W
+    SAFETY-07 AC 3 (GUARDED):      2850/2879 = 98.99 %
+      guard cycles 143810, engaged on the measurement 1542, blind 195,
+      saturated 0, modelled discharge 8060 Wh
+
+2879 rather than 2880 quarters: the last quarter of 2026-08-30 closes only when
+a telegram past its boundary arrives, and that telegram is 2026-08-31's.
+
+### What the numbers actually say — three findings, not a pass
+
+1. **AC 3 is met on the ">= 95 % of intervals" reading, and the criterion turns
+   out to be nearly insensitive.** The UNCONTROLLED month — no controller, no
+   peak shaving, nothing running — already scores 98.89 %. A criterion that a
+   house passes by doing nothing does not discriminate between a working guard
+   and an absent one. That is a finding about the acceptance criterion, and it
+   is reported rather than filed as a win.
+2. **On the other reading of the same sentence, AC 3 is NOT met.** "Monthly peak
+   held under the soft limit" taken as *the peak itself* fails: the guard pulls
+   August's peak from **5029.8 W to 4107.3 W** (-922.5 W, -18.3 %), which is
+   real money on a Belgian capacity tariff, but 4107.3 W is still over the
+   3500 W soft limit. Both readings are printed by the tool; neither is hidden.
+3. **The guard stops defending the soft limit once the month's peak is set, and
+   that is by design.** `quarter_ceiling_w` uses `CEILING_MONTH_PEAK`: the
+   billed quantity is the month's maximum, so a quarter under an
+   already-recorded peak costs nothing extra and the guard does not spend the
+   battery on it. The month's 32 over-cap quarters fall on four nights
+   (2026-08-17, -18, -20, -21); **31 of them are pulled down** — 7494 W of
+   quarter-average removed in total, 8060 Wh of modelled discharge — but only
+   **3 land under 3500 W**, because by then the ceiling being defended is the
+   running month peak (~4107 W), not the soft limit. The single untouched
+   quarter, 2026-08-18T08:15Z at 4039.7 W, is the same rule seen from the other
+   side: the running peak was already 4833 W, so 4039.7 W added nothing to the
+   bill and the guard correctly stayed out. AC 3's wording asks the guard for
+   something its own tariff logic deliberately does not optimise.
+
+Also worth an eye: **195 blind engagements** over 143,810 cycles — the guard
+acting on a projection it could not fully cover. On the two committed days that
+count was 5. It scales with the gaps above.
+
+## Verification of the exporter
+
+`tools/export_p1_history.py --verify` re-fetches a committed day by the exact
+route used here and diffs it against the file:
+
+    python3 tools/export_p1_history.py \
+        --verify scenarios/p1-net-2026-08-20.jsonl.gz \
+                 scenarios/p1-net-2026-08-23.jsonl.gz
+
+Both days come back **byte-identical after decompression** — 865,024 B /
+15,600 samples and 894,387 B / 16,351 samples — and the copies of those two days
+inside this directory are byte-identical to the committed ones too. The gzip
+CONTAINERS differ by design: a gzip header carries an mtime and a stored
+filename, and this exporter writes mtime 0 so its own output is reproducible,
+where the 2026-08-25 one-off wrote a wall-clock mtime. Content equality is the
+claim; container equality would only assert that two files were written at the
+same second.
+
+`tools/replay_ac3.py` is checked the same way rather than trusted: pointed at
+`scenarios/` it must reproduce `test_peakguard.py` part 6's published totals,
+and `--expect` makes it a hard check.
+
+    python3 tools/replay_ac3.py scenarios --expect 189/190
+
+reproduces 189/190 quarters, the 5029.8 W billed quarter, the 3485.3 W guarded
+result and the 878 Wh of modelled discharge that part 6 prints.

goodwe_controller/scenarios/p1-net-30d-2026-08/manifest.json

@@ -0,0 +1,767 @@
+{
+  "generated": "2026-08-31T08:42:40.614548+00:00",
+  "generator": "tools/export_p1_history.py",
+  "source": "http://192.168.2.158:8123/api/history/period",
+  "entity": "sensor.p1_meter_active_power",
+  "timezone": "Europe/Brussels",
+  "gap_threshold_s": 30.0,
+  "format": "{\"t\": <ISO-8601 UTC>, \"w\": <float watts>} per line, gzip",
+  "days": [
+    {
+      "date": "2026-08-01",
+      "window": [
+        "2026-08-01T00:00:00+02:00",
+        "2026-08-02T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1128060,
+      "attempts": 1,
+      "samples": 16511,
+      "non_numeric_states": [],
+      "first": "2026-07-31T22:00:00+00:00",
+      "last": "2026-08-01T21:59:56.268499+00:00",
+      "gaps": [],
+      "covered_span_s": 86396.3,
+      "mean_cadence_s": 5.233,
+      "file": "p1-net-2026-08-01.jsonl.gz",
+      "bytes_gz": 140531,
+      "bytes_raw": 913203,
+      "sha256_raw": "120de2a0b7eb552281dac4bc1f8fd76d947ba72d1f5b426d9dcdd85ec103bd06",
+      "sha256_gz": "e09bdee349dd3668a073b7fd77974e639c269ec37e73e81a9706cadde083f064"
+    },
+    {
+      "date": "2026-08-02",
+      "window": [
+        "2026-08-02T00:00:00+02:00",
+        "2026-08-03T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1115387,
+      "attempts": 1,
+      "samples": 16303,
+      "non_numeric_states": [],
+      "first": "2026-08-01T22:00:00+00:00",
+      "last": "2026-08-02T21:59:55.191360+00:00",
+      "gaps": [],
+      "covered_span_s": 86395.2,
+      "mean_cadence_s": 5.3,
+      "file": "p1-net-2026-08-02.jsonl.gz",
+      "bytes_gz": 141404,
+      "bytes_raw": 903234,
+      "sha256_raw": "9ab4891c0abf9d621fa528848fc3a874687843804768e8aeab6a88f7bb04b679",
+      "sha256_gz": "94774139b3e19d04bcda3ac5ea988dd4d645e99004f90b917c6b0bf3fbac21cb"
+    },
+    {
+      "date": "2026-08-03",
+      "window": [
+        "2026-08-03T00:00:00+02:00",
+        "2026-08-04T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1123668,
+      "attempts": 1,
+      "samples": 16424,
+      "non_numeric_states": [],
+      "first": "2026-08-02T22:00:00+00:00",
+      "last": "2026-08-03T21:59:55.255808+00:00",
+      "gaps": [],
+      "covered_span_s": 86395.3,
+      "mean_cadence_s": 5.261,
+      "file": "p1-net-2026-08-03.jsonl.gz",
+      "bytes_gz": 144202,
+      "bytes_raw": 909942,
+      "sha256_raw": "13f8dd904a31b5b67fcfde04f6afc49c34c3a9504617278d79d87516fcd6441f",
+      "sha256_gz": "e1bc0cb0e271cbc8d896aee97aa0f5c18e49e78905d1aaf137904a768047c7bc"
+    },
+    {
+      "date": "2026-08-04",
+      "window": [
+        "2026-08-04T00:00:00+02:00",
+        "2026-08-05T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1108582,
+      "attempts": 1,
+      "samples": 16286,
+      "non_numeric_states": [],
+      "first": "2026-08-03T22:00:00+00:00",
+      "last": "2026-08-04T21:59:58.729138+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.7,
+      "mean_cadence_s": 5.305,
+      "file": "p1-net-2026-08-04.jsonl.gz",
+      "bytes_gz": 136505,
+      "bytes_raw": 896650,
+      "sha256_raw": "a65cd9d1ceda61e5a40043edb401c2154feea2b36bd3221710df808d778eabce",
+      "sha256_gz": "c19b19ac890f4caad4140cb27d2fe6f3e972545f664127e5d9f457e711ad8c88"
+    },
+    {
+      "date": "2026-08-05",
+      "window": [
+        "2026-08-05T00:00:00+02:00",
+        "2026-08-06T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1136556,
+      "attempts": 1,
+      "samples": 16655,
+      "non_numeric_states": [],
+      "first": "2026-08-04T22:00:00+00:00",
+      "last": "2026-08-05T21:59:56.189152+00:00",
+      "gaps": [],
+      "covered_span_s": 86396.2,
+      "mean_cadence_s": 5.188,
+      "file": "p1-net-2026-08-05.jsonl.gz",
+      "bytes_gz": 142561,
+      "bytes_raw": 919827,
+      "sha256_raw": "dd327685c6f322bfaa49bc5bf228301e790e5a96fd7c23c487b845e44a962db4",
+      "sha256_gz": "5ff7a1336c49ba38b8058820181dd8ed9c2b8db41b5a3a52412a5a3d8c515332"
+    },
+    {
+      "date": "2026-08-06",
+      "window": [
+        "2026-08-06T00:00:00+02:00",
+        "2026-08-07T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1124419,
+      "attempts": 1,
+      "samples": 16412,
+      "non_numeric_states": [],
+      "first": "2026-08-05T22:00:00+00:00",
+      "last": "2026-08-06T21:59:57.192711+00:00",
+      "gaps": [],
+      "covered_span_s": 86397.2,
+      "mean_cadence_s": 5.265,
+      "file": "p1-net-2026-08-06.jsonl.gz",
+      "bytes_gz": 142313,
+      "bytes_raw": 910849,
+      "sha256_raw": "7cd1fe8315e24dc6391693c49d6306b0c0cf9b6c3a478e457da921001cea930c",
+      "sha256_gz": "9108f169d645b9da07d4ae310666a1365ea07275ff311cd60adad1b702edbf11"
+    },
+    {
+      "date": "2026-08-07",
+      "window": [
+        "2026-08-07T00:00:00+02:00",
+        "2026-08-08T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1087531,
+      "attempts": 1,
+      "samples": 15952,
+      "non_numeric_states": [],
+      "first": "2026-08-06T22:00:00+00:00",
+      "last": "2026-08-07T21:59:58.195053+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.2,
+      "mean_cadence_s": 5.416,
+      "file": "p1-net-2026-08-07.jsonl.gz",
+      "bytes_gz": 135979,
+      "bytes_raw": 879941,
+      "sha256_raw": "e0f67a9214980e2fd4893208cb402165065dadce2105ce1581c6b1d49952f39a",
+      "sha256_gz": "b70b84f3743d1d84055c911bcd5589cb8f0371e8916bde741308c5bb50702c29"
+    },
+    {
+      "date": "2026-08-08",
+      "window": [
+        "2026-08-08T00:00:00+02:00",
+        "2026-08-09T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1058569,
+      "attempts": 1,
+      "samples": 15468,
+      "non_numeric_states": [],
+      "first": "2026-08-07T22:00:00+00:00",
+      "last": "2026-08-08T21:59:52.805887+00:00",
+      "gaps": [],
+      "covered_span_s": 86392.8,
+      "mean_cadence_s": 5.586,
+      "file": "p1-net-2026-08-08.jsonl.gz",
+      "bytes_gz": 134025,
+      "bytes_raw": 857271,
+      "sha256_raw": "0be14ca7593b4c7d68570115cc26e24f6a26ab87fe3c168a8b942b167e8d4f68",
+      "sha256_gz": "d93dcc8ca3eae03af13b9ae36acd5ab1eaa1e7ee93c237d386e8ded1c61f5906"
+    },
+    {
+      "date": "2026-08-09",
+      "window": [
+        "2026-08-09T00:00:00+02:00",
+        "2026-08-10T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1059349,
+      "attempts": 1,
+      "samples": 15508,
+      "non_numeric_states": [],
+      "first": "2026-08-08T22:00:00+00:00",
+      "last": "2026-08-09T21:59:58.178998+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.2,
+      "mean_cadence_s": 5.572,
+      "file": "p1-net-2026-08-09.jsonl.gz",
+      "bytes_gz": 135697,
+      "bytes_raw": 857531,
+      "sha256_raw": "f4793799173c502fcee5f78e2d9b0dcc984b5d2d8bd2fc0db0cd0f8d403733b3",
+      "sha256_gz": "2fea6c5c8b1452d72ad5aa3b0ae9755bb2ea08071514c08b1a3b1155ef457cf1"
+    },
+    {
+      "date": "2026-08-10",
+      "window": [
+        "2026-08-10T00:00:00+02:00",
+        "2026-08-11T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1066721,
+      "attempts": 1,
+      "samples": 15594,
+      "non_numeric_states": [],
+      "first": "2026-08-09T22:00:00+00:00",
+      "last": "2026-08-10T21:59:59.170056+00:00",
+      "gaps": [],
+      "covered_span_s": 86399.2,
+      "mean_cadence_s": 5.541,
+      "file": "p1-net-2026-08-10.jsonl.gz",
+      "bytes_gz": 136682,
+      "bytes_raw": 863785,
+      "sha256_raw": "ff5c3fa419505127a51acc56dfc13e8437e4ec2c13a11c8d8b2d6c3e20e2410e",
+      "sha256_gz": "4fd30e495f4e6d1c8501d05c23f9891ac34364d86a9c55ac825d52b2ebb31023"
+    },
+    {
+      "date": "2026-08-11",
+      "window": [
+        "2026-08-11T00:00:00+02:00",
+        "2026-08-12T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1056281,
+      "attempts": 1,
+      "samples": 15371,
+      "non_numeric_states": [],
+      "first": "2026-08-10T22:00:00+00:00",
+      "last": "2026-08-11T21:59:58.608150+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-11T08:00:14.121653+00:00",
+          "to": "2026-08-11T08:02:54.427007+00:00",
+          "seconds": 160.305
+        },
+        {
+          "from": "2026-08-11T17:04:18.517592+00:00",
+          "to": "2026-08-11T17:08:41.759777+00:00",
+          "seconds": 263.242
+        }
+      ],
+      "covered_span_s": 86398.6,
+      "mean_cadence_s": 5.621,
+      "file": "p1-net-2026-08-11.jsonl.gz",
+      "bytes_gz": 133711,
+      "bytes_raw": 856244,
+      "sha256_raw": "67c2a740019f8908405b96b3436cd953af27baead2957acc7c1dcf10b37ac94e",
+      "sha256_gz": "4f8c553edc9051644bd7baa659f6f92a8b5f5ce12a0410c8b5235d1e6c3084c9"
+    },
+    {
+      "date": "2026-08-12",
+      "window": [
+        "2026-08-12T00:00:00+02:00",
+        "2026-08-13T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1124945,
+      "attempts": 1,
+      "samples": 16432,
+      "non_numeric_states": [],
+      "first": "2026-08-11T22:00:00+00:00",
+      "last": "2026-08-12T21:59:58.648966+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.6,
+      "mean_cadence_s": 5.258,
+      "file": "p1-net-2026-08-12.jsonl.gz",
+      "bytes_gz": 136903,
+      "bytes_raw": 911115,
+      "sha256_raw": "73c8a1626640226ddffb32d564557d1cbe57a15367ea1ba3632934e15a1413dc",
+      "sha256_gz": "acec87065b7de2c605db00504ec5a9b3c99584620dfb3b67194e2cf9464d6a5f"
+    },
+    {
+      "date": "2026-08-13",
+      "window": [
+        "2026-08-13T00:00:00+02:00",
+        "2026-08-14T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1126742,
+      "attempts": 1,
+      "samples": 16473,
+      "non_numeric_states": [],
+      "first": "2026-08-12T22:00:00+00:00",
+      "last": "2026-08-13T21:59:57.562043+00:00",
+      "gaps": [],
+      "covered_span_s": 86397.6,
+      "mean_cadence_s": 5.245,
+      "file": "p1-net-2026-08-13.jsonl.gz",
+      "bytes_gz": 136221,
+      "bytes_raw": 912379,
+      "sha256_raw": "1d9a16c529174bd8c74625a742c46d98de4acf7a045f83df8bdbac22fa86e8e7",
+      "sha256_gz": "adfef36f629decf54c625f2dbfe6b4dab9441218c42557c90ac7f6d331943a59"
+    },
+    {
+      "date": "2026-08-14",
+      "window": [
+        "2026-08-14T00:00:00+02:00",
+        "2026-08-15T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1124413,
+      "attempts": 1,
+      "samples": 16427,
+      "non_numeric_states": [],
+      "first": "2026-08-13T22:00:00+00:00",
+      "last": "2026-08-14T21:59:55.611487+00:00",
+      "gaps": [],
+      "covered_span_s": 86395.6,
+      "mean_cadence_s": 5.26,
+      "file": "p1-net-2026-08-14.jsonl.gz",
+      "bytes_gz": 135570,
+      "bytes_raw": 910648,
+      "sha256_raw": "dc1417881e54fe215e9fcd4ed643d2482a277d61f8f27f25e2ff1e2cba29f7a8",
+      "sha256_gz": "d4eff781cd16a83fd1be9e643fee5bb5d5897e7d45bb9865972a7304d92c84a4"
+    },
+    {
+      "date": "2026-08-15",
+      "window": [
+        "2026-08-15T00:00:00+02:00",
+        "2026-08-16T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1124461,
+      "attempts": 1,
+      "samples": 16516,
+      "non_numeric_states": [],
+      "first": "2026-08-14T22:00:00+00:00",
+      "last": "2026-08-15T21:59:56.581991+00:00",
+      "gaps": [],
+      "covered_span_s": 86396.6,
+      "mean_cadence_s": 5.231,
+      "file": "p1-net-2026-08-15.jsonl.gz",
+      "bytes_gz": 137670,
+      "bytes_raw": 909539,
+      "sha256_raw": "f07a242faed68313512e0363d914846522ff839315ad80b55689072ac74e8a69",
+      "sha256_gz": "082314c6003c2208752acc4614b9809f06735d01e216b935ea94faf578c5598e"
+    },
+    {
+      "date": "2026-08-16",
+      "window": [
+        "2026-08-16T00:00:00+02:00",
+        "2026-08-17T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1127871,
+      "attempts": 1,
+      "samples": 16552,
+      "non_numeric_states": [],
+      "first": "2026-08-15T22:00:00+00:00",
+      "last": "2026-08-16T21:59:59.527710+00:00",
+      "gaps": [],
+      "covered_span_s": 86399.5,
+      "mean_cadence_s": 5.22,
+      "file": "p1-net-2026-08-16.jsonl.gz",
+      "bytes_gz": 138347,
+      "bytes_raw": 912481,
+      "sha256_raw": "a44e5d961600a539ddf824d5d211ef319833666b7598e5939a6cdf2cb1e3581f",
+      "sha256_gz": "8f6511e52f5be9187f422021abc93a5fa8b698b4c785877d69d15dd6de106fd8"
+    },
+    {
+      "date": "2026-08-17",
+      "window": [
+        "2026-08-17T00:00:00+02:00",
+        "2026-08-18T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1133721,
+      "attempts": 1,
+      "samples": 16627,
+      "non_numeric_states": [],
+      "first": "2026-08-16T22:00:00+00:00",
+      "last": "2026-08-17T21:59:59.685699+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-17T17:27:00.599126+00:00",
+          "to": "2026-08-17T17:28:20.389628+00:00",
+          "seconds": 79.791
+        }
+      ],
+      "covered_span_s": 86399.7,
+      "mean_cadence_s": 5.197,
+      "file": "p1-net-2026-08-17.jsonl.gz",
+      "bytes_gz": 140214,
+      "bytes_raw": 917356,
+      "sha256_raw": "70cce79b3732f292f7f58f0b2655bdb4a00a20a6530f1f50dac62ef5f039788b",
+      "sha256_gz": "e2f9b461c4db7902e1a3d30b439ebc11ebcd9618a72d12f10e5131f38fb437bf"
+    },
+    {
+      "date": "2026-08-18",
+      "window": [
+        "2026-08-18T00:00:00+02:00",
+        "2026-08-19T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1074019,
+      "attempts": 1,
+      "samples": 15699,
+      "non_numeric_states": [
+        {
+          "t": "2026-08-18T02:03:54.417106+00:00",
+          "state": "unavailable"
+        },
+        {
+          "t": "2026-08-18T04:10:41.786299+00:00",
+          "state": "unavailable"
+        }
+      ],
+      "first": "2026-08-17T22:00:00+00:00",
+      "last": "2026-08-18T21:59:54.501766+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-18T02:02:59.633845+00:00",
+          "to": "2026-08-18T02:04:38.694366+00:00",
+          "seconds": 99.061
+        },
+        {
+          "from": "2026-08-18T04:09:54.292049+00:00",
+          "to": "2026-08-18T04:11:38.500238+00:00",
+          "seconds": 104.208
+        }
+      ],
+      "covered_span_s": 86394.5,
+      "mean_cadence_s": 5.504,
+      "file": "p1-net-2026-08-18.jsonl.gz",
+      "bytes_gz": 135894,
+      "bytes_raw": 869570,
+      "sha256_raw": "68cd44ac56099ee38f0bba4c32d7d17d33b92d28a99d27419f53c22374491ca6",
+      "sha256_gz": "d6c97508f805aff040d2b4ed4e06c0e7373db2ea6227c7d79ef24c8c79074115"
+    },
+    {
+      "date": "2026-08-19",
+      "window": [
+        "2026-08-19T00:00:00+02:00",
+        "2026-08-20T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 989720,
+      "attempts": 1,
+      "samples": 14549,
+      "non_numeric_states": [],
+      "first": "2026-08-18T22:00:00+00:00",
+      "last": "2026-08-19T21:59:56.556610+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-19T01:33:29.599224+00:00",
+          "to": "2026-08-19T01:34:01.653383+00:00",
+          "seconds": 32.054
+        }
+      ],
+      "covered_span_s": 86396.6,
+      "mean_cadence_s": 5.939,
+      "file": "p1-net-2026-08-19.jsonl.gz",
+      "bytes_gz": 126345,
+      "bytes_raw": 800369,
+      "sha256_raw": "0f11ce0cee43cbd7bdb08dc48b202e58c442157ac08b2cda5b64bbab9bd56300",
+      "sha256_gz": "13d61b7da903877c8ae7813b833cb5836ec04a1cf1efd0e1fa87e916bef95fd5"
+    },
+    {
+      "date": "2026-08-20",
+      "window": [
+        "2026-08-20T00:00:00+02:00",
+        "2026-08-21T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1068038,
+      "attempts": 1,
+      "samples": 15600,
+      "non_numeric_states": [],
+      "first": "2026-08-19T22:00:00+00:00",
+      "last": "2026-08-20T21:59:56.742604+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-20T02:11:56.607373+00:00",
+          "to": "2026-08-20T02:12:38.840458+00:00",
+          "seconds": 42.233
+        },
+        {
+          "from": "2026-08-20T20:42:04.623102+00:00",
+          "to": "2026-08-20T20:43:41.666543+00:00",
+          "seconds": 97.043
+        }
+      ],
+      "covered_span_s": 86396.7,
+      "mean_cadence_s": 5.539,
+      "file": "p1-net-2026-08-20.jsonl.gz",
+      "bytes_gz": 139693,
+      "bytes_raw": 865024,
+      "sha256_raw": "2612153963951dd13fe310ad7fbb5bec2e195db56fd99fd963134c8badae25ba",
+      "sha256_gz": "362f2ee3d9d7f23f9051ba78993c5af7443dabb3b5f16339efc673444720c892"
+    },
+    {
+      "date": "2026-08-21",
+      "window": [
+        "2026-08-21T00:00:00+02:00",
+        "2026-08-22T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1118002,
+      "attempts": 1,
+      "samples": 16383,
+      "non_numeric_states": [],
+      "first": "2026-08-20T22:00:00+00:00",
+      "last": "2026-08-21T21:59:57.771588+00:00",
+      "gaps": [],
+      "covered_span_s": 86397.8,
+      "mean_cadence_s": 5.274,
+      "file": "p1-net-2026-08-21.jsonl.gz",
+      "bytes_gz": 139105,
+      "bytes_raw": 904809,
+      "sha256_raw": "933d9a6899f59c128d0d9b84d6944cea63b1ad58dc57ac52e3e476f9c616f07b",
+      "sha256_gz": "a563581a9a3338af173abb99a200db32881ddaf893d2458f5d8de59b5ec6041f"
+    },
+    {
+      "date": "2026-08-22",
+      "window": [
+        "2026-08-22T00:00:00+02:00",
+        "2026-08-23T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1129094,
+      "attempts": 1,
+      "samples": 16520,
+      "non_numeric_states": [],
+      "first": "2026-08-21T22:00:00+00:00",
+      "last": "2026-08-22T21:59:56.913786+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-21T23:05:20.035692+00:00",
+          "to": "2026-08-21T23:07:51.147719+00:00",
+          "seconds": 151.112
+        },
+        {
+          "from": "2026-08-21T23:07:56.966604+00:00",
+          "to": "2026-08-21T23:08:27.695101+00:00",
+          "seconds": 30.728
+        }
+      ],
+      "covered_span_s": 86396.9,
+      "mean_cadence_s": 5.23,
+      "file": "p1-net-2026-08-22.jsonl.gz",
+      "bytes_gz": 141564,
+      "bytes_raw": 914120,
+      "sha256_raw": "39ccdf67c806344490f791648822cd2cd14d73ea7cc0b6e8572a1e15e8f74641",
+      "sha256_gz": "5c46f1879a723f9986d521124200cab839af2a4722b76bc97c6f6f59d0df65a2"
+    },
+    {
+      "date": "2026-08-23",
+      "window": [
+        "2026-08-23T00:00:00+02:00",
+        "2026-08-24T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1107164,
+      "attempts": 1,
+      "samples": 16351,
+      "non_numeric_states": [],
+      "first": "2026-08-22T22:00:00+00:00",
+      "last": "2026-08-23T21:59:56.921115+00:00",
+      "gaps": [],
+      "covered_span_s": 86396.9,
+      "mean_cadence_s": 5.284,
+      "file": "p1-net-2026-08-23.jsonl.gz",
+      "bytes_gz": 136277,
+      "bytes_raw": 894387,
+      "sha256_raw": "ffb15367bf3c98eff8a5600e4858ac99778b597c03d0a4f6154e6971b8f98a44",
+      "sha256_gz": "3fa76981758a468ba0aa68b50fe68d5bdb1ef38cd7faec2b6ffdb61c9ddb2db2"
+    },
+    {
+      "date": "2026-08-24",
+      "window": [
+        "2026-08-24T00:00:00+02:00",
+        "2026-08-25T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1122175,
+      "attempts": 1,
+      "samples": 16584,
+      "non_numeric_states": [],
+      "first": "2026-08-23T22:00:00+00:00",
+      "last": "2026-08-24T21:59:57.940474+00:00",
+      "gaps": [],
+      "covered_span_s": 86397.9,
+      "mean_cadence_s": 5.21,
+      "file": "p1-net-2026-08-24.jsonl.gz",
+      "bytes_gz": 136834,
+      "bytes_raw": 906369,
+      "sha256_raw": "30465d5ff51220201b4a79341e5da7bfc3d88290465b1c9d886ba94eee8dd234",
+      "sha256_gz": "5103088e047bfcbd9b3f55521f431b01cd27de10c2642e00281a13faa762bdd9"
+    },
+    {
+      "date": "2026-08-25",
+      "window": [
+        "2026-08-25T00:00:00+02:00",
+        "2026-08-26T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1110567,
+      "attempts": 1,
+      "samples": 16451,
+      "non_numeric_states": [
+        {
+          "t": "2026-08-25T01:52:02.104225+00:00",
+          "state": "unavailable"
+        }
+      ],
+      "first": "2026-08-24T22:00:00+00:00",
+      "last": "2026-08-25T21:59:56.883744+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-25T01:51:25.942719+00:00",
+          "to": "2026-08-25T01:52:53.203963+00:00",
+          "seconds": 87.261
+        }
+      ],
+      "covered_span_s": 86396.9,
+      "mean_cadence_s": 5.252,
+      "file": "p1-net-2026-08-25.jsonl.gz",
+      "bytes_gz": 135890,
+      "bytes_raw": 896416,
+      "sha256_raw": "0e7c86b2b74f2108bc7f5f5d2de2627caaafe473ca4ae18515534dff10526e26",
+      "sha256_gz": "2a5411c10d8d3b271f133c62c04bd722279b48b08d7376084fbad6cc6dd66d76"
+    },
+    {
+      "date": "2026-08-26",
+      "window": [
+        "2026-08-26T00:00:00+02:00",
+        "2026-08-27T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1123610,
+      "attempts": 1,
+      "samples": 16542,
+      "non_numeric_states": [],
+      "first": "2026-08-25T22:00:00+00:00",
+      "last": "2026-08-26T21:59:58.915457+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.9,
+      "mean_cadence_s": 5.223,
+      "file": "p1-net-2026-08-26.jsonl.gz",
+      "bytes_gz": 139301,
+      "bytes_raw": 908350,
+      "sha256_raw": "88d72c1b9f51707d62e744f40402de4260a04617875b85c65d2df6079c6c84ca",
+      "sha256_gz": "0661588fbc0c6c42825b67d483c8818c070405c1002424b3f1d61d8fdadb6370"
+    },
+    {
+      "date": "2026-08-27",
+      "window": [
+        "2026-08-27T00:00:00+02:00",
+        "2026-08-28T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1122433,
+      "attempts": 1,
+      "samples": 16573,
+      "non_numeric_states": [],
+      "first": "2026-08-26T22:00:00+00:00",
+      "last": "2026-08-27T21:59:58.538446+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-27T18:50:29.030586+00:00",
+          "to": "2026-08-27T18:52:22.938470+00:00",
+          "seconds": 113.908
+        }
+      ],
+      "covered_span_s": 86398.5,
+      "mean_cadence_s": 5.214,
+      "file": "p1-net-2026-08-27.jsonl.gz",
+      "bytes_gz": 138009,
+      "bytes_raw": 906770,
+      "sha256_raw": "528ab8ee10a46275d2e91d56ef2ed847e5932fae76a1752e6f2e9828dbfa9865",
+      "sha256_gz": "5cacc8c5788f43d6e6e2f569445fa82d9edc5a63b1f082f9a1d6a3bb0b404260"
+    },
+    {
+      "date": "2026-08-28",
+      "window": [
+        "2026-08-28T00:00:00+02:00",
+        "2026-08-29T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1114796,
+      "attempts": 1,
+      "samples": 16456,
+      "non_numeric_states": [],
+      "first": "2026-08-27T22:00:00+00:00",
+      "last": "2026-08-28T21:59:58.515555+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.5,
+      "mean_cadence_s": 5.251,
+      "file": "p1-net-2026-08-28.jsonl.gz",
+      "bytes_gz": 135917,
+      "bytes_raw": 900654,
+      "sha256_raw": "f89838bc9f61af074c17817e4a6eab037318f38fa3c65dad3edfa2106abbc9fb",
+      "sha256_gz": "97090b605f67dcc1f84dea2c51d4832dfe1c2af497a4f4cfe50ecb51024d9b4c"
+    },
+    {
+      "date": "2026-08-29",
+      "window": [
+        "2026-08-29T00:00:00+02:00",
+        "2026-08-30T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1092983,
+      "attempts": 1,
+      "samples": 16132,
+      "non_numeric_states": [],
+      "first": "2026-08-28T22:00:00+00:00",
+      "last": "2026-08-29T21:59:57.574524+00:00",
+      "gaps": [
+        {
+          "from": "2026-08-29T00:03:20.539844+00:00",
+          "to": "2026-08-29T00:03:50.569581+00:00",
+          "seconds": 30.03
+        }
+      ],
+      "covered_span_s": 86397.6,
+      "mean_cadence_s": 5.356,
+      "file": "p1-net-2026-08-29.jsonl.gz",
+      "bytes_gz": 134210,
+      "bytes_raw": 883053,
+      "sha256_raw": "896d4c9d660be4faabc5a088323e246e257877d5ff6bd0ec084b785480d76e12",
+      "sha256_gz": "b6f264cd3afba63209123a27490e7e1c3ae70a86731d7ea05ae67f88917f136f"
+    },
+    {
+      "date": "2026-08-30",
+      "window": [
+        "2026-08-30T00:00:00+02:00",
+        "2026-08-31T00:00:00+02:00"
+      ],
+      "read": "OK",
+      "http_bytes": 1118895,
+      "attempts": 1,
+      "samples": 16490,
+      "non_numeric_states": [],
+      "first": "2026-08-29T22:00:00+00:00",
+      "last": "2026-08-30T21:59:58.533323+00:00",
+      "gaps": [],
+      "covered_span_s": 86398.5,
+      "mean_cadence_s": 5.24,
+      "file": "p1-net-2026-08-30.jsonl.gz",
+      "bytes_gz": 138429,
+      "bytes_raw": 904311,
+      "sha256_raw": "e704818efb58bb6c505791bc9eab2e9476bf48ff8911d0e79b401fd35b529fa0",
+      "sha256_gz": "9052fead2418bff3083bec3ae8ce64d6b9f6224b668f4bb510c79775f66c5b79"
+    }
+  ],
+  "summary": {
+    "days_requested": 30,
+    "days_read": 30,
+    "days_failed": 0,
+    "samples": 485841,
+    "bytes_gz": 4126003,
+    "empty_days": []
+  }
+}

goodwe_controller/test_price.py

@@ -212,6 +212,14 @@ def shipped(key):
         if in_schema or not line.startswith(f"  {key}:"):
             continue
         raw = line.split(":", 1)[1].split("#", 1)[0].strip().strip('"').strip("'")
+        # OPT-04 added the first BOOLEAN price option, and without this the
+        # mirror check would compare the string "false" against `False` and go
+        # red for a file that is perfectly in step. Parsing a bool as a bool is
+        # what the yaml module this image does not carry would have done; it
+        # widens nothing, because a key whose shipped value disagrees with the
+        # mirror still drifts.
+        if raw in ("true", "false"):
+            return raw == "true"
         try:
             return int(raw)
         except ValueError:

goodwe_controller/test_price_forecast.py

@@ -0,0 +1,911 @@
+"""Runnable check for FCST-03 - provisional prices.  `python3 test_price_forecast.py`
+
+WHAT THIS FILE IS DEFENDING, in the order the ticket's acceptance criteria name
+it:
+
+  AC1  Every price point carries a `provisional` flag MATCHING ITS TRUE
+       PROVENANCE - a point filled from yesterday's profile is provisional even
+       when the number happens to be right, a point the feed published keeps
+       whatever flag the feed gave it, and an unmarked carry-forward is not
+       constructible rather than merely discouraged.
+  AC2  An irreversible action gated on a provisional price is REJECTED, with the
+       spec's own example - a maintenance-phase transition - actually refused:
+       the phase machine is still in `idle` afterwards.
+  AC3  Real-time / imbalance prices get MEASURABLY WIDER thresholds. Measured,
+       by finding the smallest spread each regime will accept and comparing the
+       two numbers - not by reading a constant back out of the module that
+       defines it.
+
+THREE RULES THIS FILE HOLDS ITSELF TO, because the reviewer will:
+
+  * EVERY VERDICT IS DERIVED. The carried/published split is re-derived here
+    from the set of hours the fixture published, by different arithmetic than
+    app/price_forecast.py uses; the DST day lengths come from the offset
+    difference rather than from a 23 or a 25 typed into a check; the widening
+    factor is MEASURED by bisecting the accept/refuse boundary and then
+    compared with the declared one.
+
+  * NO STIMULUS IS EVALUATED WHERE THE QUANTITY IT GRADES IS DEGENERATE, and
+    this ticket is full of that trap:
+      - YESTERDAY AND TODAY MUST PRICE EVERY HOUR DIFFERENTLY, or a fill that
+        carried the wrong day forward is invisible. Asserted first, as a check.
+      - THE PROVISIONAL HOURS MUST CONTAIN THE CHEAPEST HOUR, or "arbitrage
+        ignores provisional hours" grades nothing: the firm-only spread and the
+        whole-series spread would be the same number. Asserted before it is
+        used, and it is the realistic shape of the danger - yesterday's cheap
+        hour luring a charge that today's prices do not justify.
+      - THE TWO WIDENING FACTORS MUST DIFFER, or `max`, `sum` and `product` are
+        indistinguishable combination rules. Asserted, then all three are
+        computed and only one matches what the code does.
+      - THE LOCAL-HOUR FILL AND A NAIVE `t - 24 h` FILL MUST DISAGREE on the
+        transition days, or the DST check passes for both implementations.
+        Asserted, then the correct one is graded.
+      - PRICES ARE WRITTEN TO SIX DECIMALS with distinct 3-, 4- and 6-dp
+        roundings, so an implementation that rounds differently is visible.
+        (TARIFF-03's fixtures were 3-dp, where those three are one number.)
+
+  * A FAILED READ IS NOT AN OBSERVATION. A missing price is not a zero price
+    and a stale one is not a fresh one: the gate blocks on `no_data`, blocks on
+    an hour the series does not cover, and blocks on a provisional hour - three
+    different reasons, none of them an answer.
+"""
+
+import ast
+import inspect
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app import price as _price
+from app import price_forecast as _fc
+from app import static_tariff as _st
+from app.maintenance import (
+    CHARGE_TIMEOUT_MIN, DRAIN_TIMEOUT_MIN, DRAIN, IDLE, MaintConfig, Maintenance,
+)
+from app.price import (
+    Absence, PricePoint, PriceProduct, PriceRead, PROVIDERS, Uncertainty,
+    WIDEN_FACTOR, brussels, brussels_offset, plan_is_provisional,
+    required_spread, uncertainty_of, widen_factor,
+)
+from app.price_forecast import (
+    MAINTENANCE_CHARGE, MAINTENANCE_DRAIN, Gate, Irreversible, committed_hours,
+    fill_from_yesterday, price_permits, begin_phase,
+)
+from app.arbitrage import ArbitrageDecision
+from app.static_tariff import Arbitrage, TariffPlan
+
+UTC = timezone.utc
+HERE = os.path.dirname(os.path.abspath(__file__))
+fails = []
+
+
+def check(name, cond):
+    print(f"  {'ok  ' if cond else 'FAIL'} {name}")
+    if not cond:
+        fails.append(name)
+
+
+def raises(fn, exc):
+    """True only if fn() raises EXACTLY `exc`. A different exception is False -
+    'it was refused' and 'it broke on the way to being refused' must not grade
+    the same."""
+    try:
+        fn()
+    except exc:
+        return True
+    except Exception:
+        return False
+    return False
+
+
+class _Raised:
+    def __init__(self, e):
+        self.e = e
+
+    def __eq__(self, other):
+        return False
+
+    def __hash__(self):
+        return id(self)
+
+    def __bool__(self):
+        return False
+
+    def __repr__(self):
+        return f"<raised {type(self.e).__name__}: {self.e}>"
+
+
+def derived(fn):
+    """A value a check grades. An exception becomes `_Raised`, which equals
+    nothing and is falsy - NOT a default."""
+    try:
+        return fn()
+    except Exception as e:                                    # noqa: BLE001
+        return _Raised(e)
+
+
+def near(a, b, tol=1e-9):
+    try:
+        return abs(float(a) - float(b)) <= tol
+    except (TypeError, ValueError):
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures.
+#
+# ⚠️ SIX-DECIMAL PRICES, DELIBERATELY. TARIFF-03's fixtures were 0.3410 /
+# 0.2570, where rounding to 3, 4 and 6 decimals gives the same number - so an
+# implementation that rounded differently from the one being graded survived
+# every check. These are chosen so those three roundings differ.
+# --------------------------------------------------------------------------- #
+
+def y_price(h):
+    """Yesterday's all-in EUR/kWh for local hour h."""
+    return round(0.123437 + 0.010700 * h, 6)
+
+
+def t_price(h):
+    """Today's PUBLISHED all-in EUR/kWh for local hour h. Different from
+    yesterday's at every hour, on purpose - see the degeneracy note above."""
+    return round(0.206562 + 0.009300 * h, 6)
+
+
+def local_midnight(y, m, d) -> datetime:
+    """The UTC instant of Brussels local midnight on that date, derived from
+    `brussels_offset` rather than from a table of dates."""
+    naive = datetime(y, m, d, 0, 0)
+    for hours in (1, 2):
+        guess = naive.replace(tzinfo=UTC) - timedelta(hours=hours)
+        if brussels_offset(guess).utcoffset(None) == timedelta(hours=hours):
+            return guess
+    raise AssertionError(f"no consistent Brussels offset for {naive}")
+
+
+def hours_between(a, b):
+    out, u = [], a
+    while u < b:
+        out.append(u)
+        u += timedelta(hours=1)
+    return out
+
+
+def series_of(instants, price_of, product, provider, *, provisional):
+    return PriceRead.series(
+        [PricePoint(start=brussels(u), eur_per_kwh=price_of(u),
+                    provisional=provisional) for u in instants],
+        product, provider, instants[0])
+
+
+# A plain winter day: local 2026-01-15, 24 hours, no transition in sight.
+D0 = local_midnight(2026, 1, 15)
+D1 = local_midnight(2026, 1, 16)
+YEST0 = local_midnight(2026, 1, 14)
+DAY = hours_between(D0, D1)
+YDAY = hours_between(YEST0, D0)
+
+YESTERDAY = series_of(YDAY, lambda u: y_price(brussels(u).hour),
+                      PriceProduct.DAY_AHEAD, "generic_dayahead",
+                      provisional=False)
+# The feed has published the first 12 hours of today and nothing after - the
+# ordinary state of a dynamic site before the 14-16 h CET print (§5.4).
+PUBLISHED_N = 12
+TODAY_PART = series_of(DAY[:PUBLISHED_N], lambda u: t_price(brussels(u).hour),
+                       PriceProduct.DAY_AHEAD, "generic_dayahead",
+                       provisional=False)
+
+
+print()
+print("0. the fixtures are not degenerate (checked before anything is graded)")
+
+check("yesterday and today price EVERY shared hour differently, so a fill that "
+      "carried the wrong day forward would be visible in the value and not "
+      "only in the flag",
+      all(y_price(h) != t_price(h) for h in range(24)))
+_roundings = derived(lambda: {round(y_price(3), n) for n in (3, 4, 6)})
+check(f"...and a fixture price rounds to three DIFFERENT numbers at 3, 4 and 6 "
+      f"decimals {sorted(_roundings)}, so a divergent rounding cannot hide",
+      len(_roundings) == 3)
+check("...and both widening factors differ, so max / sum / product are three "
+      "distinguishable answers",
+      len(set(WIDEN_FACTOR.values())) == len(WIDEN_FACTOR) >= 2)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("1. AC1 - the flag matches PROVENANCE, and an unmarked fill is not "
+      "constructible")
+
+FILLED = fill_from_yesterday(TODAY_PART, yesterday=YESTERDAY,
+                             since=D0, until=D1, stamp=D0)
+
+_pub_starts = {u for u in DAY[:PUBLISHED_N]}
+_expected_prov = {u: (u not in _pub_starts) for u in DAY}
+_got_prov = derived(lambda: {p.start.astimezone(UTC): p.provisional
+                             for p in FILLED.points})
+check(f"the filled series covers every hour of the day "
+      f"{len(FILLED.points) if FILLED.kind == 'series' else FILLED}",
+      FILLED.kind == "series" and len(FILLED.points) == len(DAY))
+check("...and EVERY point's flag equals what its provenance says it should be, "
+      "re-derived here from the set of hours the fixture published",
+      _got_prov == _expected_prov)
+_carried = derived(lambda: [p for p in FILLED.points if p.provisional])
+check(f"...which is {len(DAY) - PUBLISHED_N} carried hours and {PUBLISHED_N} "
+      f"published ones, counted rather than asserted",
+      len(_carried) == len(DAY) - PUBLISHED_N)
+check("...and the carried hours carry YESTERDAY's number for the same wall "
+      "clock hour, not today's and not a neighbour's",
+      all(near(p.eur_per_kwh, y_price(brussels(p.start).hour))
+          for p in _carried))
+check("...while the published hours carry TODAY's, so the two halves are not "
+      "the same data wearing two flags",
+      all(near(p.eur_per_kwh, t_price(brussels(p.start).hour))
+          for p in FILLED.points if not p.provisional))
+
+# ⚠️ THE COPY IS THE DEFECT. A published point that survives as a COPY is one
+# whose flag could have been rewritten on the way through; identity is the only
+# property that rules that out for every field at once.
+check("a published point is passed through BY IDENTITY - the object the "
+      "provider produced is the object in the filled series",
+      all(any(p is q for q in TODAY_PART.points)
+          for p in FILLED.points if not p.provisional))
+check("...and the canonical §9.3 dict carries the flag out to the wire for "
+      "both kinds",
+      FILLED.canonical()["prices"][0]["provisional"] is False
+      and FILLED.canonical()["prices"][-1]["provisional"] is True)
+check("...and plan_is_provisional() sees the series as provisional overall, "
+      "because at least one hour is",
+      plan_is_provisional(FILLED) is True)
+
+# The audit is a post-condition that RAISES. Feed it the exact defect.
+_stale_copy = PricePoint(start=FILLED.points[-1].start,
+                         eur_per_kwh=FILLED.points[-1].eur_per_kwh,
+                         provisional=False)         # the copy-the-flag bug
+check("the provenance audit REFUSES a carried hour flagged non-provisional - "
+      "the 'stale but plausible' point, which is SAFETY-18's frozen-but-fresh "
+      "meter one layer up",
+      raises(lambda: _fc._audit([_stale_copy], {}), ValueError))
+check("...and refuses a published hour that arrived as a COPY rather than as "
+      "the published object, which is where a flag gets lost",
+      raises(lambda: _fc._audit(
+          [PricePoint(start=TODAY_PART.points[0].start,
+                      eur_per_kwh=TODAY_PART.points[0].eur_per_kwh,
+                      provisional=TODAY_PART.points[0].provisional)],
+          {D0: TODAY_PART.points[0]}), ValueError))
+check("...and never repairs a flag: the audit's only outcomes are silence and "
+      "an exception, so a series it passed was already correct",
+      _fc._audit(list(FILLED.points), {u: TODAY_PART.points[i]
+                                       for i, u in enumerate(DAY[:PUBLISHED_N])})
+      is None)
+
+# ⚠️ A PUBLISHED POINT MAY BE PROVISIONAL. eneco_eddy's current-quarter print
+# is settled after the fact and says so (§9.2). "Published" is not "firm".
+_eddy = series_of(DAY[:2], lambda u: t_price(brussels(u).hour),
+                  PriceProduct.REALTIME, "eneco_eddy", provisional=True)
+_eddy_filled = derived(lambda: fill_from_yesterday(
+    _eddy, yesterday=YESTERDAY, since=D0, until=D1, stamp=D0))
+check("a PUBLISHED point that the feed itself flagged provisional keeps that "
+      "flag - the audit checks provenance, and does not force published hours "
+      "to False",
+      _eddy_filled.kind == "series"
+      and all(p.provisional for p in _eddy_filled.points[:2])
+      and _eddy_filled.points[0] is _eddy.points[0])
+
+# The structural half: the constructor has nothing to pass, and the file is
+# scanned so the pass-through idiom cannot come back looking ordinary.
+check("_carried() has NO `provisional` parameter, so a caller has nothing to "
+      "forget, default, or copy from the point being carried",
+      "provisional" not in inspect.signature(_fc._carried).parameters)
+_SRC = derived(lambda: open(os.path.join(HERE, "app", "price_forecast.py"),
+                            encoding="utf-8").read())
+
+
+def _nonliteral_provisional(src):
+    """Every `PricePoint(...)` in the module whose `provisional` is not a
+    literal. AST, not a substring: the module docstring quotes the defect it
+    exists to prevent, and a text scan would match its own documentation."""
+    out = []
+    for node in ast.walk(ast.parse(src)):
+        if isinstance(node, ast.Call) and \
+                getattr(node.func, "id", None) == "PricePoint":
+            kw = {k.arg: k.value for k in node.keywords}
+            v = kw.get("provisional")
+            if not isinstance(v, ast.Constant):
+                out.append(ast.dump(node)[:80])
+    return out
+
+
+_leaks = derived(lambda: _nonliteral_provisional(_SRC))
+check(f"no PricePoint built in app/price_forecast.py takes its `provisional` "
+      f"from an expression - it is a literal at every construction site, so "
+      f"`provisional=y.provisional` cannot reappear in a later edit {_leaks}",
+      _leaks == [])
+# The scan must be able to fail, or it grades nothing.
+check("...and that scan FAILS on the defect it names, so it is a check and not "
+      "a decoration",
+      _nonliteral_provisional(
+          "PricePoint(start=t, eur_per_kwh=v, provisional=y.provisional)") != [])
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("2. the fill keys on the WALL CLOCK, so the 23- and 25-hour days are right")
+
+for label, (y, m, d) in (("spring forward (23 h)", (2026, 3, 29)),
+                         ("fall back (25 h)", (2026, 10, 25))):
+    a = local_midnight(y, m, d)
+    b = local_midnight(y, m, d + 1)
+    yb = local_midnight(y, m, d - 1)
+    yesterday = series_of(hours_between(yb, a),
+                          lambda u: y_price(brussels(u).hour),
+                          PriceProduct.DAY_AHEAD, "generic_dayahead",
+                          provisional=False)
+    # Nothing published at all yet: the whole day is carried forward.
+    nothing = PriceRead.no_data("the day-ahead print has not landed yet")
+    got = derived(lambda: fill_from_yesterday(nothing, yesterday=yesterday,
+                                              since=a, until=b, stamp=a))
+    # ⚠️ DERIVED FROM THE OFFSETS, not from a 23 or a 25 typed here.
+    off_a = brussels_offset(a).utcoffset(None).total_seconds() / 3600
+    off_b = brussels_offset(b - timedelta(seconds=1)).utcoffset(None) \
+        .total_seconds() / 3600
+    expect = int(24 - (off_b - off_a))
+    check(f"{label}: the day is {expect} hours long, derived from the offset "
+          f"change {off_a:+.0f} -> {off_b:+.0f}, and the fill emits exactly "
+          f"that many",
+          got.kind == "series" and len(got.points) == expect)
+    check(f"{label}: every hour of it is flagged provisional - nothing was "
+          f"published",
+          got.kind == "series" and all(p.provisional for p in got.points))
+    # The discriminating part: a naive `t - 24 h` fill would give a DIFFERENT
+    # answer here, so this check separates the two implementations.
+    y_by_utc = {u: y_price(brussels(u).hour) for u in hours_between(yb, a)}
+    naive = [y_by_utc.get(u - timedelta(hours=24)) for u in hours_between(a, b)]
+    wall = [y_price(brussels(u).hour) for u in hours_between(a, b)]
+    check(f"{label}: the wall-clock fill and a naive t-24h fill DISAGREE, so "
+          f"the check below can tell them apart",
+          naive != wall)
+    check(f"{label}: ...and the emitted values are the WALL-CLOCK ones",
+          got.kind == "series"
+          and [round(p.eur_per_kwh, 6) for p in got.points] == wall)
+
+# The 25-hour day's two 02:00 hours are two distinct instants, both filled.
+_oct = local_midnight(2026, 10, 25)
+_oct_end = local_midnight(2026, 10, 26)
+_oct_fill = fill_from_yesterday(
+    PriceRead.no_data("nothing yet"),
+    yesterday=series_of(hours_between(local_midnight(2026, 10, 24), _oct),
+                        lambda u: y_price(brussels(u).hour),
+                        PriceProduct.DAY_AHEAD, "generic_dayahead",
+                        provisional=False),
+    since=_oct, until=_oct_end, stamp=_oct)
+_twos = [p for p in _oct_fill.points if brussels(p.start).hour == 2]
+check("the 25-hour day has TWO local 02:00 points, at different offsets, and "
+      "both are filled and both are flagged - a 24-slot implementation would "
+      "collide them into one",
+      len(_twos) == 2
+      and _twos[0].start.utcoffset() != _twos[1].start.utcoffset()
+      and all(p.provisional for p in _twos))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("3. §5.4 - a late publication REPLACES a carried hour and re-flags it")
+
+_late = fill_from_yesterday(
+    series_of(DAY, lambda u: t_price(brussels(u).hour),
+              PriceProduct.DAY_AHEAD, "generic_dayahead", provisional=False),
+    yesterday=YESTERDAY, since=D0, until=D1, stamp=D1)
+_h20 = DAY[20]
+_before = derived(lambda: FILLED.at(_h20))
+_after = derived(lambda: _late.at(_h20))
+check("before the print, hour 20 is provisional and carries YESTERDAY's number",
+      _before.provisional is True and near(_before.eur_per_kwh, y_price(20)))
+check("...after it, the same hour is FIRM and carries today's - the flag and "
+      "the number move together, because the series is rebuilt and not patched",
+      _after.provisional is False and near(_after.eur_per_kwh, t_price(20)))
+check("...and the two numbers actually differ, so 'it was replaced' is a "
+      "measurement and not a restatement",
+      not near(_before.eur_per_kwh, _after.eur_per_kwh))
+check("...and re-running the fill over an already-complete series changes "
+      "nothing: it is idempotent",
+      [p.canonical() for p in fill_from_yesterday(
+          _late, yesterday=YESTERDAY, since=D0, until=D1, stamp=D1).points]
+      == [p.canonical() for p in _late.points])
+
+# Nothing to fill from, and nothing published: no_data, never an empty series.
+_nothing = derived(lambda: fill_from_yesterday(
+    PriceRead.no_data("the feed timed out"),
+    yesterday=PriceRead.no_data("and there is no yesterday either"),
+    since=D0, until=D1, stamp=D0))
+check("with neither a published hour nor a yesterday, the result is no_data - "
+      "not an empty series, and not a series of zeros",
+      _nothing.kind == "no_data")
+check("...so it has no .points to iterate and no .get() to default out of",
+      raises(lambda: _nothing.points, Absence)
+      and raises(lambda: _nothing.get("points", []), Absence))
+check("...and its reason names §11.4 for an operator",
+      "§11.4" in _nothing.reason)
+check("a naive `since` is refused rather than silently interpreted as UTC",
+      raises(lambda: fill_from_yesterday(TODAY_PART, yesterday=YESTERDAY,
+                                         since=datetime(2026, 1, 15),
+                                         until=D1, stamp=D0), ValueError))
+check("...and `yesterday` has no default, so a fill with nothing to fill from "
+      "cannot be written by accident",
+      raises(lambda: fill_from_yesterday(TODAY_PART, since=D0, until=D1,
+                                         stamp=D0), TypeError))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("4. AC2 - an irreversible action is REJECTED on a provisional price")
+
+
+class FakeStore:
+    """Same surface as app/store.Store, no disk. Copied from test_maintenance."""
+
+    def __init__(self):
+        self.data = {"phase": IDLE, "phase_started": None,
+                     "last_completed": None, "last_start_attempt": None}
+
+    def set(self, k, v):
+        self.data[k] = v
+
+    def set_time(self, k, when):
+        self.data[k] = when
+
+    def get_time(self, k):
+        return self.data.get(k)
+
+    def save(self):
+        pass
+
+
+def maint():
+    return Maintenance(MaintConfig(enabled=True), FakeStore())
+
+
+check("the drain's commitment window is DERIVED from the phase machine's own "
+      "timeout, so the gate and maintenance.py cannot drift apart",
+      near(MAINTENANCE_DRAIN.commits_h, DRAIN_TIMEOUT_MIN / 60.0)
+      and near(MAINTENANCE_CHARGE.commits_h, CHARGE_TIMEOUT_MIN / 60.0))
+# The shipped `maintenance_start_hour` is 10:00 local, so a drain started on
+# schedule runs into the evening - hours a morning-only day-ahead print has not
+# covered. That is the ticket's scenario and it is where the window is placed.
+START = D0 + timedelta(hours=MaintConfig().start_hour)
+_hours = derived(lambda: committed_hours(START, MAINTENANCE_DRAIN))
+check(f"...and it commits {len(_hours) if not isinstance(_hours, _Raised) else _hours} "
+      f"whole hours, one per hour of the timeout",
+      len(_hours) == int(DRAIN_TIMEOUT_MIN / 60))
+check("an action that commits nothing is not an irreversible one and cannot be "
+      "declared", raises(lambda: Irreversible("X", 0), ValueError)
+      and raises(lambda: Irreversible("", 4), ValueError))
+
+# The stimulus: the first hours are firm, the drain's window reaches into the
+# carried ones. THIS is the ticket's scenario - a cycle started at 10:00 on
+# prices that were published for the morning and guessed for the evening.
+_m = maint()
+_gate_bad = derived(lambda: begin_phase(_m, START, FILLED, MAINTENANCE_DRAIN))
+_first_prov = derived(lambda: next(u for u in _hours if FILLED.at(u).provisional))
+check("the drain's window really does reach past the published hours while "
+      "staying INSIDE the series, so the refusal below is about provenance and "
+      "not about a short series",
+      FILLED.covers(_hours[-1])
+      and any(not FILLED.at(u).provisional for u in _hours)
+      and any(FILLED.at(u).provisional for u in _hours))
+check("a maintenance DRAIN whose window includes a carried-forward hour is "
+      "BLOCKED", _gate_bad.kind == "blocked")
+check("...and the phase machine did not move: it is still idle, so the "
+      "rejection is of the ACTION and not merely of a verdict object",
+      _m.phase == IDLE)
+check("...and the reason names §8.3, the offending hour, and when the real "
+      "price is expected",
+      "§8.3" in _gate_bad.reason
+      and _first_prov.isoformat() in _gate_bad.reason
+      and "14-16" in _gate_bad.reason)
+
+# The positive arm, so the block above is discriminating rather than universal.
+_firm_long = series_of(hours_between(START,
+                                     START + timedelta(hours=len(_hours) + 2)),
+                       lambda u: t_price(brussels(u).hour % 24),
+                       PriceProduct.DAY_AHEAD, "generic_dayahead",
+                       provisional=False)
+_m2 = maint()
+_gate_ok = derived(lambda: begin_phase(_m2, START, _firm_long,
+                                       MAINTENANCE_DRAIN))
+check("...while the SAME transition on a fully published series is PERMITTED, "
+      "and the phase machine actually moves to drain",
+      _gate_ok.kind == "permitted" and _m2.phase == DRAIN)
+check("...and the permitting arm carries the evidence it checked - one firm "
+      "point per committed hour",
+      _gate_ok.kind == "permitted" and len(_gate_ok.hours) == len(_hours)
+      and not any(p.provisional for p in _gate_ok.hours))
+
+# The other two ways a price can fail to be an observation.
+_m3 = maint()
+_gate_none = begin_phase(_m3, START, PriceRead.no_data("the feed timed out"),
+                         MAINTENANCE_DRAIN)
+check("no price data at all BLOCKS an irreversible action too - a missing "
+      "price is not a cheap one (§11.4)",
+      _gate_none.kind == "blocked" and "§11.4" in _gate_none.reason
+      and _m3.phase == IDLE)
+_short = series_of(DAY[:4], lambda u: t_price(brussels(u).hour),
+                   PriceProduct.DAY_AHEAD, "generic_dayahead",
+                   provisional=False)
+_gate_short = price_permits(_short, D0, MAINTENANCE_DRAIN)
+check("...and so does an hour the series does not cover, which is §11.4 for "
+      "that hour rather than a reason to reach for a neighbour",
+      _gate_short.kind == "blocked" and "no price covers" in _gate_short.reason)
+
+# The variant type itself, held to the same shape as PriceRead and Arbitrage.
+check("a BLOCKED gate carries a reason and nothing else: .hours and .action "
+      "raise Absence rather than answering with an empty tuple",
+      raises(lambda: _gate_bad.hours, Absence)
+      and raises(lambda: _gate_bad.action, Absence))
+check("...it is not iterable and has no .get(), the other two routes to an "
+      "empty, harmless-looking loop",
+      raises(lambda: list(_gate_bad), Absence)
+      and raises(lambda: _gate_bad.get("hours", []), Absence))
+check("...match() demands BOTH arms, so the block cannot be fallen through",
+      raises(lambda: _gate_bad.match(permitted=lambda g: 1), TypeError))
+check("...and there is no falsy variant, so `if gate:` cannot look like a "
+      "guard while being none",
+      bool(_gate_bad) is True and bool(_gate_ok) is True)
+# A genuinely carried point - the flagged one, not the mis-flagged copy above.
+_prov_pt = FILLED.points[-1]
+check("the point the two constructor checks below are handed really is "
+      "provisional, or they would be grading nothing",
+      _prov_pt.provisional is True)
+check("a permitted gate cannot be built over a provisional hour or over no "
+      "hours at all - §8.3 is the one rule this type has",
+      raises(lambda: Gate.permit(MAINTENANCE_DRAIN, [_prov_pt]), ValueError)
+      and raises(lambda: Gate.permit(MAINTENANCE_DRAIN, []), ValueError))
+
+# TEST-14, PORTED. A default on any of these constructors reopens the exact
+# hole `_NoData.reason` had - and static_tariff's `_Refused.reason` still has,
+# because nothing scanned it. Scanned by SIGNATURE, so a default added later is
+# red without anyone remembering to write a new case.
+def _defaulted(fn):
+    try:
+        ps = list(inspect.signature(fn).parameters.values())
+    except (TypeError, ValueError) as e:                      # pragma: no cover
+        return _Raised(e)
+    return [q.name for q in ps
+            if q.name != "self" and q.default is not inspect.Parameter.empty]
+
+
+_ctors = {"Gate.permit": Gate.permit, "Gate.block": Gate.block,
+          "Gate.match": Gate.match,
+          "_Permitted.__init__": _fc._Permitted.__init__,
+          "_Blocked.__init__": _fc._Blocked.__init__,
+          # ⚠️ static_tariff's outcome type is scanned HERE because nothing
+          # scanned it before: TEST-14 records `_Refused.reason` gaining a
+          # default as a mutation that survived every check in that file.
+          "Arbitrage.allow": Arbitrage.allow, "Arbitrage.refuse": Arbitrage.refuse,
+          "Arbitrage.match": Arbitrage.match,
+          "_Allowed.__init__": _st._Allowed.__init__,
+          "_Refused.__init__": _st._Refused.__init__,
+          # ⚠️ OPT-04's outcome type is scanned HERE, in the same dict, rather
+          # than by a hand-written case in test_arbitrage.py - which is TEST-14's
+          # actual instruction. A new outcome type extends the SCAN; a
+          # hand-written case is the thing that gets forgotten, and the whole
+          # reason this dict exists instead of five separate checks.
+          "ArbitrageDecision.__init__": ArbitrageDecision.__init__}
+_with_defaults = derived(lambda: {n: d for n, d in
+                                  ((n, _defaulted(f)) for n, f in _ctors.items())
+                                  if d})
+check(f"no constructor or handler of an outcome type - Gate's OR Arbitrage's - "
+      f"carries a DEFAULT, so a verdict can never be built out of nothing "
+      f"{_with_defaults}", _with_defaults == {})
+check("...so a block with no reason is a TypeError at the call site, not a "
+      "blank status line",
+      raises(lambda: Gate.block(), TypeError)
+      and raises(lambda: Gate.block(""), ValueError))
+check("...and the same holds for the refusal FCST-03 added to Arbitrage",
+      raises(lambda: Arbitrage.refuse(), TypeError))
+# ⚠️ ONE CALL PER ROLE, AND THE FIRST DRAFT SHOWED WHY. Passing the provisional
+# point as BOTH `cheapest` and `dearest` is a stimulus that cannot distinguish
+# "the constructor guards the cheapest hour" from "the constructor guards both
+# hours": a guard on either one alone raises, and the check goes green for an
+# implementation that leaves the sell hour unguarded. That is the degeneracy
+# rule this file states at the top, in a new dress - so the two roles are
+# stimulated SEPARATELY, each with a firm point in the other seat.
+_firm_pt = TODAY_PART.points[0]
+check("the two points these constructor checks use really differ in provenance, "
+      "or neither of them grades anything",
+      _prov_pt.provisional is True and _firm_pt.provisional is False)
+check("an ALLOWED arbitrage verdict cannot be constructed with a provisional "
+      "CHEAPEST hour - the buy hour - even directly: §8.3 is enforced at the "
+      "constructor, not only in the ladder above it",
+      raises(lambda: Arbitrage.allow(0.1, _prov_pt, _firm_pt, "normal",
+                                     PriceProduct.DAY_AHEAD, 0.0, frozenset()),
+             ValueError))
+check("...nor with a provisional DEAREST hour - the sell hour - which a guard "
+      "written for `cheapest` alone would have let through",
+      raises(lambda: Arbitrage.allow(0.1, _firm_pt, _prov_pt, "normal",
+                                     PriceProduct.DAY_AHEAD, 0.0, frozenset()),
+             ValueError))
+check("...while two firm points build the verdict perfectly well, so the two "
+      "refusals above are discriminating rather than universal",
+      Arbitrage.allow(0.1, _firm_pt, _firm_pt, "normal",
+                      PriceProduct.DAY_AHEAD, 0.0, frozenset()).kind
+      == "allowed")
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("5. AC3 - real-time thresholds are MEASURABLY wider (measured, not read)")
+
+
+def plan_with_spread(spread, product, provider):
+    """A two-hour series with exactly `spread` between its two prices."""
+    lo, hi = 0.150000, round(0.150000 + spread, 6)
+    pts = [PricePoint(start=brussels(D0), eur_per_kwh=lo, provisional=False),
+           PricePoint(start=brussels(D0 + timedelta(hours=1)),
+                      eur_per_kwh=hi, provisional=False)]
+    return TariffPlan(PriceRead.series(pts, product, provider, D0), None,
+                      "provider")
+
+
+def min_accepted_spread(product, sources, base, provider="generic_dayahead"):
+    """The SMALLEST spread this configuration will trade on, found by bisecting
+    the accept/refuse boundary of the real verdict. Nothing here reads a
+    factor out of the module it is grading."""
+    lo, hi = 0.0, 4.0
+    for _ in range(60):
+        mid = (lo + hi) / 2
+        v = plan_with_spread(mid, product, provider).arbitrage(
+            peak_guard_active=False, min_spread_eur_kwh=base,
+            uncertainty=sources)
+        if v.kind == "allowed":
+            hi = mid
+        else:
+            lo = mid
+    return hi
+
+
+BASE = 0.104000        # a caller's own round-trip cost threshold, EUR/kWh
+_normal = derived(lambda: min_accepted_spread(PriceProduct.DAY_AHEAD,
+                                              frozenset(), BASE))
+_wide = derived(lambda: min_accepted_spread(PriceProduct.REALTIME,
+                                            frozenset(), BASE))
+_weather = derived(lambda: min_accepted_spread(
+    PriceProduct.DAY_AHEAD, frozenset({Uncertainty.NO_WEATHER}), BASE))
+_both = derived(lambda: min_accepted_spread(
+    PriceProduct.REALTIME, frozenset({Uncertainty.NO_WEATHER}), BASE))
+
+check(f"a day-ahead product trades on any spread above its own threshold "
+      f"{_normal:.6f}, which is the base {BASE} it was given",
+      near(_normal, BASE, 1e-6))
+check(f"a REAL-TIME / imbalance product needs {_wide:.6f} - MEASURABLY wider, "
+      f"by a factor of {(_wide / _normal) if _normal else 0:.3f} measured from "
+      f"two verdict boundaries and not read from any constant",
+      _wide > _normal + 1e-6)
+check(f"...and that measured factor equals the declared one for "
+      f"REALTIME_PRODUCT ({WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT]}), so "
+      f"the declaration and the behaviour are the same thing",
+      near(_wide / _normal, WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT], 1e-4))
+check(f"§11.4's no-weather row reaches the SAME widening path by a different "
+      f"trigger, and lands at {_weather:.6f}",
+      near(_weather / _normal, WIDEN_FACTOR[Uncertainty.NO_WEATHER], 1e-4))
+
+# ⚠️ THE COMBINATION RULE, ON A STIMULUS WHERE THE THREE CANDIDATES DIFFER.
+_f1 = WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT]
+_f2 = WIDEN_FACTOR[Uncertainty.NO_WEATHER]
+check(f"with BOTH sources active the threshold is max(f1,f2)={max(_f1, _f2)} x "
+      f"base and NOT the product ({_f1 * _f2}) or the sum ({_f1 + _f2}) - two "
+      f"independent doubts must not compound into a threshold nothing can "
+      f"clear",
+      near(_both / _normal, max(_f1, _f2), 1e-4)
+      and not near(_both / _normal, _f1 * _f2, 1e-3)
+      and not near(_both / _normal, _f1 + _f2, 1e-3))
+
+# The regime must follow the DECLARED product, never the plugin id.
+_wide_named_dayahead = derived(lambda: min_accepted_spread(
+    PriceProduct.REALTIME, frozenset(), BASE, provider="generic_dayahead"))
+_normal_named_eddy = derived(lambda: min_accepted_spread(
+    PriceProduct.DAY_AHEAD, frozenset(), BASE, provider="eneco_eddy"))
+check("the widening follows the DECLARED PriceProduct even when the provider "
+      "is called 'generic_dayahead', and does NOT follow the name "
+      "'eneco_eddy' when the declared product is day-ahead - so a sixth "
+      "supplier is widened by its declaration and not by an id in a list",
+      near(_wide_named_dayahead, _wide, 1e-9)
+      and near(_normal_named_eddy, _normal, 1e-9))
+check("...and the shipped plugin §9.2 names IS the one that declares REALTIME, "
+      "so the mechanism is pointed at the real product",
+      PROVIDERS["eneco_eddy"].capabilities().product is PriceProduct.REALTIME
+      and uncertainty_of(PriceProduct.REALTIME)
+      == frozenset({Uncertainty.REALTIME_PRODUCT})
+      and uncertainty_of(PriceProduct.DAY_AHEAD) == frozenset())
+check("a string in the uncertainty set is REFUSED rather than widening by 1.0 "
+      "and reporting that it widened",
+      raises(lambda: widen_factor({"realtime"}), TypeError)
+      and raises(lambda: required_spread(0.1, {"realtime"}), TypeError))
+check("...and a negative or non-finite base threshold is refused, since it is "
+      "one every spread clears",
+      raises(lambda: required_spread(-0.01, frozenset()), ValueError)
+      and raises(lambda: required_spread(float("nan"), frozenset()), ValueError))
+check("required_spread() with nothing uncertain is the base itself, so the "
+      "widening is additive machinery and not a permanent surcharge",
+      near(required_spread(BASE, frozenset()), BASE))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("6. the refusal ladder - provisional hours are DROPPED, not traded on")
+
+# ⚠️ THE PROVISIONAL HOURS CARRY THE CHEAPEST PRICE. That is the realistic
+# danger (yesterday's cheap night luring a charge) AND the non-degenerate
+# stimulus: the firm-only spread and the whole-series spread differ, so a check
+# on the spread can tell which set was used.
+_cheap_stale = [PricePoint(start=brussels(DAY[i]),
+                           eur_per_kwh=0.041250, provisional=True)
+                for i in range(3)]
+_firm_rest = [PricePoint(start=brussels(DAY[i]),
+                         eur_per_kwh=round(0.212500 + 0.013750 * i, 6),
+                         provisional=False) for i in range(3, 12)]
+_mixed = TariffPlan(PriceRead.series(_cheap_stale + _firm_rest,
+                                     PriceProduct.DAY_AHEAD,
+                                     "generic_dayahead", D0), None, "provider")
+_all_spread = derived(lambda: _mixed.spread_eur_kwh())
+_firm_spread = derived(lambda: round(
+    max(p.eur_per_kwh for p in _firm_rest)
+    - min(p.eur_per_kwh for p in _firm_rest), 6))
+check(f"the fixture is non-degenerate: the whole-series spread "
+      f"{_all_spread:.6f} and the firm-only spread {_firm_spread:.6f} are "
+      f"different numbers, so a verdict can be traced to one of them",
+      not near(_all_spread, _firm_spread, 1e-6))
+_v = derived(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                      min_spread_eur_kwh=0.0,
+                                      uncertainty=frozenset()))
+check("a PART-published series still allows arbitrage - §8.3 forbids acting on "
+      "a provisional price, not trading at all until 16:00",
+      _v.kind == "allowed")
+check(f"...on the FIRM spread {_firm_spread:.6f}, not the one yesterday's "
+      f"carried-forward cheap hour would have invented",
+      near(_v.spread_eur_kwh, _firm_spread, 1e-9))
+check("...and the cheapest and dearest hours it hands an optimiser are both "
+      "PUBLISHED hours - the two points ARE the trade",
+      _v.cheapest.provisional is False and _v.dearest.provisional is False)
+check("...and it reports the threshold it cleared and why, rather than leaving "
+      "OPT-04 to re-derive it from a product enum",
+      near(_v.required_spread_eur_kwh, 0.0) and _v.uncertainty == frozenset())
+
+_all_prov = TariffPlan(PriceRead.series(_cheap_stale, PriceProduct.DAY_AHEAD,
+                                        "generic_dayahead", D0), None,
+                       "fallback")
+_vp = derived(lambda: _all_prov.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=0.0,
+                                          uncertainty=frozenset()))
+check("a WHOLLY provisional series - the §11.4 fallback, or a day before any "
+      "print - is still refused, and the reason counts the firm hours",
+      _vp.kind == "refused" and "0 of 3" in _vp.reason and "§8.3" in _vp.reason)
+check("...and the refusal carries no numbers to trade on",
+      raises(lambda: _vp.spread_eur_kwh, Absence)
+      and raises(lambda: _vp.cheapest, Absence))
+_one_firm = TariffPlan(
+    PriceRead.series(_cheap_stale + _firm_rest[:1], PriceProduct.DAY_AHEAD,
+                     "generic_dayahead", D0), None, "provider")
+check("one firm hour is not enough either: a buy hour and a sell hour must "
+      "BOTH be published before a cycle can be committed",
+      _one_firm.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0,
+                          uncertainty=frozenset()).kind == "refused")
+check("§10.1 still holds above all of it: the peak guard refuses the same "
+      "series that is otherwise allowed",
+      _mixed.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0,
+                       uncertainty=frozenset()).kind == "refused")
+check("the three questions cannot be skipped: all of peak_guard_active, "
+      "min_spread_eur_kwh and uncertainty are required and keyword-only",
+      raises(lambda: _mixed.arbitrage(peak_guard_active=False), TypeError)
+      and raises(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=0.0), TypeError)
+      and raises(lambda: _mixed.arbitrage(False, 0.0, frozenset()), TypeError))
+check("...nor answered with a truthy 'unknown' or a negative threshold",
+      raises(lambda: _mixed.arbitrage(peak_guard_active=None,
+                                      min_spread_eur_kwh=0.0,
+                                      uncertainty=frozenset()), TypeError)
+      and raises(lambda: _mixed.arbitrage(peak_guard_active=False,
+                                          min_spread_eur_kwh=-0.1,
+                                          uncertainty=frozenset()), TypeError))
+
+# The cheap-window flag is the other consumer of provisionality, and it is the
+# one a live install's maintenance charge floor already reads.
+_firm_hour = _firm_rest[0].start
+_prov_hour = _cheap_stale[0].start
+check("the cheap-window flag is decided per HOUR: a provisional hour is never "
+      "cheap, whatever its (stale) number says",
+      _mixed.cheap_now(_prov_hour) is False)
+check("...while a firm hour below the firm mean still is, so carry-forward "
+      "filling does not switch the maintenance charge floor off every morning",
+      _mixed.cheap_now(_firm_hour) is True)
+# ⚠️ GRADED DIRECTLY, BECAUSE ITS CONSUMERS CANNOT GRADE IT. The §11.4 refusal
+# and `cheap_now` both guard provenance independently, so `firm_points()`
+# returning the carried hours TOO still leaves both of them answering correctly
+# - a stimulus that cannot distinguish an over-reporting accessor from a
+# correct one. So the tuple itself is compared with the published points, by
+# identity and in order, rather than only the mean it feeds.
+check("firm_points() returns EXACTLY the published points, in order - not the "
+      "carried ones as well, which its two consumers would have absorbed "
+      "without either of them changing its answer",
+      list(_mixed.firm_points()) == _firm_rest
+      and all(a is b for a, b in zip(_mixed.firm_points(), _firm_rest)))
+check("...and the firm mean it compares against is derived from published "
+      "hours only",
+      near(sum(p.eur_per_kwh for p in _mixed.firm_points())
+           / len(_mixed.firm_points()),
+           sum(p.eur_per_kwh for p in _firm_rest) / len(_firm_rest)))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("7. CFG-03 and validate.py rule 7 - what this ticket did NOT widen")
+
+_defaults = derived(lambda: sorted(_price.PRICE_OPTION_DEFAULTS))
+_cfg = derived(lambda: open(os.path.join(HERE, "config.yaml"),
+                            encoding="utf-8").read())
+# ⚠️ THIS LIST IS A DRIFT PIN, NOT A BAN ON EVER ADDING AN OPTION. FCST-03 added
+# none, and said so here. OPT-04 added FOUR - and added them to this ONE dict
+# and to config.yaml, which is precisely the behaviour CFG-03 asks for: the
+# alternative is a fourth freehand copy in main.py's `o.get(k, X)` fallbacks.
+# The pin is what makes such an addition a decision somebody signs rather than a
+# thing that appears; whoever adds the fifth comes here and says which card and
+# why, as this line does.
+_OPT04_KEYS = ["arbitrage_enabled", "cycle_cost_threshold_eur",
+               "arbitrage_soc_floor", "arbitrage_soc_ceiling"]
+check(f"the in-code mirror holds exactly TARIFF-02's, TARIFF-03's and OPT-04's "
+      f"keys - FCST-03 still added none of its own {_defaults}",
+      _defaults == sorted(["price_provider", "price_markup_eur_kwh",
+                           "price_taxes_eur_kwh", "export_price_eur_kwh",
+                           "price_csv_path", "price_feed_url",
+                           "price_horizon_h", "price_timeout_s",
+                           "static_profile"] + _OPT04_KEYS))
+# ...and the four are genuinely NEW, not a rename of something that was already
+# there, or the line above would pass while the mirror silently lost a key.
+check("...and OPT-04's four keys are additions rather than replacements: the "
+      "nine TARIFF-02/03 keys are all still present",
+      isinstance(_defaults, list)
+      and len(set(_defaults) - set(_OPT04_KEYS)) == 9)
+check("...and every one of them is still in config.yaml, which stays the "
+      "source of truth",
+      isinstance(_cfg, str)
+      and all(f"\n  {k}:" in _cfg for k in _price.PRICE_OPTION_DEFAULTS))
+
+
+def _names(path):
+    try:
+        tree = ast.parse(open(path, encoding="utf-8").read())
+    except (OSError, SyntaxError):                            # pragma: no cover
+        return set()
+    out = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.ImportFrom):
+            out |= {a.name for a in node.names}
+        if isinstance(node, ast.Name):
+            out.add(node.id)
+        if isinstance(node, ast.Attribute):
+            out.add(node.attr)
+    return out
+
+
+_FC = os.path.join(HERE, "app", "price_forecast.py")
+_used = derived(lambda: _names(_FC))
+check("app/price_forecast.py reads NO options at all - it takes a PriceRead "
+      "and instants, so there is no fourth place for an option default to live",
+      isinstance(_used, set)
+      and not ({"price_option", "PRICE_OPTION_DEFAULTS", "PluginOptions"}
+               & _used))
+# ⚠️ RULE 7'S TRIPWIRE, RESPECTED RATHER THAN TRIPPED. test_price.py section 12
+# pins the set of modules that consume `load_prices()` to exactly
+# ["static_tariff.py"], and goes red when a second one appears. This module
+# deliberately does NOT fetch: it transforms a read somebody else obtained, so
+# rule 7's message about what a configured provider does or does not drive is
+# unchanged by this ticket and needed no rewording.
+check("...and it does not consume load_prices(), so validate.py rule 7's "
+      "pinned consumer list is still true and its wording still accurate",
+      "load_prices" not in _used)
+
+
+print()
+print("FAILED" if fails else "OK")
+for f in fails:
+    print("  -", f)
+sys.exit(1 if fails else 0)

goodwe_controller/test_static_tariff.py

@@ -306,8 +306,8 @@ check(f"...while the two-period spread is the day/night difference "
       f"{_spread_two}, re-derived here as {DAY_P - NIGHT_P:.4f}",
       near(_spread_two, DAY_P - NIGHT_P, 1e-9))
 
-_v_fixed = p_fixed.arbitrage(peak_guard_active=False)
-_v_two = p_two.arbitrage(peak_guard_active=False)
+_v_fixed = p_fixed.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset())
+_v_two = p_two.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset())
 check("a fully-fixed tariff REFUSES arbitrage", _v_fixed.kind == "refused")
 check("...for the true reason - the series is flat, so there is nothing to buy "
       "low and sell high, not because a FIXED enum was matched on",
@@ -327,7 +327,7 @@ _flat_dayahead = TariffPlan(
     None, "provider")
 check("a DAY_AHEAD series that happens to be flat is refused too, so the rule "
       "is arithmetic and not a product label",
-      _flat_dayahead.arbitrage(peak_guard_active=False).kind == "refused")
+      _flat_dayahead.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused")
 
 # The numbers an optimiser needs exist ONLY on the permitting variant.
 check("the allowed verdict carries the spread, the cheapest hour and the "
@@ -352,9 +352,9 @@ check("...and there is no falsy variant, so `if verdict:` cannot look like a "
 # §10.1 priority 2 over priority 3, expressed so OPT-04 cannot skip it.
 check("peak shaving outranks arbitrage: the SAME allowed plan is refused when "
       "the peak guard is holding",
-      p_two.arbitrage(peak_guard_active=True).kind == "refused")
+      p_two.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused")
 check("...and the reason names the ordering rather than the tariff",
-      "priority 2" in p_two.arbitrage(peak_guard_active=True).reason)
+      "priority 2" in p_two.arbitrage(peak_guard_active=True, min_spread_eur_kwh=0.0, uncertainty=frozenset()).reason)
 check("...and the question cannot be skipped: peak_guard_active is required "
       "and keyword-only, so a spread is not obtainable without answering it",
       raises(lambda: p_two.arbitrage(), TypeError)
@@ -497,7 +497,7 @@ check("...and its underlying read has no .points at all, so `min(read.points)` "
       "cannot run against it",
       raises(lambda: _none.read.points, Absence))
 check("...and arbitrage is refused, per §11.4",
-      _none.arbitrage(peak_guard_active=False).kind == "refused"
+      _none.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused"
       and arbitrage_allowed(_none.read) is False)
 check("...and static_status() says so in words rather than reporting a price",
       static_status(opts(None), THU) == (False, "no static profile"))
@@ -746,12 +746,12 @@ check("...marked PROVISIONAL, which is the one flag that differs",
       _fb.provisional and plan_is_provisional(_fb.read))
 check("...and arbitrage is refused on it, per §11.4, even though a full series "
       "exists and has a real spread",
-      _fb.arbitrage(peak_guard_active=False).kind == "refused"
+      _fb.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "refused"
       and near(_fb.spread_eur_kwh(), DAY_P - NIGHT_P))
 check("...while the SAME profile as the configured product allows it - so the "
       "refusal is about provisionality and not about the profile",
       static_plan(opts(TWO_PERIOD), THU, THU + timedelta(days=1)
-                  ).arbitrage(peak_guard_active=False).kind == "allowed")
+                  ).arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "allowed")
 check("...and the provisional plan has no cheap window either: §8.3 forbids an "
       "irreversible action on a provisional price, and a grid top-up is one",
       not any(_fb.cheap_now(at_local(THU, h)) for h in range(24)))
@@ -779,8 +779,8 @@ check("a live feed is used in preference to the static profile",
       and _live_plan.product is PriceProduct.DAY_AHEAD)
 check("...and arbitrage is allowed on it, with the spread derived from the "
       "feed rather than from the profile",
-      _live_plan.arbitrage(peak_guard_active=False).kind == "allowed"
-      and near(_live_plan.arbitrage(peak_guard_active=False).spread_eur_kwh,
+      _live_plan.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).kind == "allowed"
+      and near(_live_plan.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0, uncertainty=frozenset()).spread_eur_kwh,
                0.023, 1e-9))
 
 

goodwe_controller/test_tariff.py

@@ -35,16 +35,39 @@ NOT allowed to be tested at:
  10. THE WIRING, through the real `Controller` and its real status page.
 
 ------------------------------------------------------------------------------
-⚠️ AC 3 IS NOT MET, AND PART 9 DOES NOT PRETEND OTHERWISE.
+⚠️ PART 9 IS A TWO-DAY MEASUREMENT AND SAYS SO. THE 30-DAY ANSWER IS ELSEWHERE
+(DATA-01), AND IT DOES NOT LAND WHERE ANYONE EXPECTED.
 
 AC 3 asks for "the monthly peak held under the soft limit in >= 95 % of
-intervals over a 30-day simulation replay". THERE IS NO 30-DAY DATASET. The
-infra repo's `sim/scenarios/` holds exactly two days of this house's real meter
-- 2026-08-20 (the Illusmart failure day) and 2026-08-23 (the healthy reference)
-- exported on 2026-08-25 because they were about to age out of HA's recorder,
-and nothing longer was ever captured. `sim/scenarios/README.md` lists the whole
-inventory; the rest is RS485 bus frames, OTA witness logs and a 578-row rollback
-poll, none of which carries grid power over calendar time.
+intervals over a 30-day simulation replay". When this file was written there
+were two days of this house's real meter - 2026-08-20 (the Illusmart failure
+day) and 2026-08-23 (the healthy reference) - exported on 2026-08-25 because
+they were about to age out of HA's recorder.
+
+⚠️ AND THE SENTENCE THAT USED TO STAND HERE, "nothing longer was ever
+captured", WAS TRUE ABOUT THE PAST AND WAS READ AS A CLAIM ABOUT THE FUTURE.
+It was not one. HA's recorder still held the whole month; DATA-01 probed it on
+2026-08-31 (230 samples in a 20-minute window at 30 days back, 0 at 45) and
+exported thirty days the same day, into `scenarios/p1-net-30d-2026-08/` with
+`tools/export_p1_history.py` - which is committed now precisely because the
+2026-08-25 one-off was not, and its absence is what let the belief survive.
+
+Over those thirty days the criterion measures 98.89 % UNCONTROLLED and 98.99 %
+guarded, so it is met - and that is a finding about the CRITERION as much as
+about the guard, because a month with no controller at all passes it. Read the
+other way - the monthly PEAK itself under the soft limit - it is not met: the
+guard takes August's peak from 5029.8 W to 4107.3 W, still over 3500 W. Both
+numbers, and why they part company, are in
+`scenarios/p1-net-30d-2026-08/README.md`.
+
+PART 9 IS DELIBERATELY LEFT GRADING THE TWO COMMITTED DAYS. It is a per-PR
+regression check and the thirty days cost about fifty seconds of replay; they
+also live one directory down precisely so this file's glob does not pick them
+up. `tools/replay_ac3.py` is the thing that runs the month, and it is checked
+against part 6 of test_peakguard.py rather than trusted:
+
+    python3 tools/replay_ac3.py scenarios --expect 189/190
+    python3 tools/replay_ac3.py scenarios/p1-net-30d-2026-08
 
 So part 9 replays the two days that exist, reports the percentage over them, and
 states the sample size in days next to it. It is a MEASUREMENT, not a verdict:
@@ -60,8 +83,8 @@ export) for the reason `scenarios/p1-age-2026-08-26.jsonl.gz` already is: the
 infra repo is private, CI's token is minted for this repository only, and a
 regression fixture that CI cannot see is not a regression fixture.
 
-Closing AC 3 needs 30 days of capture. That is TEST-01's replay harness, and it
-cannot start before somebody starts recording.
+The recorder's window rolls: 2026-08-01 leaves it around 2026-09-15, which is
+why the committed copy is the artefact and not the API call.
 """
 
 import asyncio
@@ -748,9 +771,11 @@ print()
 print(f"    AC 3 MEASURED: {under}/{total_q} quarters = {PCT:.1f} % under the "
       f"{SHIPPED_CAP_W:.0f} W soft limit, over {replay_days:.1f} DAYS of "
       f"replay, UNCONTROLLED (no peak shaving was running on either day).")
-print(f"    AC 3 ASKS FOR 30 DAYS. {replay_days:.1f} days exist. "
-      f"AC 3 IS NOT MET and this run does not claim it is - see the module "
-      f"docstring. The figure above is the BASELINE SAFETY-07 has to improve.")
+print(f"    AC 3 ASKS FOR 30 DAYS and this run is {replay_days:.1f}, so it "
+      f"does not settle it either way. The 30 days DO now exist - "
+      f"scenarios/p1-net-30d-2026-08/, DATA-01 - and "
+      f"tools/replay_ac3.py is what runs them; the figure above is the "
+      f"BASELINE SAFETY-07 has to improve, on the two days CI replays.")
 check("the replay produced a measurable number over a stated sample size, "
       "rather than a criterion quietly redefined to fit the data",
       total_q > 100 and replay_days < 30)

goodwe_controller/tools/export_p1_history.py

@@ -0,0 +1,455 @@
+#!/usr/bin/env python3
+"""Export a P1 power signal out of Home Assistant's recorder into the committed
+scenario format - one gzipped JSON object per line, one file per LOCAL day.
+
+WHY THIS FILE EXISTS AT ALL
+===========================
+`scenarios/p1-net-2026-08-20.jsonl.gz` and `p1-net-2026-08-23.jsonl.gz` were
+produced once, by hand, and the script was thrown away. The consequence was not
+theoretical: TARIFF-01's and SAFETY-07's AC 3 ("monthly peak held under the soft
+limit in >= 95 % of intervals over a 30-day simulation replay") were both merged
+UNMET on the belief that thirty days could not be produced retroactively - a
+belief that was simply wrong, and that survived because nobody could re-run the
+export to find out. So the export is a committed, runnable artefact now, and the
+next person does not have to re-derive it under time pressure while a retention
+window rolls.
+
+    python3 tools/export_p1_history.py --days 30 --out-dir /some/where
+
+THE TWO RULES THIS FILE IS BUILT AROUND
+=======================================
+1. A FAILED READ IS NOT AN OBSERVATION. An HTTP error, a timeout, a truncated
+   body, a non-JSON body - none of those are "the meter reported nothing that
+   hour". They are "we do not know what the meter reported that hour", and the
+   two must never end up looking the same in the output. So:
+
+     * every request is retried with backoff;
+     * a day whose read ultimately fails writes NO FILE and is recorded in the
+       manifest as `"read": "FAILED"` with the error text, and the process exits
+       non-zero;
+     * a day that reads back successfully but EMPTY writes an empty file and is
+       recorded as `"read": "OK", "samples": 0`. Empty-and-known and
+       unknown are therefore distinguishable both in the manifest and by the
+       presence or absence of the file;
+     * before any day is fetched, the entity is proved to exist through
+       /api/states/<entity>. Without that check a typo in --entity would return
+       200 + `[]` for all thirty days and produce a beautifully consistent
+       dataset of nothing.
+
+2. GAPS ARE VISIBLE, NEVER INTERPOLATED. Nothing here carries a value forward,
+   fills, resamples or averages. A recorder outage or an HA restart shows up as
+   what it is: consecutive `t` values further apart than the meter's cadence.
+   The controller's own ingest already reads that correctly - `meter_max_age_s`
+   (30 s shipped) is exactly the age past which a held reading stops counting as
+   coverage - so an hour with no telegrams replays as an hour of NO COVERAGE
+   rather than as an hour of whatever the last sample said. The manifest lists
+   every gap over --gap-s so a reader does not have to diff timestamps to find
+   them.
+
+DAY AT A TIME, AND WHY NOT SMALLER
+==================================
+One request per local day. That is gentle on a live HA (~1 MB of JSON per day)
+and it is also the only chunking that reproduces the committed files: the
+history API prepends the state as it stood AT the period start
+(`include_start_time_state`), stamped with the start instant. Splitting a day
+into six-hour chunks would therefore inject three synthetic boundary samples per
+day that no meter ever sent. Days are the natural boundary because the committed
+files are local days.
+
+VERIFYING THE EXPORTER
+======================
+    python3 tools/export_p1_history.py --verify scenarios/p1-net-2026-08-20.jsonl.gz
+
+re-fetches that day by this exact route and compares the DECOMPRESSED bytes with
+the committed file. Byte equality of the .gz containers is not expected and not
+required: a gzip header carries an mtime, and this file writes mtime 0 so its
+own output is reproducible. Content equality is the claim that matters.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import hashlib
+import json
+import sys
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+try:                                    # py3.9+; the add-on image has it
+    from zoneinfo import ZoneInfo
+except ImportError:                     # pragma: no cover
+    ZoneInfo = None                     # type: ignore
+
+DEFAULT_URL = "http://192.168.2.158:8123"
+DEFAULT_ENTITY = "sensor.p1_meter_active_power"
+DEFAULT_TZ = "Europe/Brussels"
+# The shipped meter_max_age_s. A hole longer than this is a hole the controller
+# itself would refuse to see through, which makes it the honest gap threshold.
+DEFAULT_GAP_S = 30.0
+
+
+class ReadFailed(RuntimeError):
+    """The read did not happen. NOT the same thing as an empty result."""
+
+
+# ---------------------------------------------------------------------------
+# transport
+
+
+def _get(url: str, token: str, timeout: float):
+    req = urllib.request.Request(url, headers={
+        "Authorization": f"Bearer {token}",
+        "Content-Type": "application/json",
+    })
+    with urllib.request.urlopen(req, timeout=timeout) as resp:
+        if resp.status != 200:
+            raise ReadFailed(f"HTTP {resp.status}")
+        return resp.read()
+
+
+def fetch_json(url: str, token: str, *, timeout: float, retries: int,
+               backoff: float, log=print):
+    """GET and parse, or raise ReadFailed. Never returns a partial answer."""
+    last = None
+    for attempt in range(1, retries + 1):
+        try:
+            raw = _get(url, token, timeout)
+        except urllib.error.HTTPError as exc:
+            last = f"HTTP {exc.code} {exc.reason}"
+        except Exception as exc:                     # URLError, timeout, ...
+            last = f"{type(exc).__name__}: {exc}"
+        else:
+            try:
+                return json.loads(raw.decode("utf-8")), len(raw), attempt
+            except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                # A truncated body looks exactly like this. It is a failure.
+                last = f"unparseable body ({len(raw)} bytes): {exc}"
+        if attempt < retries:
+            wait = backoff * attempt
+            log(f"      read failed ({last}); retry {attempt + 1}/{retries} "
+                f"in {wait:.0f} s")
+            time.sleep(wait)
+    raise ReadFailed(last or "unknown")
+
+
+def assert_entity_exists(base: str, entity: str, token: str, *, timeout: float,
+                         retries: int, backoff: float, log=print):
+    """Prove the entity is real BEFORE trusting any empty day.
+
+    Without this, `--entity sensor.typo` answers 200 + [] for every day and the
+    exporter cheerfully writes thirty empty files.
+    """
+    url = f"{base}/api/states/{urllib.parse.quote(entity)}"
+    doc, _, _ = fetch_json(url, token, timeout=timeout, retries=retries,
+                           backoff=backoff, log=log)
+    if not isinstance(doc, dict) or doc.get("entity_id") != entity:
+        raise ReadFailed(f"{entity} is not a known entity")
+    return doc
+
+
+# ---------------------------------------------------------------------------
+# one day
+
+
+def day_bounds(day: datetime, tz):
+    start = datetime(day.year, day.month, day.day, tzinfo=tz)
+    return start, start + timedelta(days=1)
+
+
+def history_url(base: str, entity: str, start: datetime, end: datetime) -> str:
+    q = urllib.parse.urlencode({
+        "filter_entity_id": entity,
+        "end_time": end.isoformat(),
+        "minimal_response": "",
+    })
+    return (f"{base}/api/history/period/"
+            f"{urllib.parse.quote(start.isoformat())}?{q}")
+
+
+def rows_from(doc, entity: str):
+    """HA's shape -> [(iso_t, state_str)], plus the states that are not numbers.
+
+    `minimal_response` returns the first record in full and the rest as
+    {state, last_changed}. An entity that went unavailable reports the string
+    "unavailable" (or "unknown") where a number belongs. Those are dropped from
+    the numeric series - there is no float to write and the committed schema has
+    no slot for a non-number - but every one is returned here so it lands in the
+    manifest. Dropping them is what MAKES the outage visible: the series simply
+    has no samples across it, which is the same thing the meter falling silent
+    looks like, and is what the controller's freshness rule already handles.
+    """
+    if not isinstance(doc, list):
+        raise ReadFailed(f"expected a list, got {type(doc).__name__}")
+    if not doc:
+        return [], []
+    series = doc[0]
+    if not isinstance(series, list):
+        raise ReadFailed("history series is not a list")
+    good, bad = [], []
+    for rec in series:
+        eid = rec.get("entity_id")
+        if eid is not None and eid != entity:
+            raise ReadFailed(f"unexpected entity {eid!r} in the response")
+        t = rec.get("last_changed") or rec.get("last_updated")
+        s = rec.get("state")
+        if t is None:
+            raise ReadFailed("a record carries no timestamp")
+        try:
+            w = float(s)
+        except (TypeError, ValueError):
+            bad.append({"t": t, "state": s})
+            continue
+        good.append((t, w))
+    return good, bad
+
+
+def render(rows, *, newline: str) -> bytes:
+    """The committed format, exactly: `{"t": <iso>, "w": <float>}` per line.
+
+    json.dumps' default separators (", " / ": ") and repr of a float are what
+    the two committed files contain; so is the CRLF, an artefact of the original
+    one-off having been run on Windows in text mode. It is reproduced rather
+    than tidied because reproducing the committed bytes is this exporter's
+    verification, and gzip.open(..., 'rt') strips it either way.
+    """
+    out = bytearray()
+    for t, w in rows:
+        out += json.dumps({"t": t, "w": w}).encode("utf-8")
+        out += newline.encode("ascii")
+    return bytes(out)
+
+
+def gz(payload: bytes) -> bytes:
+    """gzip level 9, mtime 0 - so the same input always gives the same bytes."""
+    import io
+    buf = io.BytesIO()
+    with gzip.GzipFile(fileobj=buf, mode="wb", compresslevel=9, mtime=0) as f:
+        f.write(payload)
+    return buf.getvalue()
+
+
+def gaps_in(rows, gap_s: float):
+    out = []
+    prev = None
+    for t, _ in rows:
+        cur = datetime.fromisoformat(t)
+        if prev is not None:
+            d = (cur - prev).total_seconds()
+            if d > gap_s:
+                out.append({"from": prev.isoformat(), "to": cur.isoformat(),
+                            "seconds": round(d, 3)})
+        prev = cur
+    return out
+
+
+def export_day(base, entity, token, day, tz, *, timeout, retries, backoff,
+               gap_s, newline, log=print):
+    """Read one local day. Raises ReadFailed rather than returning a guess."""
+    start, end = day_bounds(day, tz)
+    doc, nbytes, attempts = fetch_json(
+        history_url(base, entity, start, end), token,
+        timeout=timeout, retries=retries, backoff=backoff, log=log)
+    rows, bad = rows_from(doc, entity)
+    entry = {
+        "date": day.date().isoformat(),
+        "window": [start.isoformat(), end.isoformat()],
+        "read": "OK",
+        "http_bytes": nbytes,
+        "attempts": attempts,
+        "samples": len(rows),
+        "non_numeric_states": bad,
+        "first": rows[0][0] if rows else None,
+        "last": rows[-1][0] if rows else None,
+        "gaps": gaps_in(rows, gap_s),
+    }
+    if rows:
+        span = (datetime.fromisoformat(rows[-1][0])
+                - datetime.fromisoformat(rows[0][0])).total_seconds()
+        entry["covered_span_s"] = round(span, 1)
+        entry["mean_cadence_s"] = round(span / max(1, len(rows) - 1), 3)
+    return rows, entry
+
+
+# ---------------------------------------------------------------------------
+# modes
+
+
+def do_export(args, token, tz, log=print):
+    base = args.url.rstrip("/")
+    out_dir = Path(args.out_dir)
+    out_dir.mkdir(parents=True, exist_ok=True)
+    newline = "\r\n" if args.newline == "crlf" else "\n"
+
+    log(f"    proving {args.entity} exists before trusting any empty day")
+    st = assert_entity_exists(base, args.entity, token, timeout=args.timeout,
+                              retries=args.retries, backoff=args.backoff,
+                              log=log)
+    log(f"      {args.entity} = {st.get('state')} "
+        f"{st.get('attributes', {}).get('unit_of_measurement', '')}")
+
+    if args.end_date:
+        last = datetime.fromisoformat(args.end_date).replace(tzinfo=tz)
+    else:                                # yesterday: today is still being logged
+        last = datetime.now(tz).replace(hour=0, minute=0, second=0,
+                                        microsecond=0) - timedelta(days=1)
+    days = [last - timedelta(days=i) for i in range(args.days - 1, -1, -1)]
+
+    manifest = {
+        "generated": datetime.now(timezone.utc).isoformat(),
+        "generator": "tools/export_p1_history.py",
+        "source": f"{base}/api/history/period",
+        "entity": args.entity,
+        "timezone": args.tz,
+        "gap_threshold_s": args.gap_s,
+        "format": '{"t": <ISO-8601 UTC>, "w": <float watts>} per line, gzip',
+        "days": [],
+    }
+    failures = []
+    for day in days:
+        name = f"{args.prefix}{day.date().isoformat()}.jsonl.gz"
+        log(f"    {name}")
+        try:
+            rows, entry = export_day(
+                base, args.entity, token, day, tz, timeout=args.timeout,
+                retries=args.retries, backoff=args.backoff, gap_s=args.gap_s,
+                newline=newline, log=log)
+        except ReadFailed as exc:
+            # NO FILE. A missing file is the honest record of a read that did
+            # not happen; an empty one would claim the meter was silent.
+            entry = {"date": day.date().isoformat(), "read": "FAILED",
+                     "error": str(exc), "file": None}
+            manifest["days"].append(entry)
+            failures.append(entry)
+            log(f"      READ FAILED: {exc} - no file written")
+            continue
+        payload = render(rows, newline=newline)
+        blob = gz(payload)
+        (out_dir / name).write_bytes(blob)
+        entry["file"] = name
+        entry["bytes_gz"] = len(blob)
+        entry["bytes_raw"] = len(payload)
+        entry["sha256_raw"] = hashlib.sha256(payload).hexdigest()
+        entry["sha256_gz"] = hashlib.sha256(blob).hexdigest()
+        manifest["days"].append(entry)
+        ng = len(entry.get("gaps", []))
+        log(f"      {entry['samples']} samples, {len(blob)} B gz, "
+            f"{ng} gap(s) over {args.gap_s:g} s"
+            + (f", {len(entry['non_numeric_states'])} non-numeric state(s)"
+               if entry["non_numeric_states"] else ""))
+        if day is not days[-1]:
+            time.sleep(args.delay)
+
+    ok = [d for d in manifest["days"] if d["read"] == "OK"]
+    manifest["summary"] = {
+        "days_requested": len(days),
+        "days_read": len(ok),
+        "days_failed": len(failures),
+        "samples": sum(d["samples"] for d in ok),
+        "bytes_gz": sum(d["bytes_gz"] for d in ok),
+        "empty_days": [d["date"] for d in ok if d["samples"] == 0],
+    }
+    # newline="\n" explicitly: write_text() on Windows emits CRLF, and
+    # the manifest would then differ from a Linux run of the same export
+    # for no reason visible in a diff.
+    with open(args.manifest or (out_dir / "manifest.json"), "w",
+              encoding="utf-8", newline="\n") as fh:
+        fh.write(json.dumps(manifest, indent=2) + "\n")
+    log(f"    {manifest['summary']['days_read']}/{len(days)} days, "
+        f"{manifest['summary']['samples']} samples, "
+        f"{manifest['summary']['bytes_gz'] / 1e6:.2f} MB gz")
+    if failures:
+        log(f"    {len(failures)} DAY(S) NOT READ - the dataset is incomplete "
+            f"and says so: " + ", ".join(d["date"] for d in failures))
+        return 1
+    return 0
+
+
+def do_verify(args, token, tz, log=print):
+    """Re-export a committed day by this route and diff it against the file."""
+    base = args.url.rstrip("/")
+    newline = "\r\n" if args.newline == "crlf" else "\n"
+    rc = 0
+    for target in args.verify:
+        path = Path(target)
+        stamp = path.name.split(".")[0].rsplit("-", 3)[-3:]
+        day = datetime(int(stamp[0]), int(stamp[1]), int(stamp[2]), tzinfo=tz)
+        log(f"    {path.name}  (local day {day.date().isoformat()})")
+        committed = gzip.decompress(path.read_bytes())
+        rows, entry = export_day(base, args.entity, token, day, tz,
+                                 timeout=args.timeout, retries=args.retries,
+                                 backoff=args.backoff, gap_s=args.gap_s,
+                                 newline=newline, log=log)
+        fresh = render(rows, newline=newline)
+        if fresh == committed:
+            log(f"      IDENTICAL: {len(fresh)} bytes, {entry['samples']} "
+                f"samples, sha256 {hashlib.sha256(fresh).hexdigest()[:16]}")
+            continue
+        rc = 1
+        cl = committed.split(newline.encode())
+        fl = fresh.split(newline.encode())
+        log(f"      DIFFERS: committed {len(committed)} B / {len(cl)} lines, "
+            f"re-export {len(fresh)} B / {len(fl)} lines")
+        shown = 0
+        for i in range(max(len(cl), len(fl))):
+            a = cl[i] if i < len(cl) else b"<absent>"
+            b = fl[i] if i < len(fl) else b"<absent>"
+            if a != b:
+                log(f"        line {i}: committed {a!r}")
+                log(f"                  re-export {b!r}")
+                shown += 1
+                if shown >= args.max_diff:
+                    log(f"        ... stopping after {shown} differing lines")
+                    break
+    return rc
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("--url", default=DEFAULT_URL)
+    p.add_argument("--entity", default=DEFAULT_ENTITY)
+    p.add_argument("--token", help="bearer token; else $HASS_TOKEN")
+    p.add_argument("--tz", default=DEFAULT_TZ,
+                   help="local timezone that defines a day boundary")
+    p.add_argument("--days", type=int, default=30)
+    p.add_argument("--end-date", help="last local day to export (YYYY-MM-DD); "
+                                      "default yesterday")
+    p.add_argument("--out-dir", default=".")
+    p.add_argument("--prefix", default="p1-net-")
+    p.add_argument("--manifest", help="path for the manifest JSON")
+    p.add_argument("--gap-s", type=float, default=DEFAULT_GAP_S)
+    p.add_argument("--newline", choices=("crlf", "lf"), default="crlf",
+                   help="line terminator; crlf reproduces the committed files")
+    p.add_argument("--timeout", type=float, default=120.0)
+    p.add_argument("--retries", type=int, default=4)
+    p.add_argument("--backoff", type=float, default=5.0)
+    p.add_argument("--delay", type=float, default=2.0,
+                   help="pause between days - this is a live HA")
+    p.add_argument("--verify", nargs="+", metavar="FILE",
+                   help="re-export these committed days and diff them")
+    p.add_argument("--max-diff", type=int, default=20)
+    args = p.parse_args(argv)
+
+    token = args.token or __import__("os").environ.get("HASS_TOKEN")
+    if not token:
+        print("no token: pass --token or set HASS_TOKEN", file=sys.stderr)
+        return 2
+    if ZoneInfo is None:
+        print("zoneinfo unavailable", file=sys.stderr)
+        return 2
+    tz = ZoneInfo(args.tz)
+    try:
+        if args.verify:
+            return do_verify(args, token, tz)
+        return do_export(args, token, tz)
+    except ReadFailed as exc:
+        print(f"read failed: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

goodwe_controller/tools/replay_ac3.py

@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+"""Run TARIFF-01's and SAFETY-07's AC 3 over a directory of `p1-net-*.jsonl.gz`.
+
+AC 3, both cards, same words: *"monthly peak held under the soft limit in
+>= 95 % of intervals over a 30-day simulation replay."* Both cards merged with
+it UNMET because two days of capture existed. DATA-01 exported thirty. This is
+the thing that turns those thirty days into the number.
+
+    cd goodwe_controller
+    python3 tools/replay_ac3.py scenarios/p1-net-30d-2026-08
+
+WHAT IT MEASURES
+================
+Two runs over the same telegrams, one file at a time in date order into a
+SHARED peak store, so the 15-minute blocks accumulate into a real MONTH rather
+than into 30 disconnected days:
+
+  UNCONTROLLED  the recorded meter as it happened. Nothing was shaving peaks on
+                this house during August 2026, so this is not a simulation of
+                anything - it is what the month did. It is TARIFF-01's AC 3.
+  GUARDED       the same month with `peakguard.decide()` in the loop and the
+                battery it asks for modelled, closed-loop: the meter the guard
+                sees is the recorded net MINUS the discharge it obtained. That
+                is SAFETY-07's AC 3.
+
+Both numbers are `quarters <= peak_cap_w` over `quarters closed`, with the cap
+read out of config.yaml rather than typed. Nothing here exits non-zero on 95 %:
+a measurement below the criterion is a finding about the house and the guard,
+and this tool's job is to report it, not to be graded by it.
+
+FAITHFULNESS TO THE SUITE
+=========================
+The replay loop is `test_peakguard.py` part 6's, with `pack=None` (SoC pinned
+above the floor, so SAFETY-24's energy floor is not the thing deciding the
+answer). It is not imported from there because that file runs its whole suite on
+import. The duplication is checked instead of asserted: pointed at `scenarios/`
+- the two committed days - this tool must reproduce part 6's published totals,
+and `--expect` makes that a hard check.
+
+    python3 tools/replay_ac3.py scenarios --expect 189/190
+
+GAPS
+====
+Nothing is interpolated. A hole in the export is a hole here: the shipped
+`meter_max_age_s` is what decides whether a held reading still counts as
+coverage, so an hour with no telegrams closes no quarters and contributes to
+neither numerator nor denominator. `--report-gaps` lists them.
+"""
+
+from __future__ import annotations
+
+import argparse
+import gzip
+import json
+import sys
+import tempfile
+from datetime import datetime, timedelta
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(HERE))
+
+from app.p1 import P1Ingest, make_sample, split_signed          # noqa: E402
+from app.peakguard import decide                                # noqa: E402
+from app.tariff import PeakStore, PeakTracker, month_key        # noqa: E402
+
+
+def read_option(key: str):
+    """The shipped default for `key`, out of config.yaml.
+
+    ⚠️ `peak_cap_w:` appears TWICE in config.yaml - once under `options:` with
+    the default, once under `schema:` as `int(500,15000)`. The FIRST match is
+    the options block, which is the number an install actually lands on; taking
+    the last would try to float() the schema line. Same rule as the suites.
+    """
+    for line in (HERE / "config.yaml").read_text(encoding="utf-8").splitlines():
+        if line.strip().startswith(f"{key}:"):
+            try:
+                return float(line.split(":", 1)[1].strip())
+            except ValueError:
+                continue
+    return None
+
+
+def read_schema_max(key: str):
+    for line in (HERE / "config.yaml").read_text(encoding="utf-8").splitlines():
+        s = line.strip()
+        if s.startswith(f"{key}:") and "(" in s and ")" in s:
+            try:
+                return float(s[s.index("(") + 1:s.index(")")].split(",")[-1])
+            except ValueError:
+                continue
+    return None
+
+
+def sample(t: datetime, net_w: float):
+    """One telegram through the SHIPPED sign derivation - the suites' helper."""
+    imp, exp = split_signed(net_w)
+    return make_sample("ha_signed", imp, exp, phases=1,
+                       ingest_ts=t, ingest_mono=t.timestamp())
+
+
+def rows(path):
+    """Every sample in one file, in order, with the gaps left as gaps."""
+    with gzip.open(path, "rt", encoding="utf-8") as fh:
+        for line in fh:
+            line = line.strip()
+            if not line:
+                continue
+            row = json.loads(line)
+            yield datetime.fromisoformat(row["t"]), float(row["w"])
+
+
+def replay(paths, *, guarded: bool, cap_w, max_w, max_hold_s, cycle_s,
+           soc, soc_floor, tmp: Path, gap_s: float):
+    """test_peakguard.py part 6's loop, over an arbitrary number of days.
+
+    ⚠️ ONE STORE, AND AN INGEST THAT IS RESET ONLY AT A REAL DISCONTINUITY.
+    Neither half of that is a detail.
+
+    The STORE is shared across the files because "monthly peak" is what AC 3 is
+    about and a per-file store cannot express it.
+
+    The INGEST is carried across a file boundary when the next file's first
+    telegram follows the previous file's last one within `gap_s`, and rebuilt
+    when it does not. Both failure modes are real and were measured here:
+
+      * carried across a genuine hole, one averager manufactures quarters out of
+        nothing - streamed straight through the three-day gap between the two
+        committed days this reported 285/286 where the suite reports 189/190;
+      * rebuilt at every file, each day's LAST quarter (21:45-22:00 UTC) never
+        closes, because it closes only when a telegram past the boundary
+        arrives and that telegram is in the next file. That is why the suite's
+        two days give 95 quarters each rather than 96, and it silently discards
+        one quarter per day - 30 of them over a month.
+
+    So contiguous days are joined and non-contiguous ones are not, which gives
+    189/190 on the committed pair and a full 96 quarters a day on a run of
+    consecutive days.
+    """
+    store = PeakStore(str(tmp / f"ac3-{'g' if guarded else 'u'}.db"))
+    tracker = PeakTracker(store, cap_w=cap_w)
+    engaged = blind = saturated = cycles = n = joins = 0
+    wh = 0.0
+    gaps = []
+    months = set()
+    ing = None
+    batt = 0.0                      # delivered discharge, W (positive)
+    next_cycle = None
+    prev_t = None
+    for path in paths:
+        for i, (t, w) in enumerate(rows(path)):
+            if i == 0:
+                contiguous = (prev_t is not None
+                              and 0 <= (t - prev_t).total_seconds() <= gap_s)
+                if contiguous:
+                    joins += 1
+                else:
+                    if ing is not None:
+                        months |= {month_key(b.start) for b in ing.blocks}
+                    ing = P1Ingest(phases=1, max_age_s=max_hold_s)
+                    batt = 0.0
+                    next_cycle = None
+                    prev_t = None
+            if prev_t is not None:
+                dt = (t - prev_t).total_seconds()
+                if dt > gap_s:
+                    gaps.append((prev_t, t, dt))
+                wh += batt * dt / 3600.0
+            prev_t = t
+            n += 1
+            ing.submit(sample(t, w - batt))
+            tracker.sync(ing)
+            if next_cycle is not None and t < next_cycle:
+                continue
+            next_cycle = t + timedelta(seconds=cycle_s)
+            cycles += 1
+            d = decide(PeakTracker.project(ing.averager, t), batt_w=batt,
+                       cap_w=cap_w, reading=tracker.peak(t),
+                       achievable_w=max_w, max_hold_s=max_hold_s, soc=soc,
+                       soc_floor=soc_floor, frozen=False)
+            if d.engaged:
+                blind += 1 if d.blind else 0
+                engaged += 0 if d.blind else 1
+                saturated += 1 if d.saturated else 0
+            if not guarded:
+                continue
+            engaged_floor = d.engaged and d.floor_w is not None
+            batt = max(0.0, d.floor_w) if engaged_floor else 0.0
+    if ing is not None:
+        months |= {month_key(b.start) for b in ing.blocks}
+    out = {m: dict(store.blocks_in(m)) for m in sorted(months)}
+    return {"months": out, "samples": n, "cycles": cycles, "joins": joins,
+            "engaged": engaged, "blind": blind, "saturated": saturated,
+            "wh": wh, "gaps": gaps}
+
+
+def main(argv=None):
+    p = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    p.add_argument("directory", help="a directory of p1-net-*.jsonl.gz")
+    p.add_argument("--glob", default="p1-net-*.jsonl.gz")
+    p.add_argument("--expect", help="UNDER/TOTAL the uncontrolled run must "
+                                    "reproduce, e.g. 189/190")
+    p.add_argument("--report-gaps", action="store_true")
+    args = p.parse_args(argv)
+
+    paths = sorted(Path(args.directory).glob(args.glob))
+    if not paths:
+        print(f"no {args.glob} under {args.directory}", file=sys.stderr)
+        return 2
+
+    CAP_W = read_option("peak_cap_w")
+    MAX_HOLD_S = read_option("meter_max_age_s")
+    CYCLE_S = read_option("cycle_floor_s")
+    SOC_FLOOR = read_option("peak_soc_floor")
+    LIVE_MAX_W = read_schema_max("max_w")
+    if None in (CAP_W, MAX_HOLD_S, CYCLE_S, SOC_FLOOR, LIVE_MAX_W):
+        print("could not read the shipped options out of config.yaml",
+              file=sys.stderr)
+        return 2
+    # The suites' fixture SoC: comfortably above the floor, so SAFETY-24's
+    # energy floor is not what decides an AC 3 that is not about it.
+    SOC_OK = SOC_FLOOR + 30.0
+
+    days = len(paths)
+    span_first = span_last = None
+    print(f"AC 3 - {days} file(s) from {args.directory}")
+    print(f"    shipped: peak_cap_w {CAP_W:.0f} W, meter_max_age_s "
+          f"{MAX_HOLD_S:.0f} s, cycle_floor_s {CYCLE_S:.0f} s, "
+          f"max_w schema ceiling {LIVE_MAX_W:.0f} W")
+
+    tmp = Path(tempfile.mkdtemp(prefix="goodwe-ac3-"))
+    kw = dict(cap_w=CAP_W, max_w=LIVE_MAX_W, max_hold_s=MAX_HOLD_S,
+              cycle_s=CYCLE_S, soc=SOC_OK, soc_floor=SOC_FLOOR, tmp=tmp,
+              gap_s=MAX_HOLD_S)
+    u = replay(paths, guarded=False, **kw)
+    g = replay(paths, guarded=True, **kw)
+
+    def flat(run):
+        return [w for m in run["months"].values() for w in m.values()]
+
+    uq, gq = flat(u), flat(g)
+    u_under = sum(1 for w in uq if w <= CAP_W)
+    g_under = sum(1 for w in gq if w <= CAP_W)
+    u_pct = 100.0 * u_under / max(len(uq), 1)
+    g_pct = 100.0 * g_under / max(len(gq), 1)
+
+    print(f"    {u['samples']} samples, {len(uq)} closed quarters "
+          f"({len(uq) / 96.0:.1f} days' worth), {days - u['joins']} contiguous "
+          f"run(s) of days")
+    for m in sorted(u["months"]):
+        mu = u["months"][m]
+        mg = g["months"].get(m, {})
+        print(f"    month {m}: {len(mu)} quarters, peak "
+              f"{max(mu.values()):.1f} W uncontrolled -> "
+              f"{max(mg.values()) if mg else 0.0:.1f} W guarded")
+    print()
+    print(f"    TARIFF-01 AC 3 (UNCONTROLLED, what the month did): "
+          f"{u_under}/{len(uq)} = {u_pct:.2f} % of quarters at or under "
+          f"{CAP_W:.0f} W")
+    print(f"    SAFETY-07 AC 3 (GUARDED, peakguard.decide in the loop): "
+          f"{g_under}/{len(gq)} = {g_pct:.2f} %")
+    print(f"      guard cycles {g['cycles']}, engaged on the measurement "
+          f"{g['engaged']}, blind {g['blind']}, saturated {g['saturated']}, "
+          f"modelled discharge {g['wh']:.0f} Wh")
+    # AC 3'S WORDS SUPPORT TWO READINGS AND BOTH ARE REPORTED, because they
+    # disagree on this data and picking the flattering one is the failure mode
+    # this whole card exists to correct.
+    u_peak = max(uq) if uq else 0.0
+    g_peak = max(gq) if gq else 0.0
+    print(f"    reading A - PERCENTAGE OF INTERVALS under the cap (the reading "
+          f"test_tariff.py part 9 already uses): uncontrolled {u_pct:.2f} %, "
+          f"guarded {g_pct:.2f} %")
+    print(f"    reading B - THE MONTHLY PEAK ITSELF under the cap: "
+          f"{u_peak:.1f} W uncontrolled -> {g_peak:.1f} W guarded, against a "
+          f"{CAP_W:.0f} W soft limit "
+          f"({'under' if g_peak <= CAP_W else 'STILL OVER'})")
+    print(f"    verdict at the 95 % criterion: uncontrolled "
+          f"{'MEETS' if u_pct >= 95.0 else 'DOES NOT MEET'}, guarded "
+          f"{'MEETS' if g_pct >= 95.0 else 'DOES NOT MEET'} "
+          f"({len(uq) / 96.0:.1f} days of replay)")
+
+    if u["gaps"]:
+        tot = sum(d for _, _, d in u["gaps"])
+        print(f"    gaps over {MAX_HOLD_S:.0f} s: {len(u['gaps'])}, "
+              f"{tot:.0f} s total - NOT interpolated; the quarters they fall in "
+              f"simply carry less coverage")
+        if args.report_gaps:
+            for a, b, d in u["gaps"]:
+                print(f"      {a.isoformat()} -> {b.isoformat()}  {d:.0f} s")
+
+    if args.expect:
+        want_u, want_t = (int(x) for x in args.expect.split("/"))
+        ok = (u_under, len(uq)) == (want_u, want_t)
+        print(f"    reproduces test_peakguard.py part 6's published "
+              f"{want_u}/{want_t}: {'yes' if ok else 'NO'} "
+              f"(got {u_under}/{len(uq)})")
+        return 0 if ok else 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())