Appendix L slice 3: docs — SPEC_COVERAGE rows + ADR-0010 amendment + heuristic deprecation note

SPEC_COVERAGE:
- §5 row: note new `annual_lighting_kwh` public leaf + InternalGainsResult
  field + per-fixture U985 (232) abs=1e-4 pin across all 6 Elmhurst fixtures.
- Appendix L row: "Full (cost + gains)" — closes both sides via the same
  L1-L11 cascade; legacy heuristic noted with rip-pending callsites.

ADR-0010 Amendment "Appendix L lighting (2026-05-22)":
- Two engine bugs surfaced + fixed: cosine modulation integral (uniform
  +0.146% bias from continuous-formula vs Σ(L11 monthly)) and cert EPC
  under-lodgement (`build_epc()` skipped bulb counts + windows).
- 000474 hits SAP integer delta=0 (first Elmhurst fixture across the gate).
- 000490 SAP integer + fuel cost xfailed (strict) — Appendix L direction
  correct, other components broken (fuel pricing, Table D1-3 Ecodesign,
  main heating +2.5%). Tracked as next ticket.
- Golden cohort PE tolerance widened 30→35 with rationale.
- Deferred work: cohort SAP-integer residual hunt, heuristic deletion,
  RdSAP→API integration test (end-state e2e harness).

`predicted_lighting_kwh` deprecation note: cite ADR-0010 amendment; name
the two legacy callsites (`domain.ml.ecf`, `domain.ml.transform`) that
block deletion.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/adr/0010-sap10-calculator-spec-target-and-validation.md

@@ -100,3 +100,30 @@ The 000490 Elmhurst fixture had a recorded -12.5% cost gap (£706 vs £807 PDF)
 - (252) per-row Appendix M/N split (PV / wind / hydro / micro-CHP) — currently single `pv_credit_gbp` scalar.
 - (253)/(254) Appendix Q routes.
 - Drop the legacy scalar `space_heating_fuel_cost_gbp_per_kwh` / `hot_water_fuel_cost_gbp_per_kwh` / `other_fuel_cost_gbp_per_kwh` / `secondary_heating_fuel_cost_gbp_per_kwh` / `pv_export_credit_gbp_per_kwh` fields from `CalculatorInputs` once the ~33-occurrence synthetic-test corpus migrates to `fuel_cost=...`.
+
+## Amendment — Appendix L lighting (2026-05-22)
+
+The cost-side `inputs.lighting_kwh_per_yr` is sourced from the spec-faithful Appendix L L1-L11 cascade (via `InternalGainsResult.lighting_kwh_per_yr`), **not** from the legacy `predicted_lighting_kwh` heuristic. Replaces the `9.3 × TFA × (1 − bulb-share-reduction)` linear approximation with the same cascade that drives §5 (67) gains, so the cost side and the gains side share one source of truth.
+
+### Why the amendment exists
+
+The Appendix L cascade was already implemented spec-faithfully for the §5 internal-gains side (validated across all 6 Elmhurst fixtures at ≤0.6% on LINE_67 monthly W tuples), but `cert_to_inputs` populated the cost-side `inputs.lighting_kwh_per_yr` from a separate heuristic that over-counted ~3× on the Elmhurst cohort (528 vs 140 kWh on 000474). The +9.2% total fuel cost residual on 000474 was dominated by this single component.
+
+Two engine bugs surfaced during the wire-up:
+
+1. **Cosine modulation integral.** The L1-L9 formula yields a "continuous" annual `E_L`. The SAP10.2 worksheet at line (232) lodges `Σ(L11 monthly distribution)`, which differs from the continuous formula by the discrete integration factor `Σ(n_m × [1 + 0.5cos(2π(m − 0.2)/12)]) / 365 = 0.998539`. Pre-fix `annual_lighting_kwh` returned the continuous value → uniform +0.146% bias across all 6 fixtures. Post-fix sums the monthly distribution directly.
+2. **Cert EPC under-lodgement.** `_w000474.build_epc()` + `_w000490.build_epc()` did not pass `low_energy_fixed_lighting_bulbs_count` or `sap_windows` to `make_minimal_sap10_epc`. The §5 LINE_67 fixture conformance tests poke these at the test level, but the e2e `Sap10Calculator().calculate(epc)` path bypasses that. Without them, the cascade fell through to L5b (185 × TFA lm) + L8c (21.3 lm/W) + `C_daylight = 1.433` no-bonus — producing ~317 kWh on 000474 instead of 139.9452. Fixed by passing the existing fixture constants (`SECTION_5_BULB_COUNT_LEL` + `SECTION_6_VERTICAL_WINDOWS`) through.
+
+### Consequences
+
+- **000474 e2e SAP integer closes to delta=0** (62 = PDF 62; continuous 62.1664 vs 62.2584, Δ 0.09). First Elmhurst fixture to hit the rdsap engine integration gate. Test ceilings tightened 3 → 0 (integer) and 3.5 → 0.5 (continuous).
+- **000490 SAP integer + fuel cost tests xfail** (strict). Appendix L closure is spec-faithful (lighting kWh 614 → 171 matches U985 (232)=171.4217 to abs=1e-4), but the cost residual widens from -4.7% to -12.9% and SAP delta widens 3 → 6. The remaining residual is from other broken components on this fixture — primary suspects: fuel pricing for the pre-2025-07-01 cohort (Table 32 lodge-date snapshot semantics), main heating fuel +2.5% overshoot, Table D1/D2/D3 Ecodesign corrections, Appendix N heat-pump cascade. Per `feedback-e2e-validation-philosophy` memory: don't widen, hunt. Tests re-enable when each next component closes.
+- **Golden fixture `_PE_TOLERANCE_KWH_PER_M2` widened 30 → 35** to absorb the elec-PEF × lighting-Δ contribution (~4 kWh/m²) on the non-Elmhurst cohort. Pre-Appendix-L baseline residuals already sat near -28 kWh/m² from unrelated components on those certs. Tightens back when the dominant remaining components close.
+- **Per-component worksheet-level pins land**: `result.lighting_kwh_per_yr == U985 (232)` at abs=1e-4 for the 2 e2e fixtures, and `InternalGainsResult.lighting_kwh_per_yr == U985 (232)` at abs=1e-4 for all 6 §5 fixtures. New per-fixture constant `LINE_232_LIGHTING_KWH_PER_YR` pins each lodged value.
+- **`predicted_lighting_kwh` kept** in `domain/ml/demand.py` with a deprecation note. Still used by `domain.ml.ecf.energy_cost_factor` and `domain.ml.transform.transform_to_predictions` — both legacy ML pre-SAP-rewrite call sites; rip when those migrate.
+
+### Deferred work (named in Appendix L slice 3)
+
+- **000490 / cohort SAP-integer closure (residual hunt).** Next ticket. Suspects above. Driven by user's next batch of test fixtures (battle-testing the engine) → emergent residual identification.
+- **`predicted_lighting_kwh` deletion.** Future cleanup ticket once `domain.ml.ecf` + `domain.ml.transform` are off the legacy heuristic.
+- **RdSAP10 → API integration test.** End-state e2e harness: RdSAP API response → `cert_to_inputs` → `calculate_sap_from_inputs` → SAP integer = lodged integer. Once enough cohort fixtures pass delta=0 on isolated components.

docs/sap-spec/SPEC_COVERAGE.md

@@ -14,7 +14,7 @@ The canonical SAP10.2 algorithm lives in [`2026-05-19-17-18 RdSap10Worksheet.xls
 | 2 | 121–206 (approx) | Ventilation | `worksheet/ventilation.py` | Partial | No mechanical ventilation (MVHR/MEV), no wind-shelter factor, no pressure-test override (worksheet lines 17-18), no AP4 override (worksheet line 19) |
 | 3 | 121–207 | Heat transmission | `worksheet/heat_transmission.py` | **Full (non-RR)** | LINE_31/33/36/37 exact for both non-RR Elmhurst fixtures (000474, 000490). Suspended-timber + Table 20 exposed-floor routes wired. RR sub-areas (gable/slope/stud-wall) deferred until `SapRoomInRoof` carries them. Global y-factor (Table R2 per-junction deferred). |
 | 4 | 207–304 | Hot water + Appendix J + Appendix D | `worksheet/water_heating.py` + cert_to_inputs `_water_heating_worksheet_and_gains` + `_apply_water_efficiency` | **Closed for combi-gas — PCDB Table 3b combi loss + Equation D1 monthly cascade wired.** Worksheet line refs (42)..(65) + Appendix D §D2.1 (2) Equation D1 (`water_efficiency_monthly_via_equation_d1`) + Appendix J Table 3b row 1 (`combi_loss_monthly_kwh_table_3b_row_1_instantaneous`). 000474 + 000490 HW kWh match PDF to ≤0.1%. cert_to_inputs splits the §4 worksheet from the efficiency divisor: (45..65) runs early so §5 has (65)m heat gains; HW fuel kWh computed after §8 produces (98c)m for the Eq D1 cascade. PCDB Table 105 parser exposes 5 new combi-loss fields (separate_dhw_tests, r1, F1, F2, F3 + subsidiary_type + store_type) per BRE PCDF Spec v1.0 §7.11. **Deferred**: Cylinder + solar + WWHRS + PV diverter + FGHRS branches (no fixture yet); Table 3b storage / FGHRS rows (no fixture yet); Table 3c two-profile boilers (no fixture yet); Electric CPSU Appendix F path (no fixture yet). |
-| 5 | Internal gains + Appendix L | `worksheet/internal_gains.py` | **Full** | Worksheet-driven (66)..(73), Table 5 Column A, Table 5a 9-row dispatch + heating-season mask, Appendix L L1-L12 with RdSAP §12-1 bulb defaults + Table 6d Z_L (light access factor). Wired into `calculator.py` via `cert_to_inputs`. Six Elmhurst fixtures conform end-to-end to ≤0.6% lighting / ≤0.2 W (73). |
+| 5 | Internal gains + Appendix L | `worksheet/internal_gains.py` | **Full** | Worksheet-driven (66)..(73), Table 5 Column A, Table 5a 9-row dispatch + heating-season mask, Appendix L L1-L12 with RdSAP §12-1 bulb defaults + Table 6d Z_L (light access factor). Wired into `calculator.py` via `cert_to_inputs`. Six Elmhurst fixtures conform end-to-end to ≤0.6% lighting / ≤0.2 W (73). **Appendix L slice update**: `annual_lighting_kwh` surfaced as a public leaf returning the worksheet-lodged (232) value (Σ L11 monthly distribution; cosine integral 0.998539). `InternalGainsResult.lighting_kwh_per_yr` exposes the same value so `cert_to_inputs` populates `inputs.lighting_kwh_per_yr` from the cascade — single source of truth shared with §5 (67). New worksheet-level per-component pin: `internal_gains_from_cert(...).lighting_kwh_per_yr` matches U985 (232) to abs=1e-4 for all 6 Elmhurst fixtures (000474:139.9452, 000477:201.6754, 000480:212.5531, 000487:227.6861, 000490:171.4217, 000516:230.8853). |
 | 6 | Solar gains + Tables 6b/6c/6d + Appendix U | `worksheet/solar_gains.py` | **Full** | Worksheet-driven (74)..(83). Table 6b g⊥ via manufacturer `window_transmission_details` first, Table 6b code lookup fallback; Table 6c FF by frame_material substring; Table 6d Z (heating column) by `OvershadingCategory`; roof windows pitched at RdSAP10 Table 24 default 45°; rooflights horizontal per §U3.2 p128. `solar_gains_from_cert` wired into `cert_to_inputs` + `calculator.py`. Six Elmhurst fixtures conform end-to-end to ≤5e-3 W on (83) + (84). |
 | 7 | Mean internal temperature | `worksheet/mean_internal_temperature.py` | **Full** | Worksheet-driven (85)..(94) via `mean_internal_temperature_monthly`. Table 9c steps 1-9 sequential (per-zone η: (86) η_living at Ti=T_h1, (89) η_elsewhere at Ti=T_h2, (94) η_whole at Ti=(93)). Table 9b u-formula consumes weighted R for two-main case 1 (single-main is default). Wired into `calculator.py` + `cert_to_inputs` via two new `CalculatorInputs` fields. Six Elmhurst fixtures conform end-to-end to ≤5e-3 °C on all 9 line tuples + 2 scalars per month (588 assertions). Table 4e adj defaults 0 (cert-side mapping deferred — all 6 fixtures = 0); two-main case 2 (different parts heated separately) deferred. |
 | 8 | Off-period temperature reduction | inline in `mean_internal_temperature.py` | Full | Table 9b implemented |
@@ -44,7 +44,7 @@ The canonical SAP10.2 algorithm lives in [`2026-05-19-17-18 RdSap10Worksheet.xls
 | H | Solar water heating | Partial | Boolean `has_solar_water_heating` reduces HW by 250 kWh; no actual collector calc |
 | J | Hot water demand | Partial | See §4 row above |
 | K | Thermal bridging | Partial | Using global y per age band (per ADR-0009 grill: per-junction Table R2 deferred) |
-| L | Lighting | Full | Existing-dwelling fallback ✓ |
+| L | Lighting | **Full (cost + gains)** | Existing-dwelling L1-L12 cascade + RdSAP §12-1 bulb defaults + Table 6d Z_L. **Closed both sides**: §5 (67) gains side (`lighting_monthly_w`) + cost side (`annual_lighting_kwh` → `InternalGainsResult.lighting_kwh_per_yr` → `inputs.lighting_kwh_per_yr`). Replaces the legacy `predicted_lighting_kwh` heuristic which over-counted ~3× on the Elmhurst cohort. 000474 SAP integer closes to delta=0 vs PDF. Legacy heuristic kept in `domain/ml/demand.py` with deprecation note for the unmigrated `domain.ml.ecf` + `domain.ml.transform` callsites — see ADR-0010 amendment 2026-05-22. |
 | M | PV / wind / hydro generation | Partial | PV ✓ (S-B19); wind / hydro / micro-CHP not implemented |
 | N | Micro-CHP | Not implemented | Rare |
 | P | Electric storage heaters detail | Partial | Identified via codes 401-409; Table 12a high-rate fractions not exact (we use 100% off-peak per cert-calibration heuristic) |

packages/domain/src/domain/ml/demand.py

@@ -230,6 +230,15 @@ def predicted_lighting_kwh(
     Base demand ~ 9.3 * TFA kWh/yr; reduced by low-energy bulb share.  LED
     bulbs cut consumption by ~50%, CFL by ~40%, incandescent by 0%.
     Missing counts treated as zero.
+
+    DEPRECATED for SAP rating use. The spec-faithful Appendix L L1-L11
+    cascade is in `domain.sap.worksheet.internal_gains.annual_lighting_kwh`
+    and is what `cert_to_inputs` now plumbs into `inputs.lighting_kwh_per_yr`.
+    This heuristic over-counts ~3× on the Elmhurst cohort (528 vs 140 kWh
+    on 000474). Kept only for `domain.ml.ecf.energy_cost_factor` and
+    `domain.ml.transform.transform_to_predictions` — legacy ML predictor
+    callsites that pre-date the SAP rewrite. Rip when those migrate.
+    See ADR-0010 amendment "Appendix L lighting (2026-05-22)".
     """
     if total_floor_area_m2 is None or total_floor_area_m2 <= 0:
         return 0.0