docs: handover for Table 3a no-keep-hot continuation + SAP 10 spec PDFs

Adds the next-agent handover and the BRE technical papers referenced
by the cohort-2 negative-band investigation:

  - `HANDOVER_TABLE_3A_NO_KEEP_HOT.md` — picks up from Slice S0380.20.
    Covers cohort distribution at HEAD `4879e8c3`, the verified
    Table 3a Row 1 spec formula `(61)m = 600 × fu × nm / 365`, the
    dispatch recipe for `pcdb_combi_loss_override`, watch-outs (cert
    0360 / cohort-1 cert 000490 behaviour after the slice lands), the
    diagnostic probe script, test baselines, and the open-thread
    priority list (Ext1 roof, HP-COP, big-gap 2102, API path, parity).

  - `specs/STP09-B04_Combi_boiler_tests.pdf` — 2009 BRE methodology
    paper (Alan Shiret, BRE) defining the combi-loss test programme
    that produced the SAP Table 3a 600/900 kWh/yr keep-hot assumptions.
    Source: https://bregroup.com/documents/d/bre-group/stp09-b04_combi
    _boiler_tests.

  - `specs/sap10 technical papers/S10TP-{02..13}.pdf` — full SAP 10
    supporting technical paper set (Issue 1.2 / 1.3 / 1.4 across the
    eight papers). S10TP-12 §9.4 confirms: "No changes to the SEDBUK
    calculation method for water heating efficiency were considered
    necessary" — so the STP09-B04 (SAP 2009) Table 3a methodology
    carries through to SAP 10 unchanged.

These docs replace web-fetched references with locally-tracked copies
so the slice S0380.21 implementor can grep / pdftotext them directly.

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

domain/sap10_calculator/docs/HANDOVER_TABLE_3A_NO_KEEP_HOT.md

@@ -0,0 +1,373 @@
+# Handover — Table 3a no-keep-hot combi loss + cohort-2 closure continuation
+
+Branch `feature/per-cert-mapper-validation`. This session shipped
+**5 slices** (S0380.16 → S0380.20) closing the cohort-2 cylinder /
+glazing / party-wall / shower-count gaps, and surfacing the **PCDB
+keep-hot Table 3a sub-row gap** as the next forcing function via
+strict-raise. Picks up from `HANDOVER_38_CERT_COHORT_EXPANSION.md`.
+
+**HEAD at handover start:** `4879e8c3` (Slice S0380.20: extract PCDB
+keep-hot fields + strict-raise for no-keep-hot combis with sdt=0).
+
+## User's stated goal (carried forward verbatim)
+
+> I've added some more test cases, in the same format, in here:
+> `sap worksheets/additional with api 2`
+> We should check that the Elmhurst mapping works and then the api
+
+The Elmhurst Summary-path mapping work this session was driven by the
+**1e-4 target across the board** (incl. HP certs) per
+[[feedback-one-e-minus-4-across-the-board]] — the previous session's
+±0.07 "Appendix N3.6 PSR-precision floor" claim was rejected by the
+user. The user is comfortable working toward `abs(delta) < 1e-4` for
+every cert.
+
+API-path mapping work (cohort-2 API JSON fetch + chain tests + cross-
+mapper EPC parity) is **still deferred** — Elmhurst Summary path is
+shippable and well-instrumented, the API path is fetchable but not yet
+mirrored.
+
+## Spec docs available
+
+The repo now contains the full SAP 10 BRE technical paper set under
+`domain/sap10_calculator/docs/specs/`:
+
+  - `sap-10-2-full-specification-2025-03-14.pdf` (existing, primary)
+  - `sap-10-3-full-specification-2026-01-13.pdf` (existing, latest)
+  - `RdSAP 10 Specification 10-06-2025.pdf` (existing)
+  - `PCDF_Spec_Rev-06b_12_May_2021.pdf` (existing)
+  - **`STP09-B04_Combi_boiler_tests.pdf`** *(added this session)* —
+    2009 BRE methodology paper, origin of the combi-loss Table 3a
+    600/900 kWh/yr keep-hot assumptions. Not superseded by SAP 10
+    paper S10TP-12, which explicitly states (§9.4) "No changes to the
+    SEDBUK calculation method for water heating efficiency were
+    considered necessary".
+  - `sap10 technical papers/` *(added this session)* — full set:
+      - `S10TP-02` Chimneys and flues
+      - `S10TP-03` Heat interface units
+      - `S10TP-04` Appendix H solar space heating change
+      - `S10TP-05` Thermal bridges
+      - `S10TP-06` Lighting amendments (canonical source for the
+        L1-L12 cascade in `worksheet/internal_gains.py`)
+      - `S10TP-07` PV self-use factor calculation
+      - **`S10TP-12`** Seasonal efficiency of condensing boilers (Feb
+        2023, Issue 1.2) — canonical for boiler efficiency / annual
+        offsets / standby heat loss in SAP 10. See §9.4 for the HW
+        efficiency "no changes" position.
+      - `S10TP-13` Mechanical ventilation system assumptions
+
+**Read STP09-B04 §5.3 ("Influence of Keep-hot facility") + SAP 10.2
+spec around Table 3a (pdftotext `sap-10-2-full-specification-2025-03-
+14.pdf | sed -n '15280,15410p'`) before implementing the no-keep-hot
+sub-row** — both lay out the formula derivations the next slice needs.
+
+## Slices shipped this session
+
+| Slice | Commit | What |
+|---|---|---|
+| S0380.16 | `6b1cdd64` | `"Normal"` cylinder → SAP code 2 (110 L). Unblocks 2 raise certs (2536, 9421). |
+| S0380.17 | `dab59ccf` | Map Elmhurst §11 glazing labels to SAP10 Table U2 int codes + strict-raise. Closed cert 3336 from +0.0674 → +0.0400. Cohort-1 mean residual +0.044 → +0.016. Cert 9418 now exact. |
+| S0380.18 | `57fbf83b` | `u_party_wall` flat-default per RdSAP10 Table 15 footnote*. Closed cert 0036 from -0.3737 → +0.2987. |
+| S0380.19 | `1f8a070f` | Count Elmhurst shower outlets by type (was: hardcoded `electric_shower_count=1`). Correctness-by-construction; cert 7800 shows 2 electric showers. |
+| S0380.20 | `4879e8c3` | Extract PCDB `keep_hot_facility` / `keep_hot_timer` from raw[57]/raw[58] (per the user's PCDB-spec breakthrough); strict-raise on no-keep-hot combis with sdt=0. Surfaces the Table 3a sub-row gap. |
+
+All on branch `feature/per-cert-mapper-validation`. Each slice includes
+unit tests, hand-built / chain-test updates as needed, pyright net-zero
+on touched files.
+
+## Cohort distribution at HEAD
+
+Cohort-2 (38-cert dataset) Summary-path probe:
+
+| Bucket (\|Δ\|) | Count | Notes |
+|---|---|---|
+| exact (<1e-4) | **10** | DG boilers (PCDF varies — TBD if all have keep-hot) |
+| 1e-4..0.07 | 13 | All triple-glazed HP certs — HP-COP cascade residual |
+| 0.07..0.5 | 2 | cert 0036 +0.30 (missing Ext1 roof), cert 7700 -0.44 (PCDF 17741 Table 3b — different issue) |
+| 0.5..1 | 1 | cert 9796 +0.55 |
+| >5 | 1 | cert 2102 -15.81 (HP routing — original big-gap) |
+| **RAISES (PCDB)** | **11** | unblocked by Table 3a no-keep-hot row (next slice) |
+
+Cohort-1 (7-cert ASHP + 2 newer): mean residual moved from +0.044 →
+**+0.016** (mainly from S0380.17 glazing fix), cert 9418 now **exact**
+at delta = +0.0000.
+
+## ★ Next concrete slice — Table 3a no-keep-hot row (S0380.21)
+
+**Goal:** implement SAP 10.2 Table 3a Row 1 ("Instantaneous, without
+keep-hot facility") so the 11 currently-raising cohort-2 certs cascade
+correctly. Closes most of the negative-band → +0.4 SAP band in one shot.
+
+### Spec formula (pdftotext-extracted from SAP 10.2 spec, p.160)
+
+Table 3a row 1:
+```
+(61)m = 600 × fu × nm / 365     kWh/month
+where  fu = V_d,m / 100  if V_d,m < 100; else 1.0
+       nm = days in month (Table 1a)
+       V_d,m = (44)m daily HW use
+```
+
+**Verified against cert 7800 worksheet (Jan)**: `600 × 0.7788 × 31/365
+= 39.67 kWh` vs worksheet (61)_Jan = 39.69 ✓ (delta 0.02 — sub-1e-4
+modulo Vd rounding).
+
+Other Table 3a rows (also need implementing eventually):
+
+| Row | Combi type | Formula |
+|---|---|---|
+| 1 | Instantaneous, without keep-hot | 600 × fu × nm / 365 |
+| 2 | Instantaneous, without keep-hot, with storage FGHRS | 540 × fu × nm / 365 |
+| 3 | Instantaneous, with keep-hot, time clock | 600 × nm / 365 ← **currently the only one implemented** |
+| 4 | Instantaneous, with keep-hot, NO time clock | 900 × nm / 365 |
+| 5 | Storage combi, Vc ≥ 55 L | 0 |
+| 6 | Storage combi, Vc < 55 L | [600 - (Vc - 15) × 15] × fu × nm / 365 |
+| 7 | Storage combi, Vc < 55 L, with storage FGHRS | [540 - (Vc - 15) × 13.5] × fu × nm / 365 |
+
+For S0380.21 you only need rows 1 + 4 (the keep-hot dispatch the strict-
+raise already gates on). Rows 2, 6, 7 (FGHRS variants) can wait until a
+fixture exercises them.
+
+### Where to implement
+
+1. `domain/sap10_calculator/worksheet/water_heating.py` — add
+   `combi_loss_monthly_kwh_table_3a_row_1_no_keep_hot()`:
+   ```python
+   def combi_loss_monthly_kwh_table_3a_row_1_no_keep_hot(
+       *,
+       daily_hot_water_monthly_l_per_day: tuple[float, ...],
+   ) -> tuple[float, ...]:
+       return tuple(
+           600.0 * min(1.0, v_d / 100.0) * n_m / 365.0
+           for v_d, n_m in zip(daily_hot_water_monthly_l_per_day, _DAYS_IN_MONTH)
+       )
+   ```
+   And similarly `..._row_4_keep_hot_no_time_clock()` returning
+   `tuple(900.0 * n / 365.0 for n in _DAYS_IN_MONTH)`.
+
+2. `domain/sap10_calculator/rdsap/cert_to_inputs.py
+   :pcdb_combi_loss_override` — extend the existing keep-hot guard
+   (currently raises `UnresolvedPcdbCombiLoss`) to dispatch via
+   `keep_hot_facility` / `keep_hot_timer`:
+   ```python
+   if sdt in (0, None):
+       kh = pcdb_record.keep_hot_facility
+       timer = pcdb_record.keep_hot_timer
+       if kh in (0, None):
+           return combi_loss_monthly_kwh_table_3a_row_1_no_keep_hot(
+               daily_hot_water_monthly_l_per_day=daily_hot_water_monthly_l_per_day,
+           )
+       # kh ∈ {1, 2, 3} = keep-hot present
+       if timer == 1:
+           return None  # row 3 = 600 kWh/yr, cascade default already does this
+       return combi_loss_monthly_kwh_table_3a_row_4_keep_hot_no_time_clock()
+   ```
+   Drop the raise once the dispatch is complete.
+
+3. Verify: probe cohort 2 — the 11 currently-raising certs should now
+   land in the [exact / ≤1e-4] band (or close to it). Cert 7800 should
+   close to within ±1e-4 of worksheet 64.7504.
+
+4. Re-add the 2 golden cert tests for `0390-2954-3640-2196-4175`
+   (Firebird oil PCDF 9005) to:
+   - `domain/sap10_calculator/rdsap/tests/test_golden_fixtures.py`
+     `_EXPECTATIONS` (with re-pinned residuals — the SAP value WILL
+     shift now that the combi loss is correct).
+   - Same file's `_PCDB_CHAIN_EXPECTATIONS`.
+
+### Watch-outs
+
+- **Electric keep-hot variants** (`keep_hot_facility ∈ {2, 3}`) require
+  per-spec routing of the keep-hot energy to electricity in (219)m
+  vs (217)m per Table 3a Note 2 (see pdftotext slice). Defer until a
+  fixture exercises — raise `UnresolvedPcdbCombiLoss` with a
+  "electric keep-hot dispatch not yet implemented" reason for now.
+
+- **Cert 0360-2266-5650-2106-8285** is currently exact (delta=0) under
+  the keep-hot 600 default. PCDF 15709's PCDB record lodges
+  `keep_hot_facility=None` (i.e. no keep-hot). After this slice, cert
+  0360 will SHIFT — the cascade will switch to Row 1 formula, but the
+  worksheet for cert 0360 uses the keep-hot 600 default. So either:
+    a) the worksheet's surveyor incorrectly enabled keep-hot for an
+       install that doesn't have it (assessor error), or
+    b) cert 0360's install legitimately does have keep-hot enabled
+       via a controller option PCDB doesn't surface.
+  The cascade should be **spec-correct per PCDB**, so we accept cert
+  0360 going from delta=0 → some negative delta. Update its chain
+  test pin if needed.
+
+- **Cohort 1 cert 000490** (Vaillant Ecotec Pro 28, PCDF 10328): PCDB
+  lodges `keep_hot_facility=1, keep_hot_timer=1` → Row 3 (`600 kWh/yr`
+  flat) — same as current cascade behaviour. Should stay GREEN.
+
+## Open threads (priority order)
+
+1. **★ Table 3a no-keep-hot (above)** — clear path, ~1-2 hour slice.
+2. **Cert 0036 missing Ext1 roof contribution** — worksheet (30) for
+   the Ext1 flat roof is U=2.30 × 1.09 m² = 2.51 W/K but cascade has
+   `roof_w_per_k = 0`. Look at `_map_elmhurst_roof` and the per-bp
+   roof routing. Should close cert 0036 from +0.30 → ~0.
+3. **HP-COP residual (10 triple-glazed certs at +0.001..+0.04)** —
+   territory the previous session called "Appendix N3.6 PSR-precision
+   floor". User has rejected that framing; the spread (cert 9418 at
+   delta=0 vs cert 0380 at +0.034 for same Mitsubishi PCDB 104568)
+   suggests it's cert-specific, not calculator-wide.
+   *Suggested first step:* audit `pcdb_table_362_heat_pumps.jsonl`
+   raw fields against the PCDF Spec — ChatGPT speculated the HP
+   records have analogous hidden fields (keep-hot has no analogue but
+   integral-cylinder / supplementary-heater fields might). Mirror the
+   audit pattern of Slice S0380.20 on Table 105.
+4. **Big-gap cert 2102 (-15.81 SAP)** — only remaining big-gap cert
+   after S0380.20 swept 6835 + 0652 into the RAISES band. Likely HP
+   mis-routing. Probe `main_heating_category` first.
+5. **API-path closure for all 38 cohort-2 certs** — fetch + persist
+   JSON via `EpcClientService._fetch_certificate`, mirror Summary
+   chain tests on the API path. The user's stated longstanding goal.
+6. **Cross-mapper EPC parity** (Summary EPC ≡ API EPC for load-bearing
+   fields) — user's longstanding north star.
+7. **Tighten cohort-1 chain tests** to 1e-4 once the residual is
+   closed. Currently pinned at ±0.07 in
+   `backend/documents_parser/tests/test_summary_pdf_mapper_chain.py
+   ::_ASHP_COHORT_CHAIN_TOLERANCE = 0.07`.
+
+## Methodology — preserved conventions
+
+Carried forward unchanged from prior sessions:
+
+- **1e-4 across the board** ([[feedback-one-e-minus-4-across-the-board]])
+  — HP certs target the same precision as boilers; reject any
+  "calculator precision floor" framing.
+- **Worksheet, not API, is the target** ([[feedback-worksheet-not-api-reference]]).
+- **One slice = one commit; stage by name** ([[feedback-commit-per-slice]]).
+- **AAA test convention** with literal `# Arrange / # Act / # Assert`
+  ([[feedback-aaa-test-convention]]).
+- **`abs(diff) <= tol`** not `pytest.approx` ([[feedback-abs-diff-over-pytest-approx]]).
+- **Spec citation in commit messages** ([[feedback-spec-citation-in-commits]]).
+- **Strict-enum raises on unmapped labels / unresolved cascade dispatch**
+  (Slices S0380.15, S0380.17, S0380.20 established the pattern).
+- **Pyright net-zero per file**.
+
+## Test baseline at HEAD
+
+```bash
+PYTHONPATH=/workspaces/model python -m pytest \
+    backend/documents_parser/tests/test_summary_pdf_mapper_chain.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_water_heating.py \
+    domain/sap10_calculator/worksheet/tests/test_mean_internal_temperature.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_362_lookup.py \
+    domain/sap10_ml/tests/test_rdsap_uvalues.py \
+    datatypes/epc/schema/tests/test_schema_loading.py \
+    --no-cov -q
+```
+
+Expected: **697 pass + 10 pre-existing fails** (9 × cert 001479 Layer 1
+hand-built skeleton + 1 × pre-existing FEE round-trip).
+
+Pyright per-file baselines (touched files):
+- `datatypes/epc/domain/mapper.py`: 32
+- `domain/sap10_calculator/rdsap/cert_to_inputs.py`: 35
+- `domain/sap10_calculator/worksheet/heat_transmission.py`: 13
+- `domain/sap10_ml/rdsap_uvalues.py`: 1
+- `domain/sap10_calculator/tables/pcdb/parser.py`: 0
+- `domain/sap10_calculator/tables/pcdb/__init__.py`: 0
+- `backend/documents_parser/tests/test_summary_pdf_mapper_chain.py`: 0
+- `backend/documents_parser/tests/test_elmhurst_end_to_end.py`: 0
+
+## Diagnostic probe script (carried forward from prior handover)
+
+```bash
+PYTHONPATH=/workspaces/model python <<'PY'
+import re, subprocess
+from collections import defaultdict
+from pathlib import Path
+from backend.documents_parser.tests.test_summary_pdf_mapper_chain import _summary_pdf_to_textract_style_pages
+from backend.documents_parser.elmhurst_extractor import ElmhurstSiteNotesExtractor
+from datatypes.epc.domain.mapper import EpcPropertyDataMapper, UnmappedElmhurstLabel
+from domain.sap10_calculator.rdsap.cert_to_inputs import (
+    cert_to_inputs, SAP_10_2_SPEC_PRICES, UnresolvedPcdbCombiLoss,
+)
+from domain.sap10_calculator.calculator import calculate_sap_from_inputs
+
+src_root = Path('/workspaces/model/sap worksheets/additional with api 2')
+buckets = defaultdict(list)
+def bucket(d):
+    a = abs(d)
+    if a < 1e-4: return "exact"
+    if a < 0.07: return "≤±0.07"
+    if a < 0.5: return "±0.07..0.5"
+    if a < 1: return "±0.5..1"
+    if a < 5: return "±1..5"
+    return "±5+"
+for cd in sorted(src_root.iterdir()):
+    if not cd.is_dir() or cd.name.startswith('.'): continue
+    sp = next(cd.glob("Summary_*.pdf"), None)
+    ws_pdf = next(cd.glob("dr87-*.pdf"), None)
+    if not (sp and ws_pdf): continue
+    out = subprocess.run(["pdftotext", str(ws_pdf), "-"], capture_output=True, text=True).stdout
+    m = re.search(r"SAP value\s*\n?\s*([\d.]+)", out)
+    ws_sap = float(m.group(1)) if m else None
+    try:
+        sn = ElmhurstSiteNotesExtractor(_summary_pdf_to_textract_style_pages(sp)).extract()
+        epc = EpcPropertyDataMapper.from_elmhurst_site_notes(sn)
+        r = calculate_sap_from_inputs(cert_to_inputs(epc, prices=SAP_10_2_SPEC_PRICES))
+        d = r.sap_score_continuous - ws_sap
+        buckets[bucket(d)].append((cd.name, d))
+    except UnresolvedPcdbCombiLoss as e:
+        buckets["RAISES (Pcdb)"].append((cd.name, e.pcdf_index))
+    except UnmappedElmhurstLabel as e:
+        buckets["RAISES (Elm)"].append((cd.name, str(e)))
+
+for b in ("exact", "≤±0.07", "±0.07..0.5", "±0.5..1", "±1..5", "±5+", "RAISES (Pcdb)", "RAISES (Elm)"):
+    if b in buckets:
+        print(f"\n[{b}] {len(buckets[b])}:")
+        for c, d in buckets[b]:
+            print(f"  {c}  {d}")
+PY
+```
+
+Mirror against `/workspaces/model/sap worksheets/Additional data with api`
+for cohort-1 cross-checks.
+
+## Memory references
+
+Cross-session memories load automatically. Key ones for this work:
+
+- [[feedback-one-e-minus-4-across-the-board]] — user target is 1e-4 for HPs too.
+- [[project-instantaneous-shower-cascade-gap]] — open thread on the Table 3a sub-row gap (now mostly addressed by Slice S0380.20 strict-raise; closing once Table 3a row 1 lands).
+- [[project-summary-path-cohort-closure]] — original 7-cert ASHP cohort context.
+- [[feedback-worksheet-not-api-reference]] — Summary path pins to worksheet, not API.
+- [[feedback-cascade-pin-methodology]] — test the actual cascade against PDF line refs.
+- [[feedback-commit-per-slice]] / [[feedback-aaa-test-convention]] /
+  [[feedback-abs-diff-over-pytest-approx]] / [[feedback-spec-citation-in-commits]] /
+  [[feedback-worksheet-shape-fidelity]] / [[feedback-zero-error-strict]] — slicing + test conventions.
+
+## First concrete actions for next agent
+
+1. **Re-run the diagnostic probe** to confirm baseline reproduces
+   (10 exact + 13 sub-±0.07 + 2 ±0.07..0.5 + 1 ±0.5..1 + 1 ±5+ + 11 RAISES).
+2. **Read** SAP 10.2 spec p.160 Table 3a (full text in this handover §
+   "Spec formula") + STP09-B04 §5.3-5.4 + the docstrings on
+   `domain/sap10_calculator/rdsap/cert_to_inputs.py:pcdb_combi_loss_override`
+   and `_water_heating_worksheet_and_gains`.
+3. **Implement Slice S0380.21** per the recipe above (Table 3a row 1
+   + row 4 + dispatch in `pcdb_combi_loss_override`, drop the strict-
+   raise once the dispatch covers it). Expect cert 7800 to close from
+   raise → delta < 1e-4 vs worksheet 64.7504.
+4. **Re-pin** the 2 golden cert tests for cert 0390-2954-3640-2196-4175
+   that were dropped in Slice S0380.20 (their cascade SAP will now
+   compute correctly, the residuals will shift — re-pin to the new
+   values).
+5. **Tighten** the original 7-cert ASHP cohort chain tests once the
+   triple-glazed HP-COP residual closes (item 3 in the open threads).
+6. **API path** — start fetching + persisting the 38-cert JSON via
+   `EpcClientService._fetch_certificate`. Pattern follows
+   `domain/sap10_calculator/rdsap/tests/fixtures/golden/*.json`.
+
+Good luck. Table 3a row 1 is the highest-leverage next slice — closes
+~25% of cohort 2 (and probably the cert-6835 big-gap by extension) in
+one commit.