Merge remote-tracking branch 'origin/release/1.0' into TARIFF-11

# Conflicts:
#	goodwe_controller/CHANGELOG.md

goodwe_controller/CHANGELOG.md

@@ -19,6 +19,418 @@ if it has, it needs 0.10.0. Whoever deploys decides.
 | _this branch_ | TARIFF-09 - the day-ahead feed is asked for the horizon it was given, so tomorrow arrives firm instead of carried |
 | _this branch_ | TARIFF-10 - configuring a price provider is what fetches prices; trading stays its own switch |
 | _this branch_ | TARIFF-12 - a supplier outage stops deleting the plan on its first failed fetch, and TARIFF_MAX_AGE_S starts governing |
+| _this branch_ | TARIFF-14 - the price a trade is decided against is the price of the interval being traded |
+| _this branch_ | TARIFF-07 - three plugins that never fetched a price are withdrawn, and a site configured on one is told so **⚠️ BACKWARD-INCOMPATIBLE** |
+| _this branch_ | TARIFF-15 - `custom_formula`: your own tariff card's two coefficients, graded against the card's own printed price |
+| _this branch_ | TARIFF-13 - the capacity-tariff row's "quarter(s) banked" stops resetting to 0 at every restart, and a tied peak's quarter stops moving |
+| _this branch_ | TARIFF-11 - the add-on's account of the tariff plan stops flattering it, and the status page is graded as a surface |
+
+⚠️ **A CONFIG THAT STARTS ON THE CURRENT VERSION CAN BE REFUSED ON THE NEXT
+ONE.** TARIFF-07 withdraws `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy`. `price_provider` set to any of those three is now **refused at
+startup** — `SystemExit(78)` (`EX_CONFIG`), the add-on does not start — where
+it was accepted before. That is as backward-incompatible as it gets, and it is
+**the point of the change** rather than a side effect of it: see the next
+paragraph for why starting was the worse outcome. Same shape as 0.8.0's
+`slew_w` rule, and the same instruction follows — **read the live options and
+check `price_provider` against the withdrawn list BEFORE `ha addons update`.**
+That check is NOT performed by this branch and cannot be.
+
+⚠️ **THE REFUSAL IS THE MIGRATION, BECAUSE THERE WAS NOTHING TO MIGRATE.** All
+three pointed at endpoints that **do not exist and never did** — verified by
+hand on 2026-09-13: a 404 from a gateway with no route, a TLS hostname the
+certificate does not cover, and a 404 with an empty body. Every fetch any of
+them ever made failed, and §11.4 turns a failed fetch into a **silent** fall
+back to the static profile. So a site configured on one of these has been
+running on `static_profile` — **or on nothing at all, where none was set** —
+since the day the id was entered, with nothing on its status page ever
+differing from a working provider that never found a cheap hour. The refusal
+names the id, the endpoint, what that endpoint actually answers, which tariff
+has really been in force, and what to set instead. **Starting quietly is what
+hid this; it is not an option that was on the table.**
+
+⚠️ **THERE IS NO ALIAS AND THERE WILL NOT BE ONE.** These were retail tariffs
+of the form `B × spot + A` with **per-contract** coefficients that live behind
+the customer's supplier login; CREG's tariff-card pages 404 and VREG was
+unreachable, so there is no public index to read them from. An alias to
+`generic_dayahead` — which reads *wholesale* — would have to invent the numbers
+a battery is priced against. A formula provider is the planned answer and is a
+separate card. *(Annotated 2026-09-13: that card is **TARIFF-15**, below, and it
+shipped on this branch as `custom_formula`. It is still not an alias — the
+operator types their own coefficients; nothing is invented on their behalf.)*
+
+### TARIFF-13 - the coverage figure beside the peak, and which quarter gets it
+
+**The capacity-tariff status row's `N quarter(s) banked` is read from the
+database instead of from process memory.** It was an `int` on `PeakTracker`,
+starting at 0 and counted up inside `sync()`, printed next to a peak read from
+SQLite. A 40-hour soak caught what that means at a restart, on both instances:
+
+```
+before: 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit; 120 quarter(s) banked
+after : 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit;   0 quarter(s) banked
+```
+
+The peak is durable and was never wrong. The **count** is what says how much of
+the billing month that peak covers, and 365 W over 120 quarters and 365 W over
+0 quarters are different claims about the same number — so mid-month, after
+every restart, the page made the weaker claim while showing the stronger one's
+value. TARIFF-01's rule that an unreadable store must not read as a zero peak,
+one column over. Two more defects in the same variable, neither in the ticket:
+it was **never scoped to a month** (on 1 October the row still showed
+September's tally beside October's empty month), and it **missed the block
+`restore()` banks** from the checkpoint at startup.
+
+⚠️ **AN UNREADABLE STORE NOW SAYS SO IN THAT CLAUSE.** Where the database will
+not answer a count, the row reads `an unreadable number of quarter(s) banked`.
+`0` was never available; `None` was rejected too, because `None quarter(s)
+banked` reads as the same zero. `0 quarter(s) banked` stays true and reachable —
+it is what a month nothing has been written to says.
+
+⚠️ **AND A TIED PEAK'S ATTRIBUTED QUARTER IS NOW DECIDED: the EARLIEST wins.**
+The wattage is what the utility bills, so this changes no bill and no guard —
+`peak_w` is still only ever raised and SAFETY-07 reads the same watts. What it
+changes is the answer to "when did my monthly peak happen", which an operator
+goes and investigates; it now stops moving. The two readers of that record
+**did** disagree: the `monthly_peak` upsert's strict `>` kept whichever tied
+block was *written* first, while `recompute_month()` has always kept the
+earliest — the same by accident only while blocks arrive in time order, and
+measured to diverge (09:45 against 09:00) when they do not.
+
+⚠️ **THE SOAK'S DRIFTING QUARTER WAS NOT A TIE, AND IS LEFT ALONE.** Driven,
+exactly equal quarters never re-attributed at all. What moved the timestamp was
+a genuine new maximum **below the row's whole-watt resolution** — 365.0000001 W
+is a new peak to the database and the same `365 W` to the reader. That is the
+instrument being right, and printing more decimals to explain it would put
+noise in the one row an operator reads when the guard engages.
+
+Reasoning in `DECISIONS/TARIFF-13-the-coverage-of-a-peak.md`; parts 11 and 12
+of `test_tariff.py` drive a real restart — a second `Controller` against the
+same file — and pin both decisions.
+### TARIFF-11 - the plan's own account of itself, corrected and put on the page
+
+**Four defects, one shape: every one of them made the add-on look better than
+it was.** They shipped together because nothing in this repository graded the
+strings a human is shown — every tariff check inspects the `TariffPlan`
+*object*, and all four were in the *sentences* built out of it.
+
+**1. `TariffPlan.words` counted points and called them hours.** The live
+add-on logged `dynamic_dayahead from generic_dayahead, 132 h` for **132
+quarter-hourly points = 33 hours**. Belgium moved to a 15-minute MTU on
+2025-10-01, so on the real feed this was wrong every time it was printed, and
+⚠️ **not by a constant factor**: measured across a 40-hour soak the
+overstatement ranged **1.79× to 5.33×**, because §8.3's carried points are
+hourly while the firm ones are quarter-hourly and the ratio moves with the mix
+through the day. It now reads
+
+```
+dynamic_dayahead from generic_dayahead, 132 points over 33 h,
+132 firm / 0 carried, 900 s spacing
+```
+
+— the same plan, with each number in its own unit. On the weekday morning that
+plan is partly carried and reads `60 points over 33 h, 36 firm / 24 carried,
+900+3600 s spacing, provisional` instead, which is the state the soak found an
+operator could learn nothing about. The `N points over H h` wording is
+FCST-04's *Price history* wording on purpose, so the two rows describing the
+same feed can be compared rather than being two conventions on one page.
+
+**2. The §8.3 and flat-tariff refusals did the same, and they reach an
+operator.** `§8.3: only 1 of 96 hours carry a published price` is 96 points,
+which is 24 hours; the flat rung counted the same points and called them `firm
+hours`. ⚠️ **This is exactly the point≠hour conflation TARIFF-14 removed from
+`at()`, left standing in the prose that describes it** — and it is not confined
+to a log line, because `self.arb.explain()` puts it on the status page. Both
+now print the two quantities separately: `only 1 of 96 points carry a published
+price - 1 of 24 hours`. The same conflation in `price_forecast.py`'s §8.3
+carry-forward log line — `%d of %d hours` with a carried-HOUR count over a
+POINT count — is corrected in the same commit.
+
+**3. The plan reached no HTTP surface at all.** `origin`, `product`, the
+firm/carried split and the spacing appeared in **no** status row. `rows["Tariff"]`
+was `static_status()`'s sentence, computed on the 30 s I/O-free tick from its
+own static plan, and it **never saw the provider plan** — it read `'no static
+profile'` at all **802** soak samples on a site whose feed was answering. So an
+operator could not tell a working dynamic tariff from no tariff machinery at
+all, and could not learn that the plan was `provisional` for 76 % of the soak
+or mixed 900/3600 s for 70 %. The *Tariff* row now carries the plan.
+
+⚠️ **The two halves of that row are not computed at the same moment and the row
+says so.** `static_status()` runs on the 30 s tick; the provider plan comes off
+the 1800 s background refresh and is served for up to `TARIFF_MAX_AGE_S`
+(5400 s since TARIFF-12). So the plan half is stamped with **its own age**,
+measured from `tariff_at` — which TARIFF-12 deliberately does not move on a
+kept plan. A provider site with no usable plan says that too, rather than
+falling silently back to the static sentence.
+
+**4. `main.py`'s "if and only if" was false, and the row named an option that
+was on.** TARIFF-10's comment asserted that `self.arb is None` **iff**
+`arbitrage.enabled(self.o)` was False. `cycle()` returns at the input hold —
+inputs missing, `bad_for < stale_input_s`, 15 s by default — **before** it
+reaches `self.arb = None`. Driven: `arbitrage_enabled: true` plus a sensor
+answering `None` gives `arbitrage.enabled(opts) = True`, `self.arb = None` and
+a row reading `off (arbitrage_enabled)`. Past the first completed cycle the
+same early return leaves the **previous** decision standing, which the row
+rendered as a current one, up to ~15 s stale. The row now distinguishes three
+facts with three remedies — trading is off; trading is on and this cycle
+reached no decision; a decision, with its age — and it reads the **option**
+rather than inferring it from a missing decision. The comment states what is
+true.
+
+⚠️ **THE DELIVERABLE IS THE CHECK, NOT THE FIXES.** All four survived 29 green
+suites because no check in this repository had ever read a rendered row.
+`test_price.py` section 12 renders through the shipped `Controller.status_payload()`,
+parses each number out of the row **by its own slot**, and compares it against
+a figure computed from the fixture's own construction parameters — never from
+the property the row was built out of (MUTATION.md habit 4). It is deliberately
+**not** a substring test over a sentence the same file wrote: `"132 points" in
+row` is satisfied by the number appearing in the *other* number's slot, which
+habit 14 shows is a zero-byte edit away. The fixtures are a **set** of four
+plan shapes, and the check computes and prints the table of field pairs no
+fixture separates — `none` — so a pair that became degenerate would go red
+rather than quietly vacuous. The *Arbitrage* row's three states are driven
+through real cycles with a sensor answering `None`, and graded by
+**inequality**: two facts that must not render identically.
+
+**Nothing about what the battery decides changes.** No threshold, no refusal
+rung, no claim, no setpoint. Every edit is to a sentence, to a derived counter
+behind one, or to where a sentence is rendered.
+
+### TARIFF-15 - your own tariff card, as two coefficients
+
+**New price provider `custom_formula`, and one new option, `price_formula`.**
+A Belgian dynamic contract prices energy as `B × index + A`; the two
+coefficients live on the customer's own tariff card and **nowhere else**.
+There is no machine-readable source for them anywhere — CREG's consumer
+tariff-card pages 404, CREG Scan is a JavaScript wizard, the annual report
+carries the supplier list without per-product coefficients, VREG was
+unreachable, and every coefficient found in research came off a supplier's own
+PDF, one image-only. So there is nothing to scrape and a per-supplier plugin
+would have no source for its numbers — which is precisely why TARIFF-07
+withdrew three of them. **The customer is the only party who can see their own
+coefficients.** They type them, once:
+
+```json
+{"index": "epex_be", "resolution": "hourly",
+ "factor": 0.102, "offset": 1.00,
+ "units": "c_eur_per_kwh", "vat_pct": 6,
+ "card": {"month": "2026-09", "index_eur_per_mwh": 133.9905,
+          "expect_incl_vat": 15.55}}
+```
+
+`price = (factor × index_eur_per_mwh + offset) × (1 + vat_pct/100)`, in
+`units`, **converted to EUR/kWh by the add-on**. The operator types what the
+card prints, in the card's own units; every unit conversion and the VAT
+multiplication are the add-on's job, because those are the two steps that
+silently cost a factor of 10, 100 or 1.06.
+
+**The index is `generic_dayahead`'s, not a second one** — same EPEX BE feed,
+same Brussels-calendar range request, same columnar parser, same declared
+egress hosts. The URL decision is now one function both plugins call, so a
+short-horizon or override bug cannot exist in one and not the other.
+`resolution: quarter_hourly` emits the feed's 96 points as they are;
+`hourly` averages each hour's members. Neither is `_Series.at()`'s hourly
+assumption returning: it decides how many points are **emitted**, and the
+window each one covers is still derived from its neighbours (TARIFF-14).
+
+⚠️ **It declares `{ENERGY, MARKUP}`, not `ALL_IN`, and that is the whole safety
+argument.** A Belgian card's `Tariefformule` line is the **energy component
+only** — Eneco tabulates network tariffs in one table and levies in a second,
+ENGIE states that the formula excludes network, distribution, transport, grid
+levies and excise. Declaring `ALL_IN` would lie on behalf of every operator who
+typed exactly what their card says, and would drop `price_taxes_eur_kwh` from
+every hour. Measured: 0.2125 → 0.1555 EUR/kWh, silently.
+
+⚠️ **THE CARD IS THE GRADER, AND IT IS WHY THIS IS SAFE TO SHIP.** The
+framework already mechanises that a *plugin* cannot double-count
+(`PluginOptions`, `FRAMEWORK_KEYS`, `code_leaks()`). This provider introduces a
+risk none of those can see, because it is **config, not code**: the *operator*
+double-counting, by folding network charges into `offset` while
+`price_taxes_eur_kwh` carries them too. So:
+
+> At startup `validate.py` computes
+> `(factor × card.index_eur_per_mwh + offset) × (1 + vat_pct/100)` and
+> **refuses to start** unless it equals `card.expect_incl_vat` to within
+> `0.01`, naming the discrepancy, the ratio and the likely causes.
+
+An inflated `offset` **cannot pass**: the printed estimate is the energy
+component alone, so ~12 c€/kWh of network charge moves the computed 15.55 to
+28.27 and the add-on stops. The same check catches VAT omitted, VAT applied
+twice, a transposed digit, and a unit mismatch between the coefficients and the
+printed price.
+
+⚠️ **And the limit, in the same sentence as the claim: it grades the
+coefficients against the card, not the card against reality.** A
+consistent-but-wrong pair — both numbers off the wrong product — reproduces its
+own printed price perfectly and passes. Nothing can catch that. A **second**
+refusal covers the one unit error the first cannot see, the one applied to both
+sides at once: the card's own point must land inside 0.02–1.00 EUR/kWh. Its
+floor is applied to the **energy** figure rather than the all-in one, because
+the shipped 0.06 of taxes is three times that floor and would carry a
+hundredfold error over it on its own — measured, and driven red by a mutation.
+
+**The market's own arithmetic, reproduced to the digit the supplier prints.**
+Both cards that were readable print the formula, the index they assumed *and*
+the resulting price:
+
+| | computed by the shipped code | the card prints |
+|---|---|---|
+| Eneco `(0.102 × 133.9905 + 1) × 1.06` | **15.5471** | **15,55** |
+| ENGIE `(0.1 × 61.96 + 0.9) × 1.06` | **7.5218** | **7,522** |
+
+⚠️ **No expression evaluation of any kind, and a check that fails if one ever
+appears.** `price_formula` takes numbers; there is no field that accepts an
+expression and an **unrecognised field is refused rather than ignored**, so
+typing `"expr"` is told it does not exist instead of quietly pricing the site
+on the fields beside it. Two reasons, and the second decides it:
+
+* the string is settable over HTTP — the add-on's own ingress page posts it to
+  `/addons/self/options` — so `eval` on it is RCE in a root container holding
+  `SUPERVISOR_TOKEN`, with `homeassistant_api` and `hassio_api`, driving an
+  inverter over RS485;
+* **an expression is unverifiable.** Two coefficients can be graded against the
+  card's printed price; an arbitrary expression cannot be graded against
+  anything, so it would make the invisible-wrong-coefficient problem *strictly
+  worse* — the exact failure this provider exists to prevent.
+
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B × index + A`. Future shapes become **named fields** (`clamp_lo`,
+`factor_negative`, `offset_bands`), each individually refusable and each
+gradeable against a card. Never a grammar. `test_price.py` 15f walks
+`app/custom_formula.py`'s AST for `eval`/`exec`/`compile`/`__import__`/
+`literal_eval` and exercises the scanner's **red** direction on every run.
+
+**Refused at startup, not at 03:00.** `card` absent or failing by more than
+0.01; `units` absent (no default, on purpose — the same convention is printed
+two ways by two suppliers); `factor == 0`, which makes every spread 0 and
+arbitrage silently never fire (the message points at `static_profile`, which is
+the first-class way to say "one price"); `factor < 0`, which inverts the market
+so the battery charges at the evening peak; `vat_pct` outside 0–30 (**0 stays
+legitimate** — injection is VAT-exempt and some cards are already VAT-inclusive);
+a non-finite or non-numeric coefficient; an unknown field; an unknown `index` or
+`resolution`; and the plausibility band above. A `card.month` older than about
+six months **warns and does not refuse** — ENGIE freezes coefficients for a
+contract's duration, so an old card is often exactly right.
+
+⚠️ **Negative output prices are NOT refused.** They are legal on EPEX and they
+are the best charging hours of the year (§17 keeps the regression case). The
+card check bounds the formula's *magnitude* without constraining the sign of
+any hour.
+
+**A startup preview, so a factor of 1000 is visible in one line.** The first
+time the feed answers, the add-on logs the next 24 h as
+`index EUR/MWh -> all-in EUR/kWh` with the min, median, max and the day's
+spread. It is a new framework hook (`PriceProvider.startup_preview()`, default
+silent) rather than a line in `load_prices()`, because only the plugin knows
+what went *in* to its own arithmetic; it is emitted once per process and it
+cannot stop a fetch — a preview that raises is caught and logged.
+
+**Surfaces.** `config.yaml` gains `price_formula` (options **and** schema) and
+`custom_formula` joins the `price_provider` enum through the **derived** set
+`PROVIDERS | RETIRED_PROVIDERS | {"off"}` rather than a hand-typed list; both
+translations describe the option and the new id. `DOCS.md` replaces the
+"planned" sentence with the shape, a worked example from a real card, the
+startup transcript, and the limit of the check stated in the same sentence as
+the claim.
+
+**Not in scope, and each is a card of its own:** the injection leg's own
+coefficients (Eneco uses 0,102 on consumption against 0,100 on injection, and
+injection is VAT-exempt where consumption is at 6 %); the hour-varying network
+charge that bites Wallonia; raising the `price_taxes_eur_kwh` default from 0.06
+to ~0.12.
+
+### TARIFF-07 - three plugins that never fetched a price, withdrawn
+
+**`engie_dynamic`, `totalenergies_dynamic` and `eneco_eddy` are gone from
+`PROVIDERS` and from every surface that listed them.** They did not stop
+working. **They never worked.** Verified by hand on 2026-09-13, before anything
+was deleted:
+
+| id | endpoint | observed |
+|---|---|---|
+| `engie_dynamic` | `https://api.engie.be/dynamic/be` | **404**, Kong `no Route matched with those values` |
+| `totalenergies_dynamic` | `https://api.totalenergies.be/prices/dynamic` | **TLS failure** — cert is `CN=pge-apigee-dev.direct-energie.com`, host not in the SAN list |
+| `eneco_eddy` | `https://api.eneco.be/eddy/prices` | **404**, empty body |
+
+They are also **structurally impossible**, not merely unfinished. ENGIE's
+`(B × eSpot_15) − A` coefficients are per-contract and sit behind the
+klantenzone login, so no public unauthenticated endpoint could return a given
+customer's price; there is no regulator index to read coefficients from; and
+**"Eddy" is not an Eneco product at all** — Eneco's dynamic product is *Zon &
+Wind Dynamisch*, indexed to Belpex/EPEX **day-ahead**, not imbalance.
+
+**The schema keeps all three ids on purpose, and that is the whole reason the
+refusal is reachable.** `price_provider` is a `list(off|…)` enum and the
+Supervisor validates the options file against it *before the add-on runs*. Drop
+a retired id from the enum and an existing config naming it becomes
+schema-invalid: the operator gets an opaque `expected one of ...`, the add-on
+never starts, and `validate.py`'s message is never seen — on exactly the sites
+that need it. `PROVIDERS` is two; the enum stays six. `test_price.py` asserts
+the schema offers exactly `PROVIDERS | RETIRED_PROVIDERS | {"off"}`, derived
+rather than typed, and `register()` refuses to re-register a retired id so the
+refusal cannot be taken away by an `@register` somebody adds back.
+
+**`PriceProduct.REALTIME` and the widening path survive with no shipped
+declarer.** `eneco_eddy` was their sole declarer, so `_WIDE`,
+`Uncertainty.REALTIME_PRODUCT` and `WIDEN_FACTOR`'s 2.5 now have none. They are
+kept: it is the AC2 seam — declare `REALTIME`, get the wide regime, edit no
+framework code — and the first real imbalance product would otherwise have to
+rebuild it. ⚠️ **No shipped plugin declares `PriceProduct.REALTIME` until one
+does**, `test_price.py` section 5 pins that so the emptiness reads as intent
+rather than a dead branch, and section 10 keeps the path live from a class
+declared outside `price.py`. See
+`DECISIONS/TARIFF-07-withdrawing-three-plugins.md`.
+
+⚠️ **FOUR FALSE CLAIMS ARE CORRECTED, AND THEY ARE WHY THIS CARD EXISTS.**
+
+* `eneco_eddy` was called a "Belgian imbalance product" in `DOCS.md`,
+  `app/price_forecast.py`, `app/price_history.py`, `app/static_tariff.py`,
+  `DECISIONS/FCST-04-the-day-that-is-carried.md` and twice in this file. It is
+  **false** — Eneco's dynamic product is day-ahead-indexed. The two historical
+  entries here are **annotated in place** rather than rewritten; the record of
+  what the project believed is part of the record.
+* The quarter-hourly examples those surfaces used `eneco_eddy` for are now
+  **Belgian day-ahead itself**, which really does settle per quarter since the
+  15-minute MTU of 2025-10-01 — `generic_dayahead` reads 96 points a day. The
+  mechanism was always right; only the example was invented.
+* `export_price_eur_kwh`'s docstring claimed *"no shipped supplier publishes a
+  dynamic injection curve"*. **Also false.** Eneco publishes
+  `0,1 × BELPEX-H − 1,188` on the same card as its consumption formula,
+  identical on the January and September 2026 cards, and ENGIE publishes
+  `(B × eSpot_15) − A`. What is true: an injection curve is the **same
+  two-coefficient shape** with **its own** coefficients and its own VAT
+  treatment — injection is VAT-exempt, consumption is at 6% — so the scalar is
+  a **simplification an operator enters by hand, not a reflection of the
+  market**. `DOCS.md` says the same.
+* `_points_from_json()` is deleted with the plugins it served. It read a
+  `{"data": [...]}` document **no feed anybody here has ever reached
+  publishes** — invented alongside these three, and graded only against
+  fixtures written from the same guess. TARIFF-08 found that loop on the
+  response side for `generic_dayahead`; this is the rest of it.
+
+**`DOCS.md` now answers the question a Belgian dynamic customer actually has.**
+The provider table is two rows. The new prose is explicit that
+`generic_dayahead` gives wholesale EPEX BE plus flat markup and taxes scalars,
+which **approximates** a retail dynamic tariff and **cannot express
+`B × spot + A`** — it has no multiplier, and it cannot represent a negative
+offset, which `price_markup_eur_kwh: float(0,1)` could not hold in any case. A
+formula provider is named as the planned answer and is a separate card.
+*(Annotated 2026-09-13: TARIFF-15 replaced that sentence. The table is three
+rows and the prose points at `custom_formula`.)*
+
+⚠️ **One check had to be rebuilt rather than deleted.** `test_price.py` 4b
+proved `code_leaks()`'s docstring strip is load-bearing by finding a shipped
+docstring a raw scan false-positives on — and that docstring was
+`engie_dynamic`'s. With it gone the check would have **passed on a tree with
+the strip deleted**: a check that had quietly stopped being one. The stimulus
+is constructed in the test file now, and the shipped set asserted clean
+separately.
+
+Nine mutations driven, all red; the table is in the decision record. Two carry
+a **+0 B** delta and two end in a traceback whose red count is therefore a
+lower bound — both flagged there, per `MUTATION.md`.
 
 ### TARIFF-10 - a configured provider is fetched, whether or not you trade
 
@@ -184,6 +596,91 @@ driven, and a mutation that makes the guard depend on `arbitrage.enabled()` is
 red on five named checks.
 
 
+### TARIFF-14 - the trade was decided against the wrong price
+
+**On the only price feed that works, `_Series.at()` returned the wrong point,
+and the error grew with depth into the series.** It asked
+`s <= u < s + 1 h` of every point **in list order** and returned the **first**
+match. On the hourly shape every fixture in this repository carried before
+TARIFF-08 that is right by accident; Belgium moved to a **15-minute MTU on
+2025-10-01** and the live day-ahead feed returns **96 points at 900 s**, where
+it is wrong twice over. Measured against the shipped code at `5059e28`:
+
+```
+series: 02:00=0.10  02:15=0.11  02:30=0.12  02:45=0.13  03:00=0.14 ...
+
+ask + 0min -> 02:00  0.10
+ask +15min -> 02:00  0.10   <-- WRONG (wanted 02:15)
+ask +45min -> 02:00  0.10   <-- WRONG
+ask +60min -> 02:15  0.11   <-- WRONG (wanted 03:00)
+ask +75min -> 02:30  0.12   <-- WRONG (wanted 03:15)
+```
+
+Inside the first hour the `:00` point wins because its hour has not run out.
+**From the second hour on the answer is not even the top of the hour** - the
+first point still inside its own hour wins - so the error compounds.
+
+**What it cost is not "a slightly wrong price".** `arbitrage._act()` tests
+`here.start == v.cheapest.start` / `== v.dearest.start` to decide whether this
+interval is the buy one or the sell one. That identity almost never held, so
+**the strategy idled through exactly the interval it exists to trade**,
+reporting *"this hour is neither the buy hour nor the sell hour"* - and read
+§8.3's `here.provisional` and §17's `price < 0` off the same wrong point.
+`static_tariff.py` emits hourly points, so **static sites were never affected**;
+this was reachable only down the dynamic path TARIFF-08/09 made work.
+
+**The rule now, in one sentence: a point covers from its own start until the
+next point's start, and never more than one hour.**
+
+| | before | after |
+|---|---|---|
+| 900 s | `at(02:15)` -> the 02:00 point | -> the 02:15 point |
+| 3600 s | `at(02:30)` -> the 02:00 point | **unchanged** |
+| **mixed** `[900, 3600]` | each point one hour wide | **each point takes its own gap** |
+
+The mixed case is not an edge case: FCST-04's carry-forward emits **hourly
+carried points beside quarter-hourly firm ones**, and the soak measured spacing
+`[900, 3600]` in **70 % of samples**. A window derived from one global spacing
+would be wrong in the normal steady state.
+
+**The one-hour cap is load-bearing.** FCST-04 leaves an hour *out* of the
+series when nothing published it and yesterday has no value either, and
+`at()` raising `Absence` for that hour is what sends the caller to the static
+profile (§11.4). Uncapped, "until the next point's start" would stretch the
+point before a three-hour hole across the whole hole and answer every instant
+in it with a stale price - filling holes, introduced by the fix for a different
+defect.
+
+**The last point's window is a decision and it is written down.**
+`DECISIONS/TARIFF-14-the-window-a-point-covers.md` §2 argues it: the last point
+is given **the same span as the point before it** (one hour when it is the only
+point). A flat one-hour tail would answer **00:30 tomorrow with today's 23:45
+price**, which is reaching for a neighbour across a day boundary. The cost of
+the choice - a mixed series ending at the firm/carried seam loses its last 45
+minutes to `Absence` - is stated there rather than buried, and the direction is
+the safe one.
+
+**`at()` now reads a point's neighbours, so it would depend on the series being
+sorted - and it establishes that itself** rather than trusting the three
+producers that happen to guarantee it today. The lookup index is sorted by UTC
+start once, at construction; a series handed its 96 points in reverse order
+answers identically, which is a check. `covers()` shared the defect exactly
+(it has no rule of its own - it asks `at()`) and is fixed by the same change;
+`window()` did not (it grades a point's **start** against a range and asks
+nothing about duration), and its docstring now says so.
+
+**Nothing about §9.3 or a point's `start` changed.** `PricePoint` still has
+three fields; the span is derived from the neighbours, not stored.
+
+Graded by `test_price.py` section 14 - 900 s, 3600 s, **mixed**, holes, the
+tail, caller order, `covers()`/`window()` - and end to end by
+`test_arbitrage.py` section 10, which drives `decide()` over a 96-point
+quarter-hourly day whose cheapest and dearest quarters are deliberately **not**
+on a whole hour. Eight mutations, all red, including a **zero-byte** one on the
+tail rule; the table with byte deltas and the checks that were NOT reached is
+in the decision note §6.
+
+
 ### TARIFF-09 - the feed is asked for the range the caller wanted
 
 **`generic_dayahead` took `since` and `until` and requested the bare feed URL,
@@ -510,7 +1007,12 @@ spread it would have created was never compared against anything.
   leaves the local hours it never held **out of the series** - §11.4 for those
   hours, and asking for one raises rather than answering. Correct behaviour,
   and the wording is now the behaviour.
-* ⚠️ **A sub-hourly feed keeps every print.** `eneco_eddy` is the imbalance
+* ⚠️ **A sub-hourly feed keeps every print.** [⚠️ **The claim that follows is
+  FALSE and TARIFF-07 corrected it: `eneco_eddy` was not an imbalance product,
+  was not an Eneco product at all, and its endpoint never existed. The real
+  quarter-hourly feed is Belgian DAY-AHEAD since the 15-minute MTU of
+  2025-10-01, which is what `generic_dayahead` reads. The behaviour described
+  below is unchanged.**] `eneco_eddy` is the imbalance
   product and settles per **quarter**; the fill walks whole hours to decide
   what needs carrying, and that is not a rule about what a published hour may
   contain. Every published point inside the horizon passes through by identity,
@@ -3726,6 +4228,10 @@ somebody else's tariff. What is mechanised is reachability; what stays human is
 truthfulness.
 
 **The product type is declared, not inferred from the plugin's name.**
+[⚠️ **FALSE, corrected by TARIFF-07: `eneco_eddy` was never a real-time /
+imbalance product — Eneco's dynamic product is day-ahead-indexed — and the
+plugin has been withdrawn. The declaration mechanism described here is
+unchanged and is now exercised only from outside `price.py`.**]
 `eneco_eddy` is a real-time/imbalance product and gets widened arbitrage
 thresholds; that reaches a consumer through `capabilities().product` and
 `volatility_regime()`, never through a name comparison. `test_price.py` asserts

goodwe_controller/DECISIONS/FCST-04-the-day-that-is-carried.md

@@ -75,8 +75,9 @@ Every point still carries `provisional=True`, so the **flag never lies** — wha
 decays is the number, behind a flag that is telling the truth.
 
 ⚠️ **No value-level check can catch that**, and claiming one would be worse than
-claiming none. A carried point and a published-provisional point (`eneco_eddy`'s
-current quarter, §9.2) are the same three fields carrying the same flag. The
+claiming none. A carried point and a published-provisional point (a real-time
+product's current interval, §9.2) are the same three fields carrying the same
+flag. The
 difference is provenance, and provenance is not in the value.
 
 The defence is therefore an **ordering**, not a validation:
@@ -139,8 +140,16 @@ file constructs and still holds a reference to.
 
 ## 4. A sub-hourly feed passes through whole; the fill only decides which hours are missing.
 
-`eneco_eddy` is the Belgian imbalance product and settles **per quarter**, and
-`price.py`'s `_validate_raw()` accepts any strictly-increasing spacing — so a
+⚠️ **This section originally said `eneco_eddy` is "the Belgian imbalance
+product". That was false and [[TARIFF-07]] withdrew the plugin: Eneco's dynamic
+product is "Zon & Wind Dynamisch" and is indexed to Belpex/EPEX **day-ahead**,
+not to imbalance, and `api.eneco.be/eddy/prices` never existed. The mechanism
+below is unaffected, because the real quarter-hourly feed is the one still
+shipped.**
+
+Belgian **day-ahead** settles per **quarter** — the 15-minute MTU took effect
+on 2025-10-01, so `generic_dayahead` reads 96 points a day rather than 24 — and
+`price.py`'s `_validate_raw()` accepts any strictly-increasing spacing, so a
 published hour may legitimately hold four points.
 
 FCST-04's first caller keyed the published set as `{_utc_hour(p.start): p for p

goodwe_controller/DECISIONS/TARIFF-07-withdrawing-three-plugins.md

@@ -0,0 +1,230 @@
+# TARIFF-07 — three plugins that never fetched a price, and the one mechanism they leave behind
+
+**Status: DECIDED 2026-09-13 — withdraw `engie_dynamic`,
+`totalenergies_dynamic` and `eneco_eddy`. Keep `PriceProduct.REALTIME` and the
+widening machinery. Refuse a retired id by name rather than aliasing it.**
+
+Filed with TARIFF-07. Follows [[TARIFF-08]], which found the same class of
+defect one layer down — a parser graded against its own guess — and left the
+question of these three open.
+
+---
+
+## 1. The endpoints, verified rather than taken on report
+
+The card said the three endpoints were dead. They were re-checked by hand on
+**2026-09-13** before anything was deleted, because "the endpoint is dead" is
+exactly the kind of claim this repository keeps finding to be second-hand:
+
+| id | endpoint | observed |
+|---|---|---|
+| `engie_dynamic` | `https://api.engie.be/dynamic/be` | **HTTP 404**, body `{"message":"no Route matched with those values","request_id":"..."}` — a Kong gateway with no route configured |
+| `totalenergies_dynamic` | `https://api.totalenergies.be/prices/dynamic` | **TLS failure**. The handshake completes and the server presents `CN=pge-apigee-dev.direct-energie.com`; `api.totalenergies.be` is not in the SAN list, so the connection is closed before any request is sent |
+| `eneco_eddy` | `https://api.eneco.be/eddy/prices` | **HTTP 404**, `content-length: 1`, `server: Microsoft-IIS/10.0` — an empty body from a live host that does not serve this path |
+
+All three failed. Had any one of them answered, this card would have stopped
+and asked, because an endpoint that answers changes the decision from
+"withdraw" to "fix the parser".
+
+## 2. Why this is not "unfinished", and why no replacement can be written
+
+An unfinished plugin has a right endpoint and a wrong parser. These have
+neither, and the reason is structural:
+
+* **ENGIE's dynamic price is `(B × eSpot_15) − A`, and `B` and `A` are
+  PER-CONTRACT.** They live behind the customer's klantenzone login. No
+  unauthenticated public URL can return *a given customer's* price, so the
+  endpoint this plugin wanted cannot exist for anybody to build.
+* **There is no regulator index to read the coefficients from.** CREG's
+  tariff-card pages 404; VREG was unreachable. Every coefficient found in
+  research came from a supplier's own PDF, which is a document, not a feed.
+* **"Eddy" is not an Eneco product at all.** Eneco's dynamic product is
+  **"Zon & Wind Dynamisch"**, and it is indexed to **Belpex/EPEX day-ahead** —
+  not to imbalance. The plugin was wrong about the product, the product type
+  and the URL simultaneously.
+
+So the three were not withdrawn for being broken. They were withdrawn for
+describing tariffs that no public endpoint can serve.
+
+## 3. What a site configured on one of these has actually been running
+
+⚠️ **This is the half that decides what the migration is.** §11.4 turns a
+failed fetch into a silent fall back: static profile, plan provisional, no
+arbitrage. That is the *correct* degradation, and it says nothing at all about
+the cause. Every fetch these three ever made raised `SourceUnavailable`.
+
+Therefore a site configured on one of them has been running on
+`static_profile` — **or on nothing at all, where no profile was set** — since
+the day the id was entered, and **nothing on its status page has ever differed
+from a working provider that simply never found a cheap hour**.
+
+The migration is therefore **not** "keep their prices working". There were no
+prices. It is *"tell them their prices never worked"*, which is why the answer
+is a refusal and not a fallback.
+
+### Why not a silent alias to `generic_dayahead`
+
+It is the friendlier-looking option and it is wrong. These published **retail**
+prices; `generic_dayahead` reads **wholesale**. Aliasing needs the site's own
+`B` and `A`, which §2 has just established nobody has. An alias would have to
+**invent the numbers a battery is priced against** — the same defect as a
+parser graded against its own guess, one layer further from anything that
+reports. The scalar `price_markup_eur_kwh` cannot stand in for `B` either: it
+is an addend, not a multiplier, and it is `float(0,1)` so it cannot even hold a
+negative `A`.
+
+## 4. ⚠️ The `config.yaml` schema is deliberately WIDER than the registry
+
+`price_provider` is a `list(off|…)` enum, and the Supervisor validates the
+options file against it **before the add-on starts**.
+
+So the obvious edit — delete the three ids from the enum along with the classes
+— has a consequence that runs exactly opposite to this card's purpose:
+
+```
+operator's config says  price_provider: eneco_eddy
+        |
+        +-- id NOT in the schema enum
+                |
+                +-- Supervisor rejects the options file
+                        |
+                        +-- add-on never starts
+                                |
+                                +-- validate.py never runs
+                                        |
+                                        +-- the named refusal is NEVER SEEN
+```
+
+The operator gets an opaque `expected one of ...` from a layer they did not
+configure, on **exactly the sites the withdrawal exists to inform**.
+
+**Decision: keep all three ids in the schema enum.** `PROVIDERS` shrinks to
+two; the enum stays at six. The cost is that the dropdown still offers three
+dead ids to a *new* operator — and that is the cheaper failure, because
+choosing one is refused at the next startup **by name**, with the endpoint, the
+observation and the alternative, which is strictly more than a schema
+rejection would say. Both translations label them withdrawn in the option
+description.
+
+`app/price.py`'s `RETIRED_PROVIDERS` is the list. `test_price.py` section 1
+asserts the schema offers exactly `PROVIDERS | RETIRED_PROVIDERS | {"off"}` —
+derived, not typed — and `register()` refuses to re-register a retired id, so
+the registry and the retired table cannot both claim one and the refusal cannot
+be taken away by an `@register` somebody adds back.
+
+## 5. ⚠️ `PriceProduct.REALTIME` and the widening path are KEPT with no shipped declarer
+
+`eneco_eddy` was the **sole** declarer of `PriceProduct.REALTIME`. Deleting it
+orphans:
+
+* `_WIDE = frozenset({PriceProduct.REALTIME})`
+* `Uncertainty.REALTIME_PRODUCT`
+* `WIDEN_FACTOR[Uncertainty.REALTIME_PRODUCT] = 2.5`
+
+**They stay.** The reasoning, stated here so the next reader finds intent
+rather than an apparent dead branch:
+
+1. A reviewer finding a mechanism with **zero callers** would reasonably delete
+   it. That is good instinct applied to a missing fact, and this file is the
+   fact.
+2. It is the **AC2 seam**. The whole point of `capabilities().product` is that
+   a new supplier is a new class and nothing else: declare `REALTIME`, get the
+   wide regime, edit no framework code. Deleting the enum member would mean the
+   first genuine imbalance product has to **rebuild** that seam — and rebuilding
+   it is precisely the "editing the optimiser to add a supplier" that AC2
+   forbids.
+3. It costs nothing. Two enum members and a dict entry.
+
+**⚠️ NO SHIPPED PLUGIN DECLARES `PriceProduct.REALTIME` UNTIL ONE DOES.** Both
+shipped plugins (`generic_dayahead`, `manual_csv`) are day-ahead. §9.2's row 2
+is unoccupied. That is not the same as it having no mechanism, and the
+difference is what this section exists to record.
+
+It is **pinned, not merely documented**. `test_price.py` section 5 asserts:
+
+* that **no shipped plugin** declares `REALTIME` — so if one ever does, the
+  check goes red and the right fix is to **edit this record**, not to delete
+  the seam;
+* that the widening still works **from a declaration alone** —
+  `volatility_regime`, `uncertainty_of` and `widen_factor` are graded on a
+  `ProviderCapabilities` the test file builds;
+* and section 10 registers `_NewSupplier`, a class defined **outside
+  `price.py`** that declares `REALTIME` and is asserted to land in the wide
+  regime. That class is now the only live declarer in the tree, which makes the
+  seam something this suite exercises end to end rather than a constant it
+  reads.
+
+## 6. What else went, and one thing that did not
+
+`_points_from_json()` went with the three. It read a `{"data": [{...}]}`
+row-per-point document that **no feed anybody here has ever reached
+publishes** — the shape was invented alongside these plugins, and the only
+bodies ever fed to it were fixtures written from the same guess. TARIFF-08
+found that loop on the response side for `generic_dayahead`; this is the rest
+of it. `needs_credentials` went too: the three were its only setters and
+nothing read it.
+
+The shape survives in **one** place and in one direction: `row_shape_body()` in
+`test_price.py`, feeding `generic_dayahead` so that section 9 grades a row
+document as a **failure** for it rather than a second dialect it might sniff.
+It is named for what it is.
+
+⚠️ **One check had to be rebuilt rather than deleted, and saying so matters.**
+`test_price.py` section 4b proved that `code_leaks()`'s docstring strip is
+load-bearing by finding a shipped docstring that a raw text scan would
+false-positive on. The docstring that did that was **`engie_dynamic`'s** — it
+spelled `price_markup_eur_kwh` in full. With it gone, no shipped docstring
+spells a full framework key, so the check would have **passed on a tree with
+the strip deleted**: a check that had quietly stopped being one, which is the
+third failure mode in `MUTATION.md`. The stimulus is now constructed in the
+test file (`_DocumentedPlugin`), and the shipped set is asserted clean
+separately.
+
+## 7. Mutations driven
+
+Every check added or rebuilt here was driven red. Harness:
+`/home/homelab/.cache/t07-mut/`, which rebuilds the tree from the worktree and
+purges `__pycache__` per `MUTATION.md`'s rule.
+
+| | mutation | Δ | red on |
+|---|---|---|---|
+| M1 | delete the retired branch from `_price_problems()` | −2785 B | 7 checks in `test_price.py` |
+| M2 | move the retired branch **after** the unknown-id branch | **+0 B** | the same 7 |
+| M3 | make `been_running` constant (drop the empty-`static_profile` case) | −212 B | 2 |
+| M4 | drop the "WHAT TO DO" half of the refusal | −874 B | 1 |
+| M5 | `RETIRED_PROVIDERS = {}` | −1099 B | 5, then a traceback |
+| M6 | drop the three ids from `config.yaml`'s enum — §4's trap | −47 B | 2 |
+| M7 | delete `register()`'s retired guard | −1101 B | 2, then a traceback |
+| M8 | `_WIDE = frozenset()` | −23 B | 3 + 4 across two suites |
+| M9 | `WIDEN_FACTOR[REALTIME_PRODUCT]` 2.5 → 1.5 | **+0 B** | 1 + 1 |
+
+⚠️ **M2 and M9 have a byte delta of zero**, which `MUTATION.md` names as the
+risky case. The harness rebuilds the tree from source on every run and purges
+`__pycache__`, so there is no inherited cache to read; and stale bytecode
+manufactures **survivors**, never reds, so a red from a `+0 B` mutation is not
+at risk from that defect. M2's grep confirmed the branch had moved on disk.
+
+⚠️ **M5 and M7's red counts are LOWER BOUNDS.** Both runs ended in a traceback
+with checks after it ungraded — FCST-06's rule: read the output, not the count.
+M7's traceback is itself informative: with the guard gone the re-registration
+**succeeds**, `PROVIDERS` is polluted with a class that has no fixture, and the
+suite dies downstream. That is the failure the guard prevents, arriving loudly.
+
+## 8. What this card did not do
+
+* **It did not pick a version number.** The change is backward-incompatible — a
+  config legal on the current version is refused on the next — and the
+  CHANGELOG says so prominently, in the shape PKG-07 established for `slew_w`.
+  Which number it belongs to depends on whether the current image has already
+  been built and pulled, which is a fact about the live box that this branch
+  cannot observe. Whoever deploys decides.
+* **It did not implement the formula provider.** `B × spot + A` with per-site
+  coefficients is the real answer for a Belgian dynamic customer and is a
+  separate card. `DOCS.md` references it as planned and is explicit about what
+  `generic_dayahead` can and cannot express in the meantime — in particular
+  that it cannot represent a negative offset, and that
+  `price_markup_eur_kwh: float(0,1)` could not hold one anyway.
+* **It did not rewrite released CHANGELOG history.** The two historical entries
+  that called `eneco_eddy` an imbalance product are annotated in place with a
+  correction naming this card, rather than silently edited. The record of what
+  the project believed is part of the record.

goodwe_controller/DECISIONS/TARIFF-13-the-coverage-of-a-peak.md

@@ -0,0 +1,225 @@
+# TARIFF-13 — the coverage of a peak, and which quarter gets the credit
+
+Two decisions. §1 is the defect the ticket was raised on; §2 is the smaller
+question it asked to be settled deliberately rather than left as an accident.
+§3 is what this branch deliberately did **not** do, and why.
+
+---
+
+## 0. What was actually wrong, stated once
+
+`main.py`'s capacity-tariff status row prints a peak read from SQLite and a
+coverage figure read from **process memory**:
+
+```python
+_pk = self.peak.peak(when)                      # SQLite, durable
+...
++ f"; {self.peak.recorded} quarter(s) banked"   # an int on the tracker
+```
+
+`PeakTracker.recorded` was `self.recorded = 0` in `__init__`, incremented once
+per block inside `sync()`. A 40-hour soak caught what that means at a driven
+restart, on both instances independently:
+
+```
+before: 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit; 120 quarter(s) banked
+after : 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+        - 10 % of the 3500 W soft limit;   0 quarter(s) banked
+```
+
+Reproduced here before anything was changed, through the real `Controller`, the
+real `P1Ingest`, and a **real restart** — a second `Controller` object against
+the same file on disk, never a re-read of the first:
+
+```
+before: 2026-09: peak 365 W, set by the quarter at 2026-09-10T09:00:00+00:00
+        - 10 % of the 3500 W soft limit; 12 quarter(s) banked
+after : 2026-09: peak 365 W, set by the quarter at 2026-09-10T09:00:00+00:00
+        - 10 % of the 3500 W soft limit;  0 quarter(s) banked
+
+    peak survives the restart: True
+    count survives the restart: False       (12 -> 0, store held 12 rows)
+```
+
+**TARIFF-01's argument, one column over.** That module's whole design is that
+an unreadable store must not read as a zero peak, *because a zero peak is
+disarming*. A coverage figure of zero is disarming in exactly the same way and
+about the same number: the count is what says how much of the billing month the
+watt figure actually covers, and 365 W over 120 quarters and 365 W over 0
+quarters are different claims about the same 365 W. After a restart the page
+made the weaker claim while displaying the stronger one's value. It did not
+under-report the peak — it under-reported **its own evidence**.
+
+Two further defects fell out of the same variable once it was driven, neither
+of them in the ticket:
+
+* **it was never scoped to a month.** It counted every block the *process* had
+  banked, so on 1 October the row read September's tally beside October's "no
+  completed quarter recorded yet". Measured, on the shipped tree:
+  `2026-10: no completed quarter recorded yet - 0 % of the 3500 W soft limit;
+  1 quarter(s) banked`.
+* **it missed the block `restore()` banks.** A stale block closed from the
+  checkpoint goes into `quarter_blocks` without passing through `sync()`, so
+  the counter never saw it.
+
+---
+
+## 1. Decision: the count is READ FROM THE TIER THE PEAK IS READ FROM
+
+The acceptance criterion allowed either route — make the count durable, or stop
+printing a number that silently resets. **Durable**, because the count is the
+useful half of the row and removing it would have cost the operator the one
+thing that says whether the peak means anything yet.
+
+`PeakStore.banked_count(month)` asks the database `SELECT COUNT(*) FROM
+quarter_blocks WHERE month=?`, and `PeakTracker.recorded` is a property over it
+rather than an attribute. Three consequences, and all three are the defects
+above:
+
+* a restart re-reads the same rows, so the figure survives it;
+* the count is per **month**, so it agrees with the peak it is printed beside;
+* a block banked by `restore()` is a row like any other and is counted.
+
+Three things this route deliberately does **not** do:
+
+* **it does not count `len(blocks_in(month))`.** `blocks_in()` returns `[]` on a
+  read error — safe there only because no caller reads its emptiness as a peak,
+  which its own docstring says — so taking its length would rebuild the
+  disarming zero one call further out. `banked_count()` returns **`None`** when
+  the database will not answer.
+* **it does not count `monthly_peak`.** That tier holds one row per *month* and
+  would answer `1` for every month ever measured — wrong by exactly the amount
+  that makes it look plausible. The two tables are proven equal on the **peak**
+  by `recompute_month()`; they were never equal on the **count**.
+* **it does not remove the dedupe.** `_seen` is still what stops `cycle()`'s
+  once-a-second `sync()` re-banking a block that `P1Ingest.blocks` keeps for a
+  day, and `sync()`'s return value is still the number newly banked. What moved
+  is only where the *status page* reads its figure. ⚠️ The check that graded the
+  dedupe used to assert `recorded == 1` — the dedupe and the figure reporting it
+  were the same variable. Counting rows in `quarter_blocks` cannot see a
+  re-bank at all (it is a PRIMARY KEY no-op), so that check is now graded on
+  `sync()`'s **return**, with the store's tally as the second half.
+
+### ⚠️ The unreadable case renders a WORD, not a number
+
+`banked_count()` returns `int | None`; `recorded_in()` renders the `None` as
+the module constant `COUNT_UNREADABLE = "an unreadable number of"`, so the
+sentence reads
+
+```
+... ; an unreadable number of quarter(s) banked
+```
+
+`0` was never available. `None` was rejected too: `f"{None} quarter(s) banked"`
+renders **"None quarter(s) banked"**, which an operator reads as the same zero.
+This is the `PeakReading` trade — no `peak_w_or(default)`, ever — applied to the
+coverage figure: a caller that formats it gets a true sentence in both states,
+and a caller that does arithmetic on it gets a `TypeError`, which is loud.
+
+"0 quarter(s) banked" remains a **true and reachable** sentence: it is what a
+month nothing has been written to says, and part 11 asserts that the two states
+are spelled differently.
+
+---
+
+## 2. Decision: at EQUAL wattage, the EARLIEST quarter keeps the attribution
+
+**First, not most recent.** The reasoning, in the order it matters:
+
+1. **It is not a money question.** The utility bills the wattage; the timestamp
+   is not part of the bill. So the decision is settled entirely on what the
+   status row is *for*.
+2. **The row answers "when did my monthly peak happen".** An operator reading it
+   goes and looks at one event — what was running, what the weather was. A
+   stable answer is the one that can be investigated; "most recent wins"
+   guarantees the answer moves every time the wattage recurs, and an operator
+   who looked yesterday is sent somewhere else today for no reason.
+3. **It is what one reader already did unconditionally.** `recompute_month()`
+   is `ORDER BY offtake_avg_w DESC, quarter_start ASC LIMIT 1` — earliest wins.
+   Choosing "most recent" would have meant changing both readers; choosing
+   "earliest" meant making the other one say out loud what it was already doing
+   by accident.
+
+### ⚠️ And the two readers DID diverge, which is why this is a code change
+
+The `monthly_peak` upsert was `WHERE excluded.peak_w > monthly_peak.peak_w` —
+strictly greater, so an exact tie never wrote and the row kept whichever tied
+block was **written first**. That coincides with *earliest* only while blocks
+arrive in time order. Fed four equal 365 W blocks newest-first, measured on the
+shipped tree:
+
+```
+ascending arrival    monthly_peak -> 09:00:00   recompute_month -> 09:00:00   agree=True
+DESCENDING arrival   monthly_peak -> 09:45:00   recompute_month -> 09:00:00   agree=False
+```
+
+That is a divergence in the derived record that part 8 of `test_tariff.py`
+exists to prove cannot happen — latent, because nothing in the shipped path
+banks out of order today. The upsert now carries the tie term explicitly:
+
+```sql
+WHERE excluded.peak_w > monthly_peak.peak_w
+   OR (excluded.peak_w = monthly_peak.peak_w
+       AND excluded.quarter_start < monthly_peak.quarter_start)
+```
+
+**`peak_w` is untouched.** The `>` term is exactly as it was, no tie can move
+the billed number, and SAFETY-07's guard reads the same watt figure it read
+before. The second term moves only the timestamp.
+
+### ⚠️ AND THE SOAK'S DRIFT WAS NOT A TIE AT ALL
+
+The ticket's reading — "ties at the same wattage are re-attributed to the most
+recent matching quarter" — is **false**, and driving it is what showed that.
+Six exactly-equal 365.0 W quarters on the shipped tree moved the attribution
+**zero** times, because `>` is strict.
+
+What the soak saw was a genuine new maximum **smaller than the row's own
+resolution**. The row renders `{peak_w:.0f}` — whole watts — so 365.0000001 W is
+a new peak to the database and the same `365 W` to the reader:
+
+```
+q0  fed 365.0        -> renders 365 W, attributed 09:00:00
+q1  fed 365.0000001  -> renders 365 W, attributed 09:15:00
+q2  fed 365.0000002  -> renders 365 W, attributed 09:30:00
+```
+
+**Decision: left alone, deliberately.** It is the instrument behaving correctly
+— the peak really did rise — and the alternative, printing more decimal places,
+puts noise in the one row an operator reads at the moment the guard engages, to
+explain a movement that is real. Both cases are pinned in part 12 so that
+neither can be changed by accident, and the distinction is recorded here so the
+next reader does not re-diagnose it as a tie.
+
+---
+
+## 3. What this branch did NOT do, and who owns it
+
+**`main.py`'s status row was not touched.** TARIFF-11 holds `main.py`'s status
+rows on a concurrent branch, and the standing instruction is to stop rather than
+race there. Everything above is in `app/tariff.py`, and the row picks the fix up
+without editing, because `self.peak.recorded` is an attribute access and is now
+a property.
+
+**The residual, stated with its scope.** `recorded` answers for
+`datetime.now()`. The peak beside it follows `checks(when=...)`. The shipped
+install has **exactly one** call site — `self.checks()` with no argument, at
+`main.py:4359` — where the two are the same month, so **the live page is correct
+and durable**. They part company only under the `when=` affordance TEST-17 added
+for the suite, and the mismatch there is strictly smaller than the one it
+replaces (this month's tally, rather than a process-wide total across all
+months).
+
+`PeakTracker.recorded_in(when)` is the scoped form and is shipped. Moving the
+row onto it is:
+
+```python
+- + f"; {self.peak.recorded} quarter(s) banked"
++ + f"; {self.peak.recorded_in(when)} quarter(s) banked"
+```
+
+one token, on one line, inside the block TARIFF-11 owns. `test_tariff.py`
+part 10 **pins the present behaviour** — graded against a row count taken
+straight from `quarter_blocks`, not against the property that produces it — so
+the gap goes red if it changes and cannot be quietly forgotten.

goodwe_controller/DECISIONS/TARIFF-14-the-window-a-point-covers.md

@@ -0,0 +1,349 @@
+# TARIFF-14 — how long one price point covers, and what the last one does
+
+One defect and one genuinely open decision. The defect had no defensible
+alternative once it was measured; the decision — the **last** point's window —
+did, and the alternative is argued below rather than dismissed.
+
+---
+
+## 0. The measurement this card exists for
+
+`_Series.at()` asked `s <= u < s + 1 h` of every point **in list order** and
+returned the **first** match. Run against the shipped code at `5059e28` on a
+quarter-hourly series:
+
+```
+series: 02:00=0.10  02:15=0.11  02:30=0.12  02:45=0.13  03:00=0.14 ...
+
+ask + 0min -> 02:00  0.10
+ask +15min -> 02:00  0.10   <-- WRONG (wanted 02:15)
+ask +30min -> 02:00  0.10   <-- WRONG
+ask +45min -> 02:00  0.10   <-- WRONG
+ask +60min -> 02:15  0.11   <-- WRONG (wanted 03:00)
+ask +75min -> 02:30  0.12   <-- WRONG (wanted 03:15)
+```
+
+**Two failure modes, not one.** Inside the first hour the `:00` point wins
+because its hour has not run out. From the second hour on the answer is not
+even the top of the hour — the first point still inside its own hour wins — so
+**the error compounds with depth into the series**.
+
+Same code, same run, after the fix:
+
+```
+ask + 0min -> 02:00  0.10        ask +60min -> 03:00  0.14
+ask +15min -> 02:15  0.11        ask +75min -> 03:15  0.15
+ask +30min -> 02:30  0.12        ask +90min -> 03:30  0.16
+ask +45min -> 02:45  0.13        ask+120min -> 04:00  0.18
+```
+
+An hourly series is **unchanged at every instant**, before and after — which is
+the whole reason nothing caught this. Every price fixture in this repository
+before TARIFF-08 was the invented hourly row shape, `static_tariff.py` emits
+hourly points, and the DST checks count points on the 23- and 25-hour days
+without ever asking `at()` for a quarter-hour. **The suite had been exercising
+the one resolution on which the broken rule and the right one agree.**
+
+Belgium moved to a 15-minute MTU on 2025-10-01 and the live day-ahead feed
+returns **96 points at 900 s**, so this is reachable only down the dynamic path
+TARIFF-08/09 just made work. Static sites are immune.
+
+## 0.1 What it cost, which is not "a slightly wrong price"
+
+`arbitrage._act()` calls `_point_at(plan, now)` → `series.at(now)` and then
+tests `here.start == v.cheapest.start` / `== v.dearest.start` to decide whether
+this interval is the buy one or the sell one. That is an **identity test
+between the matched point and the point the verdict was built from**, and on a
+quarter-hourly series it almost never matched — so the strategy idled through
+exactly the interval it exists to trade, reporting *"this hour is neither the
+buy hour nor the sell hour"*. It also read `here.provisional` (§8.3) and §17's
+`price < 0` off that same wrong point.
+
+---
+
+## 1. The rule
+
+> **A point covers from its own start until the next point's start, and never
+> more than one hour.**
+
+* **900 s** → each point covers its own quarter.
+* **3600 s** → each point covers its own hour. Identical to what shipped.
+* **MIXED** → **each point takes its own gap.** FCST-04's carry-forward emits
+  hourly carried points beside quarter-hourly firm ones, and the soak measured
+  spacing `[900, 3600]` in **70 % of samples** — so a window derived from one
+  global spacing would be wrong in the **normal steady state**, not in an edge
+  case.
+
+### 1.1 Why the one-hour cap is not decoration
+
+FCST-04 **leaves holes on purpose**: an hour with no published price and no
+yesterday value is left *out* of the series, and `price_forecast.py`'s module
+note names `at()` raising `Absence` for it as the behaviour that sends the
+caller to the static profile (§11.4 for that hour).
+
+Uncapped, "until the next point's start" stretches the point **before** a
+three-hour hole across the whole hole and answers every instant in it with a
+stale price. Filling holes is the defect this module exists to refuse, and it
+would have been introduced **by the fix for a different one**. Graded in
+`test_price.py` 14d; the mutation that removes the cap is red there.
+
+---
+
+## 2. The decision: what the **last** point covers
+
+There is no next start, and §9.3 says nothing about how wide the final interval
+is — a `PricePoint` has **three fields** and must not learn a fourth, because
+that is the wire format every store, replay, fixture and captured body in this
+repository is written against. So the tail is a **choice**, and both candidates
+are defensible.
+
+**Chosen: the last point is given the same span as the point before it** (one
+hour when it is the only point).
+
+| | flat one hour | the span in front of it (**chosen**) |
+|---|---|---|
+| 96-point 900 s day, `at(23:50)` | answers 23:45 | answers 23:45 |
+| the same day, `at(00:30)` **tomorrow** | **answers with today's 23:45 price** | `Absence` |
+| 24-point hourly day, `at(23:50)` | answers 23:00 | answers 23:00 |
+| mixed series ending at the firm/carried seam | answers for an hour | `Absence` after 15 min |
+
+**The second row is why.** A flat one-hour tail reaches across a day boundary
+and prices tomorrow morning with yesterday's last print — which is
+"reaching for a neighbouring one", the single thing the `Absence` message has
+always refused to do. The chosen rule never extends a point past a span the
+series itself demonstrates.
+
+### 2.1 The cost of the choice, stated rather than buried
+
+On a **mixed** series whose last point is a carried **hourly** one sitting
+behind quarter-hourly firm ones, the tail is **900 s**, and the last 45 minutes
+of the horizon raise `Absence` for an hour something did carry a value for.
+
+That is accepted, not tolerated, and the direction is the safe one:
+
+* the caller falls back to the static profile (§11.4) instead of trading on a
+  span the series never demonstrated;
+* the point is **carried**, so §8.3 forbids any irreversible action resting on
+  it regardless;
+* it is at the far end of a 48 h horizon, where nothing is decided at 30 s.
+
+Under-covering costs a missed decision. Over-covering prices a real interval
+with a number that does not describe it. Those are not symmetric.
+
+### 2.2 The degenerate case
+
+A series of **one** point has no gap in front of it to copy and gets **one
+hour** — the shipped behaviour, kept deliberately. `test_price.py` 14e states
+it as its own check so it cannot decay into an accident.
+
+---
+
+## 3. Does `at()` now depend on sortedness? Yes — and it establishes it itself
+
+The old rule read one point at a time and did not care about order. The new one
+reads a point's **neighbours**, so it *would* depend on the series being
+ascending.
+
+It does not, because **the lookup index is sorted by UTC start at construction**
+(`_cover_table()`, called once from `_Series.__init__`). No caller's list order
+can reach `at()`.
+
+That matters because the three things that "guarantee" order today each
+guarantee it somewhere else:
+
+| | what it guarantees | where |
+|---|---|---|
+| `_validate_raw()` | strictly increasing starts | the `load_prices()` path only |
+| `price_history._parse_points()` | re-sorts by instant | the store read path only |
+| FCST-04's fill | emits ascending | that one producer only |
+| `PriceRead.series()` | **nothing** | every other caller, including tests |
+
+Three producers agreeing today is not an invariant; it is a coincidence with
+good references. `test_price.py` 14f drives a series handed its 96 points in
+**reverse** order and asserts `at()` answers identically at every one of them —
+red the moment the sort is removed.
+
+**Duplicated starts** (refused by `_validate_raw()`, constructible by hand) give
+the earlier list entry a zero-width window and the later one the real span. One
+of the pair becomes unreachable through `at()`; **nothing raises**, at
+construction or on the 30 s control path. Stated as a check rather than left to
+be discovered.
+
+---
+
+## 4. `covers()` shared it. `window()` did not
+
+* **`covers()`** has no window rule of its own — it calls `at()` — so it shared
+  the defect exactly and the same change fixes it. It is kept as a delegation
+  for that reason: a second copy of the rule is a second place for it to be
+  wrong.
+* **`window(since, until)`** grades a point's **start** against a half-open
+  range and never asks how long a point lasts, so it carries no resolution
+  assumption at all. It is **not** a coverage query — a point that starts before
+  `since` and runs into it is absent from its result by design. That is now
+  said in its docstring and pinned by a check, because the next reader will ask.
+  It has **no callers** in `app/`.
+
+---
+
+## 5. What this card does NOT fix, with its shape
+
+`price_forecast._walk()` — §8.3's irreversible-action gate — iterates
+`committed_hours()`, which steps in **whole hours**, and asks `series.at(u)` at
+each. On a quarter-hourly series that now reliably returns the hour's `:00`
+point (it previously returned something earlier and arbitrary), so the gate
+reads **one point per hour** and never looks at the `:15`/`:30`/`:45` flags.
+
+A partially-provisional hour would therefore be gated on its first quarter
+alone. **Two things keep it off every shipped install, and both are
+circumstantial rather than structural:** `price_permits()`/`begin_phase()` have
+**no caller in `app/main.py`** — the §12 price-justified entry point is built
+and not yet wired — and FCST-04 carries **whole** hours while
+`generic_dayahead` publishes whole days, so the four quarters of an hour are
+firm or carried together anyway. Both are facts about the *callers and
+producers*, not properties of the *gate*, so this is written down here rather
+than left for the first sub-hourly feed or the first wiring-up to find. Fixing it means teaching
+`committed_hours()` about resolution, which is a data-model question this card
+deliberately does not open.
+
+---
+
+## 6. Mutations
+
+Eight, each purged before the run (TEST-15), each reverted with the tree
+fingerprint checked afterwards (MUTATION.md habit 18), backup at a `mktemp`
+path per invocation.
+
+⚠️ **Re-driven in full on the MERGED tree** after TARIFF-10 landed on
+`release/1.0` (base `88c59a9` -> `559f0eb`). All eight give the same verdicts
+and the same red-check counts as before the merge, which is the answer that
+matters: TARIFF-10 added 650 lines of checks to `test_price.py` and none of
+them moves under any of these edits, because they grade `resolve_tariff()`'s
+*reachability from a configuration* and not the lookup. Clean `app/price.py` on
+the merged tree = **`90d8ca31f7c0109d`, 85953 B** (pre-merge it was
+`30d1a56f0117e571`, 83742 B; the difference is TARIFF-10's `provider_id()` /
+`provider_configured()`, which this card does not touch).
+
+| | mutation | Δ | red in |
+|---|---|---|---|
+| M1 | `at()` back to the shipped fixed one-hour scan over `self.points` | +68 B | **24 named checks**: `test_price.py` 14b ×4, 14c ×3, 14d, 14e ×3, 14f, 14g; `test_arbitrage.py` 10b ×6, 10c ×3, 10d ×2 |
+| M2 | drop the one-hour cap | −68 B | `test_price.py` 14d |
+| M3 | flat one-hour tail instead of the span in front | **+0 B** | `test_price.py` 14e ×3, 14g — 4 checks |
+| M4 | trust the caller's list order — drop the sort | −61 B | `test_price.py` 14f |
+| M5 | `covers()` grows its own hour-wide rule | +95 B | `test_price.py` 14e, 14g |
+| M6 | `window()` becomes a coverage query | −37 B | `test_price.py` 14g |
+| M7 | the window's end becomes inclusive | +1 B | `test_price.py` 14b ×4, 14c ×4, 14d, 14e ×4, 14f ×2, 14g — 16 checks |
+| M8 | the window's start becomes exclusive | −1 B | `test_price.py` 14b ×4, 14c ×4, 14d, 14f ×2, 14g, 14h, plus the pre-existing section 6 check — 14 checks |
+
+**M3 is the zero-byte one and it is the tail decision itself** — the case
+MUTATION.md names as the risky size, caught by the check written for it.
+
+**What the arbitrage file does NOT see, with sizes.** M2, M4, M5, M6 and M8
+leave `test_arbitrage.py` green, and that is honest rather than a gap to round
+off: they are `at()`-level properties (holes, caller order, `covers()`,
+`window()`, the start boundary) that no arbitrage fixture reaches, because the
+probes are seven minutes into a slot and the plans have no holes. The one that
+matters end to end — M1, the shipped rule — is red in **both** files, on the
+named check `THE PROPERTY THE DEFECT BROKE`.
+
+---
+
+## 7. TARIFF-10 landed on the base while this was open — what it changes here
+
+Base moved `88c59a9` → `559f0eb` mid-card. The question is not whether the
+branches merge; it is whether TARIFF-10 makes any sentence above **false**.
+
+**In `app/price.py` the two do not meet.** TARIFF-10 added `provider_id()` and
+`provider_configured()` beside `price_option()` and routed `load_prices()`
+through them. That is the option-reading layer; it touches nothing in
+`_Series`, `at()`, `covers()`, `window()` or `_cover_table()`. Git merged the
+file without a conflict, and the merged `at()` is byte-identical to the one the
+mutations above were driven against.
+
+**Behaviourally it widens who has a series at all, and that cuts one way only.**
+`run_tariff_refresh()` now runs on installs with `arbitrage_enabled` **off**, so
+a provider-configured site has a standing plan — and therefore a `_Series` —
+where before it had none. **It does not add a new `at()` consumer to the 30 s
+tick**, which is the claim worth checking rather than assuming:
+
+| caller of `at()`/`covers()` | reached by a non-trading install? |
+|---|---|
+| `arbitrage._point_at()` (`arbitrage.py:300`) | no — trading only |
+| `static_tariff.TariffPlan.price_at()` / `.words` `here` (`:750`, `:819`) | on the tick these are reached through `static_status()`, which builds a **`static_plan`** — hourly points, immune. `main.py` calls only `plan.words` on the fetched plan, which counts points and never looks one up |
+| `price_forecast._walk()` (`:562`, `:568`) | **`price_permits()` and `begin_phase()` have no caller in `app/main.py` at all** — §12's price-justified entry point is built and not yet wired |
+
+So TARIFF-10 neither creates nor closes any exposure this card is about. What it
+does do is make the defect's reach larger the moment such a site arms trading,
+because the series it would trade against now exists on every configured
+install rather than only on armed ones. That strengthens the case for the fix
+and changes nothing in its reasoning.
+
+**In `test_price.py` both cards appended a section 13.** Nothing is dropped:
+TARIFF-10's stays **13**, this card's is renumbered **14** (which is also this
+card's number), and the temp-directory teardown TARIFF-10 put at the end of the
+file stays at the end of the file. The two sections share no fixture, no option
+dict and no helper name; TARIFF-10's grades `resolve_tariff()`'s *reachability
+from a configuration* and drives real fetches with a counting transport, and
+**none of its checks moves under any of the eight mutations above** — measured,
+not assumed.
+
+---
+
+## 8. TARIFF-12 landed too — a plan may now be 90 minutes old when it is asked
+
+Base moved `559f0eb` → `a6e64fb` while this was open. TARIFF-12 stops a
+returned §11.4 degradation from overwriting a standing plan that is still
+inside `TARIFF_MAX_AGE_S`, so **a served plan can now be up to
+`3 × TARIFF_REFRESH_S = 5400 s` old** where before it was at most one refresh
+interval. `at()` is what answers *"what does it cost right now"* out of that
+older plan, so the question is fair and the answer is written out rather than
+assumed.
+
+**Per-point span: unaffected, structurally.** Every window is derived from the
+neighbouring points' **absolute `start` instants**. Those are `datetime`s inside
+a frozen dataclass inside a tuple — they cannot move, and `_cover_table()` runs
+once at construction over data that cannot change afterwards. A plan's *age* is
+a property of `fetched_at` / `tariff_at`, never of a window. **The index cannot
+go stale**, which is a small positive under TARIFF-12 rather than a risk: a kept
+plan now lives longer, and there is nothing in it that needed recomputing.
+
+**The one-hour cap: unaffected.** It bites only where a gap exceeds an hour,
+i.e. at a hole FCST-04 left. Walking further into a series crosses more windows;
+each is still resolved on its own neighbours.
+
+**The tail: reachable for the first time, and the choice made in §2 is the one
+that survives it.** This is the half worth spelling out.
+
+* At the **shipped 48 h horizon** the tail is unreachable by staleness. A plan
+  is served for at most 90 minutes, so `now` is at most 90 minutes into a
+  ~48 h series — the last point is still about 46½ hours away.
+* But `price_horizon_h` is `int(1,72)` in `config.yaml`, so an operator **can**
+  configure a **1 h** horizon. A 90-minute serve-stale window against a 1 h
+  series puts `now` genuinely past the end. That is not hypothetical; it is a
+  supported configuration meeting a supported outage.
+* Under the **chosen** rule a quarter-hourly 1 h series ends at `:45` and that
+  point's window closes at the top of the next hour: `at()` raises `Absence`,
+  `_point_at()` returns None, `_act()` idles with its "no price for this
+  instant" reason, and §11.4 sends the site to the static profile.
+* Under the **rejected** flat one-hour tail the same stale plan would have gone
+  on trading against the `:45` print for **up to 45 minutes after the interval
+  it describes had ended** — pricing an outage with a number for a quarter that
+  is over.
+
+So TARIFF-12 does not weaken the tail decision. It is the first thing that makes
+it reachable on a shipped configuration, and it independently selects the same
+answer. ⚠️ **Note which direction that runs**: the more stale a plan is allowed
+to be, the more the tail rule is doing real work, so it should be re-read if
+`TARIFF_MAX_AGE_S` is ever widened again.
+
+**`TariffPlan.from_feed` cannot produce a series this code has not seen.** It is
+a pure predicate on `origin` (`== "provider"`), and TARIFF-12's decision keeps or
+replaces a **whole plan object**. It never splices two reads into one series, so
+it cannot hand `at()` an unsorted or duplicated point list — the case §3 covers
+defensively and that nothing shipped produces.
+
+**Re-graded on this base.** All 29 files green. `app/price.py` is byte-identical
+to the TARIFF-10 merge (`90d8ca31f7c0109d`, 85953 B) because TARIFF-12 does not
+touch it. **M1** re-driven: +68 B, red on the same **24 named checks** across
+both files. **M3** re-driven: **+0 B**, red on the same 4. This branch
+contributes **zero diff** to `app/main.py` and `app/static_tariff.py`.

goodwe_controller/DECISIONS/TARIFF-15-the-card-is-the-grader.md

@@ -0,0 +1,158 @@
+# TARIFF-15 — the operator's own tariff card, and why the card has to grade it
+
+**Status: DECIDED 2026-09-13 — ship `custom_formula` with FIXED coefficients and
+a REQUIRED `card` block whose printed price the add-on reproduces at startup or
+refuses to run. No expression evaluation, ever. Declare `{ENERGY, MARKUP}`,
+never `ALL_IN`.**
+
+Filed with TARIFF-15. Follows [[TARIFF-07]], which withdrew three per-supplier
+plugins and named a formula provider as the answer it could not give.
+
+---
+
+## 1. Why a formula rather than more plugins
+
+TARIFF-07 established the negative half: a per-supplier plugin has no source
+for its numbers. This card establishes the positive one.
+
+* **There is no machine-readable source of Belgian tariff coefficients
+  anywhere.** CREG's consumer tariff-card pages 404. CREG Scan is a
+  JavaScript-only wizard. The annual report carries the supplier list and no
+  per-product coefficients. VREG was unreachable. Every coefficient found in
+  research came from a supplier's **own PDF**, one of them image-only.
+* So there is nothing to scrape, and fourteen plugins would still have no
+  source for their numbers — they would be fourteen copies of the invention
+  TARIFF-07 deleted three of.
+* **The customer is the only party who can see their own coefficients**, and
+  the card they read them from **is the only artefact that can grade them**.
+  That second clause is the whole design; everything below follows from it.
+
+## 2. The shape is the market's published arithmetic
+
+Both suppliers whose 2026 cards were readable print three things on one line:
+the formula, the reference index it assumes, **and the resulting price**.
+
+| | computed | the card prints |
+|---|---|---|
+| Eneco `(0.102 × 133.9905 + 1) × 1.06` | **15.5471** | **15,55** |
+| ENGIE `(0.1 × 61.96 + 0.9) × 1.06` | **7.5218** | **7,522** |
+
+Two independent suppliers, reproduced to the last printed digit, through the
+shipped code (`test_price.py` 15a runs both, and then runs both again end to
+end through `load_prices()`).
+
+That third column is not a nicety. It is the only externally-published number
+in this whole feature, and it is what makes the design safe.
+
+## 3. The double-counting risk, and which half of it is new
+
+`price.py`'s trap 1 already mechanises that a **plugin** cannot double-count:
+`PluginOptions` refuses the framework keys, `code_leaks()` refuses a plugin
+whose *code* mentions them, `assemble()` adds the complement exactly once.
+
+`custom_formula` introduces a risk none of those can see, **because it is not
+in code**: the **operator** double-counting, by folding their network charges
+into `offset` while `price_taxes_eur_kwh` also carries them. `code_leaks()`
+scans code. This is config, typed by a person reading a PDF.
+
+It is a real reading of a real card, not a hypothetical. A Belgian card's
+`Tariefformule` line is the **energy component alone** — Eneco tabulates
+network tariffs in one table and levies in a second; ENGIE states in so many
+words that the formula excludes network, distribution, transport, grid levies
+and excise. An operator who wants "the price I actually pay" and adds ~12
+c€/kWh to `offset` has done something entirely reasonable and is now billed for
+network charges twice, on every hour, with §11.4 making the whole class of
+price defect invisible.
+
+**Decision: the card grades it.** At startup `validate.py` recomputes the
+card's own printed price from the operator's coefficients and refuses to start
+unless the two agree to within `0.01` — which is the last digit a card prints.
+An inflated `offset` cannot pass, because the printed estimate is by
+construction the energy component: 15.55 becomes 28.27 and the add-on stops and
+says why.
+
+**And the limit, stated in the same sentence as the claim**, exactly as
+`price.py` states trap 1's: *it grades the coefficients against the card, not
+the card against reality.* A consistent-but-wrong pair — both numbers off the
+wrong product, or off a card the contract has since rolled over from — agrees
+with itself perfectly and passes. Nothing here or anywhere else can catch that.
+
+### 3b. The one unit error the card check cannot see
+
+A factor applied to **both** sides — coefficients *and* printed price — cancels
+out of a comparison between them. That is a second quantity, so it is a second
+refusal: the card's own point must land inside 0.02–1.00 EUR/kWh.
+
+⚠️ **Its floor is applied to the ENERGY figure and not to the all-in one, and
+that asymmetry was found by a mutation rather than by reasoning.** The shipped
+`price_taxes_eur_kwh` is 0.06 — three times the floor — so a card read a
+hundred times too small comes out at 0.0016 EUR/kWh of energy, is carried over
+0.02 by the flat tax addend alone, and passes a band applied to the total. The
+hundredfold error is exactly what the band exists for. Graded from both
+directions in `test_price.py` 15e/15i and driven red as M10.
+
+## 4. Fixed coefficients. No expression evaluation of any kind
+
+**Decided: never a grammar.** Two arguments, and the second is the one that
+decides it.
+
+* **Security.** The add-on serves `POST config/save` → `POST
+  /addons/self/options` on its own ingress page, so `price_formula` is
+  **settable over HTTP**. `eval` on it is remote code execution in a root
+  container holding `SUPERVISOR_TOKEN`, with `homeassistant_api` and
+  `hassio_api`, driving an inverter over RS485. `eval(s, {"__builtins__": {}})`
+  is not a sandbox and this repository is not going to pretend otherwise.
+* **⚠️ AND THE DECIDING ARGUMENT IS NOT SECURITY: AN EXPRESSION IS
+  UNVERIFIABLE.** Two coefficients can be graded against the card's printed
+  estimate. An arbitrary expression cannot be graded against **anything** — so
+  it makes the invisible-wrong-coefficient problem *strictly worse*, which is
+  the exact failure this provider exists to prevent. An expression would buy
+  the operator freedom to be wrong in a way nothing could report.
+
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B × index + A`, so an expression buys nothing the market needs either.
+
+**Future shapes become NAMED FIELDS** — `clamp_lo`, `factor_negative`,
+`offset_bands` — each individually refusable and each individually gradeable
+against a card. `parse_price_formula()` therefore **refuses an unknown key**
+rather than ignoring it: an operator who types `"expr"` is told it does not
+exist, instead of being priced on the fields they also typed with the one they
+believed in dropped in silence.
+
+`test_price.py` 15f walks the module's AST for `eval`, `exec`, `compile`,
+`__import__` and `literal_eval`, and exercises the scanner's **red** direction
+on every run so it cannot become a scanner that scans nothing.
+
+## 5. `{ENERGY, MARKUP}`, not `ALL_IN`
+
+The contract's formula **is** the supplier's markup — that is what `B` and `A`
+are — but it is not the levies. Declaring `ALL_IN` would lie on behalf of every
+operator who typed exactly what their card says and would drop
+`price_taxes_eur_kwh` from every hour: measured at 0.2125 → 0.1555 EUR/kWh.
+`price_markup_eur_kwh` is therefore **ignored** under this provider, and logged
+as ignored, which is the framework's existing rule rather than a new one.
+
+## 6. What was reused rather than rebuilt
+
+The index path is `generic_dayahead`'s: same EPEX BE feed, same
+Brussels-calendar range, same columnar parser, same declared egress hosts. The
+override/range decision moved into one shared `dayahead_feed_url()` that both
+plugins call, because two copies of that rule would be two places for the
+short-horizon defect TARIFF-09 fixed to come back in only one of them.
+
+`resolution: hourly` averages each hour's members. ⚠️ **That is not
+`_Series.at()`'s hourly assumption returning (TARIFF-14):** it decides how many
+points are *emitted*; the window each point covers is still derived from its
+neighbours in `_cover_table()`. A feed that is already hourly averages one
+member per hour — the identity — so the option cannot silently assume the
+granularity it was handed. Graded.
+
+## 7. What this card did NOT do
+
+* **The injection leg.** Eneco uses `0,102` on consumption and `0,100` on
+  injection, and injection is VAT-exempt where consumption is at 6 % — a second
+  per-contract formula, not a second copy of this one. Separate card.
+* **The hour-varying network charge that bites Wallonia.** Separate card.
+* **Raising `price_taxes_eur_kwh` from 0.06 to ~0.12.** Separate card, and an
+  owner's decision. Note §3b: the band's floor is deliberately insensitive to
+  whatever that number becomes.

goodwe_controller/DOCS.md

@@ -116,7 +116,7 @@ whole rendered list, in both languages.
 
 | | |
 |---|---|
-| **All 71 options are always shown** | The frontend keeps a field when `name in options \|\| required`, and every key is in `options:`. There is no "advanced" fold |
+| **All 72 options are always shown** | The frontend keeps a field when `name in options \|\| required`, and every key is in `options:`. There is no "advanced" fold |
 | **Order comes from `schema:`** | `App.schema_ui` is `UiOptions(...)(data["schema"])`, so the **schema half** of `config.yaml` decides the order the tab renders in — not the `options:` half |
 | **There are no section headers** | Add-on options are a flat list: no header primitive, no per-option advanced flag, no units on the input, no sliders. Grouping is approximated by **order** plus the `Group · ` prefix in each label, and by nothing else |
 | **Groups, in task order** | Hardware → Meter → Limits → Tariff → Maintenance → Safety → Advanced |
@@ -1369,7 +1369,7 @@ does, and only after you have read why.
 
 | option | meaning |
 |---|---|
-| `price_provider` | `off` (default) or one of the five plugins below |
+| `price_provider` | `off` (default) or one of the three plugins below |
 | `price_markup_eur_kwh` | Your supplier's margin, EUR/kWh. **Added only when the chosen plugin's feed does not already contain it** |
 | `price_taxes_eur_kwh` | Levies and VAT, EUR/kWh. Same rule |
 | `export_price_eur_kwh` | The **injection** price. A separate scalar, not a series — see below |
@@ -1378,6 +1378,7 @@ does, and only after you have read why.
 | `price_horizon_h` | How far ahead to ask for, hours |
 | `price_timeout_s` | Per-request timeout |
 | `static_profile` | A static day/night or fully-fixed tariff. Empty by default — see below |
+| `price_formula` | For `custom_formula` only: your own contract's two coefficients, off your own tariff card. Empty by default — see below |
 
 **Which plugin sources what.** This is the one thing to get right, because
 adding your markup to a price that already contains it makes every future
@@ -1386,11 +1387,86 @@ arbitrage decision wrong by that amount, in a direction nothing reports.
 | plugin | product | the published figure contains | the add-on adds |
 |---|---|---|---|
 | `generic_dayahead` | day-ahead | energy only (wholesale EPEX BE) | markup **and** taxes |
-| `engie_dynamic` | day-ahead | energy + Engie's markup | taxes |
-| `totalenergies_dynamic` | day-ahead | energy + TotalEnergies' markup | taxes |
-| `eneco_eddy` | **real-time / imbalance** | everything, all-in | nothing |
+| `custom_formula` | day-ahead | energy **and** your contract's markup — your card's `Tariefformule` line | taxes |
 | `manual_csv` | day-ahead | everything, all-in | nothing |
 
+⚠️ **Three plugins were withdrawn in TARIFF-07, and if your configuration names
+one of them, read this.** `engie_dynamic`, `totalenergies_dynamic` and
+`eneco_eddy` are gone. They did not stop working — **they never worked.** Each
+pointed at an endpoint that does not exist and never did:
+
+| id | its endpoint | what that endpoint actually answers |
+|---|---|---|
+| `engie_dynamic` | `https://api.engie.be/dynamic/be` | **404**, gateway error `no Route matched with those values` |
+| `totalenergies_dynamic` | `https://api.totalenergies.be/prices/dynamic` | **TLS failure** — that hostname is not in the server's certificate |
+| `eneco_eddy` | `https://api.eneco.be/eddy/prices` | **404**, empty body |
+
+Every fetch any of them ever made failed, and a failed fetch falls back to the
+static tariff **silently** — so a site set to one of these has been running on
+`static_profile`, or on nothing at all, since the day it was configured, with
+nothing on the status page saying so. The add-on now **refuses to start** on one
+of these ids and tells you all of the above by name. That is deliberate: a
+silent fallback is what hid this for as long as it lasted.
+
+There is no automatic migration and there cannot be one. These were *retail*
+tariffs of the form `B x spot + A` with **per-contract** coefficients that live
+behind your supplier's customer login; there is no public index to read them
+from. Any alias would have to invent the numbers your battery is priced against.
+(`eneco_eddy` was doubly wrong: **"Eddy" is not an Eneco product at all** —
+Eneco's dynamic product is *Zon & Wind Dynamisch*, and it is indexed to
+Belpex/EPEX **day-ahead**, not to imbalance.)
+
+#### So what should a Belgian dynamic-tariff customer do today?
+
+**Honestly: `generic_dayahead` gets you close, and you should know exactly how
+close.** It reads the wholesale EPEX BE day-ahead curve and adds your
+`price_markup_eur_kwh` and `price_taxes_eur_kwh` as **flat** scalars. Your real
+Belgian dynamic contract is a **formula**:
+
+```
+consumption:  price = B x spot + A          <- B and A are in YOUR contract
+```
+
+`generic_dayahead` cannot express that. Two gaps, and the second is the
+harder one — **both are closed by `custom_formula`**, which is what the
+rest of this section is about:
+
+* **No multiplier.** `B` is typically slightly above 1 (it scales the wholesale
+  price before anything is added). A flat markup cannot scale anything, so the
+  *shape* of your curve is right but its *amplitude* is not — the peaks and
+  troughs the optimiser trades against are compressed relative to your bill.
+* **No negative offset.** `A` is frequently **negative** on injection and can be
+  on consumption. `price_markup_eur_kwh` is `float(0,1)` in the schema — it
+  **cannot hold a negative number at all**, so that contract shape is currently
+  inexpressible rather than merely approximate.
+
+What that means in practice: arbitrage decisions made on `generic_dayahead` are
+made against a curve that is *correlated* with your bill, not equal to it. For
+deciding **which hours** are cheap that is usually good enough; for deciding
+**whether a cycle pays for itself** — which is what `cycle_cost_threshold_eur`
+compares against — it is an approximation, and one that errs by however far `B`
+is from 1.
+
+**`custom_formula` is the answer to exactly this, and it shipped in TARIFF-15.**
+You type your contract's two coefficients once, off your own tariff card, and
+the add-on evaluates `B x index + A` against the same EPEX BE day-ahead curve
+`generic_dayahead` reads. Both gaps above close: `B` is a real multiplier, and
+`A` may be negative. It is documented in full in **[Your own tariff formula
+(`custom_formula`)](#your-own-tariff-formula-custom_formula)** below.
+
+So there are three honest options rather than two:
+
+1. **`custom_formula`** — your contract's own arithmetic, if you can read the
+   two coefficients off your tariff card. This is the one to use.
+2. **`generic_dayahead`** with your markup and taxes set as well as you can —
+   accepting the approximation above; or
+3. **`manual_csv`**, where you compute the all-in prices yourself from your own
+   contract's formula and hand the add-on the answers. Nothing is approximated,
+   but nothing is automatic either.
+
+If you are on a **fixed** or **day/night** tariff — most Belgian households —
+neither of those applies: use `static_profile` and leave `price_provider: off`.
+
 You cannot get this wrong by editing the markup: each plugin *declares* what its
 feed contains and the add-on adds only the rest. Set a markup under a plugin
 that already carries one and it is **ignored, with a line in the log saying so**
@@ -1404,10 +1480,13 @@ whether a plugin described its supplier's feed truthfully — that is a claim
 about somebody else's tariff, and no code can verify it. If you write a plugin,
 the `sources` declaration is the part a reviewer has to read.
 
-`eneco_eddy` is a real-time/imbalance product rather than a day-ahead one. It is
-flagged as high-volatility, which widens arbitrage thresholds once the
-optimiser lands. That comes from the plugin's own declaration, not from its
-name.
+**Real-time / imbalance products still have a place in the machinery, but no
+plugin declares one.** A plugin that declares `PriceProduct.REALTIME` is flagged
+high-volatility and gets widened arbitrage thresholds; that comes from the
+plugin's own declaration, never from its name. All three shipped plugins are
+day-ahead, so nothing exercises that path on a real install today — it is kept
+on purpose so the first genuine imbalance product does not have to rebuild it.
+See `DECISIONS/TARIFF-07-withdrawing-three-plugins.md`.
 
 **`generic_dayahead` and the shape of the public feed.** It reads Fraunhofer
 ISE's Energy-Charts API (`https://api.energy-charts.info/price?bzn=BE`, no key
@@ -1461,7 +1540,165 @@ and the moment it retires; the plan's own age is **not** reset by the failed
 refresh, so a kept plan still expires on schedule and is never presented as a
 current one. One failed fetch is a blip, not a lost tariff.
 
-**`manual_csv` — the offline fallback.** It needs no internet, no supplier
+#### Your own tariff formula (`custom_formula`)
+
+**What it is for.** A Belgian dynamic contract prices energy as a formula —
+your supplier's tariff card prints it as `Tariefformule` — and the two
+coefficients in it belong to *your contract*. There is no machine-readable
+source for them anywhere: CREG's consumer tariff-card pages return 404, CREG
+Scan is a JavaScript wizard, the annual report lists suppliers without
+per-product coefficients, and VREG was unreachable. Every coefficient found in
+research came off a supplier's own PDF, one of them image-only. **You are the
+only party who can see your own coefficients**, so you type them, once.
+
+Set `price_provider: custom_formula` and fill in `price_formula` with one line
+of JSON:
+
+```json
+{"index": "epex_be", "resolution": "hourly",
+ "factor": 0.102, "offset": 1.00,
+ "units": "c_eur_per_kwh", "vat_pct": 6,
+ "card": {"month": "2026-09", "index_eur_per_mwh": 133.9905,
+          "expect_incl_vat": 15.55}}
+```
+
+The contract it expresses is:
+
+```
+price = (factor x index_eur_per_mwh + offset) x (1 + vat_pct / 100)
+```
+
+expressed in `units`, and **converted to EUR/kWh by the add-on**. You type what
+your card prints, in the card's own units; every unit conversion and the VAT
+multiplication are the add-on's job, because those are exactly the two steps
+where a human silently loses a factor of 10, 100 or 1.06.
+
+| field | what it is |
+|---|---|
+| `index` | the reference series. `epex_be` — the EPEX BE day-ahead curve in EUR/MWh, the same feed `generic_dayahead` reads |
+| `resolution` | `quarter_hourly` (the 96 points the feed publishes) or `hourly` (each hour's quarters averaged into one point). Your card says which series your contract is written against |
+| `factor` | `B` — the multiplier on the index. Must be a number, and positive |
+| `offset` | `A` — the fixed part, in the same units. **May be negative** |
+| `units` | `c_eur_per_kwh`, `eur_per_kwh` or `eur_per_mwh`. **Required, with no default** |
+| `vat_pct` | the VAT percentage. `6` for Belgian residential electricity — not `0.06` and not `106`. `0` is legitimate |
+| `card` | the month the card is dated, the reference index it assumed, and the price it prints. **Required** — see below |
+
+##### A worked example, from a real card
+
+Eneco's September 2026 card prints the formula, the reference index it assumed
+*and* the resulting price. With `factor: 0.102`, `offset: 1.00`, `vat_pct: 6`
+and the card's own index of `133.9905` EUR/MWh:
+
+```
+(0.102 x 133.9905 + 1.00) x 1.06 = 15.5471 c€/kWh     the card prints 15,55
+```
+
+ENGIE's card, in the same shape with its own numbers:
+
+```
+(0.100 x 61.96 + 0.90) x 1.06 = 7.5218 c€/kWh         the card prints 7,522
+```
+
+Both reproduce to the last digit the card prints, through the shipped code —
+`test_price.py` section 15a runs exactly these two.
+
+##### ⚠️ The `card` block is required, and it is the safety mechanism
+
+Because your card prints the index it assumed **and** the price that comes out,
+the add-on can check your coefficients against your supplier's own worked
+example. At startup it recomputes that printed price from the numbers you
+typed and **refuses to start** unless the two agree to within `0.01` — naming
+the discrepancy, the ratio, and the likely causes.
+
+That catches, in one check: VAT left out, VAT applied twice, a transposed
+digit, and a **unit mismatch** between your coefficients and the price you
+typed beside them (a factor of 10, 100 or 1000).
+
+And it catches the expensive one. **Your card's formula line is the energy
+component only.** Eneco tabulates network tariffs in one table and levies in a
+second; ENGIE states that the formula excludes network, distribution,
+transport, grid levies and excise. The add-on therefore declares that
+`custom_formula` supplies *energy and markup*, and adds `price_taxes_eur_kwh`
+on top — once. If you fold your network charges into `offset`, you are billed
+for them twice, and nothing on the status page would ever show it. It cannot
+happen: ~12 c€/kWh of network charge moves the computed 15.55 to about 27, and
+the add-on refuses to start and says so.
+
+⚠️ **And the limit of that check, in the same breath as the claim: it grades
+your coefficients against your card, not your card against reality.** Two
+numbers copied off the wrong product — or off a card your contract has since
+rolled over from — agree with each other perfectly and pass. Nothing can catch
+that. What is mechanised is that your coefficients and your card's printed
+price *agree*; whether the card is the right card is yours to know. The add-on
+warns (and does not refuse) when `card.month` is more than about six months
+old, because ENGIE freezes coefficients for a contract's duration and an old
+card is often exactly right.
+
+One more check runs beside it: the card's own point must land inside the range
+a Belgian retail tariff can occupy (0.02–1.00 EUR/kWh). That exists because a
+unit error applied to **both** sides at once cancels out of the comparison
+above and cannot cancel out of this one. It bounds the card's own point, **not
+every hour** — a live hour may legitimately fall outside it, and a negative
+day-ahead hour, which is the best charging opportunity of the year, is never
+refused.
+
+##### ⚠️ Fixed coefficients. No expression is evaluated, ever
+
+`price_formula` takes numbers. There is no field that accepts an expression,
+and an unrecognised field is **refused** rather than ignored, so typing
+`"expr": "..."` tells you it does not exist instead of quietly pricing you on
+the other fields.
+
+Two reasons, and the second is the decisive one:
+
+* This string is settable over HTTP — the add-on's own ingress configuration
+  page posts it to the Supervisor — so evaluating it would be remote code
+  execution inside a root container that holds a Supervisor token and drives
+  an inverter. (`eval` with an emptied `__builtins__` is not a sandbox.)
+* **An expression could not be graded against anything.** Two coefficients can
+  be checked against your card's printed price; an arbitrary expression
+  cannot, so it would make the invisible-wrong-coefficient problem strictly
+  worse — which is the exact failure this provider exists to prevent.
+
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B x index + A`, so an expression would buy nothing the market needs. If a
+future contract needs a different shape, it gets a **named field**
+(`clamp_lo`, `factor_negative`, `offset_bands`) that can be refused on its
+own. Never a grammar.
+
+##### What you see at startup
+
+The first time the feed answers, the add-on logs a preview of the next 24
+hours as `index EUR/MWh -> all-in EUR/kWh`, followed by the minimum, median,
+maximum and the day's spread. It is there so that a formula off by a factor of
+1000 is visible in one line rather than in a month of bills:
+
+```
+custom_formula preview - the next 24 h of YOUR tariff, index EUR/MWh -> all-in
+EUR/kWh, computed as (0.102 x index + 1) x (1 + 6/100) c_eur_per_kwh, converted
+to EUR/kWh and with price_taxes_eur_kwh added by the framework:
+    2026-09-10T00:00:00+02:00    216.080 ->   0.30423
+    2026-09-10T00:15:00+02:00    216.080 ->   0.30423
+    ... 72 further point(s) not listed; the figures below cover ALL 96
+  min 0.17277 / median 0.28031 / max 0.67499 EUR/kWh, spread 0.50222 EUR/kWh
+  over 96 point(s). ⚠️ If those are a thousand times what your bill says,
+  `units` is wrong; if the spread is 0, `factor` is.
+```
+
+(That transcript is the shipped code run against the committed
+`scenarios/energy-charts-be-price-2026-09-10-quarterhourly.json` capture with
+the default markup and taxes, not an illustration.)
+
+##### What it does not do
+
+The **injection** leg is a separate card. Eneco uses `0,102` on consumption and
+`0,100` on injection, and injection is VAT-exempt where consumption is at 6 %,
+so it is a second per-contract formula rather than a second copy of this one.
+`export_price_eur_kwh` is still the scalar you enter by hand.
+
+#### `manual_csv` — the offline fallback
+
+It needs no internet, no supplier
 account and no HTTP stack at all, and it is the supported way to run this
 add-on price-aware on a site with no outbound connectivity. Write a file and
 point `price_csv_path` at it:
@@ -1519,20 +1756,59 @@ applies to those hours, and asking the plan for one raises rather than
 answering. An hour with no price is not a free hour, and the fill does not
 invent a neighbour, a mean or a zero for it.
 
-**A quarter-hourly feed keeps all four of its prints.** `eneco_eddy` settles
-per quarter, and the fill decides *which whole hours need carrying* — never what
-a published hour may contain. Every point the provider published inside the
+**A quarter-hourly feed keeps all four of its prints.** Belgian day-ahead
+settles per quarter — the 15-minute MTU took effect on 2025-10-01, so
+`generic_dayahead` reads 96 points a day — and the fill decides *which whole
+hours need carrying*, never what a published hour may contain. Every point the provider published inside the
 horizon is passed through untouched; a carried point is added only for a whole
 hour the feed did not print at all.
 
 **What you can actually see on the status page.** *Price history* (below) says
 what is held. *Arbitrage* carries the strategy's own sentence, which names the
-firm/provisional split whenever that split is what refused a trade. *Tariff*
-does **not** report the fill: it is the static-profile or Home Assistant
-price-entity sentence, regenerated on the 30 s tick. The provider plan's own
-line — `dynamic_dayahead from generic_dayahead, 48 h, provisional` — goes to the
-**add-on log** at every refresh, alongside `§8.3: 33 of 48 hours carried forward
-from yesterday's profile and flagged provisional; 15 published`.
+firm/provisional split whenever that split is what refused a trade. And
+**Tariff** on the status page reads `provisional` through the morning, because
+since TARIFF-11 that row carries the provider plan itself:
+
+```
+Tariff: no static profile (recomputed this tick); provider plan fetched 412 s
+        ago for a 48 h horizon: dynamic_dayahead from generic_dayahead,
+        60 points over 33 h, 36 firm / 24 carried, 900+3600 s spacing,
+        provisional
+```
+
+⚠️ **The two halves of that row are not computed at the same moment, and the
+row says so.** Everything before the semicolon is the static-profile or Home
+Assistant price-entity sentence, regenerated on the **30 s tick** from options
+alone — no network. Everything after it is the **background refresh's**
+resolution, which runs every 1800 s and is served for up to 5400 s before it is
+retired; `fetched N s ago` is the age of the fetch that produced it and is the
+only figure in the row that tells you whether the feed is still answering. On a
+site with a provider configured and no usable plan the row says that too,
+rather than falling silently back to the static half.
+
+Read the plan half as five separate facts: which *product* the feed publishes
+and which *plugin* read it, how many **points** it carries and how many **whole
+hours** those points cover, how many of the points are **firm** (published for
+their own interval) against **carried** (filled from yesterday under §8.3), the
+**spacing** of the points in seconds — `900+3600` is the normal mixed steady
+state, quarter-hourly firm points beside hourly carried ones — and `provisional`
+whenever any point is carried.
+
+⚠️ **Points and hours are two different numbers and this row used to print one
+of them under the other's name.** `words` was `f"… {len(points)} h"`, so a
+33-hour plan of quarter-hourly points logged `dynamic_dayahead from
+generic_dayahead, 132 h`. It is the same conflation the *Price history* row
+carried before FCST-04 and the same one `at()` carried before TARIFF-14, and it
+is **not a constant factor**: measured over a 40-hour soak the overstatement
+ranged **1.79× to 5.33×**, because the carried points are hourly while the firm
+ones are quarter-hourly, so the ratio moves with the mix as the day goes on.
+The same sentence is in the **add-on log** at every refresh, alongside `§8.3:
+33 of 48 hours carried forward from yesterday's profile and flagged
+provisional; the feed published 60 points over the other 15 hours`.
+
+The §8.3 refusal an operator reads when a trade is declined counts in the same
+two units — `§8.3: only 1 of 96 points carry a published price - 1 of 24 hours`
+— where it used to say `only 1 of 96 hours` about a 24-hour day.
 
 The plan is also now cut to the horizon you asked for, which means **hours that
 have already elapsed are no longer in it**. That is a real change to arbitrage:
@@ -1571,8 +1847,21 @@ volume being full exactly as it applies to the volume being absent.
 
 **Injection is priced separately** (`export_price_eur_kwh`). In Belgium it is
 often near zero, which by itself strongly favours self-consumption over export.
-It is a single number rather than a curve because no supported supplier
-publishes a dynamic injection tariff; negative values are accepted.
+Negative values are accepted — you can be paid to *not* export at midday in
+summer.
+
+⚠️ It is a single number rather than a curve, and the reason given here until
+TARIFF-07 — *"no supported supplier publishes a dynamic injection tariff"* — was
+**false**. Suppliers do. Eneco publishes `0,1 x BELPEX-H − 1,188` on the same
+tariff card as its consumption formula (identical on the January and the
+September 2026 cards), and ENGIE publishes one in the same shape,
+`(B x eSpot_15) − A`. What is true is narrower: an injection curve is the **same
+two-coefficient formula** as the consumption curve but with **its own**
+coefficients and **its own VAT treatment** — injection is VAT-exempt where
+consumption is at 6% — so it is a second per-contract formula rather than a copy
+of the first, and the add-on cannot evaluate either one yet. Until the formula
+provider ships, **this scalar is a simplification you enter by hand — an average
+of what you are actually paid — and not a reflection of the market.**
 
 **The old Home Assistant price sensors.** `price_now_entity` and
 `price_avg_entity` still work and are unchanged: the add-on compares them and
@@ -1700,6 +1989,33 @@ only thing that decides whether a request leaves the machine is
 `price_provider`: with it `off`, the refresh resolves the static profile in
 memory and opens no connection.
 
+**The *Arbitrage* status row says which of three things is true** — trading is
+off, trading is on and this cycle reached no decision, or a decision was
+reached — and it stamps every decision with its age. Until TARIFF-11 it said
+one of two, because the first two rendered identically. They have three
+different remedies:
+
+| the row opens with | what is true | what to do |
+|---|---|---|
+| **off** — *"arbitrage_enabled is false, so nothing trades"* | Trading is not armed. Nothing will happen, and nothing is wrong | Arm it, if you meant to |
+| **ON (arbitrage_enabled), but NO DECISION has been reached yet** | Trading **is** armed, and no cycle has run as far as the arbitrage step. The row then names the control loop's own reason, usually *inputs missing* | Fix the input the loop names |
+| **decided N s ago:** … | The strategy answered this cycle, and `N` is how old that answer is | Read the sentence that follows — it is the strategy's own |
+| **no decision this cycle (reason); the last one was taken N s ago:** … | Trading is armed, a decision stands from an earlier cycle, and **this** cycle stopped before reaching the step | As row 2 — the standing decision is history, not a verdict on now |
+
+A fifth rendering — *"…no decision this cycle …, and none stands from an
+earlier one"* — covers the case where trading was armed after a cycle had
+already run without it.
+
+⚠️ **The second row used to render exactly like the first one**, naming
+`arbitrage_enabled` on a site where `arbitrage_enabled` is `true`. A cycle with
+a missing input returns after roughly `stale_input_s` (15 s by default) without
+reaching the arbitrage step at all, so on an armed site the row reported *off*
+at startup and, once one decision had been taken, went on showing that decision
+for up to 15 s after the site stopped deciding anything. The age on the third
+row is printed **always**, including when it is zero: a row that reports
+staleness only once it is stale cannot be told from one that never reports
+it.
+
 ### Site
 
 | option | meaning |

goodwe_controller/MUTATION.md

@@ -780,6 +780,89 @@ static routing pin catches. The *bound* variant — right actuator, wrong
 numbers — is a different defect with a different fix, and it was absent. Both
 are in the table now.
 
+## TARIFF-15 — the card-graded formula, mutation by mutation
+
+Twenty-two mutations, one per check the card added, **run** rather than
+reasoned about. Harness: `/home/homelab/.cache/t15-mut/run.py`, backups beside
+it rather than in a shared scratchpad — two agents' harnesses collided in one
+this week. Each run restores from backup, purges `__pycache__` **on the host**
+first, and grades through the CI image with the tree bind-mounted `:ro`, so the
+interpreter cannot write a cache into the tree under test at all (TEST-15's
+structural immunity, borrowed).
+
+**No survivors.** Two entries are `+0 B` and are called out as such, per the
+reporting rule.
+
+| | mutation | file | Δ | red |
+|---|---|---|---|---|
+| M1 | `CARD_TOLERANCE` widened to 100 — the self-check stops checking | `custom_formula.py` | +1 B | **8** |
+| M2 | `CARD_TOLERANCE` tightened to 0 — the other direction, so the tolerance is a number and not a shape | `custom_formula.py` | −1 B | **16** |
+| M3 | `units` becomes optional | `custom_formula.py` | +10 B | 1 |
+| M4 | the `factor == 0` rung removed | `custom_formula.py` | −8 B | 1 |
+| M5 | the `factor < 0` rung removed | `custom_formula.py` | −7 B | 1 |
+| M6 | the `vat_pct` band widened to ±1000 | `custom_formula.py` | +6 B | 2 |
+| M7 | the non-finite rung removed from `_finite()` | `custom_formula.py` | −26 B | 2 |
+| M8 | the non-numeric rung removed from `_finite()` | `custom_formula.py` | −16 B | 4 |
+| M9 | an unknown top-level field ignored instead of refused | `custom_formula.py` | −2 B | 1 |
+| M10 | the plausibility **floor** applied to the all-in figure instead of the energy one | `custom_formula.py` | **+0 B** | 2 |
+| M11 | `hourly` stops averaging and emits the feed's own points | `custom_formula.py` | +12 B | 3 |
+| M12 | the hourly bucket takes the FIRST quarter instead of the mean | `custom_formula.py` | −11 B | 1 |
+| M13 | the preview drops the index column from each row | `custom_formula.py` | −13 B | 1 |
+| M14 | the preview is emitted on every refresh rather than once | `price.py` | −8 B | 1 |
+| M15 | `custom_formula` declares `ALL_IN` — the double-counting lie | `price.py` | −41 B | **10** |
+| M16 | a stale card never warns | `custom_formula.py` | −8 B | 1 |
+| M17 | a stale card REFUSES instead of warning | `validate.py` | −3 B | 1 |
+| M18 | the empty-formula refusal removed from the startup gate | `validate.py` | −38 B | 1 |
+| M19 | the index scaled to EUR/kWh before the formula — the factor-1000 | `price.py` | +2 B | **7** |
+| M20 | an `eval` call planted in `app/custom_formula.py` | `custom_formula.py` | +14 B | 1 |
+| M21 | `custom_formula` stops passing the caller's range to the feed | `price.py` | **+0 B** | 1 |
+| M22 | **PAIRED**: M1 *and* the plausibility band removed, together | `custom_formula.py` | −60 B | **12** |
+
+### The four that are worth reading rather than counting
+
+**M13 was a SURVIVOR of the whole suite on the first attempt, at −13 B.** The
+check read `"index EUR/MWh -> all-in EUR/kWh" in log` — which is the preview's
+**heading**. Deleting the index column from every **row** left the heading
+saying it prints something it no longer printed, and nothing went red. That is
+this file's third failure mode arriving in the check written to close it: the
+assertion ran, the sentence was true, and the data could not reach the failure
+it named. It is graded on a rendered ROW now, built here from the captured
+document (`'  216.080 ->   0.30123'`), and M13 is red.
+
+**M10 is `+0 B` and it is a real defect, not a synthetic one.** It came out of
+writing the mutation rather than out of review: `implausible_all_in()`'s floor
+was applied to the all-in figure, and `price_taxes_eur_kwh` ships at 0.06 —
+**three times the 0.02 floor** — so a card read a hundred times too small
+(0.0016 EUR/kWh of energy) is carried over the floor by the flat tax addend
+alone and passes. The hundredfold error is exactly what that band exists for.
+The floor is applied to the **energy** figure now and the ceiling to the all-in
+one, both directions are graded, and the trap is stated as a check in its own
+right so the asymmetry cannot be "tidied up" later.
+
+**M15 is the one the framework CANNOT catch, and the reds say which half does.**
+Declaring `ALL_IN` makes `assemble()` add nothing, and section 3's all-in check
+is *derived from the declaration* — so it passes on the lie, exactly as
+`price.py`'s trap 1 says no code can catch a misdeclaration. What goes red is
+the **docstring/declaration agreement** check, the card reproductions, and the
+`sources` pin: ten reds, none of them from the arithmetic. That is the
+guarantee at its true size — the two claims are held to agree, and whether
+either is true about somebody else's tariff remains human.
+
+**M22 is the paired run (TEST-16).** The card self-check and the plausibility
+band both answer a unit error, so each could be masking the other. Weakened
+**together** they produce twelve reds rather than the eight M1 alone produces,
+and the band's own checks stay red — so neither rung is doing the other's work.
+
+### What this battery does NOT establish
+
+It does not establish that a card is the right card. Every mutation above moves
+the relationship between the coefficients and the printed price; **none of them
+can move the relationship between the printed price and the operator's actual
+contract**, because nothing in this repository observes that. A
+consistent-but-wrong pair passes every one of these checks, by construction,
+and `DECISIONS/TARIFF-15-the-card-is-the-grader.md` §3 says so in the same
+sentence as the claim.
+
 ## Where each surface stands
 
 * **Local and dev-harness runs — the exposed one.** This is where FCST-03 hit

goodwe_controller/app/config_page.py

@@ -24,7 +24,7 @@ since the status page shipped; this file has five more chances to get it wrong.
 
 ⚠️ AND IT IS BUILT FOR A PHONE FIRST. This is the screen someone stands in
 front of the inverter with: one column, big touch targets, sections that start
-collapsed so 71 options do not arrive as one wall, and the refusal block pinned
+collapsed so 72 options do not arrive as one wall, and the refusal block pinned
 where it cannot be scrolled past.
 """
 

goodwe_controller/app/custom_formula.py

@@ -0,0 +1,670 @@
+"""TARIFF-15 - the customer's own tariff card, as two fixed coefficients.
+
+WHAT THIS IS FOR, in one sentence: a Belgian dynamic contract prices energy as
+`B x index + A` with coefficients that exist in exactly one place - the tariff
+card in the customer's klantenzone - so the customer types those two numbers
+and the add-on does every unit conversion and the VAT multiplication itself.
+
+WHY A FORMULA AND NOT FOURTEEN MORE PLUGINS (§9.2, TARIFF-07)
+=============================================================
+There is NO machine-readable source of Belgian tariff coefficients anywhere.
+CREG's consumer tariff-card pages 404, CREG Scan is a JS-only wizard, the
+annual report carries the supplier list and no per-product coefficients, and
+VREG was unreachable. Every coefficient found in research came off a supplier's
+own PDF, one of them image-only. So there is nothing to scrape and a
+per-supplier plugin would have no source for its numbers - fourteen plugins
+would be fourteen copies of the same invention, which is the defect TARIFF-07
+withdrew three plugins for. THE CUSTOMER IS THE ONLY PARTY WHO CAN SEE THEIR
+OWN COEFFICIENTS, and the card they read them from is the only artefact that
+can grade them.
+
+THE SHAPE IS THE MARKET'S PUBLISHED ARITHMETIC, NOT OUR APPROXIMATION
+====================================================================
+Both suppliers whose 2026 cards were readable print the formula, the reference
+index they assumed AND the resulting price, so the arithmetic below is
+reproducible against something they published rather than against our own
+guess:
+
+    Eneco   (0.102 x 133.9905 + 1.00) x 1.06 = 15.5471   card prints  15,55
+    ENGIE   (0.100 x  61.96   + 0.90) x 1.06 =  7.5218   card prints   7,522
+
+Two independent suppliers, reproduced to the last printed digit, in
+c EUR/kWh. test_price.py section 13 runs both through the SHIPPED code.
+
+⚠️ THE DOUBLE-COUNTING MECHANISM, AND WHY THIS DESIGN IS SAFE AT ALL
+====================================================================
+This provider declares `sources = {ENERGY, MARKUP}` and NOT `ALL_IN`. A Belgian
+card's `Tariefformule` line is THE ENERGY COMPONENT ONLY: Eneco puts network
+tariffs in one table and levies in a second, and ENGIE states in so many words
+that the formula "does not include fixed network/distribution costs, transport,
+grid levies, or excise duties". Declaring ALL_IN would lie on behalf of every
+user who typed what their card says, and would silently drop ~12 c EUR/kWh.
+
+price.py already mechanises that a PLUGIN cannot double-count (`PluginOptions`,
+`FRAMEWORK_KEYS`, `code_leaks()`). This provider introduces a risk none of those
+can see, because it is not in the code: THE OPERATOR double-counting, by folding
+their network charges into `offset` while `price_taxes_eur_kwh` carries them as
+well. `code_leaks()` scans code. This is config.
+
+So the card is the grader:
+
+    At startup validate.py computes
+    `(factor x card.index_eur_per_mwh + offset) x (1 + vat_pct/100)` and
+    REFUSES TO START unless it equals `card.expect_incl_vat` to within
+    CARD_TOLERANCE, naming the discrepancy.
+
+An `offset` inflated by network charges CANNOT PASS: the card's printed estimate
+is by construction the energy component alone, so adding ~12 c EUR/kWh moves
+15.55 to ~27 and the add-on refuses. The same check catches VAT omitted, VAT
+applied twice, a transposed digit, and a UNIT MISMATCH BETWEEN THE TWO SIDES -
+coefficients read off the formula line while the expected price is typed in
+another convention, which is the factor-10/100/1000 class as it actually
+happens.
+
+⚠️ THE ONE UNIT ERROR THE CARD CHECK CANNOT SEE IS THE ONE APPLIED TO BOTH
+SIDES AT ONCE, and saying so is the difference between a guard and a slogan:
+scaling the coefficients AND the expected price by the same 100 cancels out of
+a comparison between them. That is what `implausible_all_in()` is for, and it
+is a SEPARATE refusal on a SEPARATE quantity - the card's own point, all-in,
+against the band a Belgian retail tariff can occupy.
+
+⚠️ AND THE LIMIT, IN THE SAME BREATH AS THE CLAIM, exactly as price.py's trap 1
+states its own: THE CHECK GRADES THE COEFFICIENTS AGAINST THE CARD, NOT THE CARD
+AGAINST REALITY. A consistent-but-wrong pair - both numbers copied off the wrong
+product, or off last year's card - reproduces its own printed price perfectly
+and passes. Nothing here or anywhere else can catch that; what is mechanised is
+that the two coefficients and the printed estimate AGREE, which is the whole of
+the unit/VAT/decimal-point class and none of the "wrong contract" class.
+
+⚠️ FIXED COEFFICIENTS. NO EXPRESSION EVALUATION OF ANY KIND.
+============================================================
+All 24 surveyed Belgian products, both injection legs and aWATTar AT fit
+`B x index + A`, so an expression buys nothing the market needs. Against that:
+
+  * the add-on serves `POST config/save` -> `POST /addons/self/options` on its
+    own ingress page, so this string is SETTABLE OVER HTTP. `eval` on it is
+    remote code execution in a root container holding SUPERVISOR_TOKEN, with
+    `homeassistant_api` and `hassio_api`, driving an inverter over RS485.
+    (`eval(s, {"__builtins__": {}})` is not a sandbox and never was.)
+  * ⚠️ AND THE DECIDING ARGUMENT IS NOT SECURITY - AN EXPRESSION IS
+    UNVERIFIABLE. Two coefficients can be graded against the card's printed
+    estimate. An arbitrary expression cannot be graded against anything, so it
+    makes the invisible-wrong-coefficient problem STRICTLY WORSE, which is the
+    exact failure this provider exists to prevent.
+
+Future shapes become NAMED FIELDS - `clamp_lo`, `factor_negative`,
+`offset_bands` - each individually refusable and each individually gradeable
+against a card. Never a grammar. `parse_price_formula()` therefore REFUSES AN
+UNKNOWN KEY rather than ignoring it, so a user who types `"expr"` is told it
+does not exist instead of being silently priced on the fields they also typed.
+test_price.py section 13f walks this module's AST and fails if `eval`, `exec`,
+`compile`, `__import__` or `literal_eval` ever appears in it.
+
+WHERE THE NUMBERS COME FROM AND WHERE THEY GO
+=============================================
+`index` names the reference series. `epex_be` is the EPEX BE day-ahead curve in
+EUR/MWh, which is what `generic_dayahead` already fetches - same feed, same
+`brussels_date_range()` request, same columnar parser, same declared egress
+hosts. No new parser and no new failure mode.
+
+`resolution` says which series the contract is written against:
+
+  * `quarter_hourly` - the 96 points the feed publishes since Belgium's
+    15-minute MTU (2025-10-01), emitted as they are;
+  * `hourly`         - the four quarters of each hour averaged into one point.
+
+⚠️ NEITHER IS AN HOURLY ASSUMPTION IN `_Series.at()`'s SENSE (TARIFF-14). The
+hourly option changes how many POINTS are emitted and their spacing; the window
+each point covers is still derived from its neighbours by `_cover_table()`, and
+nothing here tells anything downstream how long a point lasts. A feed that is
+already hourly averages one member per hour, which is the identity - so the
+option cannot silently assume the granularity it was handed.
+
+`units` is NOT bureaucracy. Two suppliers publish the same shape in different
+units and the market aggregator prints both conventions in one column, so the
+add-on has to be told which one the card is in - and the unit conversion is the
+add-on's job precisely because it is one of the two steps that silently costs a
+factor of 10, 100 or 1000. The other is VAT, which is also the add-on's.
+"""
+
+import json
+import math
+from dataclasses import dataclass
+from datetime import date, datetime, timezone
+
+
+class FormulaInvalid(Exception):
+    """`price_formula` cannot be used. Raised by the parser, refused by
+    validate.py at startup - never at 03:00 on a fetch."""
+
+
+# --------------------------------------------------------------------------- #
+# The enumerations. Every one of these is a CLOSED set, and that is the point:
+# an unknown value is refused by name rather than guessed at.
+# --------------------------------------------------------------------------- #
+
+# unit -> how many EUR/kWh one of it is. ⚠️ THE WHOLE FACTOR-1000 CLASS LIVES
+# HERE, so the table is tiny, explicit, and has no "default".
+UNITS: dict = {
+    "c_eur_per_kwh": 0.01,      # eurocent per kWh - Eneco and ENGIE print this
+    "eur_per_kwh": 1.0,         # some aggregators print this
+    "eur_per_mwh": 0.001,       # the wholesale convention, occasionally reused
+}
+
+RESOLUTIONS: tuple = ("hourly", "quarter_hourly")
+
+# index id -> the human name of the series it refers to. One entry today; a
+# second index is a new row here plus a fetch path, not a new grammar.
+INDEXES: dict = {
+    "epex_be": "EPEX BE day-ahead, EUR/MWh",
+}
+
+# ⚠️ 0.01 IN THE CARD'S OWN UNITS, WHICH IS THE LAST DIGIT BOTH REAL CARDS
+# PRINT. Eneco prints 15,55 against a computed 15.5471 (0.0029 out) and ENGIE
+# prints 7,522 against a computed 7.5218 (0.0002 out), so the tolerance has to
+# absorb the card's own rounding and nothing more. Every error class this check
+# exists for - a factor of 10, of 100, of 1000, a missing or doubled 1.06, a
+# transposed digit, ~12 c EUR/kWh of network charge folded into `offset` - is
+# at least two orders of magnitude bigger than this.
+CARD_TOLERANCE = 0.01
+
+# The all-in plausibility band, EUR/kWh. `MAX_PLAUSIBLE_EUR_KWH` in price.py
+# bounds only prices that are too LARGE; this is the other end, and it is the
+# one the factor-1000 error falls off.
+PLAUSIBLE_LO_EUR_KWH = 0.02
+PLAUSIBLE_HI_EUR_KWH = 1.00
+
+# ~6 months. ⚠️ A WARNING, NEVER A REFUSAL: ENGIE freezes a contract's
+# coefficients for its duration, so a card two years old can be exactly right
+# and a site refused over one would be a site that cannot start.
+CARD_STALE_DAYS = 183
+
+_CARD_KEYS = ("month", "index_eur_per_mwh", "expect_incl_vat")
+_TOP_KEYS = ("index", "resolution", "factor", "offset", "units", "vat_pct",
+             "card")
+
+
+@dataclass(frozen=True)
+class FormulaSpec:
+    """One contract's published arithmetic. SEVEN numbers and no code.
+
+    ⚠️ EVERY FIELD IS A FIXED, NAMED SCALAR. There is deliberately no field
+    that holds an expression, a callable, a lambda or a template, and there is
+    no place to put one: `parse_price_formula()` refuses an unrecognised key.
+    """
+
+    index: str
+    resolution: str
+    factor: float
+    offset: float
+    units: str
+    vat_pct: float
+    card_month: str                 # "YYYY-MM", as the card is dated
+    card_index_eur_per_mwh: float
+    card_expect_incl_vat: float     # in `units`, as the card prints it
+
+    @property
+    def unit_to_eur_kwh(self) -> float:
+        return UNITS[self.units]
+
+
+# --------------------------------------------------------------------------- #
+# The arithmetic. Two functions, and the SECOND one is the contract.
+# --------------------------------------------------------------------------- #
+
+def in_card_units(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
+    """`(factor x index + offset) x (1 + vat_pct/100)`, in the card's units.
+
+    This is the line the card prints, spelled exactly as the card spells it,
+    and it is the only place the coefficients are combined. The card
+    self-check and the price path both go through here, so a mutation to it
+    cannot move the price without also moving the self-check.
+    """
+    return ((spec.factor * float(index_eur_per_mwh) + spec.offset)
+            * (1.0 + spec.vat_pct / 100.0))
+
+
+def price_eur_kwh(spec: FormulaSpec, index_eur_per_mwh: float) -> float:
+    """The energy+markup price for one index value, in EUR/kWh.
+
+    ⚠️ THE UNIT CONVERSION IS THE ADD-ON'S JOB AND IT HAPPENS HERE, ONCE. The
+    user types what their card prints, in the card's own units; every step
+    from there to EUR/kWh is code, because those steps are exactly the ones
+    that silently cost a factor of 10, 100 or 1000 when a human does them.
+    """
+    return in_card_units(spec, index_eur_per_mwh) * spec.unit_to_eur_kwh
+
+
+def card_discrepancy(spec: FormulaSpec) -> float:
+    """How far the coefficients land from the card's own printed estimate.
+
+    In the card's units, signed: positive means the formula computes MORE than
+    the card prints, which is the direction an `offset` carrying network
+    charges moves it.
+    """
+    return in_card_units(spec, spec.card_index_eur_per_mwh) \
+        - spec.card_expect_incl_vat
+
+
+# --------------------------------------------------------------------------- #
+# Reading the option
+# --------------------------------------------------------------------------- #
+
+def _finite(value, field: str) -> float:
+    """A real, finite number - or a refusal naming the field.
+
+    ⚠️ SAME CLASS AS `_validate_raw()`'s NaN RULE, one layer earlier. A NaN
+    factor makes every price NaN, every comparison False, and an arbitrage
+    strategy that silently never fires; `True` is an `int` in Python and would
+    price the whole day at the index.
+    """
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise FormulaInvalid(
+            f"price_formula.{field} is {value!r}, which is not a number. "
+            f"Write the coefficient as a bare JSON number - 0.102, not "
+            f"\"0.102\" and not an expression: this provider takes FIXED "
+            f"coefficients and evaluates nothing.")
+    if not math.isfinite(float(value)):
+        raise FormulaInvalid(
+            f"price_formula.{field} is {value!r}, which is not finite. A NaN "
+            f"or an infinity here makes every price NaN, every price "
+            f"comparison False, and an arbitrage strategy that never fires "
+            f"while reporting that it is armed.")
+    return float(value)
+
+
+def _card(raw) -> tuple:
+    """The `card` block: the estimate the coefficients are graded against."""
+    if raw is None:
+        raise FormulaInvalid(
+            "price_formula has no \"card\" block, and it is REQUIRED. It is "
+            "the only thing that can tell a correct pair of coefficients from "
+            "a plausible-looking wrong one: the add-on recomputes your "
+            "supplier's own printed example from the numbers you typed and "
+            "refuses to start if it does not come out. Copy the three figures "
+            "off the same tariff card as the coefficients: "
+            "{\"month\": \"2026-09\", \"index_eur_per_mwh\": 133.9905, "
+            "\"expect_incl_vat\": 15.55}.")
+    if not isinstance(raw, dict):
+        raise FormulaInvalid(
+            f"price_formula.card is {type(raw).__name__}, not an object with "
+            f"{', '.join(_CARD_KEYS)}.")
+    unknown = sorted(set(raw) - set(_CARD_KEYS))
+    if unknown:
+        raise FormulaInvalid(
+            f"price_formula.card has no field(s) {unknown}. The fields it "
+            f"takes are {list(_CARD_KEYS)}; a key that is merely ignored is a "
+            f"number the operator believes took effect.")
+    month = str(raw.get("month", "") or "").strip()
+    if not _month_date(month):
+        raise FormulaInvalid(
+            f"price_formula.card.month is {raw.get('month')!r}; write the "
+            f"month the card is dated as \"YYYY-MM\", e.g. \"2026-09\". It is "
+            f"not used in any price - it is what lets the add-on tell you "
+            f"your card has gone stale.")
+    return (month,
+            _finite(raw.get("index_eur_per_mwh"), "card.index_eur_per_mwh"),
+            _finite(raw.get("expect_incl_vat"), "card.expect_incl_vat"))
+
+
+def _month_date(month: str):
+    """`"2026-09"` -> the first of that month, or None if it is not one."""
+    try:
+        year, mon = str(month).split("-")
+        return date(int(year), int(mon), 1)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_price_formula(value):
+    """`price_formula` -> a `FormulaSpec`, or None when unset.
+
+    Accepts what the option can actually arrive as, exactly as
+    `parse_static_profile()` does:
+
+      * `None` / `""` / `"null"`   - unset.
+      * a JSON string              - what config.yaml's flat `str?` option
+                                     carries on a Supervisor install.
+      * a dict                     - already parsed, from a future nested
+                                     schema, from sim/inject.py, or a check.
+
+    Raises `FormulaInvalid`; never returns a half-built spec.
+
+    ⚠️ THE CARD SELF-CHECK IS PART OF PARSING, not a separate step a caller
+    may forget. Both callers - validate.py's startup gate and the plugin's own
+    fetch - go through this one function, so there is no route to a price that
+    has not been graded against the card.
+    """
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text or text.lower() in ("null", "none", "off"):
+            return None
+        try:
+            value = json.loads(text)
+        except ValueError as e:
+            raise FormulaInvalid(
+                f"price_formula is not valid JSON ({e}). It is a JSON object "
+                f"on one line, e.g.\n"
+                f'  {{"index":"epex_be","resolution":"hourly","factor":0.102,'
+                f'"offset":1.00,"units":"c_eur_per_kwh","vat_pct":6,'
+                f'"card":{{"month":"2026-09","index_eur_per_mwh":133.9905,'
+                f'"expect_incl_vat":15.55}}}}\n'
+                f"Leave it empty unless price_provider is 'custom_formula'.")
+    if not isinstance(value, dict):
+        raise FormulaInvalid(
+            f"price_formula is {type(value).__name__}, not a JSON object with "
+            f"{', '.join(_TOP_KEYS)}.")
+
+    # ⚠️ AN UNKNOWN KEY IS REFUSED, NOT IGNORED, AND THIS IS THE HALF THAT
+    # KEEPS THE "NEVER A GRAMMAR" PROMISE HONEST. A future shape is a NAMED
+    # field - clamp_lo, factor_negative, offset_bands - added here and
+    # refusable on its own. Ignoring unknown keys would mean a user who typed
+    # "expr" or "formula" gets priced on the fields they also typed, with the
+    # one they believed in dropped in silence.
+    unknown = sorted(set(value) - set(_TOP_KEYS))
+    if unknown:
+        raise FormulaInvalid(
+            f"price_formula has no field(s) {unknown}. The fields it takes "
+            f"are {list(_TOP_KEYS)}. ⚠️ There is deliberately NO field that "
+            f"takes an expression: this provider multiplies and adds two "
+            f"FIXED coefficients and evaluates nothing, because two "
+            f"coefficients can be graded against your card's printed price "
+            f"and an arbitrary expression cannot be graded against anything. "
+            f"If your contract needs a shape this cannot express, it needs a "
+            f"new named field here - say which shape.")
+
+    index = str(value.get("index", "") or "").strip()
+    if index not in INDEXES:
+        raise FormulaInvalid(
+            f"price_formula.index is {value.get('index')!r}. The reference "
+            f"series this add-on can fetch are "
+            f"{', '.join(f'{k!r} ({v})' for k, v in sorted(INDEXES.items()))}. "
+            f"If your card names a different index, the add-on cannot get it "
+            f"and guessing which series your supplier meant would price your "
+            f"battery against the wrong curve.")
+
+    resolution = str(value.get("resolution", "") or "").strip()
+    if resolution not in RESOLUTIONS:
+        raise FormulaInvalid(
+            f"price_formula.resolution is {value.get('resolution')!r}; it "
+            f"must be one of {list(RESOLUTIONS)}. Belgium has been on a "
+            f"15-minute MTU since 2025-10-01 and the feed publishes 96 points "
+            f"a day; a contract written against the HOURLY series is priced "
+            f"on the mean of each hour's quarters. Which one your contract "
+            f"uses is on your card and cannot be inferred from the feed.")
+
+    # ⚠️ `units` IS REQUIRED AND HAS NO DEFAULT. A default here would be the
+    # factor-1000 class with a friendly face: the add-on would silently assume
+    # a convention the card never stated, and the card self-check would then
+    # be graded in units nobody chose.
+    units = str(value.get("units", "") or "").strip()
+    if units not in UNITS:
+        raise FormulaInvalid(
+            f"price_formula.units is {value.get('units')!r} and is REQUIRED - "
+            f"there is no default, on purpose. It must be one of "
+            f"{sorted(UNITS)}. Your card prints the formula in ONE of these "
+            f"and two suppliers use two different conventions for the same "
+            f"shape, so assuming one would be a factor of 100 or 1000 on "
+            f"every hour with nothing able to notice.")
+
+    factor = _finite(value.get("factor"), "factor")
+    offset = _finite(value.get("offset"), "offset")
+    vat_pct = _finite(value.get("vat_pct"), "vat_pct")
+
+    # ⚠️ ZERO IS NOT "NO INDEXATION", IT IS A FIXED TARIFF WEARING A DYNAMIC
+    # ONE'S CLOTHES. Every hour comes out at the same price, so every spread is
+    # 0, arbitrage can never clear any threshold, and a strategy that never
+    # fires is indistinguishable from one that is switched off (§14's warning
+    # box). The add-on already has a first-class way to say "one price": point
+    # the operator at it rather than let them build it by accident.
+    if factor == 0.0:
+        raise FormulaInvalid(
+            "price_formula.factor is 0, so the index would not enter the "
+            "price at all: every hour of every day comes out at "
+            f"{offset:g} x (1 + {vat_pct:g}/100), every spread is exactly 0, "
+            "and arbitrage can never clear any threshold - a strategy that "
+            "silently never fires rather than one that is off. If your tariff "
+            "really is one flat price, that is `static_profile` with a single "
+            "period covering 00:00-24:00 on all days and price_provider "
+            "'off'; the add-on then says so at startup instead of leaving you "
+            "to find out from a year of unchanged bills.")
+
+    # ⚠️ A NEGATIVE FACTOR INVERTS THE MARKET, and the direction is the danger:
+    # the dearest hour becomes the cheapest one, so the battery is told to
+    # charge into the evening peak and to discharge at 03:00. That is not a
+    # mispriced site, it is a site actively trading against itself.
+    if factor < 0.0:
+        raise FormulaInvalid(
+            f"price_formula.factor is {factor:g}, which is NEGATIVE. That "
+            f"inverts the market: the dearest hour of the day comes out as "
+            f"the cheapest one, so the battery would charge at the evening "
+            f"peak and discharge at 03:00 - trading against itself on every "
+            f"cycle. No consumption tariff is indexed negatively; if your "
+            f"card shows a minus sign it is on the OFFSET (`A`), which is "
+            f"allowed here and common on injection.")
+
+    # ⚠️ 0 IS LEGITIMATE AND MUST STAY SO: injection is VAT-exempt in Belgium,
+    # and some cards are already quoted VAT-inclusive. The bound exists for the
+    # 106 / 1.06 / 6 confusion, not to make VAT compulsory.
+    if not 0.0 <= vat_pct <= 30.0:
+        raise FormulaInvalid(
+            f"price_formula.vat_pct is {vat_pct:g} and must be between 0 and "
+            f"30. It is a PERCENTAGE, so Belgian residential electricity is "
+            f"6, not 0.06 and not 106. Zero is legitimate and is not refused: "
+            f"injection is VAT-exempt, and a card that already quotes "
+            f"VAT-inclusive coefficients needs no second multiplication.")
+
+    month, card_index, card_expect = _card(value.get("card"))
+    spec = FormulaSpec(index=index, resolution=resolution, factor=factor,
+                       offset=offset, units=units, vat_pct=vat_pct,
+                       card_month=month, card_index_eur_per_mwh=card_index,
+                       card_expect_incl_vat=card_expect)
+
+    delta = card_discrepancy(spec)
+    if abs(delta) > CARD_TOLERANCE:
+        raise FormulaInvalid(card_refusal(spec, delta))
+    return spec
+
+
+def card_refusal(spec: FormulaSpec, delta: float) -> str:
+    """The sentence an operator reads when their formula misses its own card.
+
+    ⚠️ IT NAMES THE DISCREPANCY AND THE SIX WAYS IT HAPPENS. "Invalid
+    configuration" would be true and useless: every one of these errors looks
+    exactly like a working tariff from the status page, which is why the check
+    exists at all.
+    """
+    got = in_card_units(spec, spec.card_index_eur_per_mwh)
+    ratio = (got / spec.card_expect_incl_vat
+             if spec.card_expect_incl_vat else float("inf"))
+    return (
+        f"price_formula does not reproduce its own card, so the add-on will "
+        f"NOT start on it. Your contract's arithmetic is "
+        f"price = (factor x index_eur_per_mwh + offset) x (1 + vat_pct/100); "
+        f"on the card's own index that is "
+        f"({spec.factor:g} x {spec.card_index_eur_per_mwh:g} + "
+        f"{spec.offset:g}) x (1 + {spec.vat_pct:g}/100) = {got:.4f} "
+        f"{spec.units}, but card.expect_incl_vat says "
+        f"{spec.card_expect_incl_vat:g} - OUT BY {delta:+.4f} {spec.units} "
+        f"(ratio {ratio:.4g}; the tolerance is {CARD_TOLERANCE}, which is the "
+        f"last digit a card prints). One of the two sides is wrong and the "
+        f"add-on cannot tell which, so it refuses rather than price a battery "
+        f"on it. The usual causes, in the order they happen: the coefficients "
+        f"and the expected price are in DIFFERENT units (ratio 10, 100 or "
+        f"1000 - `units` must be the one the formula line is printed in); VAT "
+        f"left out or applied twice (ratio 1.06 or 1/1.06); a transposed "
+        f"digit; the two sides copied off DIFFERENT cards or different "
+        f"months; or - the expensive one - network charges, levies or excise "
+        f"folded into `offset`. ⚠️ THEY DO NOT BELONG THERE: a Belgian card's "
+        f"Tariefformule line is the ENERGY component alone (Eneco tabulates "
+        f"network tariffs and levies separately; ENGIE says in so many words "
+        f"that the formula excludes network, distribution, transport, levies "
+        f"and excise), the add-on adds price_taxes_eur_kwh on top of it, and "
+        f"folding ~12 c EUR/kWh of network charge into `offset` bills you for "
+        f"it twice. That is the error this check exists to catch, and it is "
+        f"why it cannot be switched off.")
+
+
+# --------------------------------------------------------------------------- #
+# The two questions the PLUGIN cannot ask, because they need framework numbers
+# --------------------------------------------------------------------------- #
+
+def implausible_all_in(spec: FormulaSpec, taxes_eur_kwh: float):
+    """The card's own point, if its LEVEL cannot be a Belgian retail price.
+
+    Returns a refusal sentence or None. ⚠️ CALLED FROM validate.py AND FROM
+    NOWHERE ELSE, because it reads a FRAMEWORK-owned number: a plugin that
+    could see `taxes` could add it a second time, which is price.py's trap 1.
+
+    ⚠️ THE LOW END IS GRADED ON THE ENERGY COMPONENT AND THE HIGH END ON THE
+    ALL-IN FIGURE, AND THAT ASYMMETRY IS THE CHECK RATHER THAN AN OVERSIGHT.
+    `price_taxes_eur_kwh` ships at 0.06, which is three times the low bound -
+    so a card read a HUNDRED times too small comes out at 0.0016 EUR/kWh of
+    energy, is carried over the floor by the flat tax addend alone, and passes
+    a band applied to the all-in total. The hundredfold error is precisely
+    what this exists to catch, so the floor is applied where it can still see
+    it. The ceiling is applied to the all-in figure because that is the number
+    the site is really billed at, and taxes only push it up.
+
+    ⚠️ AND THE LIMIT, WITH THE CLAIM. This grades the CARD'S OWN POINT - one
+    price, at the monthly index the card assumed - and not every hour of every
+    day. A live EPEX hour can and should fall outside this band (a negative
+    hour is the best charging opportunity of the year, and §17 keeps a
+    regression case for it), so the band is deliberately NOT applied to the
+    fetched series. What it catches is a formula whose whole LEVEL is wrong,
+    which is the factor-of-1000 class arriving from the end
+    `MAX_PLAUSIBLE_EUR_KWH` does not bound.
+    """
+    energy = price_eur_kwh(spec, spec.card_index_eur_per_mwh)
+    all_in = energy + float(taxes_eur_kwh)
+    if energy >= PLAUSIBLE_LO_EUR_KWH and all_in <= PLAUSIBLE_HI_EUR_KWH:
+        return None
+    return (
+        f"price_formula's own card works out at {energy:.5f} EUR/kWh of "
+        f"energy ({spec.card_expect_incl_vat:g} {spec.units} as the card "
+        f"prints it) and {all_in:.5f} EUR/kWh all-in once "
+        f"price_taxes_eur_kwh is added, which is outside the plausible band "
+        f"{PLAUSIBLE_LO_EUR_KWH}-{PLAUSIBLE_HI_EUR_KWH} EUR/kWh for a Belgian "
+        f"retail tariff. The card self-check passed, so the coefficients and "
+        f"the printed price AGREE - they simply agree on a number no Belgian "
+        f"bill carries, which is what a whole card read in the wrong units "
+        f"looks like (a factor of 10, 100 or 1000 applied to BOTH sides at "
+        f"once cancels out of that check and cannot cancel out of this one). "
+        f"Check `units` against the unit printed beside your formula. "
+        f"⚠️ This bounds the CARD'S OWN POINT, not every hour: a live hour may "
+        f"legitimately fall outside the band, and a negative day-ahead hour - "
+        f"the best charging opportunity of the year - is never refused.")
+
+
+def stale_card(spec: FormulaSpec, today=None):
+    """A warning when the card is older than ~6 months, or None. NEVER a
+    refusal: ENGIE freezes a contract's coefficients for its duration, so an
+    old card can be exactly right and refusing one would stop the add-on on a
+    correctly configured site."""
+    dated = _month_date(spec.card_month)
+    now = today or datetime.now(timezone.utc).date()
+    if dated is None or (now - dated).days <= CARD_STALE_DAYS:
+        return None
+    return (
+        f"price_formula's card is dated {spec.card_month}, which is "
+        f"{(now - dated).days} days ago. Suppliers reprice: if your contract "
+        f"has been renewed or rolled over since then, the coefficients here "
+        f"are last year's and every price this add-on computes is wrong by "
+        f"however far they moved - and the card self-check cannot see it, "
+        f"because it grades your coefficients against the card you typed, not "
+        f"the card against your current contract. Not refused: ENGIE freezes "
+        f"coefficients for the contract's duration, so an old card is often "
+        f"exactly right. Worth re-reading your klantenzone once.")
+
+
+# --------------------------------------------------------------------------- #
+# Resolution
+# --------------------------------------------------------------------------- #
+
+def to_resolution(pairs, resolution: str) -> list:
+    """`[(instant, index EUR/MWh)]` -> the series the CONTRACT is written on.
+
+    `quarter_hourly` hands the feed's own points back, ascending.
+    `hourly` averages each hour's members into one point AT THE TOP OF THE
+    HOUR.
+
+    ⚠️ THE BUCKET IS A UTC HOUR AND THAT IS EXACT FOR BELGIUM, not an
+    approximation: CET and CEST are both WHOLE-hour offsets, so a Brussels hour
+    and a UTC hour start at the same instant on every day of the year including
+    both transition days. Keying by a naive local hour is what collides the two
+    02:00s in October; keying by the UTC instant cannot.
+
+    ⚠️ AND THIS IS NOT `_Series.at()`'s HOURLY ASSUMPTION COMING BACK
+    (TARIFF-14). It decides how many points are EMITTED, not how long one
+    covers - the coverage window is still derived from the neighbours in
+    `_cover_table()`. A feed that already publishes hourly points averages one
+    member per hour, i.e. the identity, so this cannot silently assume the
+    granularity it was handed.
+
+    ⚠️ AN INCOMPLETE HOUR IS AVERAGED OVER WHAT IS THERE rather than dropped or
+    zero-filled. A horizon that starts at 09:20 has two quarters in its first
+    hour; their mean is the best statement available about that hour, and
+    dropping it would leave a hole `at()` answers with `Absence` for an hour
+    the feed did publish.
+    """
+    ordered = sorted(pairs, key=lambda r: r[0].astimezone(timezone.utc))
+    if resolution == "quarter_hourly":
+        return list(ordered)
+    if resolution != "hourly":
+        raise FormulaInvalid(f"unknown resolution {resolution!r}")
+    buckets: dict = {}
+    for start, value in ordered:
+        key = start.astimezone(timezone.utc).replace(
+            minute=0, second=0, microsecond=0)
+        buckets.setdefault(key, []).append(value)
+    return [(k, sum(v) / len(v)) for k, v in sorted(buckets.items())]
+
+
+# --------------------------------------------------------------------------- #
+# The startup preview
+# --------------------------------------------------------------------------- #
+
+PREVIEW_HOURS = 24
+PREVIEW_MAX_ROWS = 24
+
+
+def preview_lines(spec: FormulaSpec, rows) -> list:
+    """`[(instant, index EUR/MWh, all-in EUR/kWh)]` -> lines for the log.
+
+    THE DEFECT THIS EXISTS TO MAKE VISIBLE: every error this module refuses is
+    one the operator cannot see from the status page, and the two numbers that
+    would have shown it - the index that went IN and the price that came OUT -
+    are never printed beside each other anywhere else. A factor of 1000 is
+    obvious in one line of `61.96 -> 0.13522` and invisible in a plan.
+
+    ⚠️ IT PRINTS A BOUNDED NUMBER OF ROWS AND SAYS SO. At `quarter_hourly` the
+    next 24 h is 96 points; the cap is a row COUNT rather than "every fourth
+    point", because sampling every fourth point would assume the granularity
+    TARIFF-14 spent a card removing the assumption of.
+    """
+    if not rows:
+        return []
+    shown = rows[:PREVIEW_MAX_ROWS]
+    prices = sorted(r[2] for r in rows)
+    mid = len(prices) // 2
+    median = (prices[mid] if len(prices) % 2
+              else (prices[mid - 1] + prices[mid]) / 2.0)
+    out = [
+        f"custom_formula preview - the next {PREVIEW_HOURS} h of YOUR tariff, "
+        f"index EUR/MWh -> all-in EUR/kWh, computed as "
+        f"({spec.factor:g} x index + {spec.offset:g}) x "
+        f"(1 + {spec.vat_pct:g}/100) {spec.units}, converted to EUR/kWh and "
+        f"with price_taxes_eur_kwh added by the framework:"]
+    for start, index, all_in in shown:
+        out.append(f"    {start.isoformat()}  {index:9.3f} -> {all_in:9.5f}")
+    if len(rows) > len(shown):
+        out.append(f"    ... {len(rows) - len(shown)} further point(s) not "
+                   f"listed; the figures below cover ALL {len(rows)}")
+    out.append(
+        f"  min {prices[0]:.5f} / median {median:.5f} / max {prices[-1]:.5f} "
+        f"EUR/kWh, spread {prices[-1] - prices[0]:.5f} EUR/kWh over "
+        f"{len(rows)} point(s). ⚠️ If those are a thousand times what your "
+        f"bill says, `units` is wrong; if the spread is 0, `factor` is.")
+    return out

goodwe_controller/app/main.py

@@ -218,6 +218,106 @@ def pack_energy_of(inv):
                                 inv.capacity_kwh, inv.max_w)
 
 
+def tariff_plan_row(plan, tick_words: str, *, age_s, horizon_h: float,
+                    provider: bool, max_age_s: float) -> str:
+    """The *Tariff* status row: the 30 s tick's sentence AND the provider plan.
+
+    THE DEFECT THIS PREVENTS (TARIFF-11). `origin`, `product`, the horizon,
+    the firm/carried split and the spacing appeared in NO status row. The row
+    was `static_status()`'s sentence alone, computed on the 30 s I/O-free tick
+    from its own static plan, and it NEVER SAW the provider plan - it read
+    `'no static profile'` at all 802 samples of a 40-hour soak on a site whose
+    feed was answering. The only external evidence a plan existed at all was
+    one `_LOG.info` line, and that line carried the point<->hour mislabel
+    `TariffPlan.words` is fixed for.
+
+    ⚠️ TWO SOURCES, TWO CLOCKS, AND THE ROW SAYS SO IN WORDS. These sentences
+    are NOT computed at the same moment and presenting them as though they
+    were would be a new version of the defect being fixed:
+
+        `tick_words`  static_status() / the Home Assistant price entities,
+                      regenerated on THIS tick, every 30 s, I/O-free;
+        `plan`        the background refresh's resolution, up to
+                      TARIFF_REFRESH_S old before it is retried and up to
+                      TARIFF_MAX_AGE_S (5400 s since TARIFF-12) old before
+                      `fresh_tariff_plan()` retires it.
+
+    So the plan half is stamped with its OWN age in seconds, measured from
+    `tariff_at` - the moment of the fetch that produced it, which TARIFF-12
+    deliberately does not move on a kept plan.
+
+    ⚠️ AND `age_s` IS THE CALLER'S MEASUREMENT, NOT THIS FUNCTION'S. A clock
+    read in here would be a second clock disagreeing with the one that decided
+    the plan was fresh enough to pass at all.
+
+    ⚠️ "NO PLAN" IS SAID OUT LOUD ON A SITE THAT CONFIGURED A PROVIDER. A
+    dynamic site whose refresh has never completed, or whose plan has aged
+    past `max_age_s`, is the exact state the soak measured; rendering it as
+    the bare static sentence is how it stayed invisible for 802 samples.
+    """
+    if plan is None:
+        if not provider:
+            return tick_words
+        return (f"{tick_words} (recomputed this tick); NO provider plan - "
+                f"none has been resolved yet, or the last one is older than "
+                f"{max_age_s:.0f} s")
+    return (f"{tick_words} (recomputed this tick); provider plan fetched "
+            f"{age_s:.0f} s ago for a {horizon_h:.0f} h horizon: {plan.words}")
+
+
+def arbitrage_row(*, on: bool, decision, decided_at, cycle_at, now,
+                  why: str) -> str:
+    """The *Arbitrage* status row: THREE states, which used to render as two.
+
+    THE DEFECT THIS PREVENTS (TARIFF-11). The row was
+    `"off (arbitrage_enabled)" if self.arb is None else self.arb.explain()`,
+    under a comment asserting that `self.arb is None` if and only if
+    `arbitrage.enabled(self.o)` was False. IT IS NOT: `cycle()` returns at the
+    input hold - inputs missing, `bad_for < stale_input_s`, default 15 s -
+    BEFORE it reaches `self.arb = None`. Driven: `arbitrage_enabled: true`
+    plus a sensor answering `None` gives `arbitrage.enabled(opts) = True`,
+    `self.arb = None` (its `__init__` value, untouched) and a row reading
+    `off (arbitrage_enabled)` - NAMING AN OPTION THAT IS ON. Past the first
+    completed cycle the same early return leaves the PREVIOUS decision
+    standing instead, which the row then rendered as a current one.
+
+    THE THREE FACTS, and they are three because they have three remedies:
+
+        trading is off          the operator has not armed it. Nothing is
+                                wrong and nothing will happen.
+        no decision this cycle  it is armed, and the cycle did not get as far
+                                as the arbitrage step. `why` is the control
+                                loop's own reason - usually "inputs missing".
+        a decision              the strategy's own sentence, with the age of
+                                the cycle that produced it.
+
+    ⚠️ `on` IS READ FROM THE OPTIONS, NOT INFERRED FROM `decision is None`.
+    Inferring it is the whole defect: the option is the only thing that
+    answers "is trading armed", and it is available on every render.
+
+    ⚠️ THE AGE IS ALWAYS PRINTED, INCLUDING WHEN IT IS ZERO. A row that
+    reports staleness only once it is stale cannot be told, on any single
+    render, from one that never reports it - and the bound TARIFF-10's
+    comment claimed did not exist is ~15 s of it.
+    """
+    if not on:
+        return "off - `arbitrage_enabled` is false, so nothing trades"
+    if decided_at is None:
+        return (f"ON (`arbitrage_enabled`), but NO DECISION has been reached "
+                f"yet - no cycle has run as far as the arbitrage step. The "
+                f"loop's own reason: {why or 'none recorded'}")
+    age = (now - decided_at).total_seconds()
+    stale = cycle_at is not None and decided_at < cycle_at
+    head = (f"no decision this cycle ({why or 'no reason recorded'}); the "
+            f"last one was taken {age:.0f} s ago: " if stale else
+            f"decided {age:.0f} s ago: ")
+    if decision is None:
+        return (f"ON (`arbitrage_enabled`), no decision this cycle "
+                f"({why or 'no reason recorded'}), and none stands from an "
+                f"earlier one")
+    return head + decision.explain()
+
+
 class Controller:
     def __init__(self, opts: dict, hass: HomeAssistant, store, mqtt_pub, *, stop,
                  peak_db_path: str = "/data/tariff.db",
@@ -796,6 +896,19 @@ class Controller:
         self.tariff_plan = None
         self.tariff_at = None
         self.arb = None
+        # TARIFF-11. WHEN the standing arbitrage decision was taken, or None if
+        # this controller has never reached the arbitrage step. ⚠️ `self.arb is
+        # None` DOES NOT MEAN "TRADING IS OFF" AND NEVER DID - see
+        # `arbitrage_row()`. It also means "cycle() returned before the step
+        # ran", and at that point `self.arb` is either this attribute's initial
+        # None (startup) or the PREVIOUS cycle's decision (an input hold), and
+        # the status row rendered all three identically.
+        self.arb_at = None
+        # TARIFF-11. When the most recent cycle() STARTED. `arb_at < cycle_at`
+        # is the exact, derived statement of "the latest cycle did not get as
+        # far as the arbitrage step", which is the fact the *Arbitrage* row
+        # used to render identically to "trading is switched off".
+        self.cycle_at = None
         self._arb_action = None
         self.inputs_bad_since = None
         # SAFETY-03. What the loop's OWN bounds did last cycle - a
@@ -1565,6 +1678,24 @@ class Controller:
             self.cheap, self.tariff_words = static_status(
                 o, datetime.now(timezone.utc))
 
+        # ⚠️ TARIFF-11. THE PROVIDER PLAN REACHES THE *Tariff* ROW HERE, AND
+        # THIS IS THE ONLY PLACE THE TWO SOURCES MEET. Everything above is the
+        # 30 s I/O-free tick; `fresh_tariff_plan()` is an attribute read and an
+        # age comparison against TARIFF_MAX_AGE_S - still no fetch on this path,
+        # which is the rule the whole branch above exists to keep. What the row
+        # gains is the plan's SHAPE (origin, product, horizon, the firm/carried
+        # split, the spacing) and what it must never gain is the suggestion
+        # that the two halves were computed at the same instant, so the plan
+        # half carries its own age in seconds. See `tariff_plan_row()`.
+        _tick = datetime.now(timezone.utc)
+        _standing = self.fresh_tariff_plan(_tick)
+        self.tariff_words = tariff_plan_row(
+            _standing, self.tariff_words,
+            age_s=(None if _standing is None
+                   else (_tick - self.tariff_at).total_seconds()),
+            horizon_h=float(price_option(o, "price_horizon_h")),
+            provider=provider_configured(o), max_age_s=TARIFF_MAX_AGE_S)
+
         if self.inputs_ok:
             if self.inputs_bad_since is not None:
                 self.log_event("inputs recovered")
@@ -1918,6 +2049,11 @@ class Controller:
         method's only job is to state honestly what each strategy wants.
         """
         now = datetime.now(timezone.utc)
+        # ⚠️ BEFORE THE FIRST `return` OF THIS METHOD, ON PURPOSE (TARIFF-11).
+        # It stamps that a cycle RAN, which is a different fact from any of the
+        # decisions the cycle may or may not reach, and the status row needs
+        # the two separately.
+        self.cycle_at = now
 
         # ⚠️ EACH PACK ON ITS OWN READING, NOT "the SoC". §12's recalibration
         # drains and refills ONE pack and grades ONE coulomb counter, so each
@@ -2577,7 +2713,13 @@ class Controller:
         # `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
+        # ⚠️ TARIFF-11: BOTH ATTRIBUTES, AND `arb_at` IS WHAT MAKES THE ROW
+        # HONEST. Reaching this line is the only proof that this cycle got as
+        # far as the arbitrage step; the early return at the input hold above
+        # leaves BOTH standing at whatever the last completed cycle left, and
+        # `arb_at` is then the age the status row reports rather than a
+        # decision presented as current.
+        self.arb, self.arb_at = None, now
         if arbitrage.enabled(self.o):
             floor_pct, ceiling_pct = arbitrage.soc_bounds(self.o)
             charge_w, discharge_w = self.trade_power_w(floor_pct, ceiling_pct)
@@ -4481,15 +4623,23 @@ class Controller:
             # every refusal it can make already carries a reason a human can
             # act on, and "Arbitrage: no" would throw all of them away.
             #
-            # ⚠️ TARIFF-10 RE-READ THIS STRING AND LEFT IT ALONE, which is worth
-            # saying because that card is about the two switches being
-            # different. `self.arb` is None if and only if
-            # `arbitrage.enabled(self.o)` was False, so `off (arbitrage_enabled)`
-            # still names the option that is actually off - and on a site with a
-            # provider configured it is now the row that says the prices
-            # arriving on the *Price history* row above are moving nothing.
-            ("Arbitrage", "off (arbitrage_enabled)" if self.arb is None
-             else self.arb.explain()),
+            # ⚠️ TARIFF-10 RE-READ THIS STRING AND LEFT IT ALONE UNDER A
+            # COMMENT THAT WAS FALSE, AND TARIFF-11 IS THAT CORRECTION. The
+            # claim was that `self.arb is None` **if and only if**
+            # `arbitrage.enabled(self.o)` was False. Only the forward direction
+            # holds: `cycle()` returns at the input hold (`bad_for <
+            # stale_input_s`, default 15 s) BEFORE it reaches `self.arb = None`
+            # at all, so on an armed site `self.arb` is `__init__`'s None at
+            # startup and the PREVIOUS cycle's decision during a later hold -
+            # and the row rendered `off (arbitrage_enabled)` on a site whose
+            # `arbitrage_enabled` is `true`. `arbitrage_row()` reads the option
+            # instead of inferring it, and separates "trading is off" from "no
+            # decision was reached this cycle"; `cycle_at` and `arb_at` are what
+            # make the second one an observation rather than a guess.
+            ("Arbitrage", arbitrage_row(
+                on=arbitrage.enabled(self.o), decision=self.arb,
+                decided_at=self.arb_at, cycle_at=self.cycle_at,
+                now=datetime.now(timezone.utc), why=self.reason)),
         ]
         return {
             "banner": banner, "level": level, "rows": rows, "checks": checks,

goodwe_controller/app/price.py

@@ -63,14 +63,22 @@ THE THREE THINGS THIS MODULE IS SHAPED BY
    knowing which of those two things you are reading.
 
 2. THE PRODUCT TYPE IS DECLARED, NOT INFERRED FROM THE PLUGIN'S NAME.
-   `eneco_eddy` is a real-time / imbalance product (§9.2) and §8.3 says those
-   are treated as high-volatility with widened arbitrage thresholds. If the
-   optimiser has to write `if provider_id == "eneco_eddy"` to know that, then
-   adding a sixth supplier means editing the optimiser - which is precisely
-   what AC2 forbids. So `capabilities().product` is a `PriceProduct`, it rides
-   along on the series, and `volatility_regime()` reads the enum. A plugin id
-   appears nowhere in this file except in `PROVIDERS` and in the class that
-   answers to it.
+   §9.2 classes real-time / imbalance products separately from day-ahead ones
+   and §8.3 says those are treated as high-volatility with widened arbitrage
+   thresholds. If the optimiser had to write `if provider_id == "<supplier>"`
+   to know that, then adding a supplier would mean editing the optimiser -
+   which is precisely what AC2 forbids. So `capabilities().product` is a
+   `PriceProduct`, it rides along on the series, and `volatility_regime()`
+   reads the enum. A plugin id appears nowhere in this file except in
+   `PROVIDERS`, in `RETIRED_PROVIDERS`, and in the class that answers to it.
+
+   ⚠️ NO SHIPPED PLUGIN DECLARES `PriceProduct.REALTIME` (TARIFF-07). All
+   three shipped plugins are day-ahead, so `_WIDE`,
+   `Uncertainty.REALTIME_PRODUCT` and `WIDEN_FACTOR`'s 2.5 currently have no
+   shipped declarer. They are KEPT
+   deliberately - see DECISIONS/TARIFF-07-withdrawing-three-plugins.md - and
+   test_price.py section 10 keeps them live by declaring REALTIME from a class
+   defined outside this file, which is AC2's own stimulus.
 
 3. "NO PRICE DATA" IS A TYPE, NOT AN EMPTY LIST.
    §11.4: no price data -> fall back to the static profile, mark the plan
@@ -142,6 +150,10 @@ from enum import Enum
 from textwrap import dedent
 from urllib.parse import urlencode
 
+from .custom_formula import (
+    FormulaInvalid, PREVIEW_HOURS, parse_price_formula, preview_lines,
+    price_eur_kwh, to_resolution)
+
 _LOG = logging.getLogger("goodwe.price")
 
 
@@ -480,7 +492,6 @@ class ProviderCapabilities:
     product: PriceProduct
     sources: frozenset          # which Components the published figure contains
     horizon_h: int = 48         # aligns with the §8.1/§8.2 forecast horizon
-    needs_credentials: bool = False
     egress_hosts: tuple = ()    # §16 allow-list, declared not discovered
 
     def __post_init__(self):
@@ -541,6 +552,121 @@ class PriceRead(_Outcome):
         return _NoData(reason)
 
 
+# --------------------------------------------------------------------------- #
+# How long ONE point covers - TARIFF-14
+# --------------------------------------------------------------------------- #
+
+# ⚠️ A POINT DOES NOT CARRY ITS OWN DURATION AND MUST NOT LEARN TO. §9.3 lists
+# THREE fields and `PricePoint` has three; a fourth would change the wire
+# format every store, replay, fixture and captured body in this repository is
+# written against. The span is DERIVED from the neighbours instead - here,
+# once, at construction.
+MAX_POINT_SPAN = timedelta(hours=1)
+
+
+def _cover_table(points) -> tuple:
+    """`(start_utc, end_utc, point)` per point, ascending. The `at()` index.
+
+    THE DEFECT THIS PREVENTS (TARIFF-14, HIGH). `at()` asked
+    `s <= u < s + 1 h` of every point IN LIST ORDER and returned the FIRST
+    match. On an hourly series - the only resolution any fixture carried
+    before TARIFF-08 - that is right by accident. Belgium moved to a
+    15-minute MTU on 2025-10-01 and the live day-ahead feed returns 96 points
+    at 900 s, where it is wrong twice over. Measured on shipped `5059e28`:
+
+        series: 02:00=0.10  02:15=0.11  02:30=0.12  02:45=0.13  03:00=0.14
+
+        at(02:15) -> 02:00   the :00 point's HOUR has not run out yet
+        at(03:15) -> 02:30   and from the second hour on it is not even the
+                             top of the hour: the first point still inside
+                             its own hour wins, so the error COMPOUNDS with
+                             depth into the series
+
+    `arbitrage._act()` compares `here.start` against `v.cheapest.start` and
+    `v.dearest.start` to decide whether this interval is the buy or the sell
+    one. That identity test almost never matched the extremum, so the
+    strategy idled through exactly the interval it exists to trade - and read
+    `here.provisional` and §17's `price < 0` guard off the wrong point while
+    doing it. `static_tariff.py` emits hourly points, so static sites never
+    saw it; this is reachable only down the dynamic path TARIFF-08/09 made
+    work.
+
+    THE RULE, in one sentence:
+
+        A POINT COVERS FROM ITS OWN START UNTIL THE NEXT POINT'S START, AND
+        NEVER MORE THAN ONE HOUR.
+
+      * 900 s  -> each point covers its own quarter, so `at(02:15)` is the
+        02:15 point;
+      * 3600 s -> each point covers its own hour, unchanged from shipped;
+      * MIXED  -> EACH POINT TAKES ITS OWN GAP. FCST-04's carry-forward emits
+        HOURLY carried points beside QUARTER-HOURLY firm ones, and the soak
+        measured spacing `[900, 3600]` in 70 % of samples - so mixed is the
+        normal steady state, and a window derived from one global spacing
+        would be wrong THERE rather than in an edge case.
+
+    ⚠️ WHY THE ONE-HOUR CAP, WHICH IS NOT DECORATION. FCST-04 LEAVES HOLES ON
+    PURPOSE: an hour with no published price AND no yesterday value is left
+    OUT of the series, and `price_forecast.py`'s module note names `at()`
+    raising `Absence` for it as the behaviour that sends the caller to the
+    static profile (§11.4 for that hour). Uncapped, "until the next point's
+    start" would stretch the point BEFORE a three-hour hole across the whole
+    hole and answer every instant in it with a stale price. Filling holes is
+    the defect this module exists to refuse, and it would have been
+    introduced by the fix for a different one.
+
+    ⚠️ THE LAST POINT'S WINDOW IS DECIDED, NOT INHERITED. There is no next
+    start and nothing in §9.3 says how wide the final interval is, so THE
+    LAST POINT IS GIVEN THE SAME SPAN AS THE POINT BEFORE IT - one hour when
+    it is the only point. Three consequences, all intended:
+
+      * on a 96-point 900 s day the 23:45 point covers 23:45 .. 00:00, so
+        `at(23:50)` ANSWERS and `at(00:00)` raises `Absence`. A flat one-hour
+        tail would have answered 00:30 TOMORROW with today's last price,
+        which is reaching for a neighbour across a day boundary;
+      * on an hourly series the tail is an hour, exactly as it shipped, so no
+        static or hourly site changes behaviour;
+      * on a MIXED series whose last point is a carried HOURLY one behind
+        quarter-hourly firm ones, the tail is 900 s and the last 45 minutes
+        of the horizon raise `Absence`. That is the SAFE direction and it is
+        accepted rather than tolerated: the caller falls back to the static
+        profile (§11.4) instead of trading on a span the series never
+        demonstrated, and a carried point is provisional, so §8.3 forbids any
+        irreversible action resting on it regardless.
+
+    ⚠️ ORDER IS ESTABLISHED HERE, NOT ASSUMED - and that is the difference
+    between this and the rule it replaces. `at()` now reads neighbours, so it
+    WOULD depend on sortedness; the table is therefore sorted by UTC start at
+    construction, and no caller's list order can reach it. `_validate_raw()`
+    rejects out-of-order and duplicate starts on the `load_prices()` path,
+    `price_history._parse_points()` re-sorts what it reads off disk, and
+    FCST-04's fill emits ascending - but `PriceRead.series()` itself has
+    never enforced any of that, and an assumption that holds today and is
+    unstated is how this class of defect recurs.
+
+    ⚠️ NOTHING HERE RAISES ON A MALFORMED SERIES. A duplicated start - not
+    reachable through `load_prices()`, which refuses it - gives the earlier
+    list entry a ZERO-width window and the later one the real span, so one of
+    the pair becomes unreachable through `at()` and neither the 30 s control
+    path nor construction raises.
+    """
+    rows = sorted(((p.start.astimezone(timezone.utc), i, p)
+                   for i, p in enumerate(points)),
+                  key=lambda r: (r[0], r[1]))
+    out = []
+    for n, (start, _i, point) in enumerate(rows):
+        if n + 1 < len(rows):
+            span = rows[n + 1][0] - start          # -> the next point's start
+        elif n:
+            span = start - rows[n - 1][0]          # -> the tail, see above
+        else:
+            span = MAX_POINT_SPAN                  # -> a series of one point
+        if span > MAX_POINT_SPAN:
+            span = MAX_POINT_SPAN
+        out.append((start, start + span, point))
+    return tuple(out)
+
+
 class _Series(PriceRead):
     kind = "series"
 
@@ -564,6 +690,10 @@ class _Series(PriceRead):
         self.provider = provider
         self.fetched_at = fetched_at
         self.regime = volatility_regime(product)
+        # ⚠️ TARIFF-14. Built ONCE, here, so that `at()` scans an index whose
+        # order it established itself rather than one it hopes it was handed.
+        # See `_cover_table()` for the window rule and for what the tail does.
+        self._cover = _cover_table(self.points)
         self.words = (f"{len(self.points)} points from {provider} "
                       f"({product.value}, {self.regime} thresholds)")
 
@@ -572,25 +702,47 @@ class _Series(PriceRead):
         return {"prices": [p.canonical() for p in self.points]}
 
     def at(self, instant: datetime) -> PricePoint:
-        """The point covering `instant`. Raises `Absence` if the series does not.
+        """The point whose OWN interval covers `instant`, at ANY resolution.
 
         ⚠️ RETURNS A POINT OR RAISES; it never returns None. `series.at(t) or
         fallback` is the same defaulting bug one level down, so the falsy
         answer does not exist. Ask `covers()` first if you mean to branch.
+
+        ⚠️ TARIFF-14: THE WINDOW IS NOT ONE HOUR WIDE ANY MORE, AND WAS NEVER
+        ENTITLED TO BE. It runs to the next point's start, capped at an hour -
+        `_cover_table()` above holds the rule, the tail decision and the
+        reproduction on a quarter-hourly series. A fixed `s + 1 h` here
+        returned the FIRST point still inside its own hour, which on the live
+        900 s feed is neither the covering point nor, past the first hour,
+        even the top of the hour.
+
+        A linear scan over the index, which is 192 entries on the shipped 48 h
+        horizon. This runs on the 30 s control path through
+        `arbitrage._point_at()`; a bisect would be correct and is not worth
+        the second way to be wrong at this size.
         """
         u = instant.astimezone(timezone.utc)
-        for p in self.points:
-            s = p.start.astimezone(timezone.utc)
-            if s <= u < s + timedelta(hours=1):
-                return p
+        for start, end, point in self._cover:
+            if start <= u < end:
+                return point
         raise Absence(
             f"no price point covers {u.isoformat()}; the series runs "
             f"{self.points[0].start.isoformat()} .. "
-            f"{self.points[-1].start.isoformat()}. An hour outside the series "
-            f"is an hour with no price, which is §11.4 for that hour - not a "
-            f"reason to reach for a neighbouring one.")
+            f"{self.points[-1].start.isoformat()}. An instant outside the "
+            f"series - or inside a hole FCST-04 left because nothing "
+            f"published that hour - is an instant with no price, which is "
+            f"§11.4 for it, not a reason to reach for a neighbouring one.")
 
     def covers(self, instant: datetime) -> bool:
+        """Whether `at(instant)` would answer.
+
+        ⚠️ SHARED TARIFF-14 EXACTLY, AND IS FIXED BY THE SAME CHANGE. It has
+        no window rule of its own - it asks `at()` - so on the 900 s feed it
+        answered True for instants no point covered and False for none of
+        them, because the hour-wide window is never SHORTER than the truth.
+        It is kept as a delegation for that reason: a second copy of the rule
+        is a second place for it to be wrong.
+        """
         try:
             self.at(instant)
             return True
@@ -598,7 +750,17 @@ class _Series(PriceRead):
             return False
 
     def window(self, since: datetime, until: datetime) -> tuple:
-        """Points whose start falls in [since, until). May legitimately be empty."""
+        """Points whose START falls in [since, until). May legitimately be empty.
+
+        ⚠️ DID NOT SHARE TARIFF-14, AND THE REASON IS WORTH STATING RATHER
+        THAN REDISCOVERING. This grades a point's `start` against a half-open
+        range and never asks how long a point lasts, so it carries no
+        resolution assumption to be wrong about - the same call answers the
+        same set at 900 s, at 3600 s and mixed. It is therefore NOT a
+        coverage query: a point that starts before `since` and runs into it
+        is absent from this tuple by design. `at()`/`covers()` are the
+        coverage questions.
+        """
         a = since.astimezone(timezone.utc)
         b = until.astimezone(timezone.utc)
         return tuple(p for p in self.points
@@ -689,6 +851,13 @@ 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": "",
+    # TARIFF-15. A JSON object carrying ONE contract's two coefficients, the
+    # units they are printed in, its VAT rate and the card figures the add-on
+    # grades them against; "" is unset. Parsed and validated by
+    # app/custom_formula.py, refused at startup by validate.py - the
+    # `static_profile` precedent exactly, and here for the same CFG-03 reason:
+    # this dict is the ONE in-code mirror of config.yaml.
+    "price_formula": "",
     # 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
@@ -811,11 +980,37 @@ def export_price_eur_kwh(opts: dict) -> float:
     """AC4 / §9.3: the injection price is a SEPARATE SCALAR, not a second series.
 
     In Belgium it is often near zero, which by itself favours self-consumption
-    over export. It is deliberately not routed through the plugin framework: no
-    shipped supplier publishes a dynamic injection curve, and inventing the
-    shape for one would be a second canonical format nobody emits. When one
-    appears it gets a `PriceProvider` of its own and this scalar becomes its
-    FIXED-product default - the seam is already the right shape for that.
+    over export. It is deliberately not routed through the plugin framework -
+    but ⚠️ NOT because nothing dynamic exists to route. That claim stood here
+    until TARIFF-07 and it was FALSE:
+
+      * Eneco publishes an injection formula on the same tariff card as its
+        consumption formula - `0,1 x BELPEX-H - 1,188` - identical on the
+        January and the September 2026 cards;
+      * ENGIE publishes one in the same two-coefficient shape,
+        `(B x eSpot_15) - A`.
+
+    So a supplier DOES publish a dynamic injection curve. What is true is
+    narrower and is the actual reason this is a scalar: an injection curve is
+    the SAME `B x spot - A` shape as the consumption curve but carries ITS OWN
+    coefficients and its own VAT treatment - injection is VAT-exempt where
+    consumption is at 6% - so it is a second per-contract formula, not a second
+    copy of the first.
+
+    ⚠️ TARIFF-15 LANDED THE EVALUATOR AND DID NOT LAND THIS CURVE, and the
+    difference is the point rather than an omission. `custom_formula` can now
+    express `B x index + A` exactly - it is what it exists for - but it is a
+    CONSUMPTION provider: it declares {ENERGY, MARKUP}, the framework adds the
+    consumption taxes, and an injection leg carries its OWN coefficients
+    (Eneco: 0,102 consumption against 0,100 injection) and its own VAT
+    treatment (injection is exempt; consumption is at 6%). Pointing this
+    scalar at that machinery would mean pricing an injection curve with a
+    consumption card, which is the wrong-card defect the card self-check
+    exists to refuse. So until the injection card lands this scalar remains a
+    SIMPLIFICATION an operator enters by hand - an average of what they are
+    actually paid - and not a reflection of the market. When it does land, an
+    injection curve gets a `PriceProvider` of its own and this scalar becomes
+    its FIXED-product default; the seam is already the right shape for that.
 
     ⚠️ It is NOT reachable from a plugin: `export_price_eur_kwh` is in
     FRAMEWORK_KEYS, so a consumption plugin cannot quietly fold an injection
@@ -862,18 +1057,38 @@ class PriceProvider(ABC):
         past today from the trade set as provisional - so the optimiser never
         saw tomorrow as firm, at any hour of any day, and nothing reported it.
 
-        This promise is NOT mechanically enforced, and the honest reason is
-        TARIFF-08's: three of the five shipped plugins point at endpoints
-        nobody has verified (TARIFF-07 is the open decision on withdrawing
-        them), so nobody knows how those feeds spell a date range. A rule
-        obliging them to pass one would be satisfied by an INVENTED parameter
+        This promise is NOT mechanically enforced. A rule obliging every
+        plugin to pass a range would be satisfied by an INVENTED parameter
         name - the parser-graded-against-its-own-guess defect, moved from the
-        response to the request. What exists instead is a roster pin in
-        test_price.py: which plugins consume the range and which do not is
-        asserted as a literal, so a sixth supplier, or a change to one of the
-        three, forces the decision rather than inheriting the silence.
+        response to the request, and the defect TARIFF-08 found on the
+        response side. What exists instead is a roster pin in test_price.py:
+        which plugins consume the range and which do not is asserted as a
+        literal, so a third supplier forces the decision rather than
+        inheriting the silence.
         """
 
+    def startup_preview(self, points) -> list:
+        """Lines to log ONCE, the first time this provider answers (TARIFF-15).
+
+        `points` are the ASSEMBLED, all-in `PricePoint`s - what the site is
+        really priced on - and the default is to say nothing, so no existing
+        plugin changes behaviour.
+
+        ⚠️ IT IS A HOOK RATHER THAN A LINE IN `load_prices()` BECAUSE THE
+        FRAMEWORK CANNOT KNOW WHAT IS WORTH PREVIEWING. Only the plugin knows
+        what went IN to its own arithmetic - for `custom_formula` the index in
+        EUR/MWh - and printing that beside the all-in figure is the whole
+        point: a factor of 1000 is obvious in one line of
+        `61.96 -> 0.13522` and invisible in a plan. The framework supplies the
+        one number a plugin may never read, by handing back the assembled
+        result rather than the tax rate.
+
+        ⚠️ IT MUST NOT RAISE INTO THE CONTROL PATH and it is not trusted not
+        to: `_emit_startup_preview()` catches everything. A log line is not a
+        reason to stop regulating a battery.
+        """
+        return []
+
 
 # ⚠️ THE NAMES A PLUGIN'S OWN CODE MAY NOT MENTION. FRAMEWORK_KEYS is the
 # obvious half; the other three are the routes review of PR #16 actually used to
@@ -899,9 +1114,10 @@ def code_leaks(cls) -> list:
 
     ⚠️ DOCSTRINGS ARE STRIPPED BEFORE THE SEARCH, AND THAT IS NOT COSMETIC.
     Every shipped plugin's docstring is REQUIRED to name the components it
-    sources, so `engie_dynamic` says "markup" in prose and would false-positive
-    against `price_markup_eur_kwh` on a raw text scan. The check that fires on
-    the documentation it also mandates is the check that gets deleted. So the
+    sources, so `generic_dayahead` says "markup" in prose and would
+    false-positive against `price_markup_eur_kwh` on a raw text scan. The
+    check that fires on the documentation it also mandates is the check that
+    gets deleted. So the
     class is parsed, every docstring node is dropped, and the search runs on
     `ast.unparse` of what is left - i.e. on code, which is the only thing that
     can actually add a number twice.
@@ -911,8 +1127,8 @@ def code_leaks(cls) -> list:
     or zipapp build would not. Refusing to start a battery controller because a
     STATIC ANALYSIS could not run would trade a real outage for a hypothetical
     accounting error, so an unreadable source returns `[]` and logs. CI proves
-    the scan really runs: test_price.py asserts source was found for all five
-    shipped plugins, so a build that silently lost it is a red check, not a
+    the scan really runs: test_price.py asserts source was found for every
+    shipped plugin, so a build that silently lost it is a red check, not a
     quietly disarmed guard.
     """
     try:
@@ -931,6 +1147,58 @@ def code_leaks(cls) -> list:
     return sorted({name for name in BANNED_IN_PLUGIN_CODE if name in code})
 
 
+# --------------------------------------------------------------------------- #
+# TARIFF-07: the ids that USED to resolve here, and what an operator on one of
+# them has actually been running.
+#
+# ⚠️ THE DEFECT THIS EXISTS TO PREVENT: A RETIRED ID READ AS A TYPO. Without
+# this table `price_provider: "eneco_eddy"` reaches validate.py's unknown-id
+# branch and is refused as "not a shipped plugin" - true, and useless. The
+# operator did not mistype it; it WAS a shipped plugin, they chose it on
+# purpose, and the add-on has accepted it every startup since. What they need
+# told is not "that id is wrong" but "that id never fetched a price, and here
+# is what you have been running instead" - because §11.4 turned every failed
+# fetch into a silent fall back to `static_profile`, so NOTHING they can see
+# has ever differed from a working provider that finds no cheap hour.
+#
+# ⚠️ AND WHY THERE IS NO SILENT ALIAS. Mapping these to `generic_dayahead`
+# would be the friendlier-looking option and it is the wrong one: these three
+# published RETAIL prices (`B x spot + A`, per contract) and `generic_dayahead`
+# reads WHOLESALE. Aliasing needs the site's own two coefficients, which nobody
+# has - they live behind the customer's klantenzone login, and there is no
+# regulator index to read them from (CREG's tariff-card pages 404; VREG was
+# unreachable; every coefficient found in research came from a supplier's own
+# PDF). An alias would therefore have to INVENT the numbers it prices a battery
+# against, which is the same class of defect as the parser graded against its
+# own guess - just one layer further from anything that reports.
+#
+# Each value is the ID-SPECIFIC half of the refusal: the endpoint, what it was
+# observed to answer on 2026-09-13, and why no replacement plugin can be built.
+# validate.py owns the common framing. Verified by hand before deletion, not
+# taken on report - see DECISIONS/TARIFF-07-withdrawing-three-plugins.md.
+# --------------------------------------------------------------------------- #
+RETIRED_PROVIDERS: dict = {
+    "engie_dynamic": (
+        "its endpoint https://api.engie.be/dynamic/be does not exist - the "
+        "gateway there answers 404 with Kong's \"no Route matched with those "
+        "values\". No public endpoint could replace it: ENGIE's dynamic price "
+        "is (B x eSpot_15) - A with PER-CONTRACT coefficients that live behind "
+        "your klantenzone login, so no unauthenticated URL can return YOUR "
+        "price"),
+    "totalenergies_dynamic": (
+        "its endpoint https://api.totalenergies.be/prices/dynamic does not "
+        "exist - the TLS handshake fails outright because that hostname is "
+        "absent from the certificate the server presents. The coefficients are "
+        "per-contract there too"),
+    "eneco_eddy": (
+        "its endpoint https://api.eneco.be/eddy/prices does not exist - it "
+        "answers 404 with an empty body - and \"Eddy\" is not an Eneco "
+        "product at all; their dynamic product is \"Zon & Wind Dynamisch\", "
+        "which is indexed to Belpex/EPEX DAY-AHEAD and whose coefficients are "
+        "likewise per-contract"),
+}
+
+
 PROVIDERS: dict = {}
 
 
@@ -944,6 +1212,22 @@ def register(cls):
     """
     if cls.id in PROVIDERS:
         raise ValueError(f"duplicate provider id {cls.id!r}")
+    if cls.id in RETIRED_PROVIDERS:
+        # ⚠️ AT IMPORT, NOT AT FETCH, and for the same reason the leak check is.
+        # A retired id that is registered again is the one state in which
+        # validate.py's retired-id refusal goes quiet WITHOUT anyone deciding
+        # it should: `pid in PROVIDERS` becomes true, the named message is
+        # never reached, and the operator is back to a provider that looks
+        # like it works. Re-shipping an id is legitimate - the endpoint could
+        # become real - but it is a DECISION, and taking the id out of
+        # RETIRED_PROVIDERS in the same commit is what records it.
+        raise ValueError(
+            f"{cls.id!r} is in RETIRED_PROVIDERS and cannot also be a shipped "
+            f"plugin. A site configured on it is refused at startup with a "
+            f"message naming the id; registering it silently takes that "
+            f"message away. If this id really ships again, remove it from "
+            f"RETIRED_PROVIDERS in the same commit - and say in the CHANGELOG "
+            f"what changed about the endpoint.")
     cls.capabilities()          # fail at import, not at 15:00 on fetch day
     leaks = code_leaks(cls)
     if leaks:
@@ -1082,7 +1366,7 @@ def check_egress(url: str, caps: ProviderCapabilities) -> str:
 
 
 # --------------------------------------------------------------------------- #
-# The five shipped plugins.
+# The shipped plugins.
 #
 # ⚠️ EACH DOCSTRING STATES WHICH COMPONENTS IT SOURCES AND WHICH THE FRAMEWORK
 # ADDS, in the two fixed lines `SOURCES: ...` / `The framework ADDS: ...`. That
@@ -1092,49 +1376,22 @@ def check_egress(url: str, caps: ProviderCapabilities) -> str:
 # what its feed contains is a red check rather than a 3 c/kWh error nobody sees.
 # --------------------------------------------------------------------------- #
 
-def _points_from_json(body, price_key, scale, provisional_default):
-    """Shared parse for the three JSON feeds. Shape differences are the args."""
-    try:
-        text = body.decode("utf-8") if isinstance(body, (bytes, bytearray)) \
-            else str(body)
-        doc = json.loads(text)
-    except (ValueError, UnicodeDecodeError) as e:
-        raise SourceUnavailable(f"the feed did not parse as JSON: {e}")
-    rows = doc.get("data") if isinstance(doc, dict) else doc
-    if not isinstance(rows, list):
-        raise SourceUnavailable("the feed carried no 'data' list")
-    out = []
-    for row in rows:
-        try:
-            start = datetime.fromisoformat(str(row["start"]))
-            value = float(row[price_key]) * scale
-        except (KeyError, TypeError, ValueError) as e:
-            raise SourceUnavailable(f"malformed row {row!r}: {e}")
-        if start.tzinfo is None:
-            raise SourceUnavailable(
-                f"row {row['start']!r} carries no UTC offset; this feed is "
-                f"required to publish absolute instants")
-        out.append(RawPoint(start=start, eur_per_kwh=value,
-                            provisional=bool(row.get("provisional",
-                                                     provisional_default))))
-    return out
-
-
-
-# --------------------------------------------------------------------------- #
 # TARIFF-08: the COLUMNAR document, which is what the public EPEX feed really
 # publishes.
 #
-# ⚠️ THIS IS A SECOND SHAPE, READ BY A SECOND FUNCTION ON PURPOSE.
-# `_points_from_json()` above reads a row-per-point document: `{"data": [{...},
-# {...}]}`. `https://api.energy-charts.info/price?bzn=BE` does not publish that
-# and never did - it publishes PARALLEL ARRAYS:
+# ⚠️ THIS IS THE ONLY PARSER LEFT, AND THE SHAPE IT DOES **NOT** READ IS WHY.
+# Until TARIFF-07 a second function, `_points_from_json()`, read a row-per-point
+# document: `{"data": [{...}, {...}]}`. NO FEED ANYBODY REACHED EVER PUBLISHED
+# THAT SHAPE - it was invented alongside the three withdrawn plugins, and the
+# only bodies ever fed to it were the fixtures written from the same guess. It
+# went with them. `https://api.energy-charts.info/price?bzn=BE` publishes
+# PARALLEL ARRAYS:
 #
 #     {"unix_seconds": [1788991200, 1788992100, ...],   <- UTC epoch seconds
 #      "price":        [216.08,     209.90,     ...],   <- one per instant
 #      "unit": "EUR / MWh", "license_info": "...", "deprecated": false}
 #
-# The shipped parser was pointed at that URL and asked for `doc["data"]`, so
+# The row parser was pointed at that URL and asked for `doc["data"]`, so
 # every fetch ended `SourceUnavailable: the feed carried no 'data' list` ->
 # §11.4 -> static profile, arbitrage off, and nothing in the status page said
 # why. Verified live 2026-09-10 against both fixtures under `scenarios/`.
@@ -1277,6 +1534,60 @@ def _points_from_columnar_json(body, expect_unit, scale,
     return out
 
 
+def dayahead_feed_url(plugin_id, opts, since, until, base, bzn) -> str:
+    """The day-ahead URL for a window, or the operator's override, verbatim.
+
+    ⚠️ SHARED BY `generic_dayahead` AND `custom_formula`, ON PURPOSE
+    (TARIFF-15). They read the SAME feed for the same range; two copies of this
+    rule would be two places for the Brussels-calendar derivation and the
+    override decision to disagree, and the one that is wrong would be wrong
+    silently - §11.4 turns a short horizon into provisional hours, not into an
+    error. It takes `plugin_id` rather than reading one, so the framework's
+    AC2 rule (no plugin id in shared code) still holds here.
+
+    ⚠️ AN OVERRIDE IS THE EXACT URL AND NOTHING IS APPENDED TO IT, WHICH COSTS
+    THE OVERRIDING SITE THE RANGE. That is a decision, not an oversight, and
+    the sentence below is why it is not a footnote:
+
+      * `price_feed_url` says "override the plugin's default feed", and an
+        override that is silently rewritten is not one. Merging parameters
+        into an operator's query string means parsing and re-serialising a
+        URL they wrote - which reorders, de-duplicates and re-escapes it,
+        and can hand the server a request nobody typed.
+      * `start`/`end` are ENERGY-CHARTS' spelling, and both providers DECLARE
+        A SECOND HOST: `web-api.tp.entsoe.eu`. Nothing here has verified that
+        host's day-ahead parameters and nothing here should guess them - but
+        they are not `start`/`end`, so an override to the other DECLARED host
+        is exactly the case where appending our vocabulary adds two parameters
+        that host ignores and yields the short horizon anyway, with nothing
+        saying so.
+      * and blind appending is refused outright: `dated_feed_url()` will not
+        add a query string to a base that has one.
+
+    So the cost is real and it is REPORTED, at fetch time, on the shipped
+    logger, naming the horizon consequence rather than the substitution.
+    §11.4 is what makes a price defect quiet; an operator who has taken the
+    short horizon has to be able to find out from the log that they did.
+    """
+    override = str(opts.get("price_feed_url") or "").strip()
+    if override:
+        _LOG.warning(
+            "price_feed_url is set, so %s is requesting %s exactly as "
+            "given and is adding NO date range to it. The public feed "
+            "answers a single Brussels day to a request that names no "
+            "range, and every hour past that day is then carried forward "
+            "from yesterday's profile and flagged provisional - §8.3 "
+            "drops provisional hours from the trade set, so arbitrage "
+            "would never see tomorrow as firm. Clear price_feed_url to "
+            "let this plugin ask for the %s..%s it was given.",
+            plugin_id, override, *(d.isoformat()
+                                   for d in brussels_date_range(since, until)))
+        return override
+    first, last = brussels_date_range(since, until)
+    return dated_feed_url(base, bzn=bzn, start=first.isoformat(),
+                          end=last.isoformat())
+
+
 @register
 class GenericDayAhead(PriceProvider):
     """Public EPEX BE day-ahead feed, COLUMNAR, in EUR/MWh.
@@ -1290,7 +1601,8 @@ class GenericDayAhead(PriceProvider):
     either number, it cannot be the one that adds them twice.
 
     ⚠️ IT READS THE COLUMNAR SHAPE, AND SAYS SO IN ITS OWN `fetch()`. Until
-    TARIFF-08 it called `_points_from_json()` and asked
+    TARIFF-08 it called the row-per-point parser (withdrawn by TARIFF-07) and
+    asked
     `api.energy-charts.info` for a `"data"` list it has never published, so
     every fetch this provider ever made ended in `SourceUnavailable` and §11.4
     turned that into a silent fall back to the static profile. See
@@ -1318,57 +1630,22 @@ class GenericDayAhead(PriceProvider):
     async def fetch(self, opts, since, until, transport):
         """Request the range the CALLER asked for, on the Brussels calendar.
 
-        ⚠️ THE ARGUMENTS ARE USED. Until TARIFF-09 this method took `since` and
-        `until` and asked for the bare `?bzn=BE`, which answers ONE Brussels
-        day - so a 48 h horizon was 15 firm hours and 33 carried at 09:00, and
-        1 firm and 47 carried at 23:00, with the whole trade set inside a
-        single calendar day at every hour of every day. See
-        `brussels_date_range()` for the measurement and for why the calendar
-        is Brussels rather than UTC.
+        ⚠️ THE ARGUMENTS ARE USED, and `dayahead_feed_url()` above is where
+        they are turned into a URL. Until TARIFF-09 this method took `since`
+        and `until` and asked for the bare `?bzn=BE`, which answers ONE
+        Brussels day - so a 48 h horizon was 15 firm hours and 33 carried at
+        09:00, and 1 firm and 47 carried at 23:00, with the whole trade set
+        inside a single calendar day at every hour of every day.
 
-        ⚠️ AN OVERRIDE IS THE EXACT URL AND THIS METHOD APPENDS NOTHING TO IT,
-        WHICH COSTS THE OVERRIDING SITE THE RANGE. That is a decision, not an
-        oversight, and the sentence below is why it is not a footnote:
-
-          * `price_feed_url` says "override the plugin's default feed", and an
-            override that is silently rewritten is not one. Merging parameters
-            into an operator's query string means parsing and re-serialising a
-            URL they wrote - which reorders, de-duplicates and re-escapes it,
-            and can hand the server a request nobody typed.
-          * `start`/`end` are ENERGY-CHARTS' spelling, and this provider
-            DECLARES A SECOND HOST: `web-api.tp.entsoe.eu`. Nothing here has
-            verified that host's day-ahead parameters and nothing here should
-            guess them - but they are not `start`/`end`, so an override to the
-            other DECLARED host is exactly the case where appending our
-            vocabulary adds two parameters that host ignores and yields the
-            short horizon anyway, with nothing saying so.
-          * and blind appending is refused outright: `dated_feed_url()` will
-            not add a query string to a base that has one.
-
-        So the cost is real and it is REPORTED, at fetch time, on the shipped
-        logger, naming the horizon consequence rather than the substitution.
-        §11.4 is what makes a price defect quiet; an operator who has taken the
-        short horizon has to be able to find out from the log that they did.
+        ⚠️ THE URL DECISION MOVED OUT OF THIS METHOD IN TARIFF-15 AND DID NOT
+        CHANGE. `custom_formula` reads the same feed with the same range and
+        the same parser, and a second copy of the override rule would be a
+        second place for it to be wrong - which is the reason `covers()`
+        delegates to `at()` rather than restating its window. The reasoning,
+        the warning and the exact URL are all in `dayahead_feed_url()`.
         """
-        override = str(opts.get("price_feed_url") or "").strip()
-        if override:
-            url = override
-            _LOG.warning(
-                "price_feed_url is set, so %s is requesting %s exactly as "
-                "given and is adding NO date range to it. The public feed "
-                "answers a single Brussels day to a request that names no "
-                "range, and every hour past that day is then carried forward "
-                "from yesterday's profile and flagged provisional - §8.3 "
-                "drops provisional hours from the trade set, so arbitrage "
-                "would never see tomorrow as firm. Clear price_feed_url to "
-                "let this plugin ask for the %s..%s it was given.",
-                self.id, url, *(d.isoformat()
-                                for d in brussels_date_range(since, until)))
-        else:
-            first, last = brussels_date_range(since, until)
-            url = dated_feed_url(self.FEED_BASE, bzn=self.BZN,
-                                 start=first.isoformat(),
-                                 end=last.isoformat())
+        url = dayahead_feed_url(self.id, opts, since, until,
+                                self.FEED_BASE, self.BZN)
         check_egress(url, self.capabilities())
         body = await transport(url, float(opts.get("price_timeout_s")))
         return _points_from_columnar_json(body, expect_unit="EUR / MWh",
@@ -1376,101 +1653,6 @@ class GenericDayAhead(PriceProvider):
                                           provisional_default=False)
 
 
-@register
-class EngieDynamic(PriceProvider):
-    """Engie's dynamic day-ahead product, published in EUR/kWh.
-
-    SOURCES: energy, markup
-    The framework ADDS: taxes
-
-    ⚠️ Engie's published figure ALREADY CONTAINS THEIR MARKUP - it is a retail
-    price, not a wholesale one. Adding `price_markup_eur_kwh` on top of it is
-    the defect this ticket's design exists to make unreachable; the declaration
-    above is what stops it, and nothing here needs to remember the rule.
-    """
-
-    id = "engie_dynamic"
-
-    @classmethod
-    def capabilities(cls):
-        return ProviderCapabilities(
-            product=PriceProduct.DAY_AHEAD,
-            sources=frozenset({Component.ENERGY, Component.MARKUP}),
-            needs_credentials=True,
-            egress_hosts=("api.engie.be",))
-
-    async def fetch(self, opts, since, until, transport):
-        url = opts.get("price_feed_url") or "https://api.engie.be/dynamic/be"
-        check_egress(url, self.capabilities())
-        body = await transport(url, float(opts.get("price_timeout_s")))
-        return _points_from_json(body, "price_eur_kwh", 1.0, False)
-
-
-@register
-class TotalEnergiesDynamic(PriceProvider):
-    """TotalEnergies' dynamic day-ahead product, published in EUR/kWh.
-
-    SOURCES: energy, markup
-    The framework ADDS: taxes
-
-    Same retail shape as Engie: the supplier's own margin is inside the number.
-    """
-
-    id = "totalenergies_dynamic"
-
-    @classmethod
-    def capabilities(cls):
-        return ProviderCapabilities(
-            product=PriceProduct.DAY_AHEAD,
-            sources=frozenset({Component.ENERGY, Component.MARKUP}),
-            needs_credentials=True,
-            egress_hosts=("api.totalenergies.be",))
-
-    async def fetch(self, opts, since, until, transport):
-        url = opts.get("price_feed_url") or \
-            "https://api.totalenergies.be/prices/dynamic"
-        check_egress(url, self.capabilities())
-        body = await transport(url, float(opts.get("price_timeout_s")))
-        return _points_from_json(body, "price_eur_kwh", 1.0, False)
-
-
-@register
-class EnecoEddy(PriceProvider):
-    """Eneco Eddy / Eddy Flex - a REAL-TIME / IMBALANCE product, all-in EUR/MWh.
-
-    SOURCES: energy, markup, taxes
-    The framework ADDS: nothing
-
-    ⚠️ THE PRODUCT TYPE IS THE INTERESTING FIELD HERE, NOT THE PRICE. §9.2
-    classes Eddy Flex as real-time / imbalance and §8.3 says those get widened
-    arbitrage thresholds. That regime reaches the optimiser through
-    `capabilities().product` -> `_Series.product` -> `volatility_regime()`. If
-    it reached the optimiser through the string "eneco_eddy" instead, then the
-    sixth supplier would need an optimiser edit and AC2 would be dead. This
-    class is the reason the enum exists.
-
-    Imbalance prices are settled after the fact, so the current quarter's figure
-    is genuinely provisional and the feed says so per point.
-    """
-
-    id = "eneco_eddy"
-
-    @classmethod
-    def capabilities(cls):
-        return ProviderCapabilities(
-            product=PriceProduct.REALTIME,
-            sources=ALL_IN,
-            horizon_h=24,
-            needs_credentials=True,
-            egress_hosts=("api.eneco.be",))
-
-    async def fetch(self, opts, since, until, transport):
-        url = opts.get("price_feed_url") or "https://api.eneco.be/eddy/prices"
-        check_egress(url, self.capabilities())
-        body = await transport(url, float(opts.get("price_timeout_s")))
-        return _points_from_json(body, "price_eur_mwh", 0.001, True)
-
-
 @register
 class ManualCsv(PriceProvider):
     """A file on disk. AC3: the documented fallback, fully offline.
@@ -1540,10 +1722,160 @@ class ManualCsv(PriceProvider):
         return out
 
 
+@register
+class CustomFormula(PriceProvider):
+    """The operator's OWN tariff card, as two fixed coefficients. TARIFF-15.
+
+    SOURCES: energy, markup
+    The framework ADDS: taxes
+
+    ⚠️ IT DECLARES `{ENERGY, MARKUP}` AND NOT `ALL_IN`, AND THAT IS THE WHOLE
+    SAFETY ARGUMENT. A Belgian card's `Tariefformule` line is the ENERGY
+    component only - Eneco tabulates network tariffs and levies separately,
+    ENGIE states that the formula excludes network, distribution, transport,
+    grid levies and excise - so declaring ALL_IN would lie on behalf of every
+    operator who typed exactly what their card says, and would silently drop
+    ~12 c EUR/kWh from every hour. The framework adds `price_taxes_eur_kwh`
+    on top, once, and this class cannot see or apply it (trap 1).
+
+    The risk that introduces is one no guard in this file can see, because it
+    is not in code: THE OPERATOR folding their network charges into `offset`
+    while the tax option carries them too. `app/custom_formula.py`'s card
+    self-check is what refuses that - the card's printed estimate is the
+    energy component alone, so an inflated offset moves 15.55 to ~27 and the
+    add-on will not start. Its limit is stated in the same breath there: it
+    grades the coefficients against the card, NOT the card against reality.
+
+    ⚠️ NO EXPRESSION EVALUATION OF ANY KIND, AND THE COEFFICIENTS ARE NUMBERS
+    BECAUSE THE PARSER REFUSES ANYTHING ELSE. This string is settable over
+    HTTP through the add-on's own ingress config page, so `eval` on it would
+    be RCE in a root container holding SUPERVISOR_TOKEN - and, the deciding
+    argument, an arbitrary expression could not be graded against the card at
+    all. See app/custom_formula.py.
+
+    ⚠️ THE INDEX PATH IS `generic_dayahead`'s, NOT A SECOND ONE. Same feed,
+    same `dayahead_feed_url()` request on the Brussels calendar, same columnar
+    parser, same declared egress hosts. A second parser would be a second
+    failure mode for a document that already has one that works.
+    """
+
+    id = "custom_formula"
+
+    FEED_BASE = "https://api.energy-charts.info/price"
+    BZN = "BE"
+
+    # Written by fetch(), read by startup_preview(), and by nothing else.
+    spec = None
+    index_by_instant: dict = {}
+
+    @classmethod
+    def capabilities(cls):
+        return ProviderCapabilities(
+            product=PriceProduct.DAY_AHEAD,
+            sources=frozenset({Component.ENERGY, Component.MARKUP}),
+            egress_hosts=("api.energy-charts.info", "web-api.tp.entsoe.eu"))
+
+    async def fetch(self, opts, since, until, transport):
+        """Fetch the index, apply the card's arithmetic, return RawPoints.
+
+        ⚠️ `since`/`until` ARE USED, through the shared URL builder - see
+        `dayahead_feed_url()` and TARIFF-09 for what ignoring them costs.
+        """
+        try:
+            spec = parse_price_formula(opts.get("price_formula"))
+        except FormulaInvalid as e:
+            raise SourceUnavailable(f"price_formula: {e}")
+        if spec is None:
+            raise SourceUnavailable(
+                "price_provider is 'custom_formula' but price_formula is "
+                "empty, so there are no coefficients to price anything with. "
+                "validate.py refuses this configuration at startup; reaching "
+                "it here means the options blob changed under a running "
+                "add-on")
+        url = dayahead_feed_url(self.id, opts, since, until,
+                                self.FEED_BASE, self.BZN)
+        check_egress(url, self.capabilities())
+        body = await transport(url, float(opts.get("price_timeout_s")))
+        # ⚠️ `scale=1.0`, SO THESE RawPoints CARRY EUR/**MWh** IN A FIELD
+        # SPELLED `eur_per_kwh`. That is a trap and it is contained on purpose:
+        # the list is destructured on the very next line and never leaves this
+        # method, so nothing downstream can read the wrong unit off it. The
+        # alternative - scaling to EUR/kWh and multiplying by 1000 again to
+        # feed the formula - is two conversions where the contract needs none,
+        # and every extra conversion here is another place to lose a factor of
+        # 1000. If this list ever DID escape, `_validate_raw()` would refuse it
+        # at `MAX_PLAUSIBLE_EUR_KWH` rather than price a day on it.
+        index = _points_from_columnar_json(body, expect_unit="EUR / MWh",
+                                           scale=1.0,
+                                           provisional_default=False)
+        pairs = to_resolution([(p.start, p.eur_per_kwh) for p in index],
+                              spec.resolution)
+        self.spec = spec
+        self.index_by_instant = {t.astimezone(timezone.utc): v
+                                 for t, v in pairs}
+        # ⚠️ `provisional=False` FOR THE SAME REASON `generic_dayahead` SAYS
+        # SO: the day-ahead auction is settled once published, and the columnar
+        # document carries no per-point flag to read one from. FCST-04's
+        # carry-forward is what marks the hours nobody published yet.
+        return [RawPoint(start=t, eur_per_kwh=price_eur_kwh(spec, v),
+                         provisional=False)
+                for t, v in pairs]
+
+    def startup_preview(self, points) -> list:
+        """`index EUR/MWh -> all-in EUR/kWh` for the first 24 h, once.
+
+        ⚠️ THE INDEX COLUMN IS WHY THIS HOOK EXISTS. The all-in price alone
+        says nothing about which of the two numbers is wrong; printed beside
+        the index it came from, a factor of 1000 is one glance. See
+        `preview_lines()` for the rows and the min/median/max/spread line.
+        """
+        if self.spec is None or not points:
+            return []
+        cut = points[0].start + timedelta(hours=PREVIEW_HOURS)
+        rows = []
+        for point in points:
+            if point.start >= cut:
+                break
+            index = self.index_by_instant.get(
+                point.start.astimezone(timezone.utc))
+            if index is not None:
+                rows.append((point.start, index, point.eur_per_kwh))
+        return preview_lines(self.spec, rows)
+
+
 # --------------------------------------------------------------------------- #
 # The one entry point
 # --------------------------------------------------------------------------- #
 
+# Provider ids whose startup preview has already been emitted in this process.
+# ⚠️ NOT A PLUGIN NAME IN THE FRAMEWORK: it is filled at runtime from whatever
+# id was resolved, and starts empty. AC2 is intact.
+_PREVIEWED: set = set()
+
+
+def _emit_startup_preview(plugin, pid: str, points) -> None:
+    """Log a plugin's preview once per process, and never fail because of it.
+
+    ⚠️ THE ID IS RECORDED BEFORE THE HOOK RUNS, DELIBERATELY. A preview that
+    raises must not be retried every 30 minutes for the life of the add-on -
+    that would turn a cosmetic defect into a log flood on the one path §11.4
+    already makes hard to read.
+    """
+    if pid in _PREVIEWED:
+        return
+    _PREVIEWED.add(pid)
+    try:
+        lines = list(plugin.startup_preview(points))
+    except Exception as e:                                    # noqa: BLE001
+        _LOG.warning("%s's startup preview raised (%s: %s); prices are "
+                     "unaffected - this is a log line, not a decision",
+                     pid, type(e).__name__, e)
+        return
+    for line in lines:
+        _LOG.info("%s", line)
+
+
+
 async def load_prices(opts: dict, since: datetime, until: datetime,
                       transport=None) -> PriceRead:
     """Resolve the configured provider, fetch, assemble all-in, return a read.
@@ -1589,8 +1921,9 @@ async def load_prices(opts: dict, since: datetime, until: datetime,
 
     if transport is None:
         transport = https_get
+    plugin = cls()
     try:
-        raw = await cls().fetch(PluginOptions(opts), since, until, transport)
+        raw = await plugin.fetch(PluginOptions(opts), since, until, transport)
         _validate_raw(raw, caps)
         points = assemble(caps, raw, markup, taxes)
     except FrameworkOption:
@@ -1600,5 +1933,6 @@ async def load_prices(opts: dict, since: datetime, until: datetime,
     except Exception as e:          # noqa: BLE001 - see the docstring
         return PriceRead.no_data(f"{pid}: {type(e).__name__}: {e}")
 
+    _emit_startup_preview(plugin, pid, points)
     return PriceRead.series(points, caps.product, pid,
                             datetime.now(timezone.utc))

goodwe_controller/app/price_forecast.py

@@ -71,12 +71,19 @@ So the flag is not passed through anywhere in this file:
     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.
+⚠️ "PUBLISHED" DOES NOT MEAN "FIRM". §9.3's canonical format carries
+`provisional` PER POINT, not per series, precisely because a real-time /
+imbalance product's current-interval print is settled after the fact and is
+genuinely provisional while it is published. 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.
+
+⚠️ NO SHIPPED PLUGIN EMITS ONE TODAY (TARIFF-07 withdrew the only declarer of
+`PriceProduct.REALTIME`), and that is exactly why this paragraph stays. The
+rule is a property of the FORMAT, not of any supplier; weakening it to
+"published implies False" while nothing exercises it is how the first real
+imbalance feed would arrive mispriced and flagged firm.
 
 
 THE FILL, AND WHY IT KEYS ON THE WALL CLOCK
@@ -104,8 +111,9 @@ because an empty series is not constructible on purpose (price.py trap 3).
 
 ⚠️ A SUB-HOURLY FEED IS NOT DECIMATED TO ONE POINT AN HOUR, and the hourly walk
 below is about WHICH HOURS NEED FILLING - never about what a published hour is
-allowed to contain. `eneco_eddy` is the Belgian imbalance product and settles
-per QUARTER, `_validate_raw()` accepts any strictly-increasing spacing, and a
+allowed to contain. BELGIAN DAY-AHEAD ITSELF SETTLES PER QUARTER since the
+15-minute MTU took effect on 2025-10-01 - `generic_dayahead` reads 96 points a
+day, not 24 - `_validate_raw()` accepts any strictly-increasing spacing, and a
 published hour may therefore hold four points. So EVERY published point inside
 the window is passed through, in order, and a carried point is added only for a
 whole hour with NO published coverage at all.
@@ -171,7 +179,7 @@ class Provenance(Enum):
     flag" and "the others".
     """
     PUBLISHED = "published"    # the provider printed this hour. Flag: the
-                               # feed's own - an imbalance print may be
+                               # feed's own - a real-time print may be
                                # published AND provisional (§9.2).
     CARRIED = "carried"        # yesterday's same-wall-clock hour (§8.3).
                                # Flag: ALWAYS True, by construction.
@@ -414,9 +422,19 @@ def fill_from_yesterday(read: PriceRead, *, yesterday: PriceRead,
     _audit(out, published)
     carried = sum(1 for p in out if _utc_hour(p.start) not in published)
     if carried:
+        # ⚠️ THREE QUANTITIES, THREE NAMES (TARIFF-11). This line read
+        # "%d of %d hours ... ; %d published" with `carried` (a count of
+        # carried HOURS - the fill emits exactly one point per unpublished
+        # hour) over `len(out)` (a count of POINTS, four per hour wherever the
+        # feed printed) and `len(out) - carried` (POINTS again) under the same
+        # noun. On the Belgian quarter-hourly feed that reads "33 of 141
+        # hours" about a 48-hour horizon. The fill's unit is the HOUR and the
+        # feed's is the POINT; nothing derived from one answers for the other.
+        total_h = len({_utc_hour(p.start) for p in out})
         _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)
+                  "profile and flagged provisional; the feed published %d "
+                  "points over the other %d hours",
+                  carried, total_h, len(out) - carried, total_h - carried)
 
     product = read.match(series=lambda r: r.product,
                          no_data=lambda _r: yesterday.product)

goodwe_controller/app/price_history.py

@@ -107,7 +107,8 @@ THE FOUR RULES THIS FILE IS SHAPED BY
 
    ⚠️ NO VALUE-LEVEL CHECK CAN CATCH THAT, and saying so is more useful than a
    guarantee that would not hold. A carried point and a published-provisional
-   point (`eneco_eddy`'s current quarter, §9.2) are the same three fields with
+   point (a real-time product's current interval, §9.2) are the same three
+   fields with
    the same flag; the difference is provenance, and provenance is not in the
    value. So the mechanism is ORDERING, not validation: `carry()` is the only
    public entry point, it remembers the argument and returns the fill, and the

goodwe_controller/app/static_tariff.py

@@ -13,7 +13,7 @@ is an EMS for a minority." The §9.2 product table maps four products onto four
 EMS behaviours, and TARIFF-02 shipped the machinery for the top two only:
 
     Dynamic day-ahead    hourly EPEX BE + markup     full arbitrage
-    Real-time/imbalance  e.g. Eneco Eddy Flex        arbitrage, wider thresholds
+    Real-time/imbalance  no shipped plugin (TARIFF-07) arbitrage, wider thresh.
     Static day/night     two-period tariff           TIME-WINDOW SHIFTING   <- here
     Fully fixed          single price                SELF-CONSUMPTION ONLY  <- here
 
@@ -771,6 +771,63 @@ class TariffPlan:
             series=lambda r: any(p.provisional for p in r.points),
             no_data=lambda _r: True)
 
+    # -- the plan's SHAPE, in the two units it actually has (TARIFF-11) ------
+    # ⚠️ POINTS AND HOURS ARE TWO NUMBERS AND THIS PLAN HAD ONLY EVER
+    # REPORTED ONE OF THEM, UNDER THE OTHER'S NAME. `words` read
+    # `f"... {len(self.read.points)} h"`, which counts POINTS: on the
+    # quarter-hourly Belgian feed (15-minute MTU, 2025-10-01) a 33-hour plan
+    # logged `dynamic_dayahead from generic_dayahead, 132 h`. It is the same
+    # conflation TARIFF-14 removed from `at()` and FCST-04 removed from the
+    # *Price history* row, left standing in the prose. ⚠️ AND THE ERROR IS
+    # NOT A FLAT 4x: a 40 h soak measured 1.79x .. 5.33x, because §8.3's
+    # carried points are HOURLY while the firm ones are quarter-hourly, so
+    # the ratio moves with the firm/carried mix as the day goes on. Nothing
+    # derived from ONE of these numbers can answer for the other.
+
+    @property
+    def n_points(self) -> int:
+        """How many points the series carries. A `no_data` read carries none."""
+        return self.read.match(series=lambda r: len(r.points),
+                               no_data=lambda _r: 0)
+
+    @property
+    def hours(self) -> int:
+        """How many distinct WHOLE CLOCK HOURS those points touch.
+
+        Same rule as `price_history._held()`, deliberately - the *Tariff* and
+        *Price history* rows describe the same feed and an operator reading
+        `132 points over 33 h` beside `96 points over 24 h` must be able to
+        compare them. A point is attributed to the UTC hour its own start
+        falls in; hours the feed never printed are simply not in the set, so
+        this counts what is PRICED rather than what was asked for.
+        """
+        return self.read.match(series=lambda r: _whole_hours(r.points),
+                               no_data=lambda _r: 0)
+
+    @property
+    def n_firm(self) -> int:
+        """Points carrying a published price for their own interval (§8.3)."""
+        return len(self.firm_points())
+
+    @property
+    def n_carried(self) -> int:
+        """Points filled from yesterday's profile, or from §11.4's fallback."""
+        return self.n_points - self.n_firm
+
+    @property
+    def spacings_s(self) -> tuple:
+        """The distinct gaps between consecutive points, ascending, in seconds.
+
+        ⚠️ MIXED IS THE NORMAL STEADY STATE, NOT AN EDGE CASE. FCST-04's
+        carry-forward emits HOURLY carried points beside QUARTER-HOURLY firm
+        ones and the soak measured `[900, 3600]` in 70 % of samples - so a
+        surface reporting one global spacing would be wrong about the usual
+        case. `price._cover_table()` is where that rule is enforced; this
+        only reports it.
+        """
+        return self.read.match(
+            series=lambda r: _spacings(r.points), no_data=lambda _r: ())
+
     def price_at(self, instant: datetime) -> float:
         """EUR/kWh now. Raises `Absence` when there is no price - never 0.0."""
         return self.read.match(
@@ -926,20 +983,30 @@ class TariffPlan:
         pts = self.read.points
         firm = tuple(p for p in pts if not p.provisional)
         if len(firm) < 2:
+            # ⚠️ POINTS, AND THE HOUR FIGURE BESIDE IT RATHER THAN INSTEAD OF
+            # IT (TARIFF-11). This sentence read "only 1 of 96 hours carry a
+            # published price" about 96 quarter-hourly points, which are 24
+            # hours - the point<->hour conflation TARIFF-14 removed from
+            # `at()`, still standing here, and this one reaches an OPERATOR
+            # through main.py's *Arbitrage* row and not only the log.
             return Arbitrage.refuse(
-                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")
+                f"§8.3: only {len(firm)} of {len(pts)} points carry a "
+                f"published price - {_whole_hours(firm)} of "
+                f"{_whole_hours(pts)} hours - and the rest are provisional "
+                f"(origin {self.origin!r}), so no irreversible action may be "
+                f"taken on them. A buy interval and a sell interval must BOTH "
+                f"be firm before a cycle can be committed. Load shifting, "
+                f"self-consumption and 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:
+            # ⚠️ POINTS AND HOURS, SEPARATELY, for the §8.3 rung's reason -
+            # this sentence counted points and called them "firm hours" too.
             return Arbitrage.refuse(
-                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"the tariff is flat - every one of the {len(firm)} firm "
+                f"points, spanning {_whole_hours(firm)} hours, costs "
+                f"{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")
 
@@ -969,15 +1036,77 @@ class TariffPlan:
 
     @property
     def words(self) -> str:
+        """The plan's whole shape in one sentence - LOG *AND* STATUS PAGE.
+
+        ⚠️ THIS STRING IS OPERATOR-FACING SINCE TARIFF-11, which is a reason
+        for its wording to matter MORE rather than less. It used to reach only
+        `_LOG.info("tariff refreshed: %s")`; main.py's *Tariff* row now carries
+        it, age-stamped, so every number in it is read by somebody who cannot
+        see the object.
+
+        ⚠️ EVERY QUANTITY IS NAMED IN ITS OWN UNIT. `{n} points over {h} h` is
+        FCST-04's *Price history* wording on purpose - the two rows describe
+        the same feed and have to be comparable - and the firm/carried split
+        and the spacing are here because they were the two facts the soak
+        found an operator could not learn at all: the plan was `provisional`
+        for 76 % of a 40-hour soak and mixed 900/3600 s for 70 %, and no HTTP
+        surface said either.
+        """
         if not self.has_prices:
             return f"no tariff - {self.read.reason}"
         tag = {"provider": self.read.provider, "static": "static_profile",
                "fallback": "static_profile (feed down)"}.get(self.origin,
                                                              self.origin)
-        return (f"{self.product.value} from {tag}, {len(self.read.points)} h"
+        gaps = self.spacings_s
+        return (f"{self.product.value} from {tag}, "
+                f"{self.n_points} points over {self.hours} h, "
+                f"{self.n_firm} firm / {self.n_carried} carried"
+                + (f", {'+'.join(str(g) for g in gaps)} s spacing"
+                   if gaps else "")
                 + (", provisional" if self.provisional else ""))
 
 
+def _whole_hours(points) -> int:
+    """How many distinct whole CLOCK HOURS a point list touches. Never raises.
+
+    THE DEFECT THIS PREVENTS (TARIFF-11). Three sentences in this module
+    reported `len(points)` under the name "hours": `TariffPlan.words`, §8.3's
+    firm-pair refusal and the flat-tariff refusal. On the hourly series that
+    was the only resolution any fixture carried before TARIFF-08 the two
+    numbers are identical, which is why it shipped; on the Belgian
+    quarter-hourly feed (15-minute MTU, 2025-10-01) `words` read
+    `dynamic_dayahead from generic_dayahead, 132 h` for 33 hours and the
+    refusal read `only 1 of 96 hours` for 24.
+
+    ⚠️ IT IS NOT `n / 4`, AND A CONSTANT FACTOR IS THE WRONG FIX. §8.3's
+    carry-forward emits ONE HOURLY point per unpublished hour beside the
+    feed's four-per-hour firm ones, so the measured overstatement over a
+    40-hour soak ranged 1.79x .. 5.33x as the mix moved. The hour count has
+    to be COUNTED.
+
+    ⚠️ IT COUNTS PRICED HOURS, NOT THE HORIZON. FCST-04 leaves an hour out
+    of the series when neither the feed nor yesterday can price it, so this
+    is at most the horizon and is smaller whenever the plan has holes - which
+    is the honest direction for a figure an operator reads as "how far ahead
+    do I have prices".
+    """
+    return len({p.start.astimezone(timezone.utc)
+                .replace(minute=0, second=0, microsecond=0) for p in points})
+
+
+def _spacings(points) -> tuple:
+    """Distinct gaps between consecutive points, ascending, in whole seconds.
+
+    Sorted by START, not by list order: `price._cover_table()` establishes
+    that order for `at()` rather than assuming it, and a surface that reported
+    the gaps of an unsorted list would print negative spacings about a series
+    that answers correctly.
+    """
+    starts = sorted(p.start.astimezone(timezone.utc) for p in points)
+    return tuple(sorted({int((b - a).total_seconds())
+                         for a, b in zip(starts, starts[1:])}))
+
+
 def _absent(reason):
     raise Absence(
         f"this plan observed no prices ({reason}). A number invented here is "
@@ -1082,7 +1211,8 @@ async def resolve_tariff(opts: dict, since: datetime, until: datetime,
 
     ⚠️ THE FILL IS PER WHOLE HOUR AND ITS COVERAGE IS CONDITIONAL. Every point
     the provider published inside the window passes through BY IDENTITY - four
-    of them in one hour on a quarter-hourly product like `eneco_eddy` - and a
+    of them in one hour on the quarter-hourly day-ahead feed `generic_dayahead`
+    reads (Belgium's 15-minute MTU, 2025-10-01) - and a
     carried point is added only for a whole hour the feed did not print at all
     AND yesterday did. An hour neither source can price is left out, which is
     §11.4 for that hour: `plan.price_at()` raises rather than answering, and an

goodwe_controller/app/tariff.py

@@ -132,6 +132,18 @@ OBSERVED = "observed"          # the store answered and there is a peak
 NO_RECORD = "no_record"        # the store answered and this month has none yet
 NOT_OBSERVED = "not_observed"  # the store did not answer. NOT a zero peak.
 
+# TARIFF-13. What the COVERAGE figure reads when the store cannot count.
+#
+# ⚠️ NOT 0, AND NOT `None`. This is the reading-state argument of TARIFF-01
+# applied to the number printed BESIDE the peak rather than to the peak. A
+# coverage figure of 0 says "this month has been measured over no quarters at
+# all", which is the strongest possible claim that the peak next to it means
+# nothing - and `f"{None} quarter(s) banked"` renders "None quarter(s) banked",
+# which an operator reads as that same zero. The one honest answer to "how many
+# quarters have I banked" when the table will not answer is that it is not
+# known, and it has to SAY so in the sentence the operator reads.
+COUNT_UNREADABLE = "an unreadable number of"
+
 
 # --------------------------------------------------------------------------- #
 # local time, without a hard dependency on the tz database
@@ -388,6 +400,23 @@ class PeakStore:
                     "   per_phase_json=excluded.per_phase_json"
                     " WHERE excluded.offtake_avg_w > quarter_blocks.offtake_avg_w",
                     (start, month, w, pp_json))
+                # TARIFF-13. THE TIE RULE, DECIDED RATHER THAN EMERGENT:
+                # at EQUAL wattage the EARLIEST quarter keeps the attribution.
+                # See DECISIONS/TARIFF-13-the-coverage-of-a-peak.md §2.
+                #
+                # `peak_w` itself is still only ever RAISED - the `>` term is
+                # untouched and no tie can move the billed number - so SAFETY-07
+                # reads exactly the watt figure it read before. The second term
+                # moves only the TIMESTAMP the status page attributes it to.
+                #
+                # ⚠️ WITHOUT THE SECOND TERM THE TWO READERS DISAGREE, measured:
+                # `>` alone keeps whichever tied block was WRITTEN FIRST, while
+                # `recompute_month()`'s `ORDER BY offtake_avg_w DESC,
+                # quarter_start ASC` keeps the EARLIEST. Those coincide only
+                # while blocks arrive in time order. Fed four equal 365 W blocks
+                # newest-first, `monthly_peak` answered 09:45 and the recompute
+                # answered 09:00 - a divergence in the derived record part 8 of
+                # test_tariff.py exists to prove cannot happen.
                 self._db.execute(
                     "INSERT INTO monthly_peak(month, peak_w, quarter_start, per_phase_json)"
                     " VALUES(?,?,?,?)"
@@ -395,7 +424,9 @@ class PeakStore:
                     "   peak_w=excluded.peak_w,"
                     "   quarter_start=excluded.quarter_start,"
                     "   per_phase_json=excluded.per_phase_json"
-                    " WHERE excluded.peak_w > monthly_peak.peak_w",
+                    " WHERE excluded.peak_w > monthly_peak.peak_w"
+                    "    OR (excluded.peak_w = monthly_peak.peak_w"
+                    "        AND excluded.quarter_start < monthly_peak.quarter_start)",
                     (month, w, start, pp_json))
             return True
         except sqlite3.Error as err:
@@ -449,6 +480,49 @@ class PeakStore:
                            quarter_start=datetime.fromisoformat(row[1]),
                            per_phase_w=pp)
 
+    def banked_count(self, month: str) -> int | None:
+        """How many quarters this month has banked. `None` when unknowable.
+
+        TARIFF-13. THE DEFECT THIS PREVENTS: the status page printed a coverage
+        figure held in PROCESS MEMORY - `PeakTracker.recorded`, incremented once
+        per block banked by THIS process - beside a peak read from SQLite. The
+        peak outlives a restart and the counter does not, so a driven restart
+        mid-month took a real reading of
+
+            2026-09: peak 365 W ... ; 120 quarter(s) banked
+
+        to the same peak, the same attributed quarter and `0 quarter(s) banked`,
+        on both instances independently. The count is what tells an operator how
+        much of the billing month the number beside it actually covers: 365 W
+        over 120 quarters and 365 W over 0 quarters are different claims about
+        the same watt figure, and after a restart the page made the weaker claim
+        while displaying the stronger one's value. Reading the count from the
+        same durable tier the peak comes from is what makes the two agree.
+
+        ⚠️ `None`, NOT 0, and NOT `len(blocks_in(month))`. `blocks_in()` returns
+        `[]` on a read error - safe there only because no caller reads its
+        emptiness as a peak (§ its own docstring) - so counting its length would
+        rebuild the disarming zero one call further out. This asks the database
+        for a COUNT and refuses to answer when the database refuses.
+
+        ⚠️ Counts `quarter_blocks`, the tier with one row per closed block, and
+        NOT `monthly_peak`, which has one row per MONTH and would answer 1 for
+        every month that has ever been measured. The two tables are proven equal
+        on the PEAK by `recompute_month()`; they were never equal on the COUNT
+        and are not meant to be.
+        """
+        if self._db is None:
+            return None
+        try:
+            row = self._db.execute(
+                "SELECT COUNT(*) FROM quarter_blocks WHERE month=?",
+                (month,)).fetchone()
+        except sqlite3.Error as err:
+            self.last_error = str(err)
+            _LOG.error("could not count quarters for %s (%s)", month, err)
+            return None
+        return int(row[0])
+
     def blocks_in(self, month: str) -> list:
         """(quarter_start, offtake_avg_w) for a month, oldest first. [] on error
         is safe here ONLY because no caller reads emptiness as a peak - AC 3's
@@ -539,11 +613,59 @@ class PeakTracker:
         self.cap_w = float(cap_w)
         self.policy = policy
         self.checkpoint_s = float(checkpoint_s)
-        self.recorded = 0
         self.restore_state = "not attempted"
         self._seen: set = set()
         self._last_ckpt = 0.0
 
+    # -- coverage -----------------------------------------------------------
+    #
+    # TARIFF-13. `recorded` USED TO BE AN `int` ATTRIBUTE ON THIS OBJECT,
+    # starting at 0 and incremented in `sync()`. It is a property over the store
+    # now, and the three things that changes are all defects it was carrying:
+    #
+    #   * it RESET TO 0 ON EVERY RESTART, beside a peak that did not - see
+    #     `PeakStore.banked_count()` for the driven reading;
+    #   * it was NOT SCOPED TO A MONTH. It counted every block this process had
+    #     banked, so on 1 October the row still read September's tally beside
+    #     October's "no completed quarter recorded yet";
+    #   * it MISSED the block `restore()` banks. A stale block closed from the
+    #     checkpoint goes into `quarter_blocks` and never went through `sync()`,
+    #     so the counter never saw it. Counting the table cannot miss it.
+    #
+    # ⚠️ REMOVING THE COUNTER DOES NOT REMOVE THE DEDUPE. `_seen` is still what
+    # stops `cycle()`'s once-a-second `sync()` re-banking a closed quarter that
+    # `P1Ingest.blocks` keeps for a DAY, and `sync()`'s RETURN value is still
+    # the count of blocks newly banked on that call. What changed is only where
+    # the STATUS PAGE's figure is read from. The check that grades the dedupe
+    # must therefore grade `sync()`'s return, not this property, which now
+    # answers 1 from the database however many times the block was offered.
+
+    def recorded_in(self, when: datetime | None = None):
+        """Quarters banked in `when`'s billing month - `int`, or the sentinel.
+
+        ⚠️ The return type is `int | str` on purpose, and the `str` is
+        `COUNT_UNREADABLE`. A caller that formats this into a sentence gets a
+        true sentence in both cases; a caller that wants to do arithmetic on it
+        gets a TypeError, which is loud. That is the same trade `PeakReading`
+        makes by having no `peak_w_or(default)`.
+        """
+        n = self.store.banked_count(month_key(when or datetime.now(timezone.utc)))
+        return COUNT_UNREADABLE if n is None else n
+
+    @property
+    def recorded(self):
+        """Quarters banked in the month being billed TODAY.
+
+        ⚠️ This is the live status page's reading, where the peak beside it is
+        also read for `datetime.now()`. `checks(when=X)` for an X in another
+        month is a test affordance (TEST-17); the row scoped that way gets this
+        month's count beside that month's peak, which is strictly better than
+        the process-wide counter it replaces but is still a mismatch.
+        `recorded_in(when)` is the scoped form the row should read once
+        `main.py`'s status rows are free to change - TARIFF-11 holds them.
+        """
+        return self.recorded_in()
+
     # -- startup ------------------------------------------------------------
     def restore(self, averager, now: datetime | None = None) -> str:
         """Put the open block back. Returns which of the three cases happened."""
@@ -600,7 +722,6 @@ class PeakTracker:
                 continue
             if self.store.record_block(block, self.policy):
                 self._seen.add(key)
-                self.recorded += 1
                 n += 1
         if n:
             # A block just closed, so the checkpoint's block is gone: clearing it

goodwe_controller/app/validate.py

@@ -118,8 +118,14 @@ NOT READY banner already names the problem, (b) does not apply.
      It is warned about below, not refused.
 
   7. A price configuration that cannot mean what it says.  [(a)]
-     Three cases, all in `_price_problems()`: an unknown `price_provider` id
-     (refused rather than defaulted to 'off', per the §14 warning box);
+     Four cases, all in `_price_problems()`: an unknown `price_provider` id
+     (refused rather than defaulted to 'off', per the §14 warning box); a
+     RETIRED id - one this add-on really did ship and has been accepting ever
+     since, whose plugin never once fetched a price because its endpoint does
+     not exist (TARIFF-07), which is case (a) in its purest form: §11.4's
+     silent fall back to the static profile IS the layer the operator cannot
+     see, and it has been overriding their chosen source since the day they
+     set it;
      `price_provider` set alongside `price_now_entity`/`price_avg_entity`,
      which is TWO PRICE SOURCES ON ONE SITE where the Home Assistant pair
      silently wins; and `manual_csv` with no `price_csv_path`, which turns the
@@ -318,11 +324,13 @@ import logging
 
 from .arbitrage import enabled as arbitrage_on
 from .control import SLEW_RAIL_FRAC, LOOP_TICK_S, PLANT_SETTLE_S
+from .custom_formula import (
+    FormulaInvalid, implausible_all_in, parse_price_formula, stale_card)
 from .inverter import roster_entries
 from .maintenance import MAINT_OPTION_DEFAULTS
 from .p1 import is_enabled, validate_meter_options
 from .peakguard import PEAK_OPTION_DEFAULTS
-from .price import PRICE_OPTION_DEFAULTS, PROVIDERS
+from .price import PRICE_OPTION_DEFAULTS, PROVIDERS, RETIRED_PROVIDERS
 from .static_tariff import ProfileInvalid, parse_static_profile
 from .watchdog import SIGN_OPTION_DEFAULTS
 
@@ -1242,17 +1250,74 @@ def _price_problems(opts: dict) -> list[str]:
     without a price feed is an add-on that a Belgian fixed-tariff site - a large
     share of the installed base, per §9.2 - cannot run at all.
 
-    Four refusals and two log lines (TARIFF-03 added one refusal, one parse and
-    two notices), and every refusal is still case (a) from this module's
-    docstring: a source the operator SET being overridden by a layer they cannot
-    see. The additions are `static_profile` alongside the Home Assistant price
-    pair - the same silent-loser shape as provider-plus-pair, and a LIVE one -
-    and a `static_profile` that does not tile the day, which would leave hours
-    with no price at all.
+    Five refusals and two log lines (TARIFF-03 added one refusal, one parse and
+    two notices; TARIFF-07 added the retired-id one; TARIFF-15 added three -
+    a `custom_formula` with no formula, a formula that does not parse or does
+    not reproduce its own card, and one whose card lands outside the plausible
+    band - plus two notices, a formula nothing reads and a stale card), and
+    every refusal is still case (a) from this module's docstring: a source the
+    operator SET being overridden by a layer they cannot see. The additions are `static_profile`
+    alongside the Home Assistant price pair - the same silent-loser shape as
+    provider-plus-pair, and a LIVE one - and a `static_profile` that does not
+    tile the day, which would leave hours with no price at all.
+
+    ⚠️ THE RETIRED-ID BRANCH IS NOT A FRIENDLIER SPELLING OF THE UNKNOWN-ID
+    ONE, AND MUST NOT COLLAPSE INTO IT. They answer different questions. An
+    unknown id is a TYPO: the operator meant something else and the fix is to
+    spell it right. A retired id is a CHOICE THE ADD-ON ACCEPTED - it was in
+    the schema, it was in the dropdown, it resolved to a class, and every
+    startup since said nothing. What that operator needs is not "this id is
+    wrong" but "this id has never once returned a price, and here is what your
+    site has actually been running instead" - because §11.4 made the failure
+    silent and NOTHING on their status page has ever distinguished it from a
+    working provider that never finds a cheap hour. The retired branch is
+    therefore FIRST, and it names the id, the endpoint, the observation, the
+    tariff that has really been in force, and the move to make.
     """
     problems: list[str] = []
     pid = str(opts.get("price_provider", "") or "off").strip() or "off"
 
+    if pid in RETIRED_PROVIDERS:
+        # ⚠️ BEFORE the unknown-id branch, and the order is load-bearing: a
+        # retired id is ALSO not in PROVIDERS, so the generic message would
+        # win on a reordering and the operator would be told they mistyped
+        # something they chose on purpose.
+        # ⚠️ AND THE SECOND SENTENCE CHANGES WITH `static_profile`, because
+        # "you have been on the static profile" is FALSE on a site that never
+        # set one. §11.4 falls back to the static profile; with no profile to
+        # fall back to, the site has had no tariff at all - a worse state, and
+        # one this message must not paper over.
+        been_running = (
+            f"the static day/night tariff in static_profile"
+            if str(opts.get("static_profile", "") or "").strip()
+            else "NOTHING AT ALL - static_profile is empty too, so there was "
+                 "no tariff to fall back to either")
+        problems.append(
+            f"price_provider is {pid!r}, which WAS a shipped plugin and has "
+            f"been WITHDRAWN (TARIFF-07). This is not a typo and you did not "
+            f"mistype it - the add-on offered this id, accepted it, and has "
+            f"said nothing at every startup since. "
+            f"⚠️ IT HAS NEVER FETCHED A PRICE, HERE OR ANYWHERE: "
+            f"{RETIRED_PROVIDERS[pid]}. Every fetch it ever made ended in "
+            f"SourceUnavailable, and §11.4 turns that into a SILENT fall back "
+            f"- so what this site has actually been running since the day the "
+            f"id was set is {been_running}. Nothing you could see would have "
+            f"differed from a working provider that simply never found a cheap "
+            f"hour, which is why you are being told now rather than left on "
+            f"it. WHAT TO DO: set price_provider to 'generic_dayahead' for the "
+            f"wholesale EPEX BE day-ahead curve, to which the add-on adds your "
+            f"price_markup_eur_kwh and price_taxes_eur_kwh - that APPROXIMATES "
+            f"a Belgian dynamic tariff and cannot reproduce your supplier's "
+            f"B x spot + A formula, so the level will be off even when the "
+            f"shape is right; or 'manual_csv' to enter all-in prices you "
+            f"compute yourself; or 'off' to run on static_profile "
+            f"deliberately. There is deliberately NO alias to your old "
+            f"supplier: aliasing would need your contract's own two "
+            f"coefficients, which live behind your klantenzone login and are "
+            f"in no public index, so the add-on would have to invent the "
+            f"numbers it prices your battery against.")
+        return problems      # nothing below can be judged against a dead id
+
     if pid != "off" and pid not in PROVIDERS:
         problems.append(
             f"price_provider is {pid!r}, which is not a shipped plugin. The "
@@ -1355,6 +1420,85 @@ def _price_problems(opts: dict) -> list[str]:
                 "for this product. Peak shaving, reserve management and the "
                 "maintenance cycle are unaffected.", profile.prices[0])
 
+    # ⚠️ TARIFF-15: THE FORMULA, GRADED AGAINST THE OPERATOR'S OWN CARD, AT
+    # STARTUP RATHER THAN AT 03:00.
+    #
+    # THE DEFECT THIS EXISTS TO PREVENT, and it is not one `code_leaks()` can
+    # see because it is not in code: an operator folds their NETWORK CHARGES
+    # into `offset` while `price_taxes_eur_kwh` carries them as well, and the
+    # site is billed against a price ~12 c EUR/kWh high on every hour for as
+    # long as nobody re-reads the configuration. §11.4 makes every price
+    # defect quiet, so nothing on the status page would ever differ.
+    #
+    # The card is what grades it. A Belgian tariff card prints the formula,
+    # the reference index it assumed AND the resulting price, so the add-on
+    # recomputes that printed price from the numbers the operator typed and
+    # refuses to start unless the two agree to within CARD_TOLERANCE. An
+    # inflated `offset` cannot pass - the printed estimate is the energy
+    # component alone, so ~12 c EUR/kWh moves 15.55 to ~27. The same check
+    # catches VAT omitted, VAT applied twice, a transposed digit, and a unit
+    # MISMATCH between the coefficients and the printed estimate. The one unit
+    # error it cannot see is the one applied to BOTH sides at once, because
+    # that cancels out of a comparison between them - which is why
+    # `implausible_all_in()` below is a second refusal on a second quantity
+    # rather than a restatement of this one.
+    #
+    # ⚠️ AND ITS LIMIT, IN THE SAME SENTENCE AS THE CLAIM, exactly as price.py
+    # states trap 1's: IT GRADES THE COEFFICIENTS AGAINST THE CARD, NOT THE
+    # CARD AGAINST REALITY. A consistent-but-wrong pair - both numbers off the
+    # wrong product - reproduces its own printed price and passes. Nothing can
+    # catch that.
+    raw_formula = opts.get("price_formula", "")
+    has_formula = bool(str(raw_formula or "").strip()) \
+        or isinstance(raw_formula, dict)
+    if pid == "custom_formula" and not has_formula:
+        problems.append(
+            "price_provider is 'custom_formula' but price_formula is empty, "
+            "so the add-on has no coefficients to price anything with. Every "
+            "fetch would return no-price-data and §11.4 would fall back "
+            "silently - which is the shape of defect this provider exists to "
+            "remove, arrived at by leaving one field blank. Copy the "
+            "Tariefformule line off your supplier's tariff card, e.g. "
+            "{\"index\":\"epex_be\",\"resolution\":\"hourly\","
+            "\"factor\":0.102,\"offset\":1.00,"
+            "\"units\":\"c_eur_per_kwh\",\"vat_pct\":6,"
+            "\"card\":{\"month\":\"2026-09\","
+            "\"index_eur_per_mwh\":133.9905,\"expect_incl_vat\":15.55}} "
+            "- see DOCS.md. Or set price_provider to 'generic_dayahead' for "
+            "the wholesale curve with a flat markup.")
+    elif has_formula:
+        try:
+            spec = parse_price_formula(raw_formula)
+        except FormulaInvalid as e:
+            spec = None
+            problems.append(f"price_formula cannot be used: {e}")
+        if spec is not None and pid != "custom_formula":
+            # ⚠️ A WARNING AND NOT A REFUSAL. This is not two price sources
+            # fighting over one flag - it is one that is simply not wired to
+            # anything - so the §14 warning box does not apply. But an option
+            # an operator filled in and that decides nothing is exactly the
+            # silent loser this module's case (a) is about, so it is said out
+            # loud rather than left to be discovered from a bill.
+            _LOG.warning(
+                "price_formula is filled in but price_provider is %r, so the "
+                "coefficients decide NOTHING - only 'custom_formula' reads "
+                "them. Set price_provider to 'custom_formula' to use them, or "
+                "clear price_formula so the configuration says what the "
+                "add-on is doing.", pid)
+        if spec is not None and pid == "custom_formula":
+            taxes = _number(opts, "price_taxes_eur_kwh",
+                            PRICE_OPTION_DEFAULTS["price_taxes_eur_kwh"])
+            band = implausible_all_in(spec, taxes if taxes is not None else 0.0)
+            if band:
+                problems.append(band)
+            aged = stale_card(spec)
+            if aged:
+                # ⚠️ WARN, NEVER REFUSE. ENGIE freezes a contract's
+                # coefficients for its duration, so a two-year-old card can be
+                # exactly right and a site refused over one is a site that
+                # cannot start.
+                _LOG.warning("%s", aged)
+
     # ⚠️ A WARNING, NOT A REFUSAL, AND THE ASYMMETRY IS DELIBERATE. §11.4 says a
     # site with no price data falls back to the static profile; a dynamic site
     # with none configured has nothing to fall back to when its feed dies. That

goodwe_controller/config.yaml

@@ -284,9 +284,11 @@ options:
   #
   # markup/taxes are the §14 `tariffs.energy_price.*` figures and are added by
   # the FRAMEWORK, only for the components the chosen plugin declares its feed
-  # does not already contain. engie_dynamic, totalenergies_dynamic, eneco_eddy
-  # and manual_csv publish a figure that already carries the markup, so setting
-  # it under those is ignored - and logged as ignored, never applied twice.
+  # does not already contain. manual_csv carries an all-in figure, so setting
+  # either under it is ignored - and logged as ignored, never applied twice.
+  # `custom_formula` (TARIFF-15) carries energy AND markup - your contract's
+  # formula IS the markup - so it takes price_taxes_eur_kwh only, and your
+  # price_markup_eur_kwh is ignored under it, with a line in the log saying so.
   price_provider: "off"
   price_markup_eur_kwh: 0.03
   price_taxes_eur_kwh: 0.06
@@ -325,6 +327,54 @@ options:
   # to fall back to and a dead feed leaves the site with no tariff at all.
   # validate.py warns about exactly that.
   static_profile: ""
+
+  # TARIFF-15. YOUR OWN TARIFF CARD, as two fixed coefficients. Used only when
+  # `price_provider: custom_formula`; "" is unset.
+  #
+  # A Belgian dynamic contract prices energy as `B x index + A`, and the two
+  # coefficients exist in exactly ONE place - the tariff card in your
+  # klantenzone. There is no machine-readable source for them anywhere (CREG's
+  # tariff-card pages 404, CREG Scan is a JS wizard, VREG was unreachable), so
+  # no plugin and no scraper can ever know YOUR numbers. You are the only party
+  # who can see them.
+  #
+  # A JSON object, on one line. You type what your card prints, IN THE CARD'S
+  # OWN UNITS; every unit conversion and the VAT multiplication are the
+  # add-on's job, because those are exactly the two steps that silently cost a
+  # factor of 10, 100 or 1.06.
+  #
+  #   {"index":"epex_be","resolution":"hourly","factor":0.102,"offset":1.00,
+  #    "units":"c_eur_per_kwh","vat_pct":6,
+  #    "card":{"month":"2026-09","index_eur_per_mwh":133.9905,
+  #            "expect_incl_vat":15.55}}
+  #
+  # price = (factor x index_eur_per_mwh + offset) x (1 + vat_pct/100), in
+  # `units`, converted to EUR/kWh by the add-on.
+  #
+  # ⚠️ THE `card` BLOCK IS REQUIRED AND IT IS THE SAFETY MECHANISM. Your card
+  # prints the formula, the reference index it assumed AND the resulting price.
+  # At startup the add-on recomputes that printed price from the numbers you
+  # typed and REFUSES TO START unless the two agree to within 0.01 - naming the
+  # discrepancy. That catches VAT left out or applied twice, a transposed
+  # digit, a unit MISMATCH between the coefficients and the printed price
+  # (10x/100x/1000x), and the expensive one: NETWORK CHARGES FOLDED INTO
+  # `offset`. A unit error applied to BOTH sides at once cancels out of that
+  # comparison; the add-on refuses that separately, by checking the card's own
+  # point against the band a Belgian retail tariff can occupy. Your card's formula line is the ENERGY component
+  # alone; the add-on adds price_taxes_eur_kwh on top, so folding ~12 c/kWh of
+  # network charge into `offset` would bill you for it twice - and it cannot
+  # pass, because it moves the computed 15.55 to about 27.
+  #
+  # ⚠️ AND THE LIMIT OF THAT CHECK, IN THE SAME BREATH: it grades your
+  # COEFFICIENTS AGAINST YOUR CARD, not your card against reality. Two numbers
+  # copied off the wrong product agree with each other perfectly and pass.
+  #
+  # ⚠️ FIXED COEFFICIENTS ONLY - the add-on evaluates NO expression of any kind
+  # and there is no field that takes one. An unknown key is refused rather than
+  # ignored. See DOCS.md for why (it is not only security: two coefficients can
+  # be graded against your card and an arbitrary expression cannot be graded
+  # against anything).
+  price_formula: ""
   price_csv_path: "/share/goodwe_prices.csv"
   # ⚠️ AN OVERRIDE IS THE EXACT URL (TARIFF-09). The plugin sends it verbatim
   # and appends nothing - including the `start`/`end` date range it derives from
@@ -758,9 +808,32 @@ schema:
   # Supervisor rejects a typo in the UI. validate.py ALSO refuses an unknown id
   # against app/price.py's PROVIDERS registry, because sim/inject.py and the
   # checks reach validate_startup_config() with a dict the Supervisor never saw.
-  # Adding a sixth plugin means adding it here and to PROVIDERS - and nowhere
-  # else, which is AC2.
-  price_provider: list(off|generic_dayahead|engie_dynamic|totalenergies_dynamic|eneco_eddy|manual_csv)
+  # Adding a plugin means adding it here and to PROVIDERS - and nowhere else,
+  # which is AC2.
+  #
+  # ⚠️ THREE OF THESE FIVE IDS NO LONGER RESOLVE TO A PLUGIN, AND LEAVING THEM
+  # HERE IS A DECISION (TARIFF-07). engie_dynamic, totalenergies_dynamic and
+  # eneco_eddy were withdrawn - their endpoints do not exist and never did - and
+  # the obvious edit is to delete them from this line too. DO NOT. The Supervisor
+  # validates the options file against this schema BEFORE the add-on starts, so
+  # an id that is not listed here makes an EXISTING config schema-invalid: the
+  # operator gets an opaque "expected one of ..." from the Supervisor, the add-on
+  # never runs, and validate.py's retired-id refusal - the message that tells
+  # them their prices never worked and what to do instead - IS NEVER REACHED, on
+  # exactly the sites that need it. Schema tightness would cost the only thing
+  # this withdrawal is FOR.
+  #
+  # The cost of keeping them is that the dropdown still offers three dead ids to
+  # a NEW operator. That is the cheaper failure: choosing one is refused at the
+  # next startup by name, with the endpoint, the observation and the alternative
+  # - which is strictly more than a typo-shaped schema rejection would say. Both
+  # translations label them withdrawn in the option description as well.
+  #
+  # app/price.py's RETIRED_PROVIDERS is the list, test_price.py section 1 asserts
+  # this line offers exactly PROVIDERS + RETIRED_PROVIDERS + 'off' - derived, not
+  # typed - and register() refuses to re-register a retired id, so the two
+  # cannot both claim one.
+  price_provider: list(off|generic_dayahead|custom_formula|engie_dynamic|totalenergies_dynamic|eneco_eddy|manual_csv)
   price_markup_eur_kwh: float(0,1)
   price_taxes_eur_kwh: float(0,1)
 
@@ -774,6 +847,11 @@ schema:
   # parse_static_profile() accepts an already-parsed dict too, so a future
   # nested schema is a config.yaml change and no code change at all.
   static_profile: str?
+  # TARIFF-15. A JSON string for the same reason `static_profile` is one: it is
+  # ONE option key, it survives config.yaml's flat options block, and
+  # parse_price_formula() accepts an already-parsed dict too, so a future
+  # nested schema is a config.yaml change and no code change at all.
+  price_formula: str?
   price_csv_path: str?
   price_feed_url: str?
   price_horizon_h: int(1,72)

goodwe_controller/test_arbitrage.py

@@ -1695,6 +1695,312 @@ check("soc_bounds() returns the shipped pair, floor first",
                          float(PRICE_OPTION_DEFAULTS["arbitrage_soc_ceiling"])))
 
 
+# --------------------------------------------------------------------------- #
+print()
+print("10. TARIFF-14 - the QUARTER-HOURLY day, end to end through decide()")
+# ⚠️ THIS IS THE PROPERTY THE DEFECT ACTUALLY BROKE, WHICH IS WHY IT IS GRADED
+# HERE AND NOT ONLY ON `at()`. `_act()` decides whether this interval is the
+# buy one or the sell one with `here.start == v.cheapest.start` - an IDENTITY
+# test between the point `_point_at()` matched and the point the verdict was
+# built from. `_Series.at()` used to return the first point whose start was
+# within one hour BEFORE the instant, in list order, so on a 900 s series that
+# identity almost never held: the strategy idled through exactly the interval
+# it exists to trade, and read `here.provisional` and §17's `price < 0` off a
+# point that was not the one being traded.
+#
+# Belgium moved to a 15-minute MTU on 2025-10-01 and the live day-ahead feed
+# returns 96 points at 900 s. `static_tariff.py` emits HOURLY points, so every
+# fixture above this line - and every static site - is immune; this is
+# reachable only down the dynamic path TARIFF-08/09 made work.
+
+QD0 = datetime(2026, 1, 15, 0, 0, tzinfo=timezone(timedelta(hours=1)))
+QUARTER = timedelta(minutes=15)
+
+
+def qplan_of(prices, *, provisional=False, start=QD0, gaps=None):
+    """A TariffPlan over `prices` spaced by `gaps` seconds (900 s by default).
+
+    `gaps` is what makes the MIXED fixture below expressible: FCST-04's
+    carry-forward emits HOURLY carried points beside QUARTER-HOURLY firm ones,
+    and the soak measured spacing [900, 3600] in 70 % of samples.
+    """
+    g = [900] * (len(prices) - 1) if gaps is None else list(gaps)
+    flags = ([bool(provisional)] * len(prices)
+             if isinstance(provisional, bool) else list(provisional))
+    pts, t = [], start
+    for i, (p, f) in enumerate(zip(prices, flags)):
+        pts.append(PricePoint(start=brussels(t), eur_per_kwh=round(float(p), 6),
+                              provisional=bool(f)))
+        if i < len(g):
+            t += timedelta(seconds=g[i])
+    return TariffPlan(PriceRead.series(pts, PriceProduct.DAY_AHEAD,
+                                       "generic_dayahead", start),
+                      None, "provider")
+
+
+def qprobe(i, *, start=QD0, gaps=None):
+    """An instant 7 minutes into slot `i` - inside every window, never on a
+    boundary, and NOT the midpoint of an hour either, so an implementation that
+    answered per hour and one that answers per quarter differ here."""
+    g = [900] * i if gaps is None else list(gaps)[:i]
+    return start + timedelta(seconds=sum(g)) + timedelta(minutes=7)
+
+
+def shipped_at(series, u):
+    """THE RULE TARIFF-14 REPLACED, kept here as the COUNTERFACTUAL ONLY.
+
+    The first point whose start is within one hour before `u`, in list order.
+    Nothing below is graded against it; it exists so that the fixtures can be
+    shown to SEPARATE the two rules. A check whose data cannot reach the
+    failure it names is decoration (MUTATION.md), and on an hourly series the
+    two rules agree at every instant - which is why 29 files stayed green.
+    """
+    uu = u.astimezone(UTC)
+    for p in series.points:
+        s = p.start.astimezone(UTC)
+        if s <= uu < s + timedelta(hours=1):
+            return p
+    return None
+
+
+# The hourly day interpolated across its quarters, with the two extremes
+# planted OFF the hour boundary on purpose.
+QBASE = []
+for _i in range(24):
+    _a, _b = DAY[_i], DAY[(_i + 1) % 24]
+    for _q in range(4):
+        QBASE.append(round(_a + (_b - _a) * _q / 4 + 0.000001 * (_i * 4 + _q),
+                           6))
+Q_CHEAP_I = 4 * 5 + 3          # 05:45 - a :45 quarter, not a whole hour
+Q_DEAR_I = 4 * 19 + 1          # 19:15 - a :15 quarter, not a whole hour
+QDAY = list(QBASE)
+QDAY[Q_CHEAP_I] = round(min(QBASE) - 0.030, 6)
+QDAY[Q_DEAR_I] = round(max(QBASE) + 0.030, 6)
+QPLAN = qplan_of(QDAY)
+QPTS = QPLAN.read.points
+
+print("10a. the fixture is not degenerate, and it SEPARATES the two rules")
+_qgaps = sorted({int((b.start - a.start).total_seconds())
+                 for a, b in zip(QPTS, QPTS[1:])})
+check(f"the day is 96 points at {_qgaps} s - the shape the live feed has "
+      f"returned since Belgium's 2025-10-01 move to a 15-minute MTU",
+      len(QPTS) == 96 and _qgaps == [900])
+check(f"the cheapest quarter is slot {Q_CHEAP_I} and the dearest slot "
+      f"{Q_DEAR_I} - neither first, neither last, {abs(Q_CHEAP_I - Q_DEAR_I)} "
+      f"slots apart, and NEITHER ON A WHOLE HOUR, without which this section "
+      f"would grade nothing an hourly fixture does not already grade",
+      QDAY.index(min(QDAY)) == Q_CHEAP_I and QDAY.index(max(QDAY)) == Q_DEAR_I
+      and Q_CHEAP_I % 4 != 0 and Q_DEAR_I % 4 != 0
+      and Q_CHEAP_I not in (0, 95) and Q_DEAR_I not in (0, 95)
+      and abs(Q_CHEAP_I - Q_DEAR_I) > 1)
+check("...and all 96 prices are distinct, so 'the cheapest quarter' names one "
+      "quarter and no tie-break is what any check below is really grading",
+      len(set(QDAY)) == 96)
+check(f"...and its spread is {round(max(QDAY) - min(QDAY), 6):.4f} EUR/kWh, "
+      f"clear of the widened threshold, so what follows grades the strategy "
+      f"and not the spread rung",
+      round(max(QDAY) - min(QDAY), 6) > required_spread(_shipped, NO_WEATHER))
+# ⚠️ HABIT 4, AND THE ONLY REASON THIS SECTION IS WORTH ITS LINES. State, as a
+# check, that the shipped rule and the fixed one give DIFFERENT points at the
+# two probes that matter. Without it, every check below could be passing on a
+# fixture the defect could not have changed.
+_cf_buy = derived(lambda: shipped_at(QPLAN.read, qprobe(Q_CHEAP_I)))
+_cf_sell = derived(lambda: shipped_at(QPLAN.read, qprobe(Q_DEAR_I)))
+check(f"the shipped rule and this one give DIFFERENT points at both probes - "
+      f"buy: {derived(lambda: _cf_buy.eur_per_kwh)} instead of "
+      f"{QDAY[Q_CHEAP_I]}, sell: {derived(lambda: _cf_sell.eur_per_kwh)} "
+      f"instead of {QDAY[Q_DEAR_I]} - so the fixture can reach the failure it "
+      f"names",
+      _cf_buy is not QPTS[Q_CHEAP_I] and _cf_sell is not QPTS[Q_DEAR_I]
+      and _cf_buy is not None and _cf_sell is not None)
+
+print()
+print("10b. the buy/sell identity test matches the actual extremum interval")
+_qv = QPLAN.arbitrage(peak_guard_active=False, min_spread_eur_kwh=_shipped,
+                      uncertainty=NO_WEATHER)
+check("the verdict's cheapest and dearest are the two QUARTERS, not the hours "
+      "containing them - `static_tariff` reduces over every firm point and "
+      "carries no resolution assumption of its own",
+      derived(lambda: _qv.cheapest) is QPTS[Q_CHEAP_I]
+      and derived(lambda: _qv.dearest) is QPTS[Q_DEAR_I])
+_pa_buy = derived(lambda: _arb._point_at(QPLAN, qprobe(Q_CHEAP_I)))
+_pa_sell = derived(lambda: _arb._point_at(QPLAN, qprobe(Q_DEAR_I)))
+check("THE PROPERTY THE DEFECT BROKE: at the buy probe `_point_at()` returns "
+      "the verdict's OWN cheapest point, by identity - which is what makes "
+      "`_act()`'s `here.start == v.cheapest.start` true, and what made it "
+      "false on every quarter-hourly series the add-on has ever fetched",
+      _pa_buy is derived(lambda: _qv.cheapest))
+check("...and the same at the sell probe, against the verdict's dearest",
+      _pa_sell is derived(lambda: _qv.dearest))
+_qbuy = decide(QPLAN, qprobe(Q_CHEAP_I), peak_guard_active=False, 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)
+_qsell = decide(QPLAN, qprobe(Q_DEAR_I), peak_guard_active=False, 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("...so decide() CHARGES in the cheapest quarter and DISCHARGES in the "
+      "dearest one, which is the trade the strategy exists to make and the "
+      "one it slept through",
+      _qbuy.action == CHARGE and _qsell.action == DISCHARGE)
+check(f"...at THAT QUARTER's price and not at the price of the hour "
+      f"containing it (buy {_qbuy.price_now_eur_kwh}, sell "
+      f"{_qsell.price_now_eur_kwh})",
+      near(_qbuy.price_now_eur_kwh, QDAY[Q_CHEAP_I])
+      and near(_qsell.price_now_eur_kwh, QDAY[Q_DEAR_I]))
+check("...and both reasons quote that quarter's price, so the operator's log "
+      "names the interval that was actually traded",
+      f"{QDAY[Q_CHEAP_I]:.4f}" in _qbuy.reason
+      and f"{QDAY[Q_DEAR_I]:.4f}" in _qsell.reason)
+# The negative arm. Without it "it acted" could be "it acts everywhere".
+_QOFF_I = Q_CHEAP_I + 2
+check(f"the off-peak probe's own price differs from its hour's :00 price "
+      f"({QDAY[_QOFF_I]} vs {QDAY[4 * (_QOFF_I // 4)]}), so the check below "
+      f"can tell which point the decision read",
+      QDAY[_QOFF_I] != QDAY[4 * (_QOFF_I // 4)]
+      and _QOFF_I not in (Q_CHEAP_I, Q_DEAR_I))
+_qoff = decide(QPLAN, qprobe(_QOFF_I), peak_guard_active=False, 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 quarter that is neither extremum still idles, for the reason that "
+      "names the right rule, and reports ITS OWN price - not the price of the "
+      "quarter the shipped scan would have matched",
+      _qoff.action is None and _qoff.reason == _arb.IDLE_OFF_PEAK_HOUR
+      and near(_qoff.price_now_eur_kwh, QDAY[_QOFF_I]))
+
+print()
+print("10c. §17 and §8.3 are evaluated on the QUARTER being traded")
+# ⚠️ §17 AT 900 s. The whole day is below zero and the dearest QUARTER is the
+# least negative one - section 2's shape, at the resolution the live feed
+# actually publishes. Under the shipped scan this probe never reached the
+# guard at all: the identity test failed first and the decision idled as
+# "neither the buy hour nor the sell hour", so §17 was not so much wrong as
+# never consulted.
+_shift = round(max(QDAY) + 0.020, 6)
+QNEG = [round(p - _shift, 6) for p in QDAY]
+QNEG_PLAN = qplan_of(QNEG)
+check(f"the negative day's dearest quarter is slot {Q_DEAR_I} and it is BELOW "
+      f"ZERO ({max(QNEG):+.4f}), and its spread still clears the widened "
+      f"threshold - so the refusal below is §17's and not the spread rung's",
+      QNEG.index(max(QNEG)) == Q_DEAR_I and max(QNEG) < 0
+      and round(max(QNEG) - min(QNEG), 6) > required_spread(_shipped,
+                                                            NO_WEATHER))
+_qneg_sell = decide(QNEG_PLAN, qprobe(Q_DEAR_I), peak_guard_active=False,
+                    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("selling into a negative-price QUARTER is refused, and the reason names "
+      "§17 and THAT QUARTER's price",
+      _qneg_sell.action is None and "§17" in _qneg_sell.reason
+      and f"{max(QNEG):+.4f}" in _qneg_sell.reason)
+# ...and the other side, so the refusal is about the sign and nothing else.
+QPOS = list(QNEG)
+QPOS[Q_DEAR_I] = round(-max(QNEG), 6)
+check("...while the SAME quarter-hourly series with that ONE price's SIGN "
+      "FLIPPED discharges instead",
+      decide(qplan_of(QPOS), qprobe(Q_DEAR_I), peak_guard_active=False,
+             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).action == DISCHARGE
+      and sum(1 for a, b in zip(QNEG, QPOS) if a != b) == 1)
+# §8.3's flag, read off the covering point. `_act`'s own provisional guard
+# stays unreachable here for section 4's reason - the extrema are firm by
+# `_firm_or_die` and starts are unique - and THAT ARGUMENT IS EXACTLY WHAT THE
+# DEFECT BROKE at 900 s, because the point `at()` returned was not the
+# verdict's point at all. It is restated here at the resolution that matters.
+check("the point matched for the buy quarter IS the verdict's own cheapest "
+      "point and is FIRM, so `_act`'s §8.3 guard is unreachable at 900 s for "
+      "the same construction section 4 states at 3600 s",
+      _pa_buy is derived(lambda: _qv.cheapest)
+      and derived(lambda: _pa_buy.provisional) is False
+      and len({p.start for p in QPTS}) == len(QPTS))
+
+print()
+print("10d. the MIXED series FCST-04 actually emits, traded end to end")
+# ⚠️ 70 % OF SOAK SAMPLES, NOT AN EDGE CASE. The carry-forward emits HOURLY
+# carried points beside QUARTER-HOURLY firm ones, so a window derived from one
+# global spacing would be wrong in the NORMAL steady state. Here: 12 carried
+# hourly points for the morning, then firm quarters for the rest of the day.
+MIX_N_H, MIX_N_Q = 12, 48
+MIX_GAPS = [3600] * MIX_N_H + [900] * (MIX_N_Q - 1)
+MIX_PRICES = [QDAY[4 * i] for i in range(MIX_N_H)] + QDAY[4 * MIX_N_H:]
+MIX_FLAGS = [True] * MIX_N_H + [False] * MIX_N_Q
+MIX_PLAN = qplan_of(MIX_PRICES, provisional=MIX_FLAGS, gaps=MIX_GAPS)
+MIX_PTS = MIX_PLAN.read.points
+_mix_gaps = sorted({int((b.start - a.start).total_seconds())
+                    for a, b in zip(MIX_PTS, MIX_PTS[1:])})
+check(f"the mixed plan really is mixed - spacing {_mix_gaps} s, "
+      f"{MIX_N_H} carried and {MIX_N_Q} firm points, so neither half is what "
+      f"the other half's window rule would give",
+      _mix_gaps == [900, 3600]
+      and sum(1 for p in MIX_PTS if p.provisional) == MIX_N_H
+      and sum(1 for p in MIX_PTS if not p.provisional) == MIX_N_Q)
+_mix_cheap_i = MIX_N_H + (MIX_PRICES[MIX_N_H:].index(min(MIX_PRICES[MIX_N_H:])))
+_mix_dear_i = MIX_N_H + (MIX_PRICES[MIX_N_H:].index(max(MIX_PRICES[MIX_N_H:])))
+check(f"...and its firm half's extremes are quarters {_mix_cheap_i} and "
+      f"{_mix_dear_i}, neither on a whole hour, so the identity test below is "
+      f"about the quarter and not about the hour",
+      (_mix_cheap_i - MIX_N_H) % 4 != 0 and (_mix_dear_i - MIX_N_H) % 4 != 0)
+_mv = MIX_PLAN.arbitrage(peak_guard_active=False, min_spread_eur_kwh=_shipped,
+                         uncertainty=NO_WEATHER)
+_mix_buy_t = qprobe(_mix_cheap_i, gaps=MIX_GAPS)
+_mix_sell_t = qprobe(_mix_dear_i, gaps=MIX_GAPS)
+check("the verdict over a MIXED series still names firm quarters, and "
+      "`_point_at()` matches them by identity at their own probes",
+      derived(lambda: _mv.cheapest) is MIX_PTS[_mix_cheap_i]
+      and derived(lambda: _mv.dearest) is MIX_PTS[_mix_dear_i]
+      and derived(lambda: _arb._point_at(MIX_PLAN, _mix_buy_t))
+      is MIX_PTS[_mix_cheap_i]
+      and derived(lambda: _arb._point_at(MIX_PLAN, _mix_sell_t))
+      is MIX_PTS[_mix_dear_i])
+check("...so the mixed day CHARGES and DISCHARGES in its firm quarters, at "
+      "their own prices",
+      decide(MIX_PLAN, _mix_buy_t, peak_guard_active=False, 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).action == CHARGE
+      and decide(MIX_PLAN, _mix_sell_t, peak_guard_active=False, 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).action == DISCHARGE)
+# An instant inside a CARRIED hour of the same series. The covering point is
+# the carried one; the shipped scan answered a point from the FIRM block
+# earlier in the list, which is §8.3's flag read off the wrong point.
+_mix_carried_t = QD0 + timedelta(hours=MIX_N_H - 1, minutes=37)
+check("an instant inside a CARRIED hour of the mixed series matches the "
+      "CARRIED point, whose provisional flag is what §8.3 reads - and the "
+      "strategy does nothing there, because a carried point is not in the "
+      "firm trade set",
+      derived(lambda: _arb._point_at(MIX_PLAN, _mix_carried_t))
+      is MIX_PTS[MIX_N_H - 1]
+      and MIX_PTS[MIX_N_H - 1].provisional is True
+      and decide(MIX_PLAN, _mix_carried_t, peak_guard_active=False, 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).action is None)
+
+print()
+print("10e. the HOURLY day is unchanged, which is the regression half")
+# ⚠️ A REGRESSION GUARD, NOT A WITNESS. On an hourly series the shipped rule
+# and this one agree at every instant, which is precisely why 29 files stayed
+# green through the defect. It is here so that a fix which got 900 s right by
+# breaking 3600 s cannot pass.
+_h_buy = act(PLAN, CHEAP_H, thresh=_shipped, unc=NO_WEATHER)
+_h_sell = act(PLAN, DEAR_H, thresh=_shipped, unc=NO_WEATHER)
+check("the hourly fixture still charges in its cheapest hour and discharges "
+      "in its dearest, at those hours' prices",
+      _h_buy.action == CHARGE and _h_sell.action == DISCHARGE
+      and near(_h_buy.price_now_eur_kwh, DAY[CHEAP_H])
+      and near(_h_sell.price_now_eur_kwh, DAY[DEAR_H]))
+check("...and a probe 59 minutes into an hourly slot still matches that slot, "
+      "so the hourly window did not shrink under the fix",
+      derived(lambda: _arb._point_at(
+          PLAN, D0 + timedelta(hours=CHEAP_H, minutes=59)))
+      is derived(lambda: PLAN.read.points[CHEAP_H]))
+
+
 # --------------------------------------------------------------------------- #
 print()
 if fails:

goodwe_controller/test_defaults_pin.py

@@ -7,7 +7,7 @@ WHAT UX-01 AC 4 ASKED FOR, IN ITS OWN WORDS: "every `schema:` key absent from
 check, not a grep."
 
 WHAT SHIPPED. Clause one is VACUOUS: `options:` and `schema:` declare the same
-71 keys, so "every schema key absent from options" quantifies over the empty set
+72 keys, so "every schema key absent from options" quantifies over the empty set
 and is true of any tree, including one with no defaults at all. Clause two -
 "the table changed goes red" - does work, six times over, once per mirror in its
 own suite. Clause three, THE ONE WITH THE CONTENT, was never written. The only

goodwe_controller/test_price_forecast.py

@@ -289,22 +289,29 @@ check("...and never repairs a flag: the audit's only outcomes are silence and "
                                        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)
+# ⚠️ A PUBLISHED POINT MAY BE PROVISIONAL. A real-time / imbalance product's
+# current interval is settled after the fact and says so per point (§9.2).
+# "Published" is not "firm", and §9.3 carries the flag PER POINT for exactly
+# this. No shipped plugin declares REALTIME since TARIFF-07, so the series is
+# declared here - which is the only place the case can come from now, and is
+# why this stimulus did not go with the plugin.
+_rt = series_of(DAY[:2], lambda u: t_price(brussels(u).hour),
+                PriceProduct.REALTIME, "_realtime_not_shipped",
+                provisional=True)
 _eddy_filled = derived(lambda: fill_from_yesterday(
-    _eddy, yesterday=YESTERDAY, since=D0, until=D1, stamp=D0))
+    _rt, 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])
+      and _eddy_filled.points[0] is _rt.points[0])
 
 # ⚠️ AND A SUB-HOURLY FEED IS NOT DECIMATED TO ONE POINT AN HOUR (FCST-04 H1).
-# `eneco_eddy` settles per QUARTER and `_validate_raw()` accepts any
-# strictly-increasing spacing, so a published hour can hold four points. The
+# BELGIAN DAY-AHEAD ITSELF SETTLES PER QUARTER - the 15-minute MTU of
+# 2025-10-01, which `generic_dayahead` reads as 96 points a day - and
+# `_validate_raw()` accepts any strictly-increasing spacing, so a published
+# hour can hold four points. The
 # fill walks WHOLE HOURS to decide what needs carrying; that must not become a
 # rule about what a published hour may contain. Measured on FCST-04's first
 # draft, which keyed the published set `{_utc_hour(p.start): p ...}`: a
@@ -316,7 +323,7 @@ _QUARTERS = PriceRead.series(
                 eur_per_kwh=round(0.100000 + 0.011300 * n, 6),
                 provisional=False)
      for n in range(_QN)],
-    PriceProduct.REALTIME, "eneco_eddy", D0)
+    PriceProduct.DAY_AHEAD, "generic_dayahead", D0)
 _QHOURS = {_fc._utc_hour(p.start) for p in _QUARTERS.points}
 check(f"the quarter-hourly fixture really is sub-hourly - {_QN} points across "
       f"{len(_QHOURS)} hours - or every check below passes for an hourly feed "
@@ -942,13 +949,20 @@ _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",
+      "'eneco_eddy' when the declared product is day-ahead - so a 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
+# ⚠️ 'eneco_eddy' ABOVE IS NOW A RETIRED ID AND THE CHECK IS STRONGER FOR IT.
+# It was chosen because it was the one plugin that really did declare REALTIME,
+# so the check read "the name does not override the declaration". It declares
+# nothing now, which makes the string a pure name with no product behind it -
+# exactly the input an id-sniffing implementation would still widen.
+check("...and NO shipped plugin declares REALTIME since TARIFF-07, so the "
+      "widening path is reached by declaration alone - kept deliberately, see "
+      "DECISIONS/TARIFF-07-withdrawing-three-plugins.md",
+      [p for p, c in PROVIDERS.items()
+       if c.capabilities().product is PriceProduct.REALTIME] == []
       and uncertainty_of(PriceProduct.REALTIME)
       == frozenset({Uncertainty.REALTIME_PRODUCT})
       and uncertainty_of(PriceProduct.DAY_AHEAD) == frozenset())
@@ -1087,19 +1101,27 @@ _cfg = derived(lambda: open(os.path.join(HERE, "config.yaml"),
 # 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}",
+# TARIFF-15 added the fifth, and came here to say so as this comment instructs:
+# `price_formula` is the `custom_formula` provider's only option - one JSON
+# string carrying one contract's coefficients - and it lives in this dict and
+# in config.yaml and nowhere else, which is the arrangement `static_profile`
+# already has for the same reason.
+_T15_KEYS = ["price_formula"]
+check(f"the in-code mirror holds exactly TARIFF-02's, TARIFF-03's, OPT-04's "
+      f"and TARIFF-15's keys - FCST-03 still added none of its own "
+      f"{_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",
+                           "static_profile"] + _OPT04_KEYS + _T15_KEYS))
+# ...and the later keys 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 and TARIFF-15's one 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)
+      and len(set(_defaults) - set(_OPT04_KEYS) - set(_T15_KEYS)) == 9)
 check("...and every one of them is still in config.yaml, which stays the "
       "source of truth",
       isinstance(_cfg, str)

goodwe_controller/test_price_history.py

@@ -779,9 +779,10 @@ check("the carried hours are NOT in the trade set - the verdict's cheapest and "
 print()
 print("2b. a QUARTER-HOURLY feed keeps every print, and its spread with them")
 
-# ⚠️ THE DEFECT THIS SECTION EXISTS FOR. `eneco_eddy` is the Belgian imbalance
-# product and settles per QUARTER; `_validate_raw()` accepts any
-# strictly-increasing spacing, so a published hour may hold four points.
+# ⚠️ THE DEFECT THIS SECTION EXISTS FOR. Belgian DAY-AHEAD settles per QUARTER
+# - the 15-minute MTU took effect on 2025-10-01, so `generic_dayahead` reads 96
+# points a day - and `_validate_raw()` accepts any strictly-increasing spacing,
+# so a published hour may hold four points.
 # FCST-04's first draft keyed the published set `{_utc_hour(p.start): p ...}` -
 # LAST POINT OF THE HOUR WINS, the other three dropped - and on an all-firm,
 # fully-published 96-point feed the plan came out 15 points long with its

goodwe_controller/test_tariff.py

@@ -2,8 +2,8 @@
 
     python3 test_tariff.py
 
-Ten parts. What each is for, and - where it matters - what it is deliberately
-NOT allowed to be tested at:
+Twelve parts. What each is for, and - where it matters - what it is
+deliberately NOT allowed to be tested at:
 
   1. THE BLOCK ARITHMETIC, against a worked example written out segment by
      segment. The fixture is chosen to be non-degenerate on three axes at once:
@@ -33,6 +33,17 @@ NOT allowed to be tested at:
      proven equal to the tier it derives from, and proven never to be lowered.
   9. AC 3, ON THE REPLAY DATA THAT ACTUALLY EXISTS. See the honesty note below.
  10. THE WIRING, through the real `Controller` and its real status page.
+ 11. TARIFF-13: THE COVERAGE FIGURE PRINTED BESIDE THE PEAK, across a REAL
+     restart - a second `Controller` against the same file. The peak was
+     always durable; the count of banked quarters was an `int` on the
+     tracker and reset to 0, so the page asserted "0 quarter(s) banked"
+     for a month it had measured 120 of. An unreadable store must not
+     produce a coverage figure of 0 either - part 5's argument, one
+     column over.
+ 12. TARIFF-13: WHICH QUARTER A TIED PEAK IS ATTRIBUTED TO, decided
+     (earliest wins) rather than left emergent, and pinned on BOTH
+     readers with a newest-first fixture - ascending arrival cannot tell
+     "the earliest quarter" from "the first row written".
 
 ------------------------------------------------------------------------------
 ⚠️ PART 9 IS A TWO-DAY MEASUREMENT AND SAYS SO. THE 30-DAY ANSWER IS ELSEWHERE
@@ -106,9 +117,9 @@ from pathlib import Path
 from app.main import Controller
 from app.p1 import P1Ingest, QuarterAverager, QUARTER_S, make_sample, split_signed
 from app.tariff import (
-    BILLING_TZ, CHECKPOINT_S, NO_RECORD, NOT_OBSERVED, POLICY_MAX,
-    POLICY_NET, POLICY_SUM, PeakStore, PeakTracker, _EUTimezone, billed_w,
-    month_key,
+    BILLING_TZ, CHECKPOINT_S, COUNT_UNREADABLE, NO_RECORD, NOT_OBSERVED,
+    POLICY_MAX, POLICY_NET, POLICY_SUM, PeakStore, PeakTracker, _ClosedBlock,
+    _EUTimezone, billed_w, month_key,
 )
 
 fails = []
@@ -932,18 +943,28 @@ check("the closed quarter reached SQLite through the tracker the cycle calls",
 
 # ⚠️ `cycle()` calls sync() ONCE A SECOND against a `blocks` list that keeps a
 # closed quarter for a DAY. Without a dedupe that is ~86 000 re-banks of the
-# same row per block, and `recorded` - the number the status page prints as
-# "quarters banked" - would be a count of loop iterations rather than of
-# quarters. The database stays correct either way, which is exactly why this
-# needs its own check instead of being caught by the peak.
+# same row per block, and a coverage figure derived from the number of times a
+# block was OFFERED would be a count of loop iterations rather than of quarters.
+# The database stays correct either way, which is exactly why this needs its own
+# check instead of being caught by the peak.
+#
+# ⚠️ GRADED ON `sync()`'s RETURN, and on the STORE's tally for the month the
+# quarter is in - TARIFF-13. It used to be graded on `PeakTracker.recorded`,
+# which was then an `int` incremented inside this very loop, so the dedupe and
+# the figure that reported it were the same variable. They are not any more:
+# `recorded_in()` counts rows in `quarter_blocks`, where re-banking the same
+# `quarter_start` is a PRIMARY KEY no-op and could never have shown up as a
+# second quarter. A check written against it alone would now pass however many
+# times sync() re-banked, which is why the return value is the load-bearing
+# half of this assertion and is asserted first.
 again = c.peak.sync(c.p1)
 third = c.peak.sync(c.p1)
 print(f"    sync() called three times over the same closed quarter: "
-      f"{n}, {again}, {third} newly banked; tracker reports "
-      f"{c.peak.recorded} quarter(s)")
+      f"{n}, {again}, {third} newly banked; the store holds "
+      f"{c.peak.recorded_in(B)} quarter(s) for {month_key(B)}")
 check("...and syncing the same quarter again banks nothing new, so the count "
       "the status page shows is quarters and not cycles",
-      again == 0 and third == 0 and c.peak.recorded == 1)
+      again == 0 and third == 0 and c.peak.recorded_in(B) == 1)
 check("...and the peak is unchanged by the repeat",
       near(c.peak.peak(B).peak_w, 4998.0, 1e-6))
 
@@ -957,11 +978,33 @@ peak_rows = [r for r in rows if "peak" in r["text"] and "quarter(s) banked" in r
 print("    status row: " + (peak_rows[0]["text"] if peak_rows else "(none)"))
 check("the status page carries exactly one capacity-tariff peak row",
       len(peak_rows) == 1)
-check("...naming the peak, the soft limit and the quarters banked, all derived "
+check("...naming the peak, the soft limit and a coverage figure, all derived "
       "from the controller that was actually built",
       bool(peak_rows) and "4998 W" in peak_rows[0]["text"]
       and f"{SHIPPED_CAP_W:.0f} W soft limit" in peak_rows[0]["text"]
-      and "1 quarter(s) banked" in peak_rows[0]["text"])
+      and "quarter(s) banked" in peak_rows[0]["text"])
+
+# ⚠️ AND THE COVERAGE FIGURE IN THAT ROW IS SCOPED TO THE LIVE BILLING MONTH,
+# NOT TO `when` - TARIFF-13, and it is a KNOWN GAP stated rather than rounded
+# off. `main.py`'s row reads `self.peak.recorded`, which answers for
+# `datetime.now()`; the peak beside it follows `when`. The two agree on the
+# ONLY call site a shipped install has - `checks()` with no argument, at
+# main.py:4359 - which is why the live page is correct and durable; they part
+# company only under this suite's `when=` affordance. `PeakTracker` already
+# carries the scoped form, `recorded_in(when)`, and moving the row onto it is a
+# one-token edit inside main.py's status-row block, which TARIFF-11 holds. This
+# check PINS the present behaviour so the gap cannot be forgotten, and part 11
+# is the authority on the figure itself.
+_live_month = month_key(datetime.now(timezone.utc))
+_live_rows = len(c.peak.store.blocks_in(_live_month))
+print(f"    the row read at {month_key(B)} carries the tally for "
+      f"{_live_month} ({_live_rows} quarter(s)), which is this fixture's "
+      f"known scoping gap")
+check("the row's coverage figure is the LIVE month's tally - graded against a "
+      "row count taken straight from quarter_blocks, so this pins the gap "
+      "rather than restating the property that produces it",
+      bool(peak_rows)
+      and f"; {_live_rows} quarter(s) banked" in peak_rows[0]["text"])
 check("...and it is FLAGGED, because 4998 W is over §9.1's 80 % warning point "
       f"on a {SHIPPED_CAP_W:.0f} W limit",
       bool(peak_rows) and not peak_rows[0]["ok"] and peak_rows[0]["warn"])
@@ -1149,6 +1192,308 @@ check(f"...and the same IMPORT grader over main.py finds {_main_imports}, so "
       bool(_main_imports))
 
 
+# ==============================================================================
+print()
+print("11. TARIFF-13: what the instrument says about its OWN COVERAGE, "
+      "across a restart")
+
+# THE DEFECT THIS PART PREVENTS. The status row prints a peak read from SQLite
+# beside a count of banked quarters, and the count used to be an `int` attribute
+# on `PeakTracker` that started at 0 in `__init__`. A 40-hour soak caught what
+# that means at a driven restart, on both instances independently:
+#
+#   before: 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+#           - 10 % of the 3500 W soft limit; 120 quarter(s) banked
+#   after : 2026-09: peak 365 W, set by the quarter at 2026-09-11T18:45:00+00:00
+#           - 10 % of the 3500 W soft limit;   0 quarter(s) banked
+#
+# The peak and its attributed quarter persist; the coverage beside them does
+# not. §9.1's peak is what the utility bills, but the COUNT is what says how
+# much of the billing month the figure covers - 365 W over 120 quarters and
+# 365 W over 0 quarters are different claims about the same watt figure, and
+# after a restart the page made the weaker claim while showing the stronger
+# one's value. TARIFF-01's argument is that an unreadable store must not read as
+# a zero peak because a zero peak is DISARMING; a zero COVERAGE beside a live
+# peak is the same error one column over.
+#
+# ⚠️ THE RESTART HERE IS A REAL ONE - a second `Controller` against the same
+# file on disk, never a re-read of the first object. 11b asserts that the second
+# object has banked nothing itself, so the number it prints cannot have come
+# from process memory. Without that precondition this whole part is satisfied by
+# a counter that was simply never reset.
+
+_T13 = TMP / "t13-restart.db"
+
+# The fixture lives in the month being billed TODAY, and the row is read with NO
+# `when` argument - the LIVE status page, the surface that misinformed. That
+# also makes the check stable on every day of the year, which a fixed calendar
+# date is not (TEST-17, one part up, is the same lesson).
+_now13 = datetime.now(timezone.utc)
+_mon13 = month_key(_now13)
+# Anchor on the first 900 s boundary of the billing month, so all N quarters are
+# inside `_mon13` however close to a month edge the suite happens to run.
+_ms = datetime(int(_mon13[:4]), int(_mon13[5:]), 1, tzinfo=timezone.utc)
+_q0 = datetime.fromtimestamp(
+    (int(_ms.timestamp()) // QUARTER_S + 1) * QUARTER_S, timezone.utc)
+
+_N13 = 6            # > 1, so "count == rows" cannot be satisfied by 0 == 0
+_W13 = 1234.0
+
+c13 = built(_T13)
+for _q in range(_N13):
+    _base = _q0 + timedelta(seconds=QUARTER_S * _q)
+    for _i in range(0, QUARTER_S + 1, 5):
+        c13.p1.submit(sample(_base + timedelta(seconds=_i), _W13))
+    c13.peak.sync(c13.p1)
+
+# Ground truth from the OTHER tier, which the tracker did not supply - the count
+# under test must be graded against something that is not itself (habit 2).
+_truth_before = len(c13.peak.store.blocks_in(_mon13))
+_row_before = _peak_rows(c13.checks())[0]["text"]
+print("    before restart: " + _row_before)
+check(f"precondition: the fixture banked {_N13} quarters in {_mon13}, so a "
+      f"count of 0 and a count of the truth are different numbers",
+      _truth_before == _N13 and _N13 > 1)
+check(f"...and the row says so before the restart",
+      f"{_N13} quarter(s) banked" in _row_before)
+
+c13.peak.store.close()
+
+# THE RESTART.
+c13b = built(_T13)
+_row_after = _peak_rows(c13b.checks())[0]["text"]
+_truth_after = len(c13b.peak.store.blocks_in(_mon13))
+print("    after  restart: " + _row_after)
+print(f"    rows in quarter_blocks: {_truth_before} before, "
+      f"{_truth_after} after; the restarted tracker has banked "
+      f"{len(c13b.peak._seen)} block(s) of its own through sync()")
+
+check("precondition: the second Controller is a REAL restart - it shares no "
+      "object with the first and has banked nothing through sync(), so any "
+      "count it prints came off the disk and not out of memory",
+      c13b.peak is not c13.peak and len(c13b.peak._seen) == 0)
+check("the peak and its attributed quarter survive the restart - the durable "
+      "half, asserted so that the coverage claim below is not graded against a "
+      "reading that had already collapsed",
+      _row_before.split(" - ")[0] == _row_after.split(" - ")[0]
+      and f"{_W13:.0f} W" in _row_after)
+check("...and the COUNT BESIDE IT DOES NOT COLLAPSE TO ZERO, which is the "
+      "defect: a coverage figure that resets while the value beside it "
+      "persists actively misinforms",
+      "; 0 quarter(s) banked" not in _row_after)
+check(f"...and it is the store's own tally, {_truth_after}, not a "
+      f"process-lifetime counter - graded against a COUNT OF ROWS in the "
+      f"other tier rather than against the property under test",
+      f"{_truth_after} quarter(s) banked" in _row_after and _truth_after >= _N13)
+
+# ⚠️ The restarted run banks one MORE than it drove, and that is correct: the
+# checkpointed open block was stale, so `restore()` closed and banked it. The
+# in-memory counter never saw that block at all - it only ever counted what went
+# through `sync()` - so this is a third way the old figure under-read, and it is
+# asserted rather than tolerated. Driven at a chosen `now` so it cannot depend
+# on when the suite runs.
+_t13s = fresh_store("t13-stale")
+_tr13 = PeakTracker(_t13s, cap_w=SHIPPED_CAP_W)
+_av13 = QuarterAverager(phases=1)
+_sb = _q0 + timedelta(seconds=QUARTER_S * 40)
+for _i in range(0, 600, 5):
+    list(_av13.add(sample(_sb + timedelta(seconds=_i), 2000.0)))
+_t13s.save_partial(_av13.snapshot())
+_before_stale = _tr13.recorded_in(_sb)
+_state = _tr13.restore(QuarterAverager(phases=1),
+                       now=_sb + timedelta(seconds=QUARTER_S * 3))
+print(f"    stale-block restore: {_state}")
+print(f"    quarters banked in {month_key(_sb)}: {_before_stale} -> "
+      f"{_tr13.recorded_in(_sb)}")
+check("a block closed by restore() rather than by sync() is counted too - the "
+      "old counter incremented only in sync() and missed it entirely",
+      _before_stale == 0 and _tr13.recorded_in(_sb) == 1
+      and "banked" in _state)
+
+# --- the count is scoped to the MONTH it is printed beside --------------------
+# ⚠️ TWO MONTHS AT DIFFERENT COUNTS. Equal counts would be satisfied by a
+# cross-month total, by a constant, and by reading either month for the other.
+_t13m = fresh_store("t13-months")
+_MA = datetime(2026, 4, 6, 9, 0, tzinfo=timezone.utc)      # 2026-04
+_MB = datetime(2026, 5, 6, 9, 0, tzinfo=timezone.utc)      # 2026-05
+_trm = PeakTracker(_t13m, cap_w=SHIPPED_CAP_W)
+for _m, _k in ((_MA, 3), (_MB, 5)):
+    for _q in range(_k):
+        _t13m.record_block(_ClosedBlock(
+            start=_m + timedelta(seconds=QUARTER_S * _q),
+            offtake_avg_w=900.0 + _q, per_phase_offtake_avg_w=None))
+print(f"    banked by month: {month_key(_MA)}={_trm.recorded_in(_MA)}, "
+      f"{month_key(_MB)}={_trm.recorded_in(_MB)}, "
+      f"a month never written={_trm.recorded_in(datetime(2026, 7, 6, 9, 0, tzinfo=timezone.utc))}")
+check("precondition: the two months were given DIFFERENT numbers of quarters, "
+      "so a count that answered either one for the other would be visible here",
+      month_key(_MA) != month_key(_MB))
+check("each month reports ITS OWN quarters and not the pair's total - the old "
+      "counter was per PROCESS, so on 1 October the row still showed "
+      "September's tally beside October's empty month",
+      _trm.recorded_in(_MA) == 3 and _trm.recorded_in(_MB) == 5)
+check("...and a month with no quarters reports 0, which is TRUE of a month "
+      "nothing was written to - the sentinel below is for a store that will "
+      "not answer, and the two states must not be spelled the same way",
+      _trm.recorded_in(datetime(2026, 7, 6, 9, 0, tzinfo=timezone.utc)) == 0)
+
+# --- and a store that cannot answer does NOT report zero ----------------------
+# The other half of part 5's argument, applied to the coverage figure. `0
+# quarter(s) banked` and `an unreadable number of quarter(s) banked` are
+# opposite states: the first says the month has been measured over nothing, the
+# second says the instrument cannot say. Spelling them the same way is exactly
+# what this card was raised about.
+_t13u = PeakStore(str(TMP / "no-such-dir" / "nope13.db"))
+_tru = PeakTracker(_t13u, cap_w=SHIPPED_CAP_W)
+print(f"    unreadable store: banked_count -> {_t13u.banked_count(_mon13)!r}, "
+      f"rendered -> {_tru.recorded_in(_now13)!r}")
+check("an unreadable store answers None to a COUNT, never 0 - the store-level "
+      "half",
+      _t13u.banked_count(_mon13) is None)
+check("...and the rendered figure says it is unreadable instead of naming a "
+      "number, so the sentence cannot read as a measured zero",
+      _tru.recorded_in(_now13) == COUNT_UNREADABLE
+      and f"{_tru.recorded_in(_now13)} quarter(s) banked"
+          == "an unreadable number of quarter(s) banked")
+check("...and that sentence is not merely NON-zero by accident: the string a "
+      "count of 0 would produce is different text",
+      f"{_tru.recorded_in(_now13)} quarter(s) banked"
+      != f"{0} quarter(s) banked")
+
+# ⚠️ A STORE THAT IS OPEN AND WHOSE COUNT QUERY FAILS IS A SECOND CODE PATH, and
+# the checks above cannot reach it - a handle that never opened short-circuits
+# on `self._db is None` before any SQL runs, so `banked_count()`'s
+# `except sqlite3.Error` arm was executed by nothing. Found by this card's own
+# mutation battery, not by review: returning 0 instead of None from that arm
+# survived the whole suite at -3 B. It is the same third-path argument part 5
+# makes for `peak()`, and it is the arm a half-corrupt database on a real
+# install actually takes.
+_t13b = fresh_store("t13-broken")
+for _q in range(4):
+    _t13b.record_block(_ClosedBlock(start=_q0 + timedelta(seconds=QUARTER_S * _q),
+                                    offtake_avg_w=800.0 + _q,
+                                    per_phase_offtake_avg_w=None))
+_trb = PeakTracker(_t13b, cap_w=SHIPPED_CAP_W)
+_count_ok = _t13b.banked_count(_mon13)
+_t13b._db.execute("DROP TABLE quarter_blocks")
+_t13b._db.commit()
+_count_broken = _t13b.banked_count(_mon13)
+print(f"    open store, count query FAILS: {_count_ok} -> {_count_broken!r}, "
+      f"rendered -> {_trb.recorded_in(_now13)!r}")
+check(f"precondition: before the table was dropped the same call answered "
+      f"{_count_ok}, so 'it returns nothing now' is a change and not the "
+      f"store's resting state",
+      _count_ok == 4)
+check("a store whose COUNT QUERY fails answers None too - a different code "
+      "path from a handle that never opened, and the one a half-corrupt "
+      "database takes",
+      _count_broken is None)
+check("...and it renders as unreadable rather than as 0, so a half-corrupt "
+      "database cannot print a coverage figure that reads like a measured "
+      "month with nothing in it",
+      _trb.recorded_in(_now13) == COUNT_UNREADABLE)
+
+# --- the count reads the BLOCK tier, not the month tier -----------------------
+# `monthly_peak` holds one row per MONTH, so counting it answers 1 for every
+# month that has ever been measured - a figure that is wrong by exactly the
+# amount that makes it look plausible.
+check("the coverage figure counts quarter_blocks and not monthly_peak, which "
+      "would answer 1 for every measured month however many quarters it holds",
+      _trm.recorded_in(_MB) == 5
+      and _t13m.peak(_MB).is_observed and _t13m.recompute_month(month_key(_MB)).is_observed)
+
+
+# ==============================================================================
+print()
+print("12. TARIFF-13: which quarter a TIED peak is attributed to")
+
+# THE DECISION, recorded in DECISIONS/TARIFF-13-the-coverage-of-a-peak.md §2:
+# at equal wattage the EARLIEST quarter keeps the attribution. The wattage is
+# what is billed, so this is not a money question - it is the answer to "when
+# did my monthly peak happen", and an operator investigating that goes and looks
+# at one event. A stable answer is the useful one; "most recent wins" guarantees
+# the answer moves every time the wattage recurs.
+#
+# ⚠️ AND THE SOAK'S DRIFT WAS NOT A TIE. The 40-hour run showed 365 W attributed
+# to three different quarters with no restart and no new peak, and the obvious
+# reading - "ties re-attribute to the most recent" - is false, measured: the
+# upsert's term is strictly `>`, so an exact tie never wrote. What moved was a
+# genuine new maximum SMALLER THAN THE ROW'S OWN RESOLUTION. The row renders
+# `{peak_w:.0f}`, whole watts; 365.0000001 W is a new peak to the database and
+# the same "365 W" to the reader. Both cases are pinned below, because the fix
+# for one is not the fix for the other.
+
+_t13t = fresh_store("t13-ties")
+_TB = datetime(2026, 3, 9, 9, 0, tzinfo=timezone.utc)
+
+
+def _bank(store, q, w):
+    store.record_block(_ClosedBlock(start=_TB + timedelta(seconds=QUARTER_S * q),
+                                    offtake_avg_w=w, per_phase_offtake_avg_w=None))
+
+
+def _qt(n):
+    return _TB + timedelta(seconds=QUARTER_S * n)
+
+
+for _q in (0, 1, 2, 3):
+    _bank(_t13t, _q, 365.0)
+_asc = _t13t.peak(_TB)
+print(f"    four EXACTLY equal 365 W quarters, oldest first -> attributed "
+      f"{_asc.quarter_start.isoformat()}")
+check("an exact tie keeps the EARLIEST quarter: the attribution does not move "
+      "when the same wattage recurs",
+      _asc.quarter_start == _qt(0) and near(_asc.peak_w, 365.0))
+
+# ⚠️ FED NEWEST-FIRST, which is what separates "the earliest quarter" from
+# "whichever row was written first". Ascending arrival cannot tell those apart -
+# they are the same row - so an ascending-only fixture grades neither.
+_t13r = fresh_store("t13-ties-rev")
+for _q in (3, 2, 1, 0):
+    _bank(_t13r, _q, 365.0)
+_desc = _t13r.peak(_TB)
+_desc_rc = _t13r.recompute_month(month_key(_TB))
+print(f"    the same four fed NEWEST first -> monthly_peak attributed "
+      f"{_desc.quarter_start.isoformat()}, recompute_month attributed "
+      f"{_desc_rc.quarter_start.isoformat()}")
+check("...and it is the earliest QUARTER, not the first row WRITTEN - fed "
+      "newest-first the answer is still the oldest quarter",
+      _desc.quarter_start == _qt(0))
+check("...and BOTH readers give it, so the derived record has not diverged "
+      "from the tier it derives from on the tie rule either (part 8's "
+      "invariant, at equal wattage)",
+      _desc_rc.quarter_start == _desc.quarter_start
+      and near(_desc_rc.peak_w, _desc.peak_w))
+
+# The other direction, and the reason the tie rule may never touch `peak_w`: a
+# STRICTLY HIGHER quarter must still take the attribution, whenever it arrives.
+_t13h = fresh_store("t13-higher")
+for _q, _w in ((0, 365.0), (1, 366.0), (2, 365.0)):
+    _bank(_t13h, _q, _w)
+_hi = _t13h.peak(_TB)
+print(f"    365, then 366, then 365 -> peak {_hi.peak_w:.0f} W at "
+      f"{_hi.quarter_start.isoformat()}")
+check("a strictly higher quarter still takes both the peak and the "
+      "attribution - the tie rule moves the TIMESTAMP and never the watts",
+      near(_hi.peak_w, 366.0) and _hi.quarter_start == _qt(1))
+
+# And the mechanism the soak actually saw: an increase below the row's own
+# resolution. Not a tie, and no tie rule can address it.
+_t13d = fresh_store("t13-subdisplay")
+_seen13 = []
+for _q, _w in enumerate((365.0, 365.0000001, 365.0000002)):
+    _bank(_t13d, _q, _w)
+    _seen13.append(_t13d.peak(_TB).quarter_start)
+print(f"    365.0, 365.0000001, 365.0000002 W all render "
+      f"{_t13d.peak(_TB).peak_w:.0f} W and attribute to "
+      f"{[s.time().isoformat() for s in _seen13]}")
+check("an increase BELOW the row's whole-watt resolution is a real new maximum "
+      "and does move the attribution - so the soak's drifting quarter was a "
+      "rounded display, not a tie, and is left alone deliberately",
+      len(set(_seen13)) == 3
+      and len({f"{w:.0f}" for w in (365.0, 365.0000001, 365.0000002)}) == 1)
+
+
 # ==============================================================================
 print()
 shutil.rmtree(TMP, ignore_errors=True)

goodwe_controller/test_translations.py

@@ -362,7 +362,7 @@ print("\n7. no behaviour and no value moved")
 # test_peakguard.py's. This line is the cheap one that says the reorder did not
 # lose or duplicate a key on the way.
 check("no option was lost, gained or duplicated by the reordering: the two "
-      "halves of config.yaml hold the same 71 keys, once each",
+      "halves of config.yaml hold the same 72 keys, once each",
       sorted(_opt_order) == sorted(ORDER) and len(set(ORDER)) == len(ORDER))
 check("...and `inverters: []` is still shipped in the options half, which is "
       "what Supervisor 2026.08.0 refuses every pre-0.6.0 options blob without "

goodwe_controller/translations/en.yaml

@@ -3,8 +3,8 @@
 # ⚠️ WHAT THIS FILE IS FOR, AND WHAT HOME ASSISTANT ACTUALLY DOES WITH IT.
 # Without a `translations/` directory the Configuration tab renders the raw
 # option KEYS - `unit_sign_disagree_w`, `saturation_cycles`, `integrator_max_w`.
-# The frontend keeps a field when `e.name in options || e.required`, and all 71
-# keys are in `options:` (59 of them are `required` as well), so ALL SEVENTY-ONE are
+# The frontend keeps a field when `e.name in options || e.required`, and all 72
+# keys are in `options:` (59 of them are `required` as well), so ALL SEVENTY-TWO are
 # rendered, always, in `schema:` order, with no description. This file is what
 # turns that into sentences.
 #
@@ -143,10 +143,10 @@ configuration:
     description: "DERIVED, not picked (SAFETY-24): the reference pack holds 13.8 kWh usable and the worst modelled peak-shaving day asks for 878 Wh, which is 6.4 %, so 20 % sits ten points above the pack's own cut-out and still leaves the guard about 1.6 of its worst observed days of room. ⚠️ IT BOUNDS THE PEAK GUARD ONLY. It is not a reserve for the whole pack: ordinary self-consumption discharges straight past it and goes on down to the battery cut-out, and raising this number does not change that by a tenth of a percent. It must stay strictly above the battery cut-out or the add-on refuses to start. Do not change it without re-deriving it."
   price_provider:
     name: "Tariff · Dynamic price source"
-    description: "Where day-ahead or real-time prices come from. 'off' is what ships, and means this site runs on the static tariff below with no trading. ⚠️ SWITCHING THIS ON IS WHAT STARTS THE PRICE FETCH - not the trading switch further down. With a source selected the add-on fetches the feed every half hour, checks it, records the day and shows what it holds on the Price history row, whether or not price trading is armed. On its own it still moves no energy: trading is the separate switch, and the cheap window the monthly maintenance cycle uses comes from the fixed or day/night tariff below. It may not be combined with the two legacy Home Assistant price entities further down: two price sources on one site, one of which silently wins, is refused at startup rather than left looking armed."
+    description: "Where day-ahead or real-time prices come from. 'off' is what ships, and means this site runs on the static tariff below with no trading. ⚠️ SWITCHING THIS ON IS WHAT STARTS THE PRICE FETCH - not the trading switch further down. With a source selected the add-on fetches the feed every half hour, checks it, records the day and shows what it holds on the Price history row, whether or not price trading is armed. On its own it still moves no energy: trading is the separate switch, and the cheap window the monthly maintenance cycle uses comes from the fixed or day/night tariff below. It may not be combined with the two legacy Home Assistant price entities further down: two price sources on one site, one of which silently wins, is refused at startup rather than left looking armed. ⚠️ THREE IDS IN THIS LIST ARE WITHDRAWN AND WILL NOT START: engie_dynamic, totalenergies_dynamic and eneco_eddy. Their endpoints do not exist and never did, so those plugins never once fetched a price - a site set to one of them has silently been running on the fixed or day/night tariff below, or on nothing, since the day it was set. They are still offered here only so that such a site gets that explanation at startup instead of an unreadable schema error. Choose generic_dayahead for the wholesale curve with a flat markup, custom_formula to enter your own contract's B x index + A coefficients off your tariff card, manual_csv for a file you write yourself, or off."
   price_markup_eur_kwh:
     name: "Tariff · Supplier markup (EUR/kWh)"
-    description: "Your supplier's margin. The add-on adds it ONLY when the chosen price source does not already include it - under engie_dynamic, totalenergies_dynamic, eneco_eddy and manual_csv it is ignored, and logged as ignored, never applied twice."
+    description: "Your supplier's margin. The add-on adds it ONLY when the chosen price source does not already include it - under manual_csv, whose figures are all-in, it is ignored, and logged as ignored, never applied twice."
   price_taxes_eur_kwh:
     name: "Tariff · Levies and VAT (EUR/kWh)"
     description: "Taxes and levies per kWh, added under the same rule as the supplier markup: only when the chosen price source does not already carry them."
@@ -156,6 +156,9 @@ configuration:
   static_profile:
     name: "Tariff · Fixed or day/night tariff (one line of JSON)"
     description: "Your fixed or day/night contract, written as a single line of JSON. RECOMMENDED EVEN ON A DYNAMIC CONTRACT: this is what the add-on falls back to when the price feed dies, and with it empty a dead feed leaves the site with no tariff at all. The periods must cover every day type exactly once, with no gap and no overlap - a gap is refused at startup rather than filled in, because an invented price is one a strategy would trade on. A fully fixed tariff is one period covering 00:00-24:00 on all days. Prices are ALL IN; the markup and levies above are not added to them. Note that a window written 22:00-07:00 for mon-fri does NOT cover Saturday morning, so a weekend row is required rather than decorative."
+  price_formula:
+    name: "Tariff · Your own tariff formula (one line of JSON)"
+    description: "For price source custom_formula only: your own contract's two coefficients, written as a single line of JSON. Your supplier's tariff card prints the formula as B x index + A - those two numbers exist only on your card, there is no public index of them anywhere, and you are the only person who can read them. Type what the card prints, IN THE UNITS THE CARD PRINTS: every unit conversion and the VAT step are the add-on's job, because those are the two places a human silently loses a factor of 10, 100 or 1.06. Example: {\"index\":\"epex_be\",\"resolution\":\"hourly\",\"factor\":0.102,\"offset\":1.00,\"units\":\"c_eur_per_kwh\",\"vat_pct\":6,\"card\":{\"month\":\"2026-09\",\"index_eur_per_mwh\":133.9905,\"expect_incl_vat\":15.55}}. ⚠️ THE card BLOCK IS REQUIRED AND IT IS WHAT MAKES THIS SAFE: your card also prints the reference index it assumed and the price that comes out, so the add-on recomputes that price from your numbers and REFUSES TO START if it does not come out, telling you by how much. That catches a wrong unit, VAT left out or counted twice, a transposed digit, and the expensive one - network charges folded into the offset, which the add-on would then bill you for a second time. ⚠️ AND ITS LIMIT, IN THE SAME BREATH: it checks your coefficients against your card, not your card against reality, so two numbers copied off the wrong product agree with each other and pass. Fixed numbers only - no expression of any kind is evaluated, and an unrecognised field is refused rather than ignored."
   price_csv_path:
     name: "Tariff · Price CSV file"
     description: "For price source manual_csv only: where in /share the add-on reads your own price file from."

goodwe_controller/translations/nl.yaml

@@ -123,10 +123,10 @@ configuration:
     description: "AFGELEID, niet gekozen (SAFETY-24): de referentiebatterij heeft 13,8 kWh bruikbaar en de zwaarste doorgerekende afvlakdag vraagt 878 Wh, oftewel 6,4 %, dus 20 % ligt tien punten boven de uitschakelgrens van de batterij zelf en laat de bewaking nog ongeveer 1,6 van haar zwaarste waargenomen dagen speling. ⚠️ DIT BEGRENST ALLEEN DE PIEKBEWAKING. Het is geen reserve voor de hele batterij: gewoon eigenverbruik ontlaadt er dwars doorheen en gaat door tot aan de uitschakelgrens van de batterij, en dit getal verhogen verandert daar geen tiende procent aan. Het moet strikt boven de uitschakelgrens van de batterij blijven, anders start de add-on niet op. Verander het niet zonder de afleiding opnieuw te maken."
   price_provider:
     name: "Tarief · Bron van dynamische prijzen"
-    description: "Waar day-ahead- of realtimeprijzen vandaan komen. 'off' is de standaardinstelling en betekent dat deze installatie op het vaste tarief hieronder draait, zonder handel. ⚠️ DIT AANZETTEN IS WAT HET OPHALEN VAN PRIJZEN START - niet de handelsschakelaar verderop. Met een bron ingesteld haalt de add-on de feed elk half uur op, controleert die, bewaart de dag en toont op de rij Prijsgeschiedenis wat er bewaard is, of prijshandel nu aan staat of niet. Op zichzelf verplaatst dat nog geen energie: handelen is de aparte schakelaar, en het goedkope venster dat de maandelijkse onderhoudscyclus gebruikt komt uit het vaste of dag/nacht-tarief hieronder. Het mag niet gecombineerd worden met de twee oude Home Assistant-prijsentiteiten verderop: twee prijsbronnen op één installatie, waarvan er stilzwijgend één wint, wordt bij het opstarten geweigerd in plaats van schijnbaar actief gelaten."
+    description: "Waar day-ahead- of realtimeprijzen vandaan komen. 'off' is de standaardinstelling en betekent dat deze installatie op het vaste tarief hieronder draait, zonder handel. ⚠️ DIT AANZETTEN IS WAT HET OPHALEN VAN PRIJZEN START - niet de handelsschakelaar verderop. Met een bron ingesteld haalt de add-on de feed elk half uur op, controleert die, bewaart de dag en toont op de rij Prijsgeschiedenis wat er bewaard is, of prijshandel nu aan staat of niet. Op zichzelf verplaatst dat nog geen energie: handelen is de aparte schakelaar, en het goedkope venster dat de maandelijkse onderhoudscyclus gebruikt komt uit het vaste of dag/nacht-tarief hieronder. Het mag niet gecombineerd worden met de twee oude Home Assistant-prijsentiteiten verderop: twee prijsbronnen op één installatie, waarvan er stilzwijgend één wint, wordt bij het opstarten geweigerd in plaats van schijnbaar actief gelaten. ⚠️ DRIE IDS IN DEZE LIJST ZIJN INGETROKKEN EN STARTEN NIET MEER: engie_dynamic, totalenergies_dynamic en eneco_eddy. Hun endpoints bestaan niet en hebben nooit bestaan, dus die plugins hebben nooit één prijs opgehaald - een installatie die op zo'n bron stond, draait sindsdien stilzwijgend op het vaste of dag/nacht-tarief hieronder, of op niets. Ze staan hier alleen nog zodat zo'n installatie bij het opstarten die uitleg krijgt in plaats van een onleesbare schemafout. Kies generic_dayahead voor de groothandelscurve met een vaste marge, custom_formula om de coëfficiënten B x index + A van uw eigen contract van uw tariefkaart over te typen, manual_csv voor een bestand dat u zelf schrijft, of off."
   price_markup_eur_kwh:
     name: "Tarief · Marge van de leverancier (EUR/kWh)"
-    description: "De marge van uw energieleverancier. De add-on telt die ALLEEN op wanneer de gekozen prijsbron ze niet al bevat - bij engie_dynamic, totalenergies_dynamic, eneco_eddy en manual_csv wordt ze genegeerd, en dat wordt ook gelogd, zodat ze nooit dubbel wordt aangerekend."
+    description: "De marge van uw energieleverancier. De add-on telt die ALLEEN op wanneer de gekozen prijsbron ze niet al bevat - bij manual_csv, waarvan de bedragen alles inbegrepen zijn, wordt ze genegeerd, en dat wordt ook gelogd, zodat ze nooit dubbel wordt aangerekend."
   price_taxes_eur_kwh:
     name: "Tarief · Heffingen en btw (EUR/kWh)"
     description: "Belastingen en heffingen per kWh, opgeteld volgens dezelfde regel als de marge: alleen wanneer de gekozen prijsbron ze nog niet bevat."
@@ -136,6 +136,9 @@ configuration:
   static_profile:
     name: "Tarief · Vast of dag/nacht-tarief (één regel JSON)"
     description: "Uw vaste of dag/nacht-contract, geschreven als één regel JSON. AANBEVOLEN ZELFS BIJ EEN DYNAMISCH CONTRACT: hierop valt de add-on terug wanneer de prijsfeed uitvalt, en staat dit leeg dan blijft de installatie bij een dode feed helemaal zonder tarief achter. De periodes moeten elk dagtype precies één keer bedekken, zonder gat en zonder overlap - een gat wordt bij het opstarten geweigerd in plaats van opgevuld, want een verzonnen prijs is er één waarop een strategie zou handelen. Een volledig vast tarief is één periode van 00:00 tot 24:00 op alle dagen. De prijzen zijn ALLES INBEGREPEN; de marge en heffingen hierboven worden er niet bij opgeteld. Let op: een venster van 22:00 tot 07:00 voor ma-vr dekt zaterdagochtend NIET, dus een regel voor het weekend is noodzakelijk en niet decoratief."
+  price_formula:
+    name: "Tarief · Uw eigen tariefformule (één regel JSON)"
+    description: "Alleen voor prijsbron custom_formula: de twee coëfficiënten van uw eigen contract, als één regel JSON. De tariefkaart van uw leverancier drukt de formule af als B x index + A - die twee getallen staan alleen op uw kaart, er bestaat nergens een publieke lijst van, en u bent de enige die ze kan lezen. Typ wat de kaart afdrukt, IN DE EENHEID DIE DE KAART GEBRUIKT: elke eenheidsomrekening en de btw-stap zijn het werk van de add-on, want dat zijn precies de twee plaatsen waar een mens stilzwijgend een factor 10, 100 of 1,06 verliest. Voorbeeld: {\"index\":\"epex_be\",\"resolution\":\"hourly\",\"factor\":0.102,\"offset\":1.00,\"units\":\"c_eur_per_kwh\",\"vat_pct\":6,\"card\":{\"month\":\"2026-09\",\"index_eur_per_mwh\":133.9905,\"expect_incl_vat\":15.55}}. ⚠️ HET BLOK card IS VERPLICHT EN MAAKT DIT VEILIG: uw kaart vermeldt ook de referentie-index die ze veronderstelt en de prijs die eruit volgt, dus de add-on berekent die prijs opnieuw uit uw getallen en START NIET als het resultaat niet klopt - met vermelding van het verschil. Dat vangt een verkeerde eenheid, btw die ontbreekt of dubbel geteld is, een omgewisseld cijfer, en de dure fout: nettarieven die in de offset verwerkt zitten en die de add-on er dan nog een tweede keer bovenop zou rekenen. ⚠️ EN DE GRENS DAARVAN, IN DEZELFDE ZIN: ze toetst uw coëfficiënten aan uw kaart, niet uw kaart aan de werkelijkheid - twee getallen van het verkeerde product kloppen onderling en komen er dus door. Alleen vaste getallen: er wordt geen enkele expressie geëvalueerd, en een onbekend veld wordt geweigerd in plaats van genegeerd."
   price_csv_path:
     name: "Tarief · CSV-bestand met prijzen"
     description: "Alleen voor prijsbron manual_csv: waar in /share de add-on uw eigen prijsbestand leest."