## Proposal: extend the public boundary from machine-level COP\* to "electricity at the meter" Full proposal (17 numbered items, 20-row verification ledger, per-component honest status, reviewed and revised through this repo's gate chain): [`heatpump-validation` — `doc/upstream_proposal_heatpumpmodel.md`](https://git.persee.minesparis.psl.eu/planeterr/heatpump-validation/-/blob/main/doc/upstream_proposal_heatpumpmodel.md). This issue is the executive summary and the tracking anchor; the document is the proposal. **Version note**: drafted against `0.1.0`; `0.2.0`/`0.2.1` shipped meanwhile (dpe module, G/W design-point fix). Read every "0.2.x" in the document as "a future minor", and the release-separability ask (§5.3) as applying to whichever minor carries #2's physics change. ### The case, in three sentences The ADEME "100 PACs" validation established that the campaign's `pac` channel is a distribution-board meter — the measured quantity is an SPF4-like total (compressor + controls + standby + circulators + usually the source pump) for 88 of 100 dwellings. What consumers ultimately need to predict is therefore `E_total = E_compressor + E_backup + E_aux (+ E_DHW on the 61 % of the fleet that is dual-service)`; the package currently predicts only the first two terms. Two additive layers exist, field-exercised on 70 dwellings under a pre-registered validation design, and are offered for adoption — with their honest status, which includes pre-registered FAILs. ### What is proposed (and its status, abbreviated — the document carries the full wording) - **P5-A, auxiliary layer** (standby / load-side circulator / source pump), with the *metering perimeter* as a first-class concept: installation facts in, derived boundary label out. Status: the API shape and conventions are offered; the circulator's central coefficient is **not** — it runs +15…+51 % above the campaign's own same-sample estimate (a property of the estimator, not the sample; pre-registered as a FAIL and reported, never tuned), and the document proposes shipping it as a named, explicitly-passed constant object. - **P5-B, DHW conversion layer** (`DHWConfig`/`dhw_electricity`, `HeatPumpConfig`-based signature so it is invariant to #2's branch decision). Status: prototyped and gated **as a diagnostic**; its pre-registered rule returns FAIL on the total-electricity clause; the isolated increment agrees with a measurement-backed split target to median −0.21 COP (a lower bound; the target's own fidelity 1.00–1.13×) on 34 dwellings. - **P5-C, sizing API**: the `converged` flag of #3 extended to cover the third silent path (`max_iter` midpoint); an explicit declared-capacity override (reference implementation exists; `T_biv` diagnostics must be invalidated, not carried); a configurable backup-fraction target. The evidence says **neither** sizing convention reproduces measured backup behaviour (28× over / 44× under) — the ask is "expose the choice, document both", not "declared is right". ### The two structural asks 1. **Release separability (§5.3)**: the resolution of #2 (the two-branch COP structure) is a physics change; the additive layers are not. Ship them in separate minors (preferred) or make the curve selection opt-in — bundling them forces every consumer to take a physics change to get an API extension. 2. **What gates adoption downstream (§5.2, §6)**: `heatpump-validation` pins `<0.2` with a behaviour guard executed by its DAG; any adoption lands there only through a gated re-baseline. The repo offers its pre-registered decomposition machinery and 70-site sample as the acceptance harness for any future minor — with the explicit statement that **no criterion in that set is a release gate** (several already FAIL on 0.1.0); their value is returning the same or different FAILs on the next version. The only gates are reproduction and review. ### Relationship to the open issues - #2 (two-branch curve): the layers are designed to be invariant to either resolution — argument traced in §5.1 against the actual API. - #3 (converged flag): subsumed and extended by P5-C1. - #4 (HP-F2 partial-NaN): orthogonal; noted in §5 as the one open item that could move validation sites (through the accounting barrier, loudly). ### Prerequisites named in the document A licence on `heatpump-validation` (none exists today — tracked there as an owned standing item) before any code transfer; and the maintainer-burden/ownership questions of §5.4, including: adopting the layers without their tests (1,484 lines) is worse than not adopting them.