Add sensor freshness checks

README.md

@@ -31,7 +31,7 @@ This project targets Home Assistant OS on a Raspberry Pi 5, with one existing ON
 
 Choose multiple sensors for a single variable, e.g. OpenWeatherMap then another provider, in priority order. Switch order in **Configure** to run A/B comparisons on successive days, or simply let the second sensor act as fallback. The active source and all current alternative readings are visible in the **Heating MPC Status** entity attributes (`weather`, `weather_active_sources`, `weather_comparison`). The **MPC Outdoor Temperature** sensor also has an `active_source` attribute and an `alternatives` map.
 
-Measurements are normalized where possible: outdoor temperatures to °C; wind to m/s; pressure to hPa; visibility to meters. Unknown units or values outside plausibility bounds are rejected in favor of the next selected sensor. Clouds and humidity are expected in %, rain/snow in mm or mm/h as represented by their upstream sensor. A fallback source may have a different sampling delay; no stale-data age policy exists yet.
+Measurements are normalized where possible: outdoor temperatures to °C; wind to m/s; pressure to hPa; visibility to meters. Unknown units or values outside plausibility bounds are rejected in favor of the next selected sensor. Clouds and humidity are expected in %, rain/snow in mm or mm/h as represented by their upstream sensor. A fallback source may have a different sampling delay; configurable report-age limits now reject stale inputs (see below).
 
 Switching only the **weather-provider sensors** does not reset learned thermal parameters. The update is applied after the integration reloads, and it skips learning one transition when the primary temperature source changes, avoiding a jump in the training series. Nevertheless, two sensors with a persistent offset can bias predictions; compare their readings and validate the model again before relying on them. Replacing the physical heating switch discards incompatible model parameters. Existing room-specific parameters are retained if room entity IDs remain unchanged.
 
@@ -95,6 +95,34 @@ No active control was added; the manifest version has not been advanced.
   Predictions remain **counterfactual**: the proposed plan is not the actual
   Generic Thermostat's future command sequence.
 
-Offline lifecycle tests use HA doubles. Freshness policies, actual HA/HAOS lifecycle
+Offline lifecycle tests use HA doubles. Actual HA/HAOS lifecycle
 validation and held-out prediction accuracy remain unfinished. Back up before
 trying these changes; follow the safe trial and rollback notes in AUDIT.md.
+
+
+## Unreleased: sensor freshness
+
+Room and weather report-age limits are available during setup and in Options
+(5–1440 minutes). Defaults are 30 minutes for rooms and 120 minutes for weather;
+existing entries use these defaults until changed. Celsius/Fahrenheit handling,
+compatible learned models and entity IDs are unchanged.
+
+Stale room readings or an absence of fresh outdoor temperature sources pause
+learning and predictions. Weather selection skips stale sources; optional weather
+outages do not block predictions. Recovery begins a new sampling interval, so no
+training spans an outage. Status attribute `input_quality` lists each room and each
+weather source by metric, with report age in seconds and a reason: `valid`,
+`missing`, `unknown`, `unavailable`, `stale`, `invalid_timestamp`,
+`future_timestamp` or `invalid_value_or_unit`.
+
+Freshness uses HA `last_reported`, falling back to `last_updated` only on older HA
+versions without that field. It measures HA state reports, not the age of the
+original physical measurement: a provider republishing cached data can look fresh.
+Some integrations report only changed values; choose limits appropriate to their
+reporting behavior. The relay and thermostat are event-driven references and do
+not receive these numeric-sensor age limits. Sensor alignment and relay event
+history remain future work. These checks run on the existing five-minute poll.
+
+After backing up and upgrading, check report ages in Status, adjust limits in
+Options to match your sensors, and verify fallback/recovery with an unavailable
+source. Generic Thermostat remains the sole controller. No HAOS trial was performed.