OPT-04: charge cheap, discharge expensive - and only when it pays

Four cards built the price stack and nothing traded on it. app/arbitrage.py is
§10.1's priority 3, and it consumes all four rather than re-deciding anything:
whether a trade is permitted at all, on which two hours, against which widened
threshold is TariffPlan.arbitrage()'s answer, and that answer cannot be
obtained without first saying whether the peak guard is holding. §9.1's "peak
shaving outranks arbitrage" is therefore honoured structurally - there is no
path to a spread that skips the question - and again in the arbiter, where
P_PEAK (50) clamps a claim filed at P_ARBITRAGE (30).

A guard that never ran is not a guard that is clear. On meter_source off the
peak guard is never evaluated; that third state is carried as None and refuses,
because charging at the rail creates the billed quantity while nothing measures
the quarter. validate.py refuses that configuration too, along with arbitrage
armed with no price source 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 clears any threshold and
its dearest hour is still negative. Buying in a negative hour stays allowed.

resolve_tariff() may open an HTTPS connection and the tick feeds the ESP32
heartbeat, so the fetch runs in its own task at a 30 min cadence and the tick
reads an attribute and an age bound. test_arbitrage.py section 8 asserts that
structurally on the shipped AST: a fetch put back on cycle() is red.

AC4 is NOT met and is not restated - this repository holds no price history.
Section 7 replays a synthetic year and asserts the property that does not need
real prices: every executed round trip cleared its own widened requirement, and
zero discharges landed in the 522 negative-priced hours. 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 FCST-03's widening factors are one product
decision and it is the owner's.

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

goodwe_controller/CHANGELOG.md

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

goodwe_controller/DOCS.md

@@ -644,15 +644,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 |
 |---|---|
@@ -804,6 +805,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,10 +28,11 @@ 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_PEAK, P_SAFETY, Claim, resolve,
 )
@@ -48,7 +49,8 @@ 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
@@ -57,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:
@@ -232,6 +262,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
@@ -514,6 +554,64 @@ class Controller:
             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,
@@ -866,6 +964,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:
@@ -1243,6 +1392,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,
@@ -1370,6 +1524,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/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/validate.py

@@ -155,8 +155,9 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
 import logging
 
+from .arbitrage import enabled as arbitrage_on
 from .p1 import is_enabled, validate_meter_options
-from .price import PROVIDERS
+from .price import PRICE_OPTION_DEFAULTS, PROVIDERS
 from .static_tariff import ProfileInvalid, parse_static_profile
 
 _LOG = logging.getLogger("goodwe.config")
@@ -453,14 +454,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 +477,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 +538,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

@@ -240,6 +240,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
@@ -337,5 +369,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/test_arbitrage.py

@@ -0,0 +1,998 @@
+"""Runnable check for OPT-04 - price arbitrage.  `python3 test_arbitrage.py`
+
+⚠️ RUN IT WITH `python3 -B` AND PURGE `__pycache__` FIRST. TEST-15 records a
+size-preserving edit, reverted inside one second, whose OLD BYTECODE was still
+what ran - confirmed by disassembly - so a mutation graded code that was not
+there. Every mutation reported in the PR for this card was run as:
+
+    find . -name __pycache__ -type d -exec rm -rf {} + ; python3 -B test_*.py
+
+WHAT THIS FILE IS DEFENDING, in the order the card's acceptance criteria name it:
+
+  AC1  NO ACTION when the expected benefit is below `cycle_cost_threshold_eur`.
+       Measured by BISECTING the accept/refuse boundary and comparing the
+       boundary with a threshold derived here by different arithmetic - not by
+       reading a constant back out of the module that defines it.
+  AC2  NEGATIVE-PRICE HOURS NEVER TRIGGER EXPORT (§17). Both sides: the same
+       series with the sign of one hour changed must trade in one case and
+       refuse in the other, or the guard is graded by nothing.
+  AC3  YIELDS TO PEAK SHAVING (§9.1). Through the two mechanisms that already
+       exist - static_tariff's required `peak_guard_active` interlock and
+       arbiter.py's clause 2 - both driven end to end, plus the third state
+       (the guard never ran) that neither of them can express on its own.
+  AC4  NET-POSITIVE ACROSS 12 MONTHS OF REPLAYED PRICES. ⚠️ SEE SECTION 7. THIS
+       REPOSITORY HOLDS NO PRICE HISTORY AT ALL - `scenarios/` carries two days
+       of real METER data and nothing else - so the criterion as written cannot
+       be met, and it is NOT redefined here into something that can be. What
+       section 7 does instead is stated there in full, and what it cannot say is
+       stated with it.
+
+THREE RULES THIS FILE HOLDS ITSELF TO, because the reviewer will:
+
+  * EVERY VERDICT IS DERIVED. No `check("the guard works", True)`. The widened
+    threshold is bisected rather than read; the arbiter's ordering is computed
+    from the priority constants rather than typed; the replay's net figure is
+    accumulated from the same trades the strategy actually chose.
+
+  * NO STIMULUS IS EVALUATED WHERE THE QUANTITY IT GRADES IS DEGENERATE. This
+    ticket is thick with that trap and each one is asserted before it is used:
+
+      - A SERIES WHOSE CHEAPEST HOUR IS ALSO ITS FIRST HOUR cannot tell "acts in
+        the cheapest hour" from "acts in the first hour". The fixture's cheapest
+        and dearest hours are neither the first nor the last, and neither is
+        adjacent to the other.
+      - THE NEGATIVE-PRICE CASE MUST STILL CLEAR THE THRESHOLD, or §17's guard
+        is graded on a series that the spread rung already refused, and deleting
+        the guard changes nothing. The fixture's all-negative day has a
+        0.25 EUR/kWh spread, asserted before it is used.
+      - IT MUST ALSO BE THE DEAREST HOUR THAT IS NEGATIVE. A day with one
+        negative hour that is the CHEAPEST one is a day the guard never
+        consults, and it would pass with the guard removed.
+      - `peak_guard_active` FALSE AND TRUE MUST DIFFER ON THE SAME PLAN, or AC3
+        is graded by a plan that refuses for some other reason anyway.
+      - THE PEAK FLOOR MUST BE INSIDE THE ARBITRAGE CHARGE, or clause 2 clamps
+        nothing and the arbiter check passes for an unbound claim.
+      - SoC MUST START STRICTLY BETWEEN FLOOR AND CEILING in every check that is
+        not about SoC, or a refusal attributed to price is really about charge.
+
+  * A FAILED READ IS NOT AN OBSERVATION. No plan yet resolved, a plan that has
+    aged out, an hour the series does not cover, an unread state of charge and a
+    peak guard that never ran are five DIFFERENT reasons - and none of them is
+    an answer. Section 5 drives all five and asserts they are distinguishable.
+"""
+
+import ast
+import inspect
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+from app import arbitrage as _arb
+from app import main as _main
+from app import peakguard as _pg
+from app.arbiter import (
+    P_ARBITRAGE, P_LOOP, P_MAINT_SHAPE, P_MAINTENANCE, P_PEAK, P_SAFETY, Claim,
+    resolve,
+)
+from app.arbitrage import (
+    CHARGE, DISCHARGE, ArbitrageDecision, claim, decide, enabled, soc_bounds,
+    threshold_eur_kwh,
+)
+from app.price import (
+    PRICE_OPTION_DEFAULTS, Absence, PricePoint, PriceProduct, PriceRead,
+    Uncertainty, WIDEN_FACTOR, brussels, required_spread, widen_factor,
+)
+from app.static_tariff import TariffPlan, parse_static_profile, static_plan
+from app.validate import validate_startup_config
+
+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. See test_price.py for why."""
+    try:
+        return fn()
+    except Exception as e:                                    # noqa: BLE001
+        return _Raised(e)
+
+
+def _fn(module_src, name):
+    tree = ast.parse(module_src)
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) \
+                and node.name == name:
+            return node
+    return None
+
+
+def _awaited(node):
+    """Every name awaited anywhere inside `node`."""
+    out = set()
+    for n in ast.walk(node):
+        if not isinstance(n, ast.Await):
+            continue
+        f = n.value.func if isinstance(n.value, ast.Call) else n.value
+        out.add(getattr(f, "id", None) or getattr(f, "attr", None))
+    return {n for n in out if n}
+
+
+def near(a, b, tol=1e-9):
+    try:
+        return abs(float(a) - float(b)) <= tol
+    except (TypeError, ValueError):
+        return False
+
+
+# --------------------------------------------------------------------------- #
+# Fixtures
+# --------------------------------------------------------------------------- #
+
+D0 = datetime(2026, 1, 15, 0, 0, tzinfo=UTC)
+MAX_W = 2000.0
+NO_WEATHER = frozenset({Uncertainty.NO_WEATHER})
+
+
+def plan_of(prices, *, product=PriceProduct.DAY_AHEAD, start=D0,
+            provisional=False, provider="generic_dayahead"):
+    """A TariffPlan over consecutive hourly prices starting at `start`.
+
+    `provisional` may be a single bool or a per-hour sequence.
+    """
+    flags = ([bool(provisional)] * len(prices)
+             if isinstance(provisional, bool) else list(provisional))
+    pts = [PricePoint(start=brussels(start + timedelta(hours=i)),
+                      eur_per_kwh=round(float(p), 6), provisional=f)
+           for i, (p, f) in enumerate(zip(prices, flags))]
+    return TariffPlan(PriceRead.series(pts, product, provider, start), None,
+                      "provider")
+
+
+def hour(i, *, start=D0):
+    """Mid-hour instant of slot `i` - never a boundary, where two answers agree."""
+    return start + timedelta(hours=i, minutes=30)
+
+
+def act(plan, i, *, peak=False, soc=50.0, thresh=0.0, unc=frozenset(),
+        floor=20.0, ceiling=95.0, start=D0):
+    """`decide()` with the fixture's constants filled in. One call shape."""
+    return decide(plan, hour(i, start=start), peak_guard_active=peak, soc=soc,
+                  min_spread_eur_kwh=thresh, uncertainty=unc,
+                  charge_w=MAX_W, discharge_w=MAX_W,
+                  soc_floor_pct=floor, soc_ceiling_pct=ceiling)
+
+
+# ⚠️ THE SHAPE OF THIS DAY IS THE WHOLE DEGENERACY ARGUMENT. The cheapest hour
+# is slot 3 and the dearest is slot 18: neither is first, neither is last,
+# neither is adjacent to the other, and the last hour is not the dearest. An
+# implementation that acted on "the first hour", "the last hour", "the hour
+# after the cheapest" or "min/max swapped" produces a different answer from the
+# correct one at every probe below.
+DAY = [0.240, 0.230, 0.215, 0.150, 0.190, 0.225,
+       0.260, 0.300, 0.320, 0.310, 0.295, 0.280,
+       0.270, 0.275, 0.285, 0.300, 0.330, 0.360,
+       0.410, 0.380, 0.340, 0.300, 0.270, 0.250]
+CHEAP_H, DEAR_H = 3, 18
+SPREAD = round(max(DAY) - min(DAY), 6)
+
+print("0. the fixture is not degenerate (asserted before anything is graded)")
+check(f"the cheapest hour is slot {CHEAP_H} and the dearest slot {DEAR_H} - "
+      f"neither first, neither last, and not adjacent",
+      DAY.index(min(DAY)) == CHEAP_H and DAY.index(max(DAY)) == DEAR_H
+      and CHEAP_H not in (0, len(DAY) - 1) and DEAR_H not in (0, len(DAY) - 1)
+      and abs(CHEAP_H - DEAR_H) > 1)
+check(f"...and its spread is {SPREAD:.4f} EUR/kWh, comfortably above the "
+      f"shipped threshold, so the checks below grade the strategy rather than "
+      f"the spread rung",
+      SPREAD > PRICE_OPTION_DEFAULTS["cycle_cost_threshold_eur"] * 1.5)
+check("...and its minimum and its maximum each occur EXACTLY ONCE, so 'the "
+      "cheapest hour' names one hour and an undefined tie-break is not what "
+      "any check below is really grading",
+      DAY.count(min(DAY)) == 1 and DAY.count(max(DAY)) == 1)
+check("...and no price in it is zero or negative, so section 2's sign flip is "
+      "the only source of a negative price in this file",
+      all(p > 0 for p in DAY))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("1. AC1 - nothing happens below cycle_cost_threshold_eur")
+
+PLAN = plan_of(DAY)
+
+_buy = act(PLAN, CHEAP_H, thresh=0.0)
+_sell = act(PLAN, DEAR_H, thresh=0.0)
+check("with a zero threshold the cheapest hour CHARGES and the dearest hour "
+      "DISCHARGES - the two actions this strategy has, both reachable",
+      _buy.action == CHARGE and _sell.action == DISCHARGE)
+check("...charging is a NEGATIVE setpoint and discharging a positive one, "
+      "which is the sign convention maintenance's `hi <= 0` shaping and "
+      "peakguard's `lo >= 0` floor are both written against",
+      _buy.power_w is not None and _sell.power_w is not None
+      and _buy.power_w < 0 < _sell.power_w)
+check("...and an hour that is neither buy nor sell does NOTHING, so the "
+      "strategy is not simply always-on",
+      act(PLAN, 10, thresh=0.0).action is None)
+
+# ⚠️ MEASURED, NOT READ. The boundary is found by bisection on the threshold,
+# so this grades the shipped refusal ladder rather than restating a constant
+# that lives in the module under test.
+def boundary(unc, plan=PLAN, lo=0.0, hi=10.0):
+    """The largest threshold this plan still trades under, to 1e-9."""
+    for _ in range(200):
+        mid = (lo + hi) / 2.0
+        if act(plan, CHEAP_H, thresh=mid, unc=unc).action is None:
+            hi = mid
+        else:
+            lo = mid
+    return lo
+
+
+_b_plain = derived(lambda: boundary(frozenset()))
+check(f"the accept/refuse boundary with no uncertainty is the spread itself "
+      f"({_b_plain!r} vs {SPREAD}) - a cycle trades exactly while its spread "
+      f"covers its cost, and not one cent further",
+      near(_b_plain, SPREAD, 1e-6))
+check("...so a threshold a hair ABOVE the spread refuses and a hair BELOW it "
+      "trades: the boundary is a boundary, not a slope",
+      act(PLAN, CHEAP_H, thresh=SPREAD + 1e-4).action is None
+      and act(PLAN, CHEAP_H, thresh=SPREAD - 1e-4).action == CHARGE)
+_refusal = act(PLAN, CHEAP_H, thresh=SPREAD + 1e-4).reason
+check("...and the refusal SAYS the spread and the number it had to cover, so "
+      "an operator can tell 'no opportunity' from 'broken'",
+      "does not cover" in _refusal or "needs" in _refusal)
+
+# The widening path, end to end: the boundary must move by exactly the declared
+# factor. Derived twice - once by bisection, once through required_spread().
+_b_wide = derived(lambda: boundary(NO_WEATHER))
+check("the two widening factors this repository ships DIFFER, or 'max', 'sum' "
+      "and 'product' would be indistinguishable combination rules",
+      len(set(WIDEN_FACTOR.values())) == len(WIDEN_FACTOR))
+check(f"a widened threshold moves the boundary by exactly the declared factor: "
+      f"{_b_wide!r} x {widen_factor(NO_WEATHER)} = {_b_plain!r}",
+      near(_b_wide * widen_factor(NO_WEATHER), _b_plain, 1e-6))
+check("...which is the same number required_spread() computes from the other "
+      "direction, so the widening is one mechanism and not two",
+      isinstance(_b_wide, float)
+      and near(required_spread(_b_wide, NO_WEATHER), _b_plain, 1e-6))
+_wide_at = round(SPREAD / widen_factor(NO_WEATHER) + 1e-4, 6)
+check("...and the difference is LIVE, not arithmetic on paper: at one "
+      "threshold the plain site trades and the no-weather site does not",
+      act(PLAN, CHEAP_H, thresh=_wide_at, unc=frozenset()).action == CHARGE
+      and act(PLAN, CHEAP_H, thresh=_wide_at, unc=NO_WEATHER).action is None)
+
+# The threshold this add-on SHIPS, against the tariff most of the installed
+# base is on. Reported, not tuned - see the module docstring in app/arbitrage.py.
+STATIC_BE = ('{"periods": ['
+             '{"name":"day","from":"07:00","to":"22:00","days":"all",'
+             '"eur_per_kwh":0.34},'
+             '{"name":"night","from":"22:00","to":"07:00","days":"all",'
+             '"eur_per_kwh":0.26}]}')
+_st_plan = derived(lambda: static_plan({"static_profile": STATIC_BE}, D0,
+                                       D0 + timedelta(days=2), now=D0))
+_st_spread = derived(lambda: _st_plan.spread_eur_kwh())
+check(f"a realistic Belgian day/night profile has a spread of "
+      f"{_st_spread!r} EUR/kWh - the number the product decision is about",
+      near(_st_spread, 0.08))
+_shipped = PRICE_OPTION_DEFAULTS["cycle_cost_threshold_eur"]
+_st_verdict = derived(lambda: _st_plan.arbitrage(
+    peak_guard_active=False, min_spread_eur_kwh=_shipped,
+    uncertainty=NO_WEATHER))
+check(f"...and at the SHIPPED threshold of {_shipped} EUR/kWh that site does "
+      f"NOT trade. Reported, not tuned: the shipped default is the owner's "
+      f"decision and this check exists to make the consequence visible rather "
+      f"than to argue with it",
+      _st_verdict.kind == "refused")
+check(f"...and it is the SPREAD rung that refuses it, not a flat-tariff or a "
+      f"provisional rung that would have refused any static site whatever the "
+      f"threshold was: {_st_spread!r} < "
+      f"{required_spread(_shipped, NO_WEATHER)!r}",
+      _st_spread < required_spread(_shipped, NO_WEATHER)
+      and "cover its own round-trip cost" in _st_verdict.reason)
+check("...while the SAME site trades once the threshold is set below its "
+      "spread, so the refusal above is about the number and not about static "
+      "tariffs being unsupported",
+      derived(lambda: _st_plan.arbitrage(
+          peak_guard_active=False,
+          min_spread_eur_kwh=_st_spread / widen_factor(NO_WEATHER) - 1e-4,
+          uncertainty=NO_WEATHER).kind) == "allowed")
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("2. AC2 - §17: a negative-price hour never triggers export")
+
+# ⚠️ THE WHOLE DAY IS NEGATIVE AND THE DEAREST HOUR IS THE LEAST NEGATIVE ONE.
+# That is the case a guard written as "the spread is positive" or "not all
+# prices are negative" lets through, and it is the realistic one: Belgian
+# day-ahead has gone negative for a whole summer midday block.
+NEG = [round(-0.30 + 0.010 * i, 6) for i in range(24)]     # -0.30 .. -0.07
+NEG[DEAR_H] = -0.05                                        # dearest, still < 0
+NEG_PLAN = plan_of(NEG)
+_neg_spread = round(max(NEG) - min(NEG), 6)
+check(f"the negative day's dearest hour is slot {DEAR_H} and it is BELOW ZERO "
+      f"({max(NEG):+.4f}), which is the only shape that exercises the guard",
+      NEG.index(max(NEG)) == DEAR_H and max(NEG) < 0)
+check(f"...and its spread is {_neg_spread:.4f} EUR/kWh, which CLEARS the "
+      f"shipped threshold - so the trade is refused by §17 and not by a rung "
+      f"that would have refused it anyway",
+      _neg_spread > required_spread(_shipped, NO_WEATHER))
+_neg_sell = act(NEG_PLAN, DEAR_H, thresh=_shipped, unc=NO_WEATHER)
+check("selling into a negative-price hour is REFUSED", _neg_sell.action is None)
+check("...and the reason names §17 and the price, so the log says which rule "
+      "and not merely that nothing happened",
+      "§17" in _neg_sell.reason and "-0.0500" in _neg_sell.reason)
+# The other side of the guard, without which nothing above is discriminating.
+POS = list(NEG)
+POS[DEAR_H] = +0.05          # the SAME day with ONE SIGN FLIPPED
+POS_PLAN = plan_of(POS)
+_pos_sell = act(POS_PLAN, DEAR_H, thresh=_shipped, unc=NO_WEATHER)
+check("...while the SAME series with that one price's SIGN FLIPPED does "
+      "discharge - so the refusal is about the sign and about nothing else "
+      "that differs between the two runs",
+      _pos_sell.action == DISCHARGE)
+check("...and the two runs differ in exactly one price, by exactly its sign",
+      sum(1 for a, b in zip(NEG, POS) if a != b) == 1
+      and near(NEG[DEAR_H], -POS[DEAR_H]))
+# §17 is about EXPORT. Buying in a negative hour is the right thing to do.
+check("BUYING in a negative-price hour is still permitted - §17 forbids "
+      "exporting into one, and a guard that also blocked the buy would be "
+      "refusing to be paid to charge",
+      act(NEG_PLAN, NEG.index(min(NEG)), thresh=_shipped,
+          unc=NO_WEATHER).action == CHARGE)
+# A zero price is the boundary and it is NOT negative.
+ZERO = list(POS)
+ZERO[DEAR_H] = 0.0
+check("a sell hour priced at exactly ZERO is not a negative one, so the guard "
+      "is `< 0` rather than `<= 0` - and the boundary is stated by a check "
+      "rather than left to whoever reads the operator",
+      act(plan_of(ZERO), DEAR_H, thresh=_shipped, unc=NO_WEATHER).action
+      == DISCHARGE)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("3. AC3 - peak shaving outranks arbitrage, through both mechanisms")
+
+# MECHANISM 1: static_tariff's interlock. The spread is not obtainable without
+# answering the question, so this cannot be skipped by a caller.
+_clear = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER, peak=False)
+_held = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER, peak=True)
+check("on ONE plan, at ONE instant, with ONE threshold, the peak guard being "
+      "CLEAR trades and the peak guard HOLDING does not - the only difference "
+      "between the two runs is that boolean",
+      _clear.action == CHARGE and _held.action is None)
+check("...and the refusal cites §10.1's ordering and the capaciteitstarief, so "
+      "it cannot be mistaken for 'no opportunity today'",
+      "§10.1" in _held.reason and "peak" in _held.reason.lower())
+check("...and the interlock is REQUIRED rather than defaulted: "
+      "TariffPlan.arbitrage() has no default for peak_guard_active, so a "
+      "caller cannot reach a spread without having answered it",
+      all(p.default is inspect.Parameter.empty
+          for n, p in inspect.signature(TariffPlan.arbitrage).parameters.items()
+          if n != "self"))
+check("...nor does arbitrage.decide(): every argument of it is keyword-only "
+      "with no default, for the same reason",
+      all(p.default is inspect.Parameter.empty
+          and (p.kind is inspect.Parameter.KEYWORD_ONLY or n in ("plan", "now"))
+          for n, p in inspect.signature(decide).parameters.items()))
+
+# MECHANISM 2: the arbiter. Even with the interlock bypassed, the peak claim
+# binds the arbitrage claim - because P_PEAK > P_ARBITRAGE and clause 2 applies
+# every limit at or above the winner's priority.
+check("the priority ordering IS §10.1's, derived from the constants rather "
+      "than asserted about them: safety > maintenance > peak > maintenance "
+      "shaping > arbitrage > loop",
+      P_SAFETY > P_MAINTENANCE > P_PEAK > P_MAINT_SHAPE > P_ARBITRAGE > P_LOOP)
+_charge_claim = claim(_clear)
+PEAK_FLOOR = 500.0
+check(f"the peak floor used below ({PEAK_FLOOR:+.0f} W) is strictly INSIDE the "
+      f"arbitrage charge ({_charge_claim.value:+.0f} W), or clause 2 would "
+      f"clamp nothing and the resolution would pass for an unbound claim",
+      _charge_claim.value < PEAK_FLOOR)
+_res = resolve([
+    Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W, "max_w"),
+    Claim.limit(_pg.SOURCE, P_PEAK, lo=PEAK_FLOOR, reason="quarter peak"),
+    _charge_claim,
+    Claim.set("loop", P_LOOP, -120.0, "following"),
+])
+check(f"an arbitrage charge that WINS the arbitration is still clamped by the "
+      f"peak floor: {_res.explain()}",
+      near(_res.target_w, PEAK_FLOOR) and _res.winner == _arb.SOURCE
+      and _res.bound_by is not None and _pg.SOURCE in _res.bound_by)
+check("...and it is P_PEAK > P_ARBITRAGE that does it, not luck: the identical "
+      "floor filed BELOW the arbitrage priority does not bind at all",
+      near(resolve([
+          Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W, "max_w"),
+          Claim.limit(_pg.SOURCE, P_ARBITRAGE - 1, lo=PEAK_FLOOR),
+          _charge_claim]).target_w, _charge_claim.value))
+# The floor really is peakguard's own claim, not a hand-rolled stand-in.
+_pd = _pg.PeakDecision(engaged=True, floor_w=PEAK_FLOOR, ceiling_w=3500.0,
+                       ceiling_from=_pg.CEILING_CAP, reason="test")
+_real_peak = derived(lambda: _pg.claim(_pd))
+check("...and the claim doing the clamping is peakguard.claim()'s own output, "
+      "so this grades the shipped floor rather than a transcription of it",
+      _real_peak is not None and _real_peak.priority == P_PEAK
+      and near(resolve([
+          Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W, "max_w"),
+          _real_peak, _charge_claim]).target_w, PEAK_FLOOR))
+# ...and a DISCHARGE is deliberately not capped by it (§9.1: only offtake bills).
+check("a peak floor does NOT cap an arbitrage DISCHARGE - §9.1 bills offtake "
+      "only, and peakguard's claim leaves `hi` at +inf to say so",
+      near(resolve([
+          Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W, "max_w"),
+          _real_peak, claim(_sell)]).target_w, MAX_W))
+
+# MECHANISM 3, which is neither of the above: the guard that never ran.
+_blind = decide(PLAN, hour(CHEAP_H), peak_guard_active=None, soc=50.0,
+                min_spread_eur_kwh=_shipped, uncertainty=NO_WEATHER,
+                charge_w=MAX_W, discharge_w=MAX_W,
+                soc_floor_pct=20.0, soc_ceiling_pct=95.0)
+check("a peak guard that NEVER RAN is a third state, and it refuses: `None` is "
+      "not `False`, and 'nothing measured the quarter' is not 'the quarter is "
+      "clear'",
+      _blind.action is None and "NOT COVERED" in _blind.reason)
+check("...and it is distinguishable from the guard HOLDING, so the status page "
+      "does not report an unmeasured install as a peak event",
+      _blind.reason != _held.reason)
+# ⚠️ AND THE THREE STATES ARE GRADED ON THE SHIPPED EXPRESSION. `guard_state()`
+# is what main.py's cycle() passes; a transcription of it here would be the
+# defect `shaping_suspended()` was extracted to remove - a mutation back to a
+# bare `engaged_now` left every suite green in the case that record describes.
+_idle_pd = _pg.PeakDecision(engaged=False, floor_w=None, ceiling_w=3500.0,
+                            ceiling_from=_pg.CEILING_CAP, reason="idle")
+check("guard_state() maps peakguard's three real situations onto the three "
+      "states decide() takes, and None is NOT False",
+      _arb.guard_state(None) is None
+      and _arb.guard_state(_idle_pd) is False
+      and _arb.guard_state(_pd) is True)
+check("...and cycle() calls it rather than inlining the conjunction, so a "
+      "mutation back to a bare `engaged_now` is red rather than silent",
+      "arbitrage.guard_state(self.peak_guard)" in
+      ast.get_source_segment(
+          open(os.path.join(HERE, "app", "main.py"), encoding="utf-8").read(),
+          _fn(open(os.path.join(HERE, "app", "main.py"),
+                   encoding="utf-8").read(), "cycle")))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("4. §8.3 - no irreversible action on a provisional price")
+
+# The realistic shape: the feed has published the morning and the afternoon is
+# carried from yesterday. The CHEAPEST hour of the whole day is in the carried
+# part, which is the lure - and the firm part still has a tradeable spread, so
+# a correct implementation trades on the firm hours rather than doing nothing.
+_flags = [i >= 12 for i in range(24)]
+_part = plan_of(DAY, provisional=_flags)
+_firm = [p for p, f in zip(DAY, _flags) if not f]
+check("the fixture's carried half contains the day's DEAREST hour, so 'the "
+      "carried hours are ignored' is graded by a case where ignoring them "
+      "changes the answer",
+      _flags[DEAR_H] is True)
+check("...and the firm half still has a spread over the shipped threshold, so "
+      "the correct behaviour is to TRADE on the firm hours - a check that "
+      "expected silence would pass for an implementation that gave up",
+      round(max(_firm) - min(_firm), 6) > required_spread(_shipped, NO_WEATHER))
+_p_buy = act(_part, CHEAP_H, thresh=_shipped, unc=NO_WEATHER)
+_p_sell_carried = act(_part, DEAR_H, thresh=_shipped, unc=NO_WEATHER)
+_p_sell_firm = act(_part, _firm.index(max(_firm)), thresh=_shipped,
+                   unc=NO_WEATHER)
+check("the firm cheapest hour still CHARGES", _p_buy.action == CHARGE)
+check("...the firm dearest hour still DISCHARGES", _p_sell_firm.action == DISCHARGE)
+check("...and the CARRIED hour that is the day's real maximum does nothing - "
+      "it is not the sell hour, because it is not an observation",
+      _p_sell_carried.action is None)
+_all_prov = act(plan_of(DAY, provisional=True), CHEAP_H, thresh=0.0)
+check("a FULLY carried series trades nothing at all, whatever its spread - "
+      "§11.4's fallback plan and a pre-publication day both land here",
+      _all_prov.action is None and "§8.3" in _all_prov.reason)
+# ⚠️ A SURVIVOR, REPORTED RATHER THAN HIDDEN, AND THE ARGUMENT THAT MAKES IT
+# HARMLESS. Disabling `_act`'s own `if here.provisional:` guard changes no
+# answer in this file, and it cannot: the verdict's `cheapest`/`dearest` are
+# firm by `_firm_or_die`, starts are unique within a series, and the point
+# `at()` returns for a matched instant is therefore THE SAME OBJECT. The guard
+# is unreachable by construction, exactly the way peakguard's seventh mutation
+# is - and the honest response is to demonstrate the construction rather than
+# to write a check that cannot bite. It stays because it is the only thing
+# standing if a future caller ever hands `_act` a plan the verdict did not come
+# from.
+_probe = _arb._point_at(PLAN, hour(CHEAP_H))
+_verdict = PLAN.arbitrage(peak_guard_active=False, min_spread_eur_kwh=0.0,
+                          uncertainty=frozenset())
+check("the point matched for the buy hour IS the verdict's own cheapest point, "
+      "by identity - which is why `_act`'s provisional guard is unreachable "
+      "here, and why disabling it changes nothing this file can observe",
+      _probe is _verdict.cheapest and _probe.provisional is False)
+check("...and the starts really are unique in a series, which is the other "
+      "half of that argument",
+      len({p.start for p in PLAN.read.points}) == len(PLAN.read.points))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("4b. §10.2 hysteresis - a price on the boundary cannot flap at 30 s")
+
+# The card's technical notes ask for this to be "testable by replaying a price
+# series oscillating around the threshold and asserting a bounded transition
+# count". ⚠️ THE OSCILLATION IS THE POINT: these prices cross the shipped
+# threshold repeatedly, hour to hour, which is the shape that makes a
+# per-tick price-vs-threshold comparison flap.
+FLAP = [0.20 + (0.101 if i % 2 else 0.0) for i in range(24)]
+_flap_plan = plan_of(FLAP)
+check("the flapping fixture really does straddle the threshold hour by hour - "
+      "every neighbouring pair differs by more than it",
+      all(abs(FLAP[i] - FLAP[i + 1]) > _shipped for i in range(len(FLAP) - 1)))
+_ticks = []
+for _t in range(24 * 120):                 # 24 h at the 30 s control cadence
+    _d = decide(_flap_plan, D0 + timedelta(seconds=30 * _t),
+                peak_guard_active=False, soc=50.0, min_spread_eur_kwh=_shipped,
+                uncertainty=frozenset(), charge_w=MAX_W, discharge_w=MAX_W,
+                soc_floor_pct=20.0, soc_ceiling_pct=95.0)
+    _ticks.append(_d.action)
+_transitions = sum(1 for a, b in zip(_ticks, _ticks[1:]) if a != b)
+check(f"over {len(_ticks)} ticks of a day whose price crosses the threshold "
+      f"every hour, the strategy changes what it is doing {_transitions} "
+      f"times - not once per tick, because the decision is 'which HOUR is "
+      f"this', and an hour is 3600 s wide",
+      _transitions <= 4)
+check("...and it is not zero, so the bound above is a bound on a strategy that "
+      "acted rather than on one that did nothing",
+      _transitions > 0 and CHARGE in _ticks and DISCHARGE in _ticks)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("5. a failed read is not an observation - five reasons, all different")
+
+_no_plan = act(None, CHEAP_H, thresh=_shipped)
+_no_soc = act(PLAN, CHEAP_H, thresh=_shipped, soc=None)
+_uncovered = decide(PLAN, D0 + timedelta(days=9), peak_guard_active=False,
+                    soc=50.0, min_spread_eur_kwh=_shipped,
+                    uncertainty=frozenset(), charge_w=MAX_W, discharge_w=MAX_W,
+                    soc_floor_pct=20.0, soc_ceiling_pct=95.0)
+_reasons = [_no_plan.reason, _no_soc.reason, _uncovered.reason, _blind.reason,
+            _held.reason]
+check("no plan, no state of charge, an uncovered hour, an unmeasured peak and "
+      "a held peak are five DISTINCT reasons - none of them silence, none of "
+      "them each other",
+      len(set(_reasons)) == 5
+      and all(a.action is None for a in
+              (_no_plan, _no_soc, _uncovered, _blind, _held)))
+check("...and none of them is empty: `_idle` refuses a blank reason at the "
+      "call site, so a status line cannot decay into nothing",
+      all(r.strip() for r in _reasons)
+      and raises(lambda: _arb._idle(""), ValueError))
+# The no-data plan: `price_at` must RAISE rather than answer 0.0, and 0.0 is
+# exactly the value that would make every hour look like the cheapest.
+_empty = TariffPlan(PriceRead.no_data("nothing was fetched"), None, "none")
+check("a plan built on a no_data read trades nothing, and asking it for a "
+      "price RAISES rather than answering 0.0 - 'no data' becoming 'free' is "
+      "the defect this whole type family exists to remove",
+      act(_empty, 0, thresh=0.0).action is None
+      and raises(lambda: _empty.price_at(hour(0)), Absence))
+
+# SoC: the reserve and the headroom, each graded where the other cannot explain
+# the answer.
+check("at the reserve FLOOR the sell hour does nothing, and the reason names "
+      "the floor rather than the price",
+      act(PLAN, DEAR_H, thresh=0.0, soc=20.0, floor=20.0).action is None
+      and "reserve floor" in act(PLAN, DEAR_H, thresh=0.0, soc=20.0,
+                                 floor=20.0).reason)
+check("...one percent above it, the same hour sells - so the refusal is about "
+      "the floor and not about the hour",
+      act(PLAN, DEAR_H, thresh=0.0, soc=21.0, floor=20.0).action == DISCHARGE)
+check("at the CEILING the buy hour does nothing, and one percent below it buys",
+      act(PLAN, CHEAP_H, thresh=0.0, soc=95.0, ceiling=95.0).action is None
+      and act(PLAN, CHEAP_H, thresh=0.0, soc=94.0,
+              ceiling=95.0).action == CHARGE)
+check("...and a FULL pack in a NEGATIVE sell hour reports §17 rather than the "
+      "SoC - the rule that actually forbids the trade is the one logged",
+      "§17" in act(NEG_PLAN, DEAR_H, thresh=0.0, soc=20.0,
+                   floor=20.0).reason)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("6. the claim, and what NO claim means")
+
+check("an idle decision files NO claim - not a 0 W one, which would out-rank "
+      "the loop with a park order and silently switch self-consumption off on "
+      "every site that armed arbitrage",
+      claim(_held) is None and claim(_no_plan) is None)
+_idle_res = resolve([Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W),
+                     Claim.set("loop", P_LOOP, -120.0, "following")])
+check("...demonstrated through the arbiter: with arbitrage idle the loop's "
+      "number is what goes on the wire, unchanged",
+      near(_idle_res.target_w, -120.0) and _idle_res.winner == "loop")
+check("...whereas a trading decision DOES out-rank the loop, which is the "
+      "point: the loop would otherwise cancel every charge the moment it "
+      "created import",
+      resolve([Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W),
+               Claim.set("loop", P_LOOP, -120.0, "following"),
+               _charge_claim]).winner == _arb.SOURCE)
+check("the claim carries the §10.2 reason code, so the action log names the "
+      "strategy rather than describing it",
+      _charge_claim.reason == CHARGE and claim(_sell).reason == DISCHARGE)
+# SAFETY-02's arming gate, which an arbitrage winner must NOT leave armed.
+check("SAFETY-02 is disarmed while arbitrage drives, exactly as it is during a "
+      "maintenance grid charge: the strategy commands AGAINST the meter on "
+      "purpose, so sign agreement is not the expectation",
+      _main.loop_is_following(
+          resolve([Claim.limit("supervised", P_SAFETY, -MAX_W, MAX_W),
+                   Claim.set("loop", P_LOOP, -120.0, "following"),
+                   _charge_claim]), -120.0) is False)
+check("...and it is still ARMED when arbitrage is idle and the loop wins, so "
+      "the line above is not simply a watchdog that never fires",
+      _main.loop_is_following(_idle_res, -120.0) is True)
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("7. AC4 - 12 months of replayed prices, and what could NOT be measured")
+
+# ⚠️ READ THIS BEFORE READING THE NUMBERS BELOW.
+#
+# The acceptance criterion is "net-positive across 12 months of replayed prices
+# in simulation". THIS REPOSITORY CONTAINS NO PRICE HISTORY. `scenarios/` holds
+# three gzipped captures and all three are P1 METER data - two days of net power
+# from the reference house plus one age capture. There is no EPEX archive, no
+# supplier export, and no CSV of a past year anywhere in the tree.
+#
+# TARIFF-01 and SAFETY-07 both hit an unmeetable criterion and both DECLINED to
+# redefine it into one they could pass, and both were upheld for it. So:
+#
+#   AC4 IS NOT MET, AND IT IS NOT RESTATED. What follows is not a replay of the
+#   Belgian market; it is a replay of a SYNTHETIC year, and a euro figure from a
+#   synthetic year grades the generator that produced it, not the strategy.
+#
+# What the replay is FOR is the half of AC4 that does not need real prices. Net
+# positivity here is not an empirical outcome to be hoped for - it is a property
+# of the decision rule, and the replay's job is to demonstrate that the property
+# holds on every trade the strategy actually chose, over a year of varied days
+# including negative-price ones. Stated as an invariant:
+#
+#     every executed round trip has (sell - buy) >= required >= threshold,
+#     so its benefit net of the threshold is >= 0, on every day, always.
+#
+# That is asserted per trade below, over 365 days. What it does NOT establish -
+# and no synthetic series could - is how OFTEN a real Belgian year clears the
+# threshold, which is the actual open question and the reason the shipped
+# default is a product decision rather than a number this card picked.
+
+def synth_day(n):
+    """A synthetic all-in day-ahead day. Deterministic, seeded by day number.
+
+    A seasonal base plus a two-peak diurnal shape plus a per-day amplitude, and
+    a summer midday block that is driven NEGATIVE - the §17 case has to occur in
+    the replay or the replay never exercises it.
+    """
+    import math
+    base = 0.22 + 0.06 * math.cos(2 * math.pi * (n - 10) / 365.0)
+    amp = 0.05 + 0.09 * abs(math.sin(n * 1.7))          # varies day to day
+    out = []
+    for h in range(24):
+        shape = (math.sin(2 * math.pi * (h - 8) / 24.0)
+                 + 0.6 * math.sin(4 * math.pi * (h - 5) / 24.0))
+        p = base + amp * shape
+        if 140 < n < 230 and 11 <= h <= 14:             # summer solar glut
+            p -= 0.45 * amp * 6
+        out.append(round(p, 6))
+    return out
+
+
+REPLAY_START = datetime(2026, 1, 1, 0, 0, tzinfo=UTC)
+CAP_WH = 10000.0            # the pack the replay moves energy through
+STEP_PCT = 100.0 * MAX_W / CAP_WH    # one hour at the rail, in percent
+
+
+def replay(threshold, unc, *, soc0=50.0, floor=20.0, ceiling=95.0):
+    """Run `decide()` over a synthetic year. Returns the ledger, nothing else."""
+    soc = soc0
+    trades, holdings, bad = [], [], []
+    neg_sells = 0
+    for n in range(365):
+        day0 = REPLAY_START + timedelta(days=n)
+        prices = synth_day(n)
+        plan = plan_of(prices, start=day0)
+        open_buy = None
+        for h in range(24):
+            d = act(plan, h, thresh=threshold, unc=unc, soc=soc, floor=floor,
+                    ceiling=ceiling, start=day0)
+            if d.action is None:
+                continue
+            price = prices[h]
+            if d.action == CHARGE:
+                soc = min(ceiling, soc + STEP_PCT)
+                open_buy = (price, d)
+            else:
+                if price < 0:
+                    neg_sells += 1
+                soc = max(floor, soc - STEP_PCT)
+                if open_buy is not None:
+                    buy_price, buy_d = open_buy
+                    trades.append((buy_price, price, d))
+                    open_buy = None
+                else:
+                    holdings.append((n, h, price))
+            if d.spread_eur_kwh is None or d.required_eur_kwh is None:
+                bad.append((n, h))
+    return trades, holdings, bad, neg_sells
+
+
+_trades, _held_over, _bad, _neg_sells = derived(
+    lambda: replay(0.05, NO_WEATHER)) or (None, None, None, None)
+_kwh = MAX_W / 1000.0
+check(f"the replay is 365 days long and actually traded ({len(_trades)} "
+      f"completed round trips), or every invariant below would hold vacuously",
+      len(_trades) > 30)
+check("...and every trade carries the spread and the threshold it cleared, so "
+      "the ledger is auditable rather than a count",
+      _bad == [])
+check("...and NOT every day traded, so the strategy is selective rather than "
+      "unconditional - a replay in which everything trades grades nothing",
+      len(_trades) < 365)
+_losses = [(b, s) for b, s, _ in _trades if s - b < 0.05]
+check(f"EVERY completed round trip cleared the threshold it was run at: sell "
+      f"minus buy >= 0.05 EUR/kWh on all {len(_trades)} of them "
+      f"({len(_losses)} exceptions)", _losses == [])
+_under = [d.spread_eur_kwh for _b, _s, d in _trades
+          if d.spread_eur_kwh < d.required_eur_kwh]
+check("...and each one cleared its own WIDENED requirement, which is the "
+      "stricter statement and the one §8.3 actually asks for",
+      _under == [])
+_net = sum((s - b - 0.05) * _kwh for b, s, _ in _trades)
+check(f"so the replayed year is net-positive BY CONSTRUCTION, not by luck: "
+      f"{_net:+.2f} EUR of benefit net of the cycle cost over "
+      f"{len(_trades)} trades at {_kwh:.1f} kWh each, and no single trade "
+      f"contributes a negative term", _net > 0)
+check(f"§17 held for the whole year: {_neg_sells} discharges into a "
+      f"negative-price hour", _neg_sells == 0)
+# ...and the replay really did contain negative hours, or the line above is
+# a count of something that never had the chance to happen.
+_neg_hours = sum(1 for n in range(365) for p in synth_day(n) if p < 0)
+check(f"...and it had the chance to fail: {_neg_hours} hours of the synthetic "
+      f"year are priced below zero", _neg_hours > 100)
+# The shipped default, over the same year. Reported, not tuned.
+_sh_trades = derived(lambda: replay(_shipped, NO_WEATHER)[0])
+print(f"     [report] at the SHIPPED threshold {_shipped} EUR/kWh widened by "
+      f"{widen_factor(NO_WEATHER)}x, the same synthetic year completes "
+      f"{len(_sh_trades)} round trips; at 0.05 it completes {len(_trades)}. "
+      f"The shipped default is deliberately conservative and the number that "
+      f"matters is the one a REAL year would give, which this repository "
+      f"cannot answer.")
+check("the shipped threshold is strictly more selective than the loose one on "
+      "the same year - the parameter does what it says, at whatever value the "
+      "owner sets it to",
+      len(_sh_trades) < len(_trades))
+check("AC4 IS REPORTED AS NOT MET rather than redefined: this file says so in "
+      "section 7's preamble, and there is no price history in the repository "
+      "to meet it with",
+      not any(f.endswith((".csv", ".json.gz"))
+              and "price" in f.lower()
+              for f in os.listdir(os.path.join(HERE, "scenarios"))))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("8. the background refresh - the tick must never await a fetch")
+
+
+_MAIN_SRC = derived(lambda: open(os.path.join(HERE, "app", "main.py"),
+                                 encoding="utf-8").read())
+_cycle = derived(lambda: _fn(_MAIN_SRC, "cycle"))
+_refresh = derived(lambda: _fn(_MAIN_SRC, "run_tariff_refresh"))
+_read_inputs = derived(lambda: _fn(_MAIN_SRC, "read_inputs"))
+_FETCHERS = {"resolve_tariff", "load_prices", "https_get"}
+check("app/main.py has a run_tariff_refresh() coroutine at all",
+      _refresh is not None)
+check("...and IT is what awaits resolve_tariff(), so the fetch has somewhere "
+      "to live that is not the control path",
+      isinstance(_refresh, ast.AsyncFunctionDef)
+      and "resolve_tariff" in _awaited(_refresh))
+# ⚠️ THE FORWARD HAZARD, AND IT IS THE ONE THE CARD CALLS THE MOST DANGEROUS
+# THING IN THIS TICKET. cycle() and read_inputs() are both on the path that
+# feeds the ESP32 heartbeat; layer 1 commands 0 W if that stops for ~30 s. A
+# supplier's TLS timeout on either of them is a SUPPLIER able to drive this
+# add-on into the failsafe. Nothing warns about it at runtime - the add-on would
+# simply be slow - so it is asserted structurally, on the shipped AST.
+check(f"cycle() awaits NONE of {sorted(_FETCHERS)} - a supplier's TLS timeout "
+      f"on the tick is a supplier able to push this add-on towards layer 1's "
+      f"30 s veto {sorted(_awaited(_cycle))}",
+      isinstance(_cycle, ast.AsyncFunctionDef)
+      and not (_awaited(_cycle) & _FETCHERS))
+check("...and neither does read_inputs(), which is on the same path and is "
+      "where a fetch would most naturally be put",
+      isinstance(_read_inputs, ast.AsyncFunctionDef)
+      and not (_awaited(_read_inputs) & _FETCHERS))
+check("...and the check above can fail: the scanner really does find the "
+      "awaits that ARE there",
+      "resolve_tariff" in _awaited(_refresh)
+      and len(_awaited(_cycle)) > 0)
+
+# The age bound, driven on the shipped expression rather than a copy of it.
+class _Stub:
+    """Just enough Controller for fresh_tariff_plan(), which touches nothing else."""
+    fresh_tariff_plan = _main.Controller.fresh_tariff_plan
+
+    def __init__(self, plan, at):
+        self.tariff_plan, self.tariff_at = plan, at
+
+
+_NOW = datetime(2026, 6, 1, 12, 0, tzinfo=UTC)
+_fresh_s = _main.TARIFF_MAX_AGE_S
+# ⚠️ THE ABSOLUTE PROBE COMES FIRST, AND THE FIRST DRAFT SHOWED WHY. Probing at
+# `TARIFF_MAX_AGE_S + 1` reads the constant under test, so widening the constant
+# moves the probe with it and the check passes for a bound that has been made
+# unreachable - a mutation multiplying it by a million SURVIVED that draft.
+# Twelve hours is stale by any reading of a feed that publishes daily, and it is
+# stated here rather than derived from the module being graded.
+check("a plan resolved TWELVE HOURS ago is not handed to the strategy, whatever "
+      "the module's own constant says - a stale price is not a fresh one",
+      _Stub(PLAN, _NOW - timedelta(hours=12)).fresh_tariff_plan(_NOW) is None)
+check(f"...and the constant is inside the range that makes that true: "
+      f"{_fresh_s:.0f} s is under six hours and over one refresh interval",
+      _main.TARIFF_REFRESH_S < _fresh_s < 6 * 3600)
+check("a plan resolved a moment ago IS handed to the strategy, so the two "
+      "lines above are a bound rather than a blanket refusal",
+      _Stub(PLAN, _NOW - timedelta(seconds=1)).fresh_tariff_plan(_NOW) is PLAN)
+check(f"...and the bound is where the module says it is: one second past "
+      f"{_fresh_s:.0f} s fails and one second short of it passes",
+      _Stub(PLAN, _NOW - timedelta(seconds=_fresh_s + 1)
+            ).fresh_tariff_plan(_NOW) is None
+      and _Stub(PLAN, _NOW - timedelta(seconds=_fresh_s - 1)
+                ).fresh_tariff_plan(_NOW) is PLAN)
+check("a plan with no timestamp is not fresh either - both terms are required, "
+      "and 'nothing stored it' is not 'it is current'",
+      _Stub(PLAN, None).fresh_tariff_plan(_NOW) is None
+      and _Stub(None, _NOW).fresh_tariff_plan(_NOW) is None)
+check("the refresh cadence is strictly under the age bound, or the plan would "
+      "expire between two healthy refreshes and arbitrage would flicker",
+      _main.TARIFF_REFRESH_S < _main.TARIFF_MAX_AGE_S)
+# CFG-03: main.py gained no fourth copy of an option default.
+_names = derived(lambda: {n.id for n in ast.walk(ast.parse(_MAIN_SRC))
+                          if isinstance(n, ast.Name)})
+check("main.py reads every arbitrage option through app/arbitrage.py or "
+      "price_option(), never through `o.get('cycle_cost_threshold_eur', <a "
+      "number>)` - CFG-03 still tracks three places, not four",
+      all(f'"{k}"' not in _MAIN_SRC and f"'{k}'" not in _MAIN_SRC
+          for k in ("cycle_cost_threshold_eur", "arbitrage_soc_floor",
+                    "arbitrage_soc_ceiling")))
+
+
+# --------------------------------------------------------------------------- #
+print()
+print("9. the startup gate - the configurations that cannot work are refused")
+
+
+def vbase(**over):
+    o = {"setpoint_entity": "number.goodwe_setpoint", "max_w": 2000,
+         "soc_entity": "sensor.soc", "batt_entity": "sensor.batt",
+         "meter_source": "off",
+         "maintenance_charge_w": 2000, "maintenance_discharge_w": 2000}
+    o.update(over)
+    return o
+
+
+def why(problems, needle):
+    return any(needle in p for p in problems)
+
+
+P1_ON = {"meter_source": "ha_signed", "p1_net_entity": "sensor.p1"}
+check("the shipped configuration still starts - arbitrage_enabled ships off "
+      "and this ticket may not have made an existing install unbootable",
+      validate_startup_config(vbase(), -5000, 5000) == []
+      and enabled({}) is False)
+check("arbitrage on with a provider and P1 starts",
+      validate_startup_config(
+          vbase(arbitrage_enabled=True, price_provider="generic_dayahead",
+                **P1_ON), -5000, 5000) == [])
+check("...and so does arbitrage on a static profile with P1, because §9.2 "
+      "makes a static site first-class rather than unsupported",
+      validate_startup_config(
+          vbase(arbitrage_enabled=True, static_profile=STATIC_BE, **P1_ON),
+          -5000, 5000) == [])
+check("arbitrage on with NO price source at all is refused - a strategy that "
+      "must refuse on every cycle forever looks exactly like one that is "
+      "running and finding nothing",
+      why(validate_startup_config(vbase(arbitrage_enabled=True, **P1_ON),
+                                  -5000, 5000), "NO PRICES AT ALL"))
+check("arbitrage on with meter_source off is refused - §9.1 puts peak shaving "
+      "above arbitrage and an unmeasured peak cannot be shaved",
+      why(validate_startup_config(
+          vbase(arbitrage_enabled=True, price_provider="generic_dayahead"),
+          -5000, 5000), "meter_source"))
+check("a floor at or above the ceiling is refused - there is no band left "
+      "between them and the strategy could never act",
+      why(validate_startup_config(
+          vbase(arbitrage_enabled=True, price_provider="generic_dayahead",
+                arbitrage_soc_floor=90, arbitrage_soc_ceiling=90, **P1_ON),
+          -5000, 5000), "no band left"))
+check("...and the same numbers the right way round start",
+      validate_startup_config(
+          vbase(arbitrage_enabled=True, price_provider="generic_dayahead",
+                arbitrage_soc_floor=25, arbitrage_soc_ceiling=90, **P1_ON),
+          -5000, 5000) == [])
+check("a NEGATIVE cycle_cost_threshold_eur is refused even with arbitrage OFF "
+      "- it is a cost, and a negative one is a threshold every spread clears",
+      why(validate_startup_config(vbase(cycle_cost_threshold_eur=-0.01),
+                                  -5000, 5000), "non-negative")
+      and raises(lambda: threshold_eur_kwh({"cycle_cost_threshold_eur": -1}),
+                 ValueError))
+# Rule 7's wording, which OPT-04 had to update because it named what main.py
+# did NOT do. test_price.py section 12 pins the load_prices consumer set; this
+# pins the sentence that set exists to keep honest.
+_V = derived(lambda: open(os.path.join(HERE, "app", "validate.py"),
+                          encoding="utf-8").read())
+check("rule 7's message no longer says a configured provider shapes no energy "
+      "decision - OPT-04 made that false, and the instruction attached to the "
+      "tripwire was to fix the wording rather than to silence the check",
+      isinstance(_V, str)
+      and "shape no energy decision" not in _V
+      and "still shapes no energy decision" not in _V)
+check("...and it names the consumer that now exists, so it cannot decay into a "
+      "refusal with no stated reason",
+      isinstance(_V, str) and "app/arbitrage.py" in _V)
+# The option mirror, pinned to config.yaml the way TARIFF-02 pinned the rest.
+_CFG = derived(lambda: open(os.path.join(HERE, "config.yaml"),
+                            encoding="utf-8").read())
+check("every option this card added is in config.yaml's options block AND its "
+      "schema block, or the Supervisor drops it and the add-on silently runs "
+      "on the mirror instead of the operator's value",
+      isinstance(_CFG, str)
+      and all(_CFG.count(f"\n  {k}:") == 2
+              for k in ("arbitrage_enabled", "cycle_cost_threshold_eur",
+                        "arbitrage_soc_floor", "arbitrage_soc_ceiling")))
+check("...and app/arbitrage.py reads them through price_option() only - one "
+      "read path, one place the defaults live",
+      "PRICE_OPTION_DEFAULTS[" not in
+      open(os.path.join(HERE, "app", "arbitrage.py"), encoding="utf-8").read())
+check("soc_bounds() returns the shipped pair, floor first",
+      soc_bounds({}) == (float(PRICE_OPTION_DEFAULTS["arbitrage_soc_floor"]),
+                         float(PRICE_OPTION_DEFAULTS["arbitrage_soc_ceiling"])))
+
+
+# --------------------------------------------------------------------------- #
+print()
+if fails:
+    print(f"{len(fails)} FAILED: " + "; ".join(fails))
+    sys.exit(1)
+print("all checks passed")

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