TARIFF-15: your own tariff card, as two coefficients the card itself grades

A Belgian dynamic contract prices energy as `B x index + A`, and the two
coefficients exist on exactly one artefact: the customer's own tariff card.
There is no machine-readable source for them anywhere - CREG's consumer
tariff-card pages 404, CREG Scan is a JS wizard, the annual report has 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 nothing can be scraped and a per-supplier plugin would have no
source for its numbers, which is why TARIFF-07 withdrew three of them. The
customer is the only party who can see their own coefficients; they type them.

New provider `custom_formula`, one new option `price_formula` (a JSON string,
the `static_profile` precedent exactly), and a new module
`app/custom_formula.py`. The index path is `generic_dayahead`'s, not a second
one: the URL/override decision is now one shared `dayahead_feed_url()` both
plugins call, same feed, same Brussels-calendar range, same columnar parser,
same declared egress hosts.

It declares {ENERGY, MARKUP}, NOT ALL_IN. A card's Tariefformule line is the
energy component alone - Eneco tabulates network tariffs and levies
separately, ENGIE states the formula excludes network, distribution,
transport, levies and excise - so ALL_IN would lie for every operator who
typed what their card says and would drop the taxes from every hour
(0.2125 -> 0.1555 EUR/kWh, measured).

THE CARD IS THE GRADER, and that is why this is safe to ship. The framework
already mechanises that a PLUGIN cannot double-count. This introduces a risk
none of those guards 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 validate.py recomputes the card's own
printed price from the operator's coefficients at startup and refuses to start
unless the two agree to within 0.01, naming the discrepancy. An inflated
offset cannot pass: 15.55 becomes 28.27. The same check catches VAT omitted,
VAT doubled, a transposed digit and a unit mismatch between the two sides.

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
passes. A second refusal covers the one unit error the first cannot see - the
one applied to both sides at once - by bounding the card's own point to
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 alone; found by writing the mutation,
not by review (M10, +0 B).

The market's own arithmetic, reproduced through the shipped code:

  Eneco (0.102 x 133.9905 + 1) x 1.06 = 15.5471   card prints 15,55
  ENGIE (0.1   x  61.96   + 0.9) x 1.06 = 7.5218  card prints 7,522

NO EXPRESSION EVALUATION OF ANY KIND. The string is settable over HTTP through
the add-on's own ingress page, so eval on it is RCE in a root container
holding SUPERVISOR_TOKEN and driving an inverter over RS485 - but the deciding
argument is that an expression is UNVERIFIABLE: two coefficients can be graded
against the card, an arbitrary expression cannot be graded against anything,
so it would make the invisible-wrong-coefficient problem strictly worse. An
unknown field is REFUSED rather than ignored, so `"expr"` is told it does not
exist. Future shapes become named fields, never a grammar. test_price.py 15f
walks the module's AST for eval/exec/compile/__import__/literal_eval and
exercises the scanner's red direction on every run.

Refused at startup: card absent or out by >0.01; `units` absent (no default);
factor == 0 (every spread 0, arbitrage silently never fires - the message
points at static_profile); factor < 0 (inverts the market); vat_pct outside
0-30 (0 stays legitimate); non-finite or non-numeric; unknown field, index or
resolution; the plausibility band. A card older than ~6 months WARNS and does
not refuse - ENGIE freezes coefficients for a contract's duration. Negative
output prices are not refused anywhere.

A startup preview logs the next 24 h as `index EUR/MWh -> all-in EUR/kWh` with
min/median/max and the day's spread, through a new default-silent
`PriceProvider.startup_preview()` hook - only the plugin knows what went in to
its own arithmetic. Emitted once per process, and a preview that raises cannot
cost the site its prices.

`custom_formula` joins the config.yaml enum through the DERIVED set
PROVIDERS | RETIRED_PROVIDERS | {"off"}, not a hardcoded 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, a real
startup transcript and the limit of the check stated beside the claim.

22 mutations, one per check added, no survivors - MUTATION.md carries the
ledger. M13 (the preview's index column) was a -13 B survivor of the whole
suite on the first attempt because the check graded the HEADING and not the
row; it is graded on a rendered row now. All 29 suites green.

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

goodwe_controller/config.yaml

@@ -286,6 +286,9 @@ options:
   # the FRAMEWORK, only for the components the chosen plugin declares its feed
   # 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
@@ -324,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
@@ -782,7 +833,7 @@ schema:
   # 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|engie_dynamic|totalenergies_dynamic|eneco_eddy|manual_csv)
+  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)
 
@@ -796,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)