# Changelog

Engineering findings and test evidence behind each change are in [AUDIT.md](AUDIT.md).

## 0.2.2 — 2026-10-26

Reliability release (Milestone 0). Still **observation-only**: the integration never
calls the relay, the thermostat or any other service. No new options or UI text;
entity IDs and settings carry over. Tested in a Home Assistant Core test harness
with HA 2025.12.0 and 2026.2.3; not yet tested on HAOS or with real devices.

### Upgrade notes

- Back up Home Assistant, replace `custom_components/heating_mpc`, restart Core.
- Saved models load, but coefficients learned by 0.2.1 were fitted with a broken
  radiator-lag estimate (see Fixed). Either let them re-converge over a few days of
  heating, or reset the model: disable the integration, delete
  `/config/.storage/heating_mpc.<entry_id>`, restart Core, enable it again. Deleting
  the file while the integration runs does not work; it saves the model again.
  Deleting and re-adding the integration also resets it, but loses the settings.
- After each HA restart, learning pauses for about 30 minutes
  (`sample_result: lag_uncertain`) because the radiator state is unknown.
  Forecasts continue.
- After a day of running, compare each sensor's `max_age_seconds_24h` in Status
  with the freshness limits in Configure (see README, "Choosing freshness limits").
- Rollback: restore the previous folder (or the backup) and restart. 0.2.1 reads
  models saved by 0.2.2 and ignores the new keys.

### Fixed

- The radiator-lag estimate jumped to fully hot or fully cold at every relay
  change. In simulation this learned the heating gain about a third too low, and
  forecasts made just after a boiler cycle started from the wrong state.
- The learner's covariance grew without limit during long OFF periods (for
  example a summer), which could destabilize learning when heating resumed and
  eventually make a restart discard the saved model.
- Optional weather sources could not be removed in Configure.
- A finished forecast was discarded, making proposed heat unavailable for five
  minutes, when only a diagnostic weather sensor or the thermostat's current
  temperature changed during the calculation.
- Config entries from 0.1 were not migrated.
- Forecast entities of removed rooms stayed in the entity registry.
- Malformed or physically implausible saved models could crash setup or be used.
- ON/OFF readiness counts included rejected samples and other rooms' history.
- Polls 4–7 minutes apart, or containing a relay change, were learned as normal
  5-minute samples.
- Thermostat targets were read as Celsius on Fahrenheit installations.
- Invalid room weights or optimizer settings could cause crashes.
- 30/45-minute horizons reported their end point as a 60-minute forecast.

### Added

- Room and weather report-age limits in setup and Configure (5–1440 minutes,
  defaults 30 and 120). Stale outdoor sources fall back to the next one; a stale
  room pauses learning and forecasts until it reports again.
- A read-only listener on the relay, so all relay changes between polls are
  timestamped and integrated.
- Models of rooms removed in Configure are kept (up to 24) and restored if the
  room is added back.
- Status attributes: `input_quality` (per-source state and report age, including
  `max_age_seconds_24h`), `heat_lag`, `heat_lag_uncertainty`, `sample_result`,
  `retired_room_models`, and per-room accepted ON/OFF counts in `models`.
- Statuses `invalid_weights` and `inputs_changed`.

### Changed

- Readiness now also requires 30 accepted ON and 30 accepted OFF samples per room.
- Learning skips intervals with a relay change, an outdoor-source switch or an
  uncertain lag estimate, and polls not 270–330 seconds apart.
- `input_quality` and `weather_comparison` are no longer written to the Recorder;
  they change every poll. Other attributes are still recorded.

### Persisted data

- Model payload `schema_version` 2 (0.2.1 wrote no version). Optional keys:
  per-room `on_count`/`off_count` and `retired_learners`. Older readers ignore them.

### Development

- Home Assistant Core test harness for HA 2025.12.0 and 2026.2.3, a Gitea Actions
  matrix over both, package and translation validation, and a static test that
  fails if actuator service calls are added.

## 0.2.1

- Corrects the manifest classification from `helper` to `service`. Existing config
  entries move from Helpers to **Settings → Devices & services → Integrations**
  after replacing the files and restarting Home Assistant Core.
- Deleting the config entry removes its entities and the learned model
  (`.storage/heating_mpc.<entry_id>`). The component folder stays until removed
  manually.
- MPC behavior otherwise unchanged; read-only / shadow-only.