[juaristi22]

Adds the constituency grain to the three DESNZ domestic energy targets: electricity and gas consumption in kWh, and gas-connected households. They already bind by local authority (#1286). This is #1095's "Constituency grain" item for energy. Bus stays at region grain (see below).

How the seat rows are made

DESNZ publishes no constituency cut. The new committed resource uk/desnz_constituency_energy_facts.json splits each authority's published 2024 total over its July 2024 constituencies. The split is in proportion to DESNZ's own LSOA (England and Wales, 2021) and data zone (Scotland, 2022) figures, which sit in the pinned feed (272c987, desnz.lsoa.electricity.cy2024 and desnz.lsoa.gas.gy2024) on the same release, periods and temperature bases as the authority rows.

• Each output area takes its LSOA's value times its share of the LSOA's census households, through the committed atomic supports.
• Each authority's total is shared among its constituency pieces in proportion to those keys. Every authority keeps its total, so the two grains' kWh cells agree within each region, and DESNZ's unallocated meters (0.09–0.14% of Great Britain) follow the split.
• Two steps are modelled, both small: each output area goes to one seat through ONS's best-fit lookup of 2021 output areas to July 2024 constituencies (NRS's lookup of 2022 output areas in Scotland), and the 990 small areas (2.4% of households) that fall in two seats are split by census households.
• Checks on the 2024 data: LSOA sums sit within 0.65% of each English or Welsh authority's total and data-zone sums within 0.7% of each Scottish council's; seat totals equal authority totals; every seat's gas meters over electricity meters lies in (0, 1].
• Gas-connected households do not agree across grains by construction: each area's cells are its census households times its own gas meters over its electricity meters. Once the census reconciliation brings both grains' households to one regional total, the seat and authority sums differ by under 0.2% in every region (0.06% over Great Britain). The fence says so.
• tools/build_uk_desnz_constituency_energy_facts.py builds it from the pinned feed (streamed and hashed against uk/chronicle_feed.json) and the atomic supports (hashed against their provenance). The method is in uk_runtime/desnz_constituency_energy.py. The loader refuses a resource built on another feed or other supports; the re-pin doc now says to rebuild it.

A census household split of each authority's total was measured and not taken (public data only). It makes use per household uniform within each authority. Against the small-area split it moved seats' gas by a median 4.3% (England and Wales; p90 15%, p99 36%) and 3.5% (Scotland; up to 38%), electricity by a median 3.0%, and the gas-connected share by a median 2.3 points (up to 30).

Bus stays at region grain

The feed carries BUS01 boardings by country, region and statistical scope only, with no authority or smaller-area rows. Seat rows could only spread a region's boardings by population, which carries no information.

What changes

• Contract (uk/uk_population_targets.json):
  • the three targets list both grains, with a Great Britain constituency area_scope;
  • the kWh selectors admit the derived rows by source (["desnz", "microcosm"]);
  • the gas-connected selector reads both grains' census households.
• Appliers (uk_runtime/domestic_energy_targets.py): the seat cells take the authority cells' level factor per fuel; the gas-meter-share applier reads a seat's meters off the split.
• Metrics: the energy metrics are appended to the constituency list under the append-only rule (22 → 25).
• Loss weight: under nation_grain_family_equal_sqrt_count, domestic energy is now a family in the constituency grain too. Its share of the loss weight rises from 1/36 (2.8%, one of nine local-authority families) to 1/36 + 1/20 (7.8%), and each other constituency family's share falls from 6.25% to 5%. Its floor is 2.5%.
• Census: the family lists the derived resource as its seat source. Cross-grain: the route and partition reasons say why the single-winner rule rescales the authority cells by one.
• Every compile reads the derived resources: uk_runtime/derived_facts.py lists both committed derived resources, and the full-build targets, the parity receipt tool, the release-cut certifier and the UC matrix diagnostic read it. Both UK target kernels hash the two new modules (uk_runtime/target_compile_modules.py). A list-valued source_name now prefilters the generator's facts to its sources, in feed order.
• No-network gas cells: the Orkney and Shetland seat, like its two councils, has no mains gas and is signed absent for gas.
  • Its cells, and the councils', enter reconciliation at a declared zero and are never bound (AreaSignedDeferral.declared_value; María's ruling of 2026-10-25).
  • Without it, the local surface refuses the Scotland gas leg: both tiers lack the same territory, and nothing can imply it.
  • For gas-connected households the zero also replaces the census base those cells carried off the surface.
• Band-H deferral rationale: the English council tax band-H deferral now states its counts nationally (María's wording, 2026-10-26), and the membership's copies follow.
• CI: the engine-uk job's cap goes from 30 to 60 minutes (.github/workflows/test.yml), about twice its slowest successful leg. Since the policyengine-uk 2.162.3 bump (microcosm#1400) the UK engine tests run 25 to 30 minutes and more, and the old cap cancelled both legs of this PR's run and one leg of main's.
• Regenerated: local references and membership; the local compile-parity receipt (the 1,894 new cells are ledger-only under their own rationale); the census; the data-target parity register. Pins, on main after microcosm#1400: 25,192 compiled cells, 29,325 references, 4,133 signed exclusions.

The references, membership and parity receipt were generated from a cut of the pinned 272c987 artifact: the local-level rows a local contract selector matches, 306,418 rows. docs/uk-chronicle-feed-repin.md allows this route on a 24 GiB machine. On main with the band-H commit, the same cut reproduces all three files byte for byte.

Signatures and binding

• María signed the texts on 2026-10-26. The domestic energy family gains the fence desnz_small_area_split_for_constituencies with its in-force adjudication in uk/local_binding_adjudications.json. It is renewed on the first dense build that binds the seat cells, on the share of seat cells within 10% and 25% per fuel.
• The three DESNZ adjudications' reasons now speak of authority and seat cells (areas) rather than authority cells, and so do the basis fence's authority, the meters fence's rule and the gas-connected hold. Each records its re-wording.
• The seat rows bind (María's ruling of 2026-10-26).

Verification

• Touched engine-free tests on the rebased head: the 76 files that import a changed module or read a changed resource, the adjudication register, the uprating holds or the census, run in three chunks with JUnit counts. 2,006 tests: 1,978 passed, 28 skipped (their pinned feed, supports, ladder or uk-data tree is not mounted), none failed.
• Engine tests: test_uk_local_energy_metrics.py, test_uk_energy_price_basis.py: 4 passed.
• tools/ci_test_plan.py verify and ruff clean.
• Rebuilt inputs: the builder reproduces the committed resource from the pinned feed and supports. The supports and the OA ladder rebuild byte for byte to their pins.
• A compile of the local surface on the validated feed cut (the branch's code, the pinned ladder, the membership's deferred and off-surface cells) reconciles all 1,957 kWh cells (electricity and gas at both grains) at a factor of exactly one. The single-winner rule leaves the authority cells where they are. The Isles of Scilly's absent gas cell implies to rounding noise.

Tracker (#1095, "Consumption, energy and bus"): "Constituency grain" is done for energy; bus stays at region grain.

🤖 Generated with Claude Code

[vahid-ahmadi]

@juaristi22 round 1, at efe055793. You pushed 89d76bf10 (the signatures and re-wording) while I was reviewing, so everything below is checked at 89d76bf10.

This is a careful piece of work. The split is the right one (DESNZ's own small areas, not households), it keeps every authority's total exactly, and the seat rows are labelled as Microcosm's derivation throughout. Binding both grains doesn't double-bind in any harmful way. No musts. One should: the gas-connected cells at the two grains aren't shown to agree the way the kWh cells are.

How the split works, checked

• Weights. Each output area's key is its LSOA's (or data zone's) published value times its share of the LSOA's census households. Each authority's total is then shared among its constituency pieces in proportion to the summed keys (desnz_constituency_energy.py:379). So the weights are DESNZ's own small-area figures. Census households only enter for the 990 LSOAs that straddle two seats (2.4% of households in the receipt).
• Seat rows sum back to the authority rows. In the committed resource, the 632 electricity seat rows and the 631 gas seat rows sum to the receipt's authority totals to within rounding at 3 dp (largest gap 0.011 kWh on 97.4 TWh). I also summed the authority meter rows in the vendored desnz_local_energy_facts.json: 29,326,189 electricity and 24,681,591 gas meters, the same as the seat sums. That's the exactness you claim, checked against a file the split didn't write.
• Guards. The split refuses a published small area outside the supports (:304), so a vintage mismatch can't pass silently. It also refuses an authority whose small areas sum more than 2% from its total (:368). The receipt shows 0.994 to 1.007.

Double-binding and collinearity

• No conflict for the kWh rows. The seat rows are a linear function of the authority rows plus a within-authority split, and the two grains agree exactly. That means one exact linear dependency per region and fuel, and 23 electricity seats (22 gas) that are just sums of whole authorities and so duplicate authority rows. With consistent values that is redundant, not contradictory, and an L2 loss doesn't mind. The local surface already binds census households, age bands, HMRC income, UC and high-value homes at both grains, so this follows existing practice.
• Weight. Under nation_grain_family_equal_sqrt_count (local_doctrine.py:97), the redundancy doesn't count energy twice within a grain. It does give energy a family share in the constituency grain as well. See item 2.

Findings

1. The gas-connected cells aren't shown to agree across grains (should). For kWh, seats split the authorities' totals, so the grains agree by construction. Gas-connected households don't work that way. Each area gets its own census households times its own meter ratio (domestic_energy_targets.py:447, align_census_households_by_gas_meter_share). Summed over a region, seats' H×r and authorities' H×r differ wherever households per electricity meter vary within an authority. I expect the gap to be small, but nothing measures it. The compile's "factor of exactly one" speaks to the kWh cells' single-winner rule, not to these. Please post the gas-connected gap between grains by region from your compile, or the factor the census partition applies there. If it's under a few tenths of a percent, a sentence in the fence is enough.
2. Energy's loss share (nit). Under the doctrine rule, domestic energy was about 2.8% of the local loss against its 2.5% floor (local_doctrine.py:114-127). It's now a family at both grains. Please give the new share in the PR body, so whoever renews the fence knows how much weight the modelled seat split carries.
3. Say "best fit" (nit). Output areas go to seats through ONS's best fit OA21-to-PCON July 2024 lookup (uk_atomic_area_supports.provenance.json:100-111; NRS's OA22 lookup for Scotland). The PR calls the 990 straddling LSOAs "the only modelled step", but the best-fit assignment of output areas is a second, small one. One clause in the fence rule (local_target_census.py:1163-1181) would cover it.
4. A published cross-check for the gas share (nit, optional). DESNZ's subnational methodology page lists constituency estimates of properties not connected to the gas network, added on 28 March 2024. I haven't opened them or checked their boundaries or year. If they're on July 2024 seats, they would be an independent diagnostic for the seat gas-connected share. They're not something to bind.

Checked and fine

• No-gas declared zeros. Orkney and Shetland (S12000023, S12000027) and their seat S14000051 are signed absent for gas kWh and gas-connected households, and they enter reconciliation at a declared zero. They are never bound (local_target_reference_membership.json:14016-14062). That matches no mains gas there, and it is the zero they really hold, not a fabricated value. The Isles of Scilly has no gas total, but its electricity meters sit in the St Ives seat's denominator, so that seat's ratio is still a true ratio.
• Labelling. The seat rows carry source_name: microcosm (:536), provenance_class: derived_administrative (:503), relation: derived and a label ending "DESNZ's authority totals split by its small-area figures" (:559). The fence says binding needs "an adjudication that a seat's split is the target, not a published fact" (local_target_census.py:1180). assertion: observation (:502) is the admission gate's value (ledger_targets.py:3758-3763), and the high-value home rows use it the same way, so that's fine.
• Source and licence. Every input is OGL v3.0: DESNZ's sub-national and LSOA/data zone tables, ONS's OA21 lookups and TS041, and NRS's OA22 lookups and Census 2022 index. The resource lists the attributions (desnz_constituency_energy_facts.json:29-41). The lookups are sha-pinned in the supports' provenance, and the loader refuses other supports or another feed.
• The selector change. source_name: ["desnz", "microcosm"] can't pull a Microcosm row into an authority cell, because the resource holds constituency rows only.

What I ran

• gh auth status as vahid-ahmadi. Checked for earlier comments of every type (issue comments, reviews, inline comments): none. A fresh worktree at 89d76bf10, uv sync --all-packages --locked --extra uk.
• test_uk_desnz_constituency_energy.py, test_uk_domestic_energy_targets.py, test_uk_off_surface_cells.py, test_target_reference_authoring.py, test_uk_local_target_census.py, test_uk_local_targets.py, test_uk_full_targets.py, test_uk_battery_bindings.py, test_uk_population_targets.py, test_country_spec.py, test_uk_local_rowwise.py, test_uk_local_candidate_scorer.py, test_uk_high_value_homes_region_control.py, test_frame_serializer_registry.py, and the engine files test_uk_local_energy_metrics.py and test_uk_energy_price_basis.py: all 575 pass.
• Summed the committed resource's rows and the vendored authority meter rows (above).
• CI at 89d76bf10: lint, wheels, integration-uk and select-countries pass. Engine-free, engine-uk and engine-us were still running when I posted.
• Not run or read: no compile of the local surface, no build, no calibration. The pinned feed isn't on this machine, so I didn't rebuild the resource or check a seat value against DESNZ's LSOA file. I took your byte-for-byte rebuild on trust. I read the method module, the appliers, the census, the declarations and the contract diff in full. I only skimmed the regenerated local_target_reference_membership.json, local_target_references.json and the parity receipt (about 330k changed lines).

Verdict

Sound, and close to ready. Post the gas-connected gap (item 1) and keep it as a draft until CI is green. Then it's good from my side. The nits are up to you. Nothing here needs a ruling from Vahid. The decision to bind the seat rows was María's, and I agree with it.

🤖 Generated with Claude Code

[juaristi22]

@vahid-ahmadi thanks. All four are addressed at f1b790fb5.

1. Gas-connected cells across grains (should). You're right that nothing measured this. The figures below use the compiled value the local compile-parity receipt records for every gas-connected cell at both grains (the compile of the 272c987 cut). Each is the seats' sum over the authorities' sum, by region.

   • Compiled: from −0.04% (East of England) to +0.30% (London), and +0.08% over Great Britain. Most of London's and the South West's figure has nothing to do with the meter shares. Their authority grain leaves out the City of London and the Isles of Scilly, which sit under the local-authority support floor, while the seats that contain them bind. That makes their census households differ between grains by 0.14% and 0.04%. In every other region the two grains' census households agree to within 0.0002%.

   • After the census reconciliation brings both grains' households to one regional total (the factor the census partition carries onto the gas-connected cells):

     Region	Gap
     North East	+0.06%
     North West	+0.19%
     Yorkshire and the Humber	+0.05%
     East Midlands	+0.01%
     West Midlands	+0.11%
     East of England	−0.04%
     London	+0.15%
     South East	+0.01%
     South West	+0.03%
     Wales	+0.04%
     Scotland	+0.01%
     Great Britain	+0.06%

   That is under two tenths of a percent everywhere, so the fence rule now says it: "The gas-connected cells do not agree by construction: each area's are its census households times its own meter share. After the census reconciliation the two grains' sums differ by under 0.2% in every region (0.06% over Great Britain, on the 272c987 feed)." The body's "factor of exactly one" now says it is about the kWh cells.

2. Loss share (nit). The PR body now gives it. Under nation_grain_family_equal_sqrt_count, energy goes from 1/36 (2.8%, one of nine local-authority families) to 1/36 + 1/20 (7.8%), since it is now also one of five constituency families. Each other constituency family goes from 6.25% to 5%. The floor is 2.5%.

3. Best fit (nit). The fence rule and the body now name the second modelled step: each output area goes to one seat through ONS's best-fit lookup of 2021 output areas to July 2024 constituencies (NRS's lookup of 2022 output areas in Scotland).

4. DESNZ's constituency estimates of properties off the gas network (optional). data.gov.uk lists "Parliamentary constituency estimates of properties not connected to the gas network 2015 to 2024". The page doesn't say which boundaries it uses, and I haven't opened it. If it is on July 2024 seats, it would make a diagnostic for a follow-up. It's not something this PR binds.

The adjudication records the two sentences added to the fence. The 9 test files that read the fence text or the register pass (326 tests). The PR stays a draft until CI is green.

🤖 Generated with Claude Code

[vahid-ahmadi]

@juaristi22 round 2, at f1b790fb5.

All four round 1 items are addressed, and the gas-connected gap is measured rather than argued. I could check its Great Britain figure from the committed parity receipt. No musts or shoulds, two small nits.

Round 1 status

1. Gas-connected cells across grains (should): fixed. I summed the compiled gas-connected values in ledger_compile_parity_local_incumbent_2025_signed_differences.json at f1b790fb5. The 631 seats give 23,063,990 and the 346 authorities give 23,044,747, so the seats are 0.084% higher over Great Britain. That matches your +0.08% compiled figure. The 346 also fits your London and South West explanation. It is the 361 crosswalk areas less Northern Ireland's 11, Orkney and Shetland (declared zero) and the City of London and the Isles of Scilly, which are not in the authority grain. I can't check the regional table after the census reconciliation without a compile, so I've taken that on trust. Under 0.2% everywhere (the largest is the North West at 0.19%) is small enough for a sentence in the fence, and the new sentence says it plainly (local_target_census.py:1182-1186).
2. Energy's loss share (nit): fixed in the PR body. 1/36 + 1/20 = 7.8% checks out, as does each other constituency family going from 6.25% to 5%.
3. Best fit (nit): fixed in the fence rule and the body.
4. DESNZ's off-gas constituency estimates (optional): noted as a follow-up. Fine.

New findings

1. The doctrine comment still gives the old energy share (nit). local_doctrine.py:116-117 says domestic energy "is one of nine local-authority families (about 2.8 % of the loss)". It is now 7.8%, as one of nine authority families and one of five constituency families. One clause there would keep the floor's context right for whoever renews it.
2. The 0.2% in the fence will go stale on a re-pin (nit). The fence states a measured gap "on the 272c987 feed" as prose. Nothing fails if a later feed moves it. A test in test_uk_local_compile_parity_receipt.py that recomputes the Great Britain gap from the receipt and checks it is under 0.2% would make the sentence check itself. Doing it by region would need a seat-to-region map, so Great Britain alone is fine.

What I ran

• gh auth status as vahid-ahmadi. A fresh worktree at f1b790fb5, uv sync --all-packages --locked --extra uk.
• Read the diff from 89d76bf10: the fence text, the adjudication note and the census JSON.
• test_uk_local_target_census.py, test_uk_local_doctrine.py, test_uk_desnz_constituency_energy.py, test_uk_domestic_energy_targets.py, test_uk_local_release_preflight.py, test_uk_target_weights.py, test_country_spec.py, test_uk_local_compile_parity_receipt.py and test_contract.py (data): 570 passed.
• Summed the gas-connected cells by grain from the committed parity receipt (above).
• CI at f1b790fb5: lint, wheels, integration-uk, select-countries and both engine-uk jobs pass. Both engine-free jobs and both engine-us jobs were still running when I posted.
• Not run: no compile of the local surface, no build and no calibration.

Verdict

Good from my side. It can come out of draft once CI is green. Both nits are up to you. Nothing here needs a ruling from Vahid.

🤖 Generated with Claude Code