Merge release/1.0 (TARIFF-01) into TARIFF-02

TARIFF-01 (#17) landed on release/1.0 first, so this branch was two
commits behind and Gitea reported the PR unmergeable. Integrating rather
than rebasing: the two reviewed commits stay addressable, and the branch
is protected against force-push anyway.

ONE CONFLICT, AND IT IS THE BORING HALF OF THE ONE REVIEW PREDICTED.
Review of #16 expected collisions in four places - the tail of
`options:`, the tail of `schema:`, the rule list inside
validate_startup_config(), and the tail of validate.py. None of them
happened: TARIFF-01 touched neither config.yaml nor validate.py. It
added app/tariff.py, test_tariff.py, two P1 scenario captures, and edits
to main.py and p1.py, none of which this branch goes near.

The only conflict was CHANGELOG.md, where both branches prepended a
block under the same `## Unreleased` heading. Both blocks kept, TARIFF-02
above TARIFF-01 since it lands second. Nothing was dropped or reworded on
either side, and the resolution adds no line of its own beyond the blank
one between them.

Checked rather than assumed after the merge:
  - all ELEVEN test files pass, including TARIFF-01's own test_tariff.py
    (which this branch had never run) and the 93 s test_loop.py;
  - the 24-mutation battery still has 0 survivors;
  - no semantic overlap in config: TARIFF-01's peak tracker reads the
    peak_cap_w / peak_forecast_entity options that already existed, so
    the price options added here neither shadow nor duplicate anything.

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

goodwe_controller/CHANGELOG.md

@@ -2,6 +2,85 @@
 
 ## Unreleased
 
+**Price provider plugins, and one canonical all-in price format (TARIFF-02).**
+`app/price.py` ships five providers - `generic_dayahead` (wholesale EPEX BE),
+`engie_dynamic`, `totalenergies_dynamic`, `eneco_eddy` and the offline
+`manual_csv` - all emitting exactly `{"prices": [{"start", "eur_per_kwh",
+"provisional"}]}`, tz-aware at the Brussels offset, EUR/kWh, all-in. **Nothing
+consumes it yet**: this is the seam, landed first, so that the arbitrage work
+that follows never learns a supplier's name.
+
+**Double-counting the markup is refused rather than discouraged, given a
+correct declaration.** A plugin does not return a price; it returns the figure
+its source published and declares which of {energy, markup, taxes} that figure
+contains. The framework adds the complement, once. Engie and TotalEnergies
+publish a retail figure with their margin already inside; adding the configured
+3 c/kWh on top would make every future arbitrage decision wrong by that amount
+with nothing reporting it.
+
+Two mechanisms, because one was not enough. `PluginOptions` raises on the
+framework-owned keys - and review of PR #16 then wrote a double-counting plugin
+three more ways, one of them touching nothing but `PRICE_OPTION_DEFAULTS`, a
+public dict in the module every plugin already imports. So `register()` now also
+**refuses at import any plugin whose own code mentions a framework key**
+(`code_leaks()`, docstrings stripped via `ast` so a plugin's mandated
+`SOURCES:` line does not false-positive). Honest wholesale baseline 0.188
+EUR/kWh; every attack landed 0.219.
+
+**The guarantee's precise shape**, stated because an overclaim is worse than no
+claim: the framework adds the complement exactly once *given a correct `sources`
+declaration*. A plugin that declares `{energy}` while its feed is really all-in
+still comes out one markup high while touching no framework name, and no code
+can catch that - the declaration is the plugin's unverifiable claim about
+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.**
+`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
+mechanically that no plugin id appears anywhere in the framework's own code,
+and drives a sixth provider defined inside the test file to the correct regime
+with `price.py` untouched.
+
+**"No price data" is a type, not an empty list.** Following the same rework
+`sim/riglock.py` took, a fetch returns `PriceRead.series(...)` or
+`PriceRead.no_data(reason)`, and only the first carries fields. An empty series
+is not constructible; `no_data` has no `.points` to iterate, no `.at()`, and
+`.get("points", [])` raises rather than returning the default. **A day of free
+electricity and a day with no prices are different instructions** - arbitrage is
+pointless under the first and forbidden under the second - and an implementation
+that returns `[]` on a failed fetch cannot tell them apart. Every site-level
+failure returns `no_data`; nothing raises into the control tick.
+
+**What is not verified, and cannot be by an offline suite:** every fixture is
+synthetic, so the five feed URLs and JSON shapes are checked against a belief
+about what those suppliers publish, not against the feeds. The parse layer is
+exercised; the contract with each supplier is not. Expect the first live fetch
+of each to need a shape fix, and note that a wrong shape degrades to
+no-price-data rather than to a wrong price.
+
+**`manual_csv` is the documented offline fallback** and needs no network, no
+supplier account and no HTTP stack. See DOCS.md for the format. Its `start`
+column must carry a UTC offset - a bare local timestamp is refused, because one
+hour every October names two moments.
+
+**Injection is priced separately** (`export_price_eur_kwh`), a scalar rather
+than a second series, and negative values are accepted. Consumption plugins
+cannot reach it.
+
+**`price_provider` may not be combined with `price_now_entity` /
+`price_avg_entity`** - the add-on refuses to start on that pair. The Home
+Assistant sensors are the existing delegation of pricing to HA and still work
+alone; with both configured they would silently keep deciding while the status
+page named a supplier that decided nothing.
+
+**No timezone database is used.** The shipped Alpine image has no `tzdata`, so
+Brussels offsets are computed from the EU rule and every instant is carried as
+UTC and rendered at the offset that applies to it. The checks drive both 2026
+transitions - the 23-hour and 25-hour days - rather than a normal day, where a
+fixed 24-slot implementation and a correct one agree.
+
 **The capacity-tariff peak is now measured, banked and survives a restart
 (TARIFF-01).** New `app/tariff.py`. The 15-minute block average itself was
 already built and unwired - `p1.QuarterAverager` computes clock-aligned 900 s

goodwe_controller/DOCS.md

@@ -581,6 +581,97 @@ unchanged is 12 W, which is inside the 15 W deadband — so the command there is
 parked at 0 W and the two halves of the rule cannot both be true. At the schema
 floor of 60 s that figure is 60 W and only the margin is left.
 
+### Energy price providers
+
+> **Nothing in 0.5.x acts on a price.** This release ships the *plumbing*: the
+> five provider plugins, the canonical all-in format they emit, and the config
+> that selects one. The arbitrage strategy that would use it is a later ticket.
+> Turning a provider on today fetches, validates and publishes prices and
+> changes no charging decision. That is deliberate — the seam lands first.
+
+| option | meaning |
+|---|---|
+| `price_provider` | `off` (default) or one of the five 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 |
+| `price_csv_path` | Where `manual_csv` reads its file |
+| `price_feed_url` | Override the plugin's default feed. Only a host the plugin itself declares is accepted |
+| `price_horizon_h` | How far ahead to ask for, hours |
+| `price_timeout_s` | Per-request timeout |
+
+**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
+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 |
+| `manual_csv` | day-ahead | everything, all-in | nothing |
+
+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**
+— never applied twice.
+
+That holds **given a correct declaration**, and it is worth knowing where the
+line is. What the add-on enforces mechanically is that a plugin cannot obtain
+the markup or apply it: the numbers are not reachable from plugin code, and a
+plugin whose code mentions them fails to load at all. What it cannot check is
+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.
+
+**`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:
+
+```csv
+start,eur_per_kwh,provisional
+2026-01-15T00:00:00+01:00,0.1834,false
+2026-01-15T01:00:00+01:00,-0.0210,true
+2026-01-15T02:00:00+01:00,0.3115,false
+```
+
+- `start` **must carry its UTC offset** (`+01:00` in winter, `+02:00` in
+  summer). A bare `2026-01-15 00:00` is refused, because for one hour every
+  October a local wall clock names two different moments.
+- `eur_per_kwh` is **all-in** — energy *plus* markup *plus* taxes. This plugin
+  has no way to know what your numbers already include, so it assumes
+  everything and adds nothing.
+- Negative prices are valid and are kept. They are the best charging hours of
+  the year.
+- `provisional` is optional; omit the column and every hour is treated as
+  settled.
+
+**When there are no prices at all** — provider off, feed unreachable, CSV
+missing — the add-on does not guess. It reports *no price data*, which is a
+distinct state from "prices, all of them zero": the plan is marked provisional
+and arbitrage is disabled, per the degradation matrix. It never falls back to a
+price of zero, which would read as free electricity.
+
+**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.
+
+**The old Home Assistant price sensors.** `price_now_entity` and
+`price_avg_entity` still work and are unchanged: the add-on compares them and
+uses the result as a cheap-window hint for the maintenance charge. They are
+**not compatible with `price_provider`** — configure both and the add-on
+refuses to start, naming the conflict, because the Home Assistant pair would
+silently keep deciding while the status page named your supplier. Use one or
+the other.
+
 ### Site
 
 | option | meaning |

goodwe_controller/app/validate.py

@@ -116,6 +116,21 @@ NOT READY banner already names the problem, (b) does not apply.
      (13.8 kWh usable at 2000 W is ~6.9 h against the 720 min DRAIN_TIMEOUT).
      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);
+     `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
+     documented offline fallback into a permanent no-price-data condition
+     reached by accident. Same shape as 1, 4 and 5 every time - a source the
+     operator chose, overridden by a layer they cannot see.
+
+     ⚠️ `price_provider: "off"` IS NOT REFUSED AND MUST NOT BECOME SO. §11.4
+     makes no-price-data a supported state, and §9.2 says a large share of the
+     installed base is on a fixed or static tariff. Refusing to start without a
+     price feed would lock those sites out of the add-on entirely.
+
 WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 
   - `integrator_max_w` above `max_w`. DOCS.md is right that the only thing the
@@ -141,6 +156,7 @@ WHAT IS DELIBERATELY *NOT* REFUSED, because it is untidy rather than unsafe:
 import logging
 
 from .p1 import is_enabled, validate_meter_options
+from .price import PROVIDERS
 
 _LOG = logging.getLogger("goodwe.config")
 
@@ -349,6 +365,9 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
             f"two numbers. Lower maintenance_charge_w to {max_w:.0f} W or less, "
             f"or raise max_w to at least {charge_w:.0f} W.")
 
+    # --- 7. two price sources on one site ------------------------------------
+    problems.extend(_price_problems(opts))
+
     # --- warnings: real, but not worth refusing over -------------------------
     integ = opts.get("integrator_max_w")
     integ_w = None if not integ else _number(opts, "integrator_max_w", None)
@@ -382,6 +401,75 @@ def validate_startup_config(opts: dict, dev_min=None, dev_max=None) -> list[str]
     return problems
 
 
+def _price_problems(opts: dict) -> list[str]:
+    """Rule 7 (TARIFF-02): the price configuration, refused where it is untrue.
+
+    ⚠️ NOTE WHAT IS *NOT* HERE. `price_provider: "off"` is not refused and never
+    will be: §11.4 makes no-price-data a first-class supported state (static
+    profile, provisional plan, no arbitrage), and an add-on that will not start
+    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.
+
+    Three refusals, all case (a) from this module's docstring: a source the
+    operator SET being overridden by a layer they cannot see.
+    """
+    problems: list[str] = []
+    pid = str(opts.get("price_provider", "") or "off").strip() or "off"
+
+    if pid != "off" and pid not in PROVIDERS:
+        problems.append(
+            f"price_provider is {pid!r}, which is not a shipped plugin. The "
+            f"ids that exist are: off, {', '.join(sorted(PROVIDERS))}. "
+            "Refused rather than defaulted, per the §14 warning box - a "
+            "silent fall back to 'off' would look exactly like a working "
+            "provider that happens never to find a cheap hour.")
+        return problems          # nothing below can be judged against an unknown id
+
+    # ⚠️ THE HA-SIDE OVERLAP THE PM TOLD US TO DECIDE ABOUT, DECIDED HERE.
+    # price_now_entity/price_avg_entity are the existing delegation of pricing
+    # to Home Assistant: main.py reduces them to ONE BOOLEAN, `cheap`, read only
+    # by the maintenance cheap-window charge floor. They are KEPT (TARIFF-03 and
+    # OPT-04 are what replace them, and neither has landed), but they may not
+    # run alongside a provider. With both configured the provider series drives
+    # nothing at all while the two entities quietly keep deciding, and the
+    # operator's evidence that they picked a supplier is a status line saying
+    # they picked a supplier. That is (a), and it is the "silently double up"
+    # the PM named on 2026-08-30.
+    # ⚠️ THIS REFUSAL'S REASON EXPIRES, AND THE MESSAGE BELOW MUST BE EDITED IN
+    # THE SAME COMMIT THAT LANDS THE FIRST CONSUMER (TARIFF-03 or OPT-04).
+    # Today the message says the provider "would decide nothing" - true, because
+    # nothing reads the series. Once something does, both sources really decide
+    # and this becomes a straightforward two-writer conflict; the refusal stays
+    # right and its explanation goes wrong, which is worse than either. There is
+    # a tripwire on exactly this in test_price.py section 12: it greps app/ for
+    # a `load_prices` consumer and goes RED the moment one appears. Update the
+    # message, not the check.
+    ha_price = [k for k in ("price_now_entity", "price_avg_entity")
+                if str(opts.get(k, "") or "").strip()]
+    if pid != "off" and ha_price:
+        problems.append(
+            f"price_provider is {pid!r} AND {' and '.join(ha_price)} "
+            f"{'is' if len(ha_price) == 1 else 'are'} set, which is two price "
+            "sources on one site. THE HOME ASSISTANT ENTITIES WIN: they are "
+            "what main.py reduces to the `cheap` flag the maintenance cycle "
+            "reads, and nothing yet consumes the provider series, so the "
+            "supplier you configured would decide nothing while the status "
+            "page named it. Clear price_now_entity and price_avg_entity to use "
+            f"the {pid!r} plugin, or set price_provider to 'off' to keep the "
+            "Home Assistant sensors.")
+
+    if pid == "manual_csv" and not str(opts.get("price_csv_path", "") or "").strip():
+        problems.append(
+            "price_provider is 'manual_csv' but price_csv_path is empty, so "
+            "the offline fallback has no file to read. Every fetch would "
+            "return no-price-data with a filesystem error as its reason - "
+            "which is §11.4 behaviour arrived at by accident rather than by "
+            "configuration. Point it at the CSV, or set price_provider to "
+            "'off', which says the same thing on purpose.")
+
+    return problems
+
+
 def _number(opts: dict, key, default):
     raw = opts.get(key, default)
     if raw is None or raw == "":

goodwe_controller/config.yaml

@@ -162,9 +162,53 @@ options:
   # --- tariff / capacity tariff (all optional) ------------------------------
   peak_forecast_entity: ""
   peak_cap_w: 3500
+
+  # ⚠️ THE OLD PRICE PATH, AND IT IS NOT DEAD YET. These two entities are the
+  # add-on delegating the whole price question to Home Assistant: main.py reads
+  # both and derives ONE BOOLEAN, `cheap = now <= avg`, which is consumed by
+  # nothing except the maintenance cycle's cheap-window charge floor. That is
+  # all they have ever done. They are kept, because retiring them would take
+  # the maintenance cycle's only price signal away on a live install before
+  # anything replaces it - TARIFF-03 (static profile) and OPT-04 (arbitrage)
+  # are the cards that replace it, and neither has landed.
+  #
+  # ⚠️ They may NOT be combined with price_provider below. Two price sources on
+  # one site, one of which silently wins, is exactly the "double up" the PM
+  # named; validate.py rule 7 refuses that configuration at startup rather than
+  # letting an operator believe the provider they configured is driving
+  # something. See app/validate.py.
   price_now_entity: ""
   price_avg_entity: ""
 
+  # --- price providers (TARIFF-02, specs §9.3 / §14 `tariffs:`) --------------
+  # `off` is the shipped default and means the §11.4 no-price-data row applies:
+  # static profile, plan provisional, NO ARBITRAGE. Nothing in 0.5.x consumes
+  # the series yet - OPT-04 is the consumer - so turning this on today fetches,
+  # validates and publishes prices and changes no energy decision.
+  #
+  # ⚠️ THESE DEFAULTS ARE MIRRORED ONCE, IN app/price.py's
+  # PRICE_OPTION_DEFAULTS, and test_price.py reads THIS FILE and asserts the two
+  # agree key for key. Do not add a third copy in main.py - CFG-03 is open
+  # because that has already happened three times.
+  #
+  # 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.
+  price_provider: "off"
+  price_markup_eur_kwh: 0.03
+  price_taxes_eur_kwh: 0.06
+  price_csv_path: "/share/goodwe_prices.csv"
+  price_feed_url: ""
+  price_horizon_h: 48
+  price_timeout_s: 10
+
+  # §9.3: injection is priced SEPARATELY, and in Belgium it is often near zero -
+  # which by itself strongly favours self-consumption over export. A scalar, not
+  # a second series: no shipped supplier publishes a dynamic injection curve.
+  export_price_eur_kwh: 0.04
+
   # --- site ------------------------------------------------------------------
   estop_fitted: false
   log_level: info
@@ -239,5 +283,23 @@ schema:
   price_now_entity: str?
   price_avg_entity: str?
 
+  # ⚠️ The provider list is written out rather than left as `str`, so the
+  # 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)
+  price_markup_eur_kwh: float(0,1)
+  price_taxes_eur_kwh: float(0,1)
+  price_csv_path: str?
+  price_feed_url: str?
+  price_horizon_h: int(1,72)
+  price_timeout_s: int(2,60)
+  # ⚠️ The lower bound is NEGATIVE on purpose. Belgian injection tariffs have
+  # gone below zero (you pay to export at midday in summer), and a schema that
+  # bottoms out at 0 would make that site inexpressible.
+  export_price_eur_kwh: float(-1,1)
+
   estop_fitted: bool
   log_level: list(trace|debug|info|warning|error)