docs: handover post S0380.146..147

Captures the two slices that closed oil 1 from +2.66 → +1.18 SAP via Table 3 primary-loss extension (.146) + Appendix D §D2.1 (2) Equation D1 wiring for non-PCDB Table 4b boilers (.147). Highlights the user directive that surfaced this session ("BRE/Elmhurst software follows spec exactly; no special non-spec handling") and the resulting pin shifts on cert 0240 + 6035 (combi-no-cylinder golden fixtures re-pinned per spec correctness). Ranks next-slice candidates: oil 1 Table 4f auxiliary energy (~+0.4 SAP closure remaining), electric 5 -1.43 regressed by .145, solid fuel 2/3 anthracite outliers, community heating + electric storage unblocking. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-08 11:17:27 +00:00 · 2026-06-01 08:26:04 +00:00 · 2026-06-01 08:26:04 +00:00 · c9c418be64
commit c9c418be64
parent 54ed142512
1 changed files with 255 additions and 0 deletions
--- a/domain/sap10_calculator/docs/HANDOVER_POST_S0380_147.md
+++ b/domain/sap10_calculator/docs/HANDOVER_POST_S0380_147.md
@ -0,0 +1,255 @@
+# Handover — post Slices S0380.146..147
+
+Branch: `feature/per-cert-mapper-validation`. **HEAD `7dceeff2`**.
+Predecessor: [`HANDOVER_POST_S0380_145.md`](HANDOVER_POST_S0380_145.md).
+
+## TL;DR
+
+Two slices landed on top of `1636cfbc` (handover commit). Both close
+non-PCDB Table 4b boiler gaps that combined to drive the oil 1
+residual. Oil 1 SAP +2.66 → +1.18, with HW fuel cascade now exact at
+worksheet (219) 3638.99 kWh/yr (Eq D1 monthly back-solve verified
+Jan 81.83 / May 79.94 / Jun-Sep 72 / Dec 81.86 against worksheet).
+
+| Slice | Commit | Scope |
+|---|---|---|
+| S0380.146 | `bd193e06` | SAP 10.2 Table 3 row 1 — extend `_primary_loss_applies` Elmhurst-path fallback for Table 4b non-PCDB regular boilers + cylinder. New `_TABLE_4B_COMBI_OR_CPSU_CODES` zero-loss exclusion set per Table 3. Oil 1 (59) annual ≈ 510 kWh/yr matches worksheet. |
+| **S0380.147** | **`7dceeff2`** | **SAP 10.2 Appendix D §D2.1 (2) Equation D1 — wire monthly (winter, summer) cascade for non-PCDB Table 4b boilers. New `tables/table_4b.py` carries 41-row (winter, summer) dict verbatim from spec PDF p.168. `_apply_water_efficiency` parameter refactored to explicit `eq_d1_winter_summer_pct: Optional[tuple[float, float]]`. Call site resolves: PCDB → Table 4b fallback (when WHC=901). §9.4.11 -5pp interlock symmetric on both columns. Oil 1 HW fuel exact (3638.99 ≡ worksheet). Cert 0240 + 6035 golden re-pinned (combi-no-cylinder now uses spec-correct Eq D1).** |
+
+Extended handover suite at HEAD: **890 pass, 0 fail.** Pyright net-zero
+(44 = 44).
+
+## Critical user directive discovered this session
+
+> "The software doesnt gave special non spec handling"
+
+The BRE-approved Elmhurst lodging software follows spec exactly. When a
+spec-correct fix shifts a cohort cert pin, the pre-fix near-zero state
+was masking offsetting cascade gaps — NOT a deliberate non-spec rule.
+Don't add empirical "only fire when X is lodged" gates to keep certs
+happy. Apply spec uniformly + re-pin + document.
+
+This is captured in new memory
+[`feedback-software-no-special-handling`](../../../home/vscode/.claude/projects/-workspaces-model/memory/feedback_software_no_special_handling.md).
+
+The initial S0380.147 implementation gated the new Table 4b Eq D1
+branch on cylinder presence to avoid shifting cert 0240 + 6035 (combi-
+no-cylinder). User pushed back; the cylinder gate was removed and the
+two certs re-pinned with documentation explaining the shift.
+
+## Current residual state at HEAD `7dceeff2`
+
+### Cascade-OK tier (25 variants on pin grid) — sorted by |ΔSAP_c|
+
+| Variant | SAP code | ΔSAP_c | Δcost | ΔPE | Notes |
+|---|---:|---:|---:|---:|---|
+| solid fuel 6 | 160 | +0.03 | -£0.65 | +45 | |
+| electric 1 | 191 | -0.06 | +£1.32 | +94 | |
+| solid fuel 8 | 160 | -0.08 | +£1.85 | +45 | |
+| **electric 3** | **401** | **-0.09** | **+£2.01** | **+82** | closed via S0380.145 |
+| solid fuel 7 | 160 | +0.10 | -£2.33 | +17 | |
+| electric 9 | 421 | -0.12 | +£2.72 | +91 | |
+| solid fuel 10 | 634 | -0.16 | +£3.70 | +67 | |
+| solid fuel 5 | 153 | -0.17 | +£3.81 | +93 | |
+| **electric 6** | **404** | **-0.17** | **+£3.91** | **+103** | closed via S0380.145 |
+| electric 2 | 524 | -0.18 | +£4.24 | +393 | closed via S0380.145; PE outlier |
+| solid fuel 9 | 636 | -0.20 | +£4.51 | +93 | |
+| **electric 7** | **408** | **-0.20** | **+£4.71** | **+113** | closed via S0380.145 |
+| ashp | — | +0.24 | -£5.57 | -12 | (closed) |
+| solid fuel 11 | 634 | -0.26 | +£6.07 | +104 | |
+| electric 8 | 409 | -0.26 | +£5.92 | +126 | |
+| solid fuel 4 | 633 | -0.29 | +£6.73 | +90 | |
+| oil pcdb 1/2 | (PCDB) | +0.42 | -£9.77 | -84 | (closed) |
+| pcdb 1 | (PCDB oil) | +0.57 | -£12.55 | -109 | closed via S0380.141..143 |
+| gshp | — | +1.15 | -£26.48 | -455 | open |
+| oil pcdb 3 | (PCDB) | +1.16 | -£26.72 | -271 | open |
+| **oil 1** | **127** | **+1.18** | **-£27.12** | **-276** | **closed via S0380.146..147 (Table 4f gap remaining)** |
+| solid fuel 3 | 160 | +1.32 | -£30.45 | -935 | PE outlier |
+| **electric 5** | **402** | **-1.43** | **+£32.85** | **+535** | regressed by S0380.145 |
+| solid fuel 2 | 158 | +2.64 | -£60.79 | -1211 | PE outlier |
+
+Σ |ΔSAP_c| across 25 variants ≈ **10.7 SAP points** (was 12.2 pre-
+session, **-12%** progress).
+
+### Blocked tier (16 variants — `MissingMainFuelType`)
+
+Unchanged from previous handover. Categories: community heating × 5,
+electric storage 11-14, no system, oil 2-6, pcdb 3.
+
+## Next-slice candidates ranked by leverage
+
+### 1. **oil 1 SAP +1.18 / cost -£27 / PE -276** — Table 4f auxiliary energy
+
+Cascade pumps_fans = **130 kWh/yr** vs worksheet (231) **265 kWh/yr**
+— under by 135 kWh. Breakdown:
+- Worksheet (230c) central heating pump = **165 kWh** (cascade has 130).
+- Worksheet (230d) oil boiler pump = **100 kWh** (cascade has 0).
+
+Per SAP 10.2 Table 4f (PDF p.174). Closing both should drop cost
+residual by ~£18.50 and SAP residual by ~0.8 → oil 1 closes to ~+0.4.
+
+### 2. **electric 5 SAP -1.43** — regressed by S0380.145, still open
+
+Pre-S0380.145 was +0.07 (offsetting bugs). Post-slice with +0.4 K Table
+4e adjustment applied correctly: cascade now OVER worksheet SH by
+~248 kWh. Likely §9 MIT calc for fan-assisted storage heater R=0.40
+(code 402) OR Table 9b Tsc formula divergence.
+
+### 3. **solid fuel 2 (+2.64) / 3 (+1.32) PE -935..-1211** — anthracite outliers
+
+Both Table 4a codes 158/160. Distinct cause from oil 1. Per-variant
+probe required. Likely Table 4b solid-fuel efficiency, Table 4f
+auxiliary, or §9 anthracite-specific secondary fraction.
+
+### 4. **gshp +1.15, oil pcdb 3 +1.16** — mid-tier
+
+Each needs its own probe. gshp is heat-pump PCDB Table 362 dispatch;
+oil pcdb 3 is gas/oil PCDB Table 322 with different boiler model.
+
+### 5. **Community heating unblocking (5 variants)** — sizable
+
+Extend extractor to capture §14.1 Community Heating block (heat-network
+codes 41-58).
+
+### 6. **Electric storage unblocking (variants 11-14)** — small
+
+Extend `_ELMHURST_MAIN_HEATING_EES_TO_FUEL_CODE` for EES codes WEA,
+REA, OEA.
+
+### 7. **Investigate cert 0240 / 6035 PE residual sources**
+
+Slice S0380.147 shifted these from +0.05 / +46.10 PE to +1.02 / +47.29.
+The +1 kWh/m² delta likely indicates:
+- Dual-main Q_space split missing: cert 0240 is dual-main (51%/49%).
+  Spec says Q_space in Eq D1 = (98c)m × (204) [Main 1 fraction], but
+  cascade passes full (98c)m. Cascade over-counts Q_space → η_m closer
+  to winter → HW fuel under. The Δ shift suggests this gap is real
+  but compounded.
+- Table 4f auxiliary energy gap (same as oil 1).
+- Possibly other §4 cascade gaps unmasked by the spec-correct Eq D1.
+
+## Important diagnostic findings from this session
+
+1. **Two compound bugs for non-PCDB Table 4b oil boilers + cylinder:**
+   primary loss missed (Table 3 row 1) + Eq D1 not wired. Required two
+   slices to close. The probe-monkey-patch-verify workflow caught
+   both before implementing either.
+
+2. **Coincidence-zero closures break under spec correctness.** Cert
+   0240 + 6035 were pinned at +0.05 PE residual pre-slice (looked
+   "close to zero"). My spec-correct Eq D1 fix moved them to +1.02 /
+   +1.20. The pre-slice near-zero was masking ~1 kWh/m² of offsetting
+   cascade gaps. Per the user's directive: spec is paramount, re-pin
+   shows the real underlying state.
+
+3. **PCDB and Table 4b are separate cascade paths.** Eq D1 was already
+   wired for PCDB (since S0380.141); Table 4b non-PCDB was the gap.
+   Both use the same `water_efficiency_monthly_via_equation_d1`
+   helper — `_apply_water_efficiency` now takes the (winter, summer)
+   pair explicitly instead of a `GasOilBoilerRecord`, so future
+   extensions (Table 4a category-fallback, etc.) plug in cleanly.
+
+## Standard slice workflow
+
+1. Read spec page + identify rule
+2. Probe one cluster variant; verify diagnosis via monkey-patch
+3. Write failing AAA test (literal `# Arrange / # Act / # Assert`)
+4. Implement helper / dispatch entry / mapper extension
+5. Re-pin affected variants (DO NOT widen tolerance)
+6. Run extended handover suite (command below)
+7. Pyright net-zero check (`git stash` → pyright → `git stash pop` →
+   pyright)
+8. Commit with spec citation +
+   `Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>`
+9. Update `project-heating-systems-corpus` + `MEMORY.md` index
+
+## Test baseline at HEAD `7dceeff2`
+
+```bash
+PYTHONPATH=/workspaces/model python -m pytest \
+    backend/documents_parser/tests/test_summary_pdf_mapper_chain.py \
+    backend/documents_parser/tests/test_heating_systems_corpus.py \
+    backend/documents_parser/tests/test_elmhurst_extractor.py \
+    backend/documents_parser/tests/test_elmhurst_end_to_end.py \
+    domain/sap10_calculator/worksheet/tests/test_e2e_elmhurst_sap_score.py \
+    domain/sap10_calculator/worksheet/tests/test_heat_transmission.py \
+    domain/sap10_calculator/worksheet/tests/test_internal_gains.py \
+    domain/sap10_calculator/worksheet/tests/test_solar_gains.py \
+    domain/sap10_calculator/worksheet/tests/test_dimensions.py \
+    domain/sap10_calculator/worksheet/tests/test_rating.py \
+    domain/sap10_calculator/worksheet/tests/test_ventilation.py \
+    domain/sap10_calculator/worksheet/tests/test_appendix_h_solar.py \
+    domain/sap10_calculator/worksheet/tests/test_mev.py \
+    domain/sap10_calculator/rdsap/tests/test_cert_to_inputs.py \
+    domain/sap10_calculator/rdsap/tests/test_golden_fixtures.py \
+    domain/sap10_calculator/tests/test_pcdb_table_322_lookup.py \
+    domain/sap10_calculator/tests/test_pcdb_table_329_lookup.py \
+    domain/sap10_calculator/tests/test_table_12a.py \
+    --no-cov -q
+```
+
+Expected: **890 pass, 0 fail**.
+
+## Memories to load (in order)
+
+```
+project-heating-systems-corpus            # HEAD 7dceeff2
+feedback-sap-10-2-only-never-10-3         # CRITICAL — never reference SAP 10.3
+feedback-software-no-special-handling     # NEW — spec is paramount, no empirical gates
+feedback-worksheet-not-api-reference
+feedback-spec-citation-in-commits
+feedback-verify-handover-claims
+feedback-zero-error-strict                # TARGET: ΔSAP_c < 1e-4 vs worksheet
+feedback-commit-per-slice
+feedback-aaa-test-convention
+feedback-e2e-validation-philosophy
+feedback-abs-diff-over-pytest-approx
+feedback-spec-floor-skepticism
+feedback-golden-residuals-near-zero
+feedback-one-e-minus-4-across-the-board
+reference-unmapped-sap-code
+reference-unmapped-api-code
+project-oil-price-spec-divergence
+```
+
+## What NOT to do
+
+- **Don't reference SAP 10.3** — track 10.2 deliberately
+- **Don't widen pin tolerances** to make pins pass — re-pin smaller
+  or find the spec gap
+- **Don't add empirical gates** to keep cohort pins stable when a
+  spec rule clearly applies — the BRE/Elmhurst software follows spec
+  uniformly per `feedback-software-no-special-handling`
+- **Don't re-investigate Slices .91..147** — all settled
+- **Don't add new helpers to `domain/sap10_ml/`** — on deprecation
+  path; `domain/sap10_calculator/tables/` is the canonical home
+- **Don't treat ΔSAP=0.07 as "closed"** — it might be offsetting bugs.
+  Target is < 1e-4 vs worksheet.
+
+## Spec source quick-reference
+
+All under `domain/sap10_calculator/docs/specs/`:
+
+- **SAP 10.2 full spec**: `sap-10-2-full-specification-2025-03-14.pdf`
+  - **§4** (p.135-137) — water heating worksheet (45..65)
+  - **§9** (p.155+) — MIT calc, Tables 9/9a/9b/9c
+  - **§9.4.11** (p.30) — Boiler interlock: -5pp to BOTH SH and DHW
+  - **§A.2.2** (~p.189) — Forced-secondary set "401 to 407, 409 and 421"
+  - **Table 3** (p.160) — Primary circuit loss; zero-loss list
+  - **Table 4a** (p.163-170) — heating systems incl. R column
+  - **Table 4b** (p.168) — gas/liquid boilers seasonal efficiency, codes 101-141
+  - **Table 4c** (p.169-170) — Efficiency adjustments
+  - **Table 4d** (p.170) — heat-emitter R
+  - **Table 4e** (p.170-173) — heating system controls + temperature adjustment
+  - **Table 4f** (p.174) — pumps + fans (NEXT — oil 1 / etc.)
+  - **Table 9** (p.182) — heating periods and temperatures
+  - **Table 9c** (p.184) — heating requirement (step 8 Table 4e adj)
+  - **Table 11** (p.188) — secondary heating fraction
+  - **Table 12** (p.191) — SAP rating fuel prices
+  - **Table 12a** (p.191) — high/low-rate fraction by system × tariff
+  - **Appendix D §D2.1 (2)** (p.57) — Eq D1 monthly water eff cascade
+- **RdSAP 10 spec**: `RdSAP 10 Specification 10-06-2025.pdf`
+  - **§10.11 Table 29** (p.56) — Heating/HW parameters; inaccessible cylinder
+  - **§19 Table 32** (p.95) — RdSAP10 fuel prices / CO2 / PE
+
+## Good luck.