feat(prices): static / time-of-use tariff so planning works outside Europe

.changeset/static-price-provider.md

@@ -0,0 +1,7 @@
+---
+"ftw": minor
+---
+
+A static / time-of-use price provider, so price-driven planning works outside Europe.
+
+`price.provider: static` takes a flat rate in the install currency, plus optional local-time windows that override peak hours (overnight wrap, optional weekdays). Grid tariff and VAT still apply. Live day-ahead spot remains Europe-only; this is the stand-in for every other market. Settings and the setup wizard offer it next to Sourceful and ENTSO-E.

README.md

@@ -219,6 +219,7 @@ metadata are the detailed reference.
 - [Product roadmap](docs/roadmap.md)
 - [Power sign convention](docs/site-convention.md)
 - [Safety invariants](docs/safety.md)
+- [Geographic coverage of external data](docs/data-coverage.md)
 - [Operations and recovery](docs/operations.md)
 - [Full backup and safe restore](docs/backup-and-restore.md)
 - [Writing a driver](docs/writing-a-driver.md)

docs/architecture.md

@@ -158,6 +158,12 @@ schema. The handlers registered in
 [`go/internal/api/api.go`](../go/internal/api/api.go) define the HTTP surface. Driver metadata defines
 the device catalog. These sources replace manually duplicated reference docs.
 
+External data sources do not all work everywhere. Weather and PV forecasts
+are worldwide; live day-ahead spot is European. A site outside ENTSO-E
+uses `price.provider: static` — a flat rate or time-of-use schedule —
+which is how price-driven planning works without a market feed. See
+[data-coverage.md](data-coverage.md).
+
 Some startup bindings cannot be hot-reloaded, including state paths, API
 listener and selected integration transports. Normal device and control
 configuration is reloaded through

docs/data-coverage.md

@@ -0,0 +1,95 @@
+# Geographic coverage of external data sources
+
+FTW controls hardware anywhere. The data it plans with does not.
+
+- **Weather and PV forecasting works worldwide.**
+- **Day-ahead spot prices work in Europe only.**
+- **A static / time-of-use tariff works anywhere.** That is how a site
+  outside ENTSO-E (or on a flat retail contract inside it) gets
+  price-driven planning.
+
+A site outside Europe still gets monitoring, safety, control, the
+dashboard, weather forecasts and the self-learning PV twin. What it did
+not have, until `price.provider: static`, was a price source.
+
+## Spot prices — Europe, or a tariff you type
+
+Configured under `price.provider`.
+
+| Provider | Coverage | API key | Notes |
+|---|---|---|---|
+| `sourceful` | European day-ahead markets | No | Default. Sourceful's cached ENTSO-E API. |
+| `elprisetjustnu` | **Sweden only** — zones SE1–SE4 | No | 15-minute PTU since late 2025. |
+| `entsoe` | ENTSO-E member markets | Yes | Direct from the Transparency Platform. |
+| `static` | **Worldwide** | No | Flat rate or time-of-use schedule the operator types. |
+| `none` | — | — | Disables price fetching entirely. |
+
+There is still no live adapter for CAISO, ERCOT, PJM, AEMO/NEM, JEPX or
+the other non-European markets. `static` is the stand-in: a US TOU
+tariff, a Japanese flat contract, or any other schedule that can be
+written as hours and a rate.
+
+Prices are stored in **minor units of the configured currency** per kWh
+(öre, cent, ¢, pence, …). ENTSO-E figures that arrive in another
+currency are converted with **ECB** daily FX rates. Static prices are
+already in the install currency; nothing is converted.
+
+> The Tibber driver (`drivers/tibber.lua`) is telemetry only — it reports
+> meter readings, not prices, so it is not a fifth price source.
+
+```yaml
+price:
+  provider: static
+  currency: USD
+  static_ore_kwh: 8          # off-peak, ¢/kWh (minor units)
+  static_tou:
+    - { start: "07:00", end: "23:00", ore_kwh: 22 }   # peak
+  grid_tariff_ore_kwh: 4
+  vat_percent: 0
+```
+
+Windows are local time on the box. First match wins; hours they miss
+keep `static_ore_kwh`. Overnight windows wrap (`22:00`–`06:00`). An
+optional `days` list (`mon`…`sun`) limits a window to those weekdays.
+
+The zone picker is served from `GET /api/prices/zones` and is hidden
+when the provider is `static`. See
+[`go/internal/prices/zones.go`](../go/internal/prices/zones.go) and
+[`go/internal/prices/static.go`](../go/internal/prices/static.go).
+
+## Weather and PV forecasts — worldwide
+
+Configured under `weather.provider`. All four work at any latitude/longitude.
+
+| Provider | Coverage | API key | Signal quality |
+|---|---|---|---|
+| `met_no` | Global | No | Cloud cover only — weakest PV signal. |
+| `openweather` | Global | Yes | Cloud cover only. |
+| `open_meteo` | Global | No | Shortwave radiation (GHI) — good. |
+| `forecast_solar` | Global | No (free tier) | Site-calibrated watts from panel geometry — best. |
+
+Prefer `open_meteo` or `forecast_solar` when the site has array
+geometry: they carry an irradiance signal, which is what the
+orientation-aware plane-of-array model needs.
+
+## What is not in this tree yet
+
+| Capability | Planned source | Coverage when it lands |
+|---|---|---|
+| PV performance scoring / forecast calibration | SMHI STRÅNG ([#734](https://github.com/srcfl/ftw/pull/734)) | Nordic region only |
+| Automatic roof geometry | Lantmäteriet via STAC ([#735](https://github.com/srcfl/ftw/pull/735)) | Sweden by default; any conformant STAC catalog |
+
+Until those land, array geometry stays a manual entry on the Weather
+tab, and the PV twin still calibrates from measured production.
+
+## What a non-European site has today
+
+| Capability | Works outside Europe? |
+|---|---|
+| Device control, safety, dispatch | Yes |
+| Telemetry, history, dashboard | Yes |
+| Weather + PV forecasting | Yes |
+| Self-learning PV twin | Yes |
+| Price-driven planning | **Yes, via `static`** |
+| Live day-ahead spot | **No** — Europe only |
+| Manual array geometry | Yes |

go/internal/config/config.go

@@ -1411,7 +1411,7 @@ type StateConf struct {
 
 // Price is the spot-price source config.
 type Price struct {
-	Provider         string  `yaml:"provider" json:"provider"` // sourceful | elprisetjustnu | entsoe | none
+	Provider         string  `yaml:"provider" json:"provider"` // sourceful | elprisetjustnu | entsoe | static | none
 	Zone             string  `yaml:"zone,omitempty" json:"zone,omitempty"`
 	GridTariffOreKwh float64 `yaml:"grid_tariff_ore_kwh,omitempty" json:"grid_tariff_ore_kwh,omitempty"`
 	VATPercent       float64 `yaml:"vat_percent,omitempty" json:"vat_percent,omitempty"`
@@ -1438,6 +1438,37 @@ type Price struct {
 	// most Swedish customer agreements pass through. Set to a pointer
 	// to 0.0 if you have a guaranteed-zero-floor agreement.
 	ExportFloorOreKwh *float64 `yaml:"export_floor_ore_kwh,omitempty" json:"export_floor_ore_kwh,omitempty"`
+
+	// StaticOreKwh is the default energy price in minor units per kWh when
+	// provider=static. Time-of-use windows below override matching hours;
+	// hours they miss keep this rate. Zero is a real price (free energy).
+	StaticOreKwh float64 `yaml:"static_ore_kwh,omitempty" json:"static_ore_kwh,omitempty"`
+	// StaticTOU is an optional time-of-use schedule in the box's local
+	// time. First matching window wins. An empty Days list means every day.
+	StaticTOU []TOUWindow `yaml:"static_tou,omitempty" json:"static_tou,omitempty"`
+}
+
+// TOUWindow is one time-of-use period for provider=static.
+type TOUWindow struct {
+	Start  string   `yaml:"start" json:"start"` // "HH:MM" local, inclusive
+	End    string   `yaml:"end" json:"end"`     // "HH:MM" local, exclusive; "24:00" allowed
+	OreKwh float64  `yaml:"ore_kwh" json:"ore_kwh"`
+	Days   []string `yaml:"days,omitempty" json:"days,omitempty"` // mon..sun; empty = every day
+}
+
+// Validate checks a static tariff's windows. Other providers are accepted
+// as-is: an unknown name currently disables fetching rather than failing
+// config load, and that behaviour stays.
+func (p *Price) Validate() error {
+	if p == nil || !strings.EqualFold(p.Provider, "static") {
+		return nil
+	}
+	for i, w := range p.StaticTOU {
+		if strings.TrimSpace(w.Start) == "" || strings.TrimSpace(w.End) == "" {
+			return fmt.Errorf("price.static_tou[%d]: start and end are required (HH:MM)", i)
+		}
+	}
+	return nil
 }
 
 // Weather is the weather-forecast source config.
@@ -1562,6 +1593,18 @@ func (c Config) MaskSecrets() Config {
 	if out.Price != nil {
 		cp := *out.Price
 		cp.APIKey = ""
+		if len(cp.StaticTOU) > 0 {
+			tou := make([]TOUWindow, len(cp.StaticTOU))
+			copy(tou, cp.StaticTOU)
+			for i := range tou {
+				if len(tou[i].Days) > 0 {
+					days := make([]string, len(tou[i].Days))
+					copy(days, tou[i].Days)
+					tou[i].Days = days
+				}
+			}
+			cp.StaticTOU = tou
+		}
 		out.Price = &cp
 	}
 	if out.Weather != nil {
@@ -2170,6 +2213,11 @@ func (c *Config) Validate() error {
 	if err := c.Assistant.Validate(); err != nil {
 		return err
 	}
+	if c.Price != nil {
+		if err := c.Price.Validate(); err != nil {
+			return err
+		}
+	}
 	if err := c.validateVehicles(); err != nil {
 		return err
 	}

go/internal/config/config_test.go

@@ -628,6 +628,40 @@ batteries:
 	}
 }
 
+func TestStaticPriceParsesTOU(t *testing.T) {
+	yaml := minimalYAML + `
+price:
+  provider: static
+  currency: USD
+  static_ore_kwh: 8
+  static_tou:
+    - start: "07:00"
+      end: "23:00"
+      ore_kwh: 22
+      days: [mon, tue, wed, thu, fri]
+`
+	c, err := Parse([]byte(yaml), ".")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if c.Price.Provider != "static" || c.Price.StaticOreKwh != 8 {
+		t.Fatalf("flat = %+v", c.Price)
+	}
+	if len(c.Price.StaticTOU) != 1 || c.Price.StaticTOU[0].Start != "07:00" {
+		t.Fatalf("tou = %+v", c.Price.StaticTOU)
+	}
+	if err := c.Validate(); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestStaticPriceRejectsEmptyTOUWindow(t *testing.T) {
+	p := &Price{Provider: "static", StaticTOU: []TOUWindow{{Start: "", End: "23:00"}}}
+	if err := p.Validate(); err == nil {
+		t.Fatal("expected error")
+	}
+}
+
 func TestPVArrayGeometryDistinguishesMissingFromZero(t *testing.T) {
 	yaml := minimalYAML + `
 weather:

go/internal/prices/prices.go

@@ -11,6 +11,8 @@
 //     hourly if the provider returns that.
 //   - entsoe — All EU, needs ENTSO-E transparency platform API key.
 //     Resolution varies per bidding zone (15m or 60m).
+//   - static — Operator-supplied flat rate or time-of-use schedule. No
+//     network. Works anywhere, including markets with no day-ahead feed.
 //
 // Consumer price = (spot + grid_tariff) × (1 + VAT/100). We store both
 // pure spot AND the consumer total so the UI can surface either.
@@ -563,7 +565,11 @@ func FromConfig(cfg *config.Price, st *state.Store, fx FXConverter) *Service {
 	}
 	zone := cfg.Zone
 	if zone == "" {
-		zone = "SE3"
+		if cfg.Provider == "static" {
+			zone = "STATIC"
+		} else {
+			zone = "SE3"
+		}
 	}
 	// An unset currency follows the zone: picking BE should not leave a
 	// Belgian household paying in öre. Unknown zones keep the old default.
@@ -588,6 +594,8 @@ func FromConfig(cfg *config.Price, st *state.Store, fx FXConverter) *Service {
 		ep.Currency = currency
 		ep.FX = fx
 		p = ep
+	case "static":
+		p = NewStatic(cfg)
 	default:
 		return nil
 	}