Model/docs/adr/0039-override-aware-rebaselining.md

Effective baseline rebaselines off the calculator when overrides or prediction moved the picture

Context

Rebaselining (CONTEXT.md) is meant to fire on three triggers: (a) the cert was lodged under a superseded methodology (sap_version < 10.2), (b) Landlord Overrides / Site Notes changed the physical state, or (c) the picture was estimated (EPC Prediction) or remapped. On any trigger the calculator's scoring of the Effective EPC is the Effective Performance; otherwise Effective equals the lodged accredited figure.

The code only implemented trigger (a). CalculatorRebaseliner branched solely on sap_version: for a cert at sap_version >= 10.2 it kept the lodged figure and ran the calculator only to log divergence — regardless of whether Landlord Overrides had changed the dwelling, or the picture was a synthesised prediction. So a property's stored Effective baseline echoed the lodged accredited headline even when the authoritative picture (EPC + overrides) described a different dwelling.

This surfaced as a portfolio-796 hit-list (e.g. property 725634): a lodged ASHP+solar cert scored B/81, but the landlord override reassigned it to electric storage heaters on an uninsulated cavity. The stored Effective stayed B/81 (lodged echo) while the modelling plan modelled the override-applied picture at C/D — an incoherent "already B, post-works C/D" plan. The same applied to predicted properties, whose synthetic headline was trusted as if accredited.

The "trust lodged at ≥10.2" rule (ADR-0037 / the Calculated SAP10 Performance glossary entry) exists for a real reason: the deterministic calculator under-reads genuine accredited certs (e.g. 74.6 vs an accredited 81 on the un-overridden 725634 ASHP cert), so for a pristine lodged cert the accredited figure is the better baseline. The bug was applying that rule unconditionally — including to certs the landlord had explicitly corrected.

Decision

Thread a physical_state_changed signal (Property.physical_state_changed — true on Site Notes, Landlord Overrides, or EPC Prediction) from the PropertyBaselineOrchestrator into the Rebaseliner. The calculator output becomes Effective Performance whenever any trigger fired — pre_sap10 (a) or physical_state_changed (b/c) — tagged pre_sap10 / physical_state_changed / both. Only a pristine lodged SAP ≥ 10.2 cert with no overrides keeps its accredited figure (reason = "none"), and that is now the only case the calculator runs purely to validate (and the only case the accredited-vs-calc divergence warning is meaningful, so divergence is logged only there).

This realises trigger (b)/(c) as the domain model always claimed — restoring documented behaviour, not new policy. "EPC + overrides is authoritative" (decided with Khalim): a landlord's correction is trusted over the lodged cert, and a mistaken override is a data problem fixed at source (with the client), not papered over by the baseline.

physical_state_changed is deliberately coarse — any resolved override trips it, not only a "material" one. A no-op override (asserting what the cert already says) would re-introduce the calculator's known under-read into the baseline; we accept that because landlords rarely enter no-op overrides, and "the assembled picture is authoritative" is the simpler, more defensible rule than a materiality threshold.

Consequences

• Re-running the baseline flips every overridden / predicted property's Effective from its lodged/synthetic headline to the calculator's scoring of EPC + overrides. Many legitimately change band (725634 → D, 739060 → D, 721985 → C, …). The displayed baseline and the modelling plan now derive from the same picture, so they agree — the incoherent "B baseline, C/D plan" is gone.
• FE/product should expect a visible baseline shift on overridden/predicted properties — this is correct Rebaselining. Pristine lodged ≥10.2 certs are unchanged.
• A wrong override now visibly downgrades a property (725634 was really an ASHP cert). That is intended: the override is authoritative for modelling, and bad override data is a separate, surfaced concern — an override-plausibility scanner (anomalies like "another dwelling above", community-heated + gas-boiler) is its own ticket.
• The baseline is only correct on a faithful Effective EPC: this decision is paired with ADR-0040 (the DB EPC must round-trip without dropping PV arrays / floor flags), and the orchestrator must read the same faithful picture the plan modelled.
• Numbers finalise only after deploy + re-model (the handler re-fetches the live cert and re-saves it faithfully, then the baseline recomputes). The rebaseline_reason enum (none / pre_sap10 / physical_state_changed / both) already existed in the FE schema; this is a backend-only change.