feat(forecast): project irradiance onto each PV array's plane

[HuggeK]

Projects forecast irradiance onto each PV array's plane instead of assuming a
flat panel.

Radiation-bearing providers previously produced one estimate,
rated × (W/m² / 1000), which ignores orientation entirely — a south-facing 35°
roof and a flat one received the same forecast. When per-plane geometry is
configured (the Weather tab's PV arrays: tilt/azimuth/kWp), that GHI is now
projected onto each plane via the sunpos physics already in the tree and
summed.

This is the first half of the original #718, split per @frahlg's review. It is
the user-visible half: it improves every radiation-bearing provider today, with
no new endpoint and no new dependency.

What changed

• sunpos — POAFromComponents(sun, ghi, dhi, tilt, az) extracted so plane-of-array
  irradiance can be driven by measured components rather than only the built-in
  clear-sky model. POA now delegates to it, so existing behaviour is unchanged.
• sunpos.POAFromGHI — Erbs correlation splitting GHI into direct + diffuse, for
  providers that publish only global horizontal.
• forecast — Service.Arrays, filled from weather.pv_arrays; when complete
  arrays exist the per-plane sum replaces the flat estimate.
• forecast — negative irradiance becomes zero; non-finite irradiance and PV
  estimates are omitted before they can become SQLite NULL.
• config — array geometry keeps omitted tilt/azimuth distinct from explicit
  0°, and incomplete or invalid planes are ignored.
• Weather help text — documents that Open-Meteo also uses the configured arrays.

What is deliberately unchanged

• Sites with no complete arrays configured keep the previous flat estimate for
  GHI providers.
• Forecast.Solar's site-calibrated response and request model remain unchanged;
  its configured arrays are now validated before request construction.
• No control-tick, dispatch or optimizer-contract changes. This only sharpens a
  number those paths already consume.

Why Erbs, and what it costs when the provider gives no diffuse component

Projecting GHI onto a tilted plane requires knowing how much of it is beam and how
much is diffuse: the beam part depends on the angle of incidence, the diffuse part
largely does not. Providers like Open-Meteo publish only global horizontal, so the
split has to be inferred.

Erbs is the standard correlation for this — it estimates the diffuse fraction from
the clearness index kt (GHI over extraterrestrial horizontal). It is empirical
and imperfect on partly-cloudy hours, but it is far closer than the implicit
alternative, which was to treat every panel as horizontal. Where a provider does
publish a diffuse component, POAFromComponents takes it directly and Erbs is not
used at all.

Scope of the split, and where the rest went

The original branch also carried an SMHI STRÅNG client and an expected-vs-actual
scoring package. Those were tested but not wired to anything user-visible, which
is what made the diff hard to review at +1747/-26.

They now move to follow-up PR #734, which wires STRÅNG as an irradiance source,
adds geographic-coverage metadata, and updates the location UI. This PR no
longer depends on any of that.

Testing

sunpos: POA is asserted identical to POAFromComponents driven with the
clear-sky components, so the refactor is behaviour-preserving; a south-facing 35°
plane at solar noon is checked to receive more than a horizontal one; Erbs is
checked at both clear and overcast kt.

forecast: arrays move the predicted watts in the expected direction, a site
with no arrays is asserted identical to the old estimate, incomplete Stockholm
array metadata is ignored, and negative, zero, NaN and Inf GHI are covered with
and without arrays.

Part of the roadmap in discussion #717.

Current review state

• Rebased onto master at ee416d1f after chore(ci): bump docker/login-action from 3 to 4.5.2 #781–chore(ci): bump docker/build-push-action from 6 to 7 #784 and fix: format IPv6 endpoints for integrations #786 on 2026-08-04;
  no merge conflicts needed resolution. Those newer master commits only changed
  CI workflow pins.
• Current head is 55c2c64b.
• STRÅNG and scoring are not in this PR; they remain in feat(weather): add STRÅNG as an irradiance source and declare source coverage #734.
• The PR remains open and draft for independent review. It has not been merged.

P2 follow-up

The independent review of 1343ce8f identified three P2s. This head addresses
all three in the same branch:

1. All GHI paths share one physical boundary: negative irradiance is stored and
   estimated as zero; non-finite irradiance is logged and the row is omitted;
   non-finite PV estimates are also omitted and negative PV is clamped to zero.
2. Every configured array must have finite kWp, tilt and azimuth in range. A
   missing required field no longer becomes 0° north. Complete arrays are
   projected; if none remain, GHI providers use the safe flat path.
3. Config, Open-Meteo comments and the Weather tab now state that Open-Meteo
   uses per-array geometry. The rendered Weather tab was checked in a local
   browser; screenshot evidence was captured at /private/tmp/ftw-pr718-weather-tab.png.
   Human visual review is still required before merge.

Validation

• go test ./internal/config ./internal/forecast ./internal/sunpos ./internal/mpc
• make verify with Python 3.12.13, a project venv, and 37 drivers from
  drivers/BUNDLED_SOURCE.json
• make verify-all: full Go and optimizer tests, external MPC tests, compose
  migration, container boundaries, vet, native build, and Linux ARM64, Linux
  AMD64, and Windows AMD64 builds
• The pre-commit and pre-push hooks repeated the required verification; the
  pre-push check confirmed the branch was not behind origin/master.
• All selected GitHub checks for head 55c2c64b are green; optimizer, drivers
  and module-boundary jobs are correctly path-skipped. Merge remains blocked by
  the draft state and independent review.

[frahlg]

This has a merge conflict against master and cannot be reviewed as it stands (CONFLICTING / DIRTY). Several PRs landed today — #700, #706, #707, #715, #716, #721, #722 — so a rebase is needed before anyone can read the diff.

Not touching the branch myself: it is yours, and rebasing someone else's open work is how two people end up building the same thing twice.

Worth saying while you are in there: at +1747/-26 across 20 files this is large for one review, and it will keep conflicting while it waits. The description already splits cleanly in two — the POA-per-array wiring is live and user-visible, the STRÅNG client is tested but not wired to anything. The first half improves every radiation-bearing provider today and could go in on its own; the second half has no user-visible effect yet and can follow. Two PRs would land faster than one.

For anyone else reading: the RFC is Discussion #717, not an issue.

[HuggeK]

Rebased onto master and split, as suggested.

This PR is now the POA-per-array wiring only: +341/-22 across 5 files, down from +1747/-26 across 20. It is the half that improves every radiation-bearing provider today, with no new config, endpoint or dependency.

The STRÅNG client and the scoring package have been lifted out entirely — they are not in this diff. They move to a follow-up that actually wires STRÅNG as an irradiance source rather than leaving it unreferenced.

Two things worth recording from the rebase, both of which turned out to be trivially additive: master's energy_ledger_* tables and this branch's pv_performance_daily were added to the same migration list slot, and #652 left ftw-history-card.js untouched so nothing in the UI work collided.

On the follow-up: I checked whether STRÅNG can also serve cloud cover, since that would let it back a forward path too. It cannot — the model publishes exactly seven parameters (116-122) and all are radiation quantities. Confirmed against the live API rather than the docs, which 404. Cloud cover is derivable though, and I verified the identity that makes it cheap: at solar noon params 121 + 122 = 723.0 + 87.5 = 810.5, exactly param 117, so the direct/diffuse split is internally consistent. Param 119 is sunshine duration capped at 60 min/h, which is a direct observational proxy for cloudiness.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2bd8eca94b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Project hourly GHI at the interval midpoint

When per-array geometry is enabled with Open-Meteo, this passes the provider's hour label directly to the instantaneous solar-position model. Open-Meteo's shortwave_radiation value is an average over the preceding hour, so near sunrise and sunset the projection uses the wrong elevation and azimuth; a nonzero interval ending just after sunset can even become zero because POAFromGHI sees the sun below the horizon. Preserve the radiation interval in RawForecast and project at its midpoint (and store it under the matching slot) rather than treating the label as an instantaneous HourStart.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Bound the beam estimate at low solar elevation

When forecast GHI exceeds the instantaneous extraterrestrial-horizontal value—readily possible for an hourly average near sunrise or sunset—kt exceeds 1, Erbs fixes DHI at only 16.5% of GHI, and POAFromComponents divides the remaining 83.5% by a very small cosZ. For example, 100 W/m² at zenith 89° can become roughly 4.8 kW/m² on a sun-facing plane, yielding a many-times-nameplate PV forecast that can distort planner decisions. Cap the inferred beam/DNI to a physical bound or compute the clearness index from interval-averaged extraterrestrial irradiation before projecting it.

Useful? React with 👍 / 👎.