UK region-grain activation: fan out the 18 two-level targets over the region tier and make region a cross-grain control (#905)

[juaristi22]

Activates region grain on the UK national calibration surface (closes #905; plan repos/uk-region-grain-activation-plan.md, María's rulings of 2026-09-11).

What changes

The 18 two-level (country + region) contract targets — the nine ons.population.age_*_by_region rows and the nine voa.council_tax_stock.band_a..h/total rows — no longer compile to one country row each. They fan out over the region tier: the nine English regions at Chronicle's region level plus Wales, Scotland and Northern Ireland at country level for the ONS family (108 cells), and the nine English regions for the VOA family (81 cells). The 18 country rows are retired; the twelve ONS cells of a band sum to the retired UK row to the unit (0–9: 7,553,013 at mid-2024).

Three pieces, shared code first (ruling R3):

1. Fan-out (shared authoring). TargetReferenceAuthoringConfig.geography_fanout_by_target_id fans a target over a declared (level, geography_id) roster inside author_target_references: one reference per cell named and measured target_id@geography_id, selector = contract selector + the cell's geography, an unsigned absent cell refuses the run. The UK generator supplies the roster (UK_REGION_TIER in geography_ladder.py) and the per-cell metadata; the national rows fan over the nations only where the binding does not already pin a country (the VOA binding filters country == ENGLAND).
2. Geography predicate (shared materializer). A reference may carry metadata.geography_predicate, a JSON predicate in the ordinary vocabulary appended to the contract binding's filters; references without it are untouched. The UK cells carry {"entity":"household","variable":"region","operator":"==","value":"LONDON","reduce":"any","map_to":<entity>}, resolved through the adapter's existing household_condition projection — no adapter change.
3. Region as a cross-grain tier. UK_CROSS_GRAIN_RULE precedence becomes country > region > constituency > la; every tier code is its own leg (UK_CROSS_GRAIN_PARENT_GEOGRAPHY_LEGS), English constituencies and authorities resolve their leg through the crosswalk's new ladder-derived region_code_by_area, nations by GSS prefix. The three Chronicle-country nation rows are placed at the region grain by a cross_grain_grain stamp the surface builder reads (ruling R4). The shared operator now treats any winning row whose geography declares legs as a declared parent, so region controls get the same dedupe, bridge-completeness and receipt naming as country controls.

Registers and receipts

• target_references.json / target_reference_membership.json: 595 active (424 − 18 + 189); the 406 untouched references regenerate byte-identically; membership records the fan-out roster per target under geography_pins.
• local_area_crosswalk.json: region_code_by_area per level from the pinned ladder (bed3f13d…); every constituency and authority maps to exactly one tier code (London: 75 constituencies, 33 authorities).
• Compile-parity receipts: the 108 incumbent region×age rows and 81 regional VOA rows now compare as matched through align_uk_national_registry_parity_fixture (also applied by the battery gate loader). 2025 fixture: fixture_only 269 → 80, ledger_only 56 → 38, calibration_drift 172 → 280 — the 108 ONS cells drift against the incumbent's rounded subnational projections (ruled rationale on each row); all 81 VOA cells match exactly.
• uk_data_target_parity.json: cross_grain_council_tax_stock_england_region → ported_national.
• The two region_pin_unsupported signed exclusions were retired by Bind the Chronicle transport and energy facts on the UK national surface (#890 PR-T) #904.

Measurement (ruling R5)

Two tools/calibrate_uk_national_dataset.py runs on the spine-q national pool (cf1f9dda…, 52,846 households; feed c6f9361; epochs 1500, family_equal, lr 0.02): this branch's register (595 references, 545 after the packaged exclusions) against PR #904's (424, 374 after exclusions). Evidence: docs/evidence/uk-region-tier-905/calibration-comparison.json.

	baseline (#904)	this branch
targets after exclusions	374	545
final loss	0.0112	0.0128
within 10 %	95.7 %	96.5 %
effective sample size	10,350	10,469

Region cells: all 108 ONS cells within 5 % (median |error| 0.08 %, worst 0.5 %); 78 of 81 VOA cells within 5 % (median 0.09 %); the other three, voa.council_tax_stock.band_h in the North East, North West and Yorkshire and the Humber, sit at −100 % because the spine carries no band-H household in those regions (spine-m had 170 band-H households from 49 raw FRS households, none there — microcosm#762 A14, the class already signed for the local band-H family under council_tax_band_h_spine_support_absent). The terminal gate blocks on those three cells.

Common rows (356): fit unchanged within run noise — 332 → 329 within 5 %, 16 → 15 within 25 %. Two rows the gate also reports belong to the #890 / PR-S lane, not to this change: hmrc/self_employment_income_income_band_20_000_to_30_000 at the 25 % bound (+23.6 % → +25.0 %) and obr.fuel_duties_cars moving −14.9 % → −23.9 % inside its reviewed target-fit exclusion, which the gate now flags as stale.

Ruling needed (María): the three band-H region cells. Proposed: three reviewed measure exclusions in uk/calibration_measure_exclusions.json — voa.council_tax_stock.band_h@E12000001, @E12000002, @E12000003 — reason "no band-H household on the spine in this region (spine support absent, the local band-H class); binds when a spine vintage carries broader band-H support", tracking microcosm#796, adjudication microcosm#762 A14, windowed to 2026-11-26 with the other spine-support exclusions. Alternative: exclude all nine band-H region cells as one family. Not added without the go.

Tests

Targeted UK and shared suites green locally (471 register/parity tests, the ledger, council-tax, cross-grain, authoring, materialization, ladder, crosswalk and national-calibration files; tools/ci_test_groups.py --verify ok). Stacked on #904, so no PR CI until it re-points to main.

Notes for review

• Stacked on Bind the Chronicle transport and energy facts on the UK national surface (#890 PR-T) #904; re-pointed to main when it merges.
• Docstrings updated: geography_ladder.py (region is now a calibrated dimension), the cross-grain bridges comment, the 18 contract binding notes, the feed re-pin runbook.

🤖 Generated with Claude Code