Merge release/1.0 (TARIFF-02) into SAFETY-07

Conflict was the one anticipated: both cards prepend to CHANGELOG.md's
Unreleased section. Both entries kept, SAFETY-07 first. Nothing else of
TARIFF-02's surface (app/price.py, validate.py rule 7, config.yaml, DOCS.md)
overlaps this card - config.yaml and validate.py are untouched here, so the
CFG-03 check still reads a config.yaml that only TARIFF-02 has widened.

Full suite green on the merge result, test_price.py included.

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

goodwe_controller/CHANGELOG.md

@@ -69,6 +69,85 @@ COVERED — running it there would have blinded it permanently and stopped every
 legacy install from charging, which is what the first cut did until
 `test_clamp.py`'s export case caught it.
 
+**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

@@ -642,6 +642,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)