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

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 was 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. (Annotated 2026-09-13: TARIFF-18 raised the default to 0.11736, nearly six times the floor. The asymmetry is unchanged in kind and larger in degree — the flat addend that carries a hundredfold-small card over 0.02 got bigger.)

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. (Annotated 2026-09-13: that card is TARIFF-18 and it shipped on this branch at 0.11736 — the Eneco residential card for Flanders, September 2026, incl. 6 % VAT, summed from Fluvius Antwerpen distribution 5,35 + bijzondere accijns 4,876 + bijdrage groene stroom en WKK 1,51 c€/kWh. §3b held: the floor is still on the energy figure and nothing in this module needed a new number.)