One consistent UK target surface: enforced cross-grain reconciliation, declared uprating holds, nation household controls and the 942a1fa re-pin (#1123 PR A)

changelog.d/104-zero-target-loss-census.added.md

@@ -0,0 +1 @@
+Calibration options now census the zero-valued targets under target_loss_scales.zero_targets (count, scale range, loss-weight range, zero-weighted rows): it reports each zero target's scale (max(abs(target), 1) by default) and loss weight, so a weighting scheme that drops one is visible in the diagnostics; the census reports and does not enforce a positive weight (microcosm#104).

changelog.d/1123-band-bridge-explained-factor.changed.md

@@ -0,0 +1 @@
+Each national band bridge now names what explains its factor and the compile checks it on the values: the factor must sit within half a point of HMRC SPI Table 3.11's United Kingdom row over the twelve regional areas' sum (the taxpayers HMRC places in no region), read from a vendored resource of the UK rows (microcosm#1123).

changelog.d/1123-chronicle-repin-942a1fa.changed.md

@@ -0,0 +1 @@
+The UK Chronicle feed is re-pinned to 942a1fa (PolicyEngine/chronicle#313 via #314): mid-2025 population for the UK, regions and every local authority, the revised mid-2024 estimates, monthly UC by area, household, tenure, census residence and rent inputs, and newer SLC, ISC, public sector employment, land and DfI editions; the national population rows, local-authority ages, SLC repayments, land (preliminary 2025), ISC and DfI move to their 2025 editions, public sector employment binds its 2025 quarterly mean, and spine inputs move only by publisher revisions (microcosm#1123).

changelog.d/1123-enforced-cross-grain-coverage.changed.md

@@ -0,0 +1 @@
+UK cross-grain reconciliation gains a nation grain, lower rows that span several legs (England over its regions), same-geography partitions and a refusal of partial middle tiers; the UK declarations move to uk/cross_grain_declarations.json and a coverage check refuses any undeclared multi-grain overlap or local target without a control (microcosm#1123).

changelog.d/1123-hmrc-area-taxpayer-basis.changed.md

@@ -0,0 +1 @@
+HMRC income targets are bound on a taxpayer basis at both grains (income_tax > 0; employment and self-employment counts count income != 0, as HMRC counts a loss with nil income); the area rows take HMRC's all-ranges ITL growth to 2025 and reconcile per grain to the national SPI band partition summed over every band, gated at each grain on source agreement (within 2%) and on the gap between the two sides' uprating indices (each bridge's measured gap plus half a point); fan-outs are never exact-signature controls (microcosm#1123).

changelog.d/1123-hmrc-rate-band-taxpayers.added.md

@@ -0,0 +1 @@
+HMRC higher and additional rate Income Tax payers bind for each English region and nation (Income Tax liabilities Table 2.2, the calendar-2025 window of the 2024-25 and 2025-26 projections, on the engine's tax_band), and higher rate taxpayers bind by constituency and local authority in England, Wales and Northern Ireland (SPI 2023-24 Tables 3.14 and 3.15), each region or nation row controlling its area cells; Scotland's area cells predate its advanced rate and the additional rate area cells are too rounded and suppressed to bind (microcosm#1123).

changelog.d/1123-local-small-cell-rule.added.md

@@ -0,0 +1 @@
+Local cells below a declared small-cell floor (uk/local_small_cell_rule.json: council-tax band cells under 50 dwellings, and higher rate taxpayer cells of 5,000 or fewer; both rules are proposed and unsigned, so they defer nothing yet) are deferred by rule with an expiry the loader enforces; the joint surface still counts a deferred cell's value in its leg's control (microcosm#1123 item 7).

changelog.d/1123-nation-household-controls.changed.md

@@ -0,0 +1 @@
+Each nation's official household estimate for 2025 controls its census household cells (LFS for England's regions, NRS for Scotland, Welsh Government rolled forward for Wales, Census 2021 rolled by LPS dwelling stock for Northern Ireland); the UK household composition takes the nations' sum, A15 uprates census cells to it with the LFS UK total kept as a diagnostic, and census tenure cells partition their authority's households (microcosm#1123).

changelog.d/1123-national-compile-source-index.changed.md

@@ -0,0 +1 @@
+The UK national target compile scans only the facts of the sources a reference's selectors name, in feed order, instead of the whole Chronicle feed once per reference (microcosm#1123).

changelog.d/1123-national-register-reconciliation.changed.md

@@ -0,0 +1 @@
+The UK national target register is reconciled across its own grains (exact signatures, and HMRC ITL Table 2.5 bands controlling the SPI regional band cells) and written back before the measure exclusions and the frozen-register check, in both the full and national loaders; the joint local pass refuses a national factor away from one (microcosm#1123).

changelog.d/1123-off-surface-cells.fixed.md

@@ -0,0 +1 @@
+A signed local cell that is off the UK target surface (deferred with its published value, or absent from the publisher's table) now counts in its leg's control where a control moves the leg, so the leg's bound cells no longer take its share: the South West's local authorities took 2.4% more employees than its constituencies because HMRC's local-authority tables carry no Torbay row (microcosm#1123).

changelog.d/1123-rolled-forward-by-ratio.added.md

@@ -0,0 +1 @@
+Ledger target references gain a rolled_forward_by_ratio value operation: an official estimate for an earlier period (one cell or the sum of its cells) carried to the target period by base * numerator / denominator, with the numerator pinned to the target period, the denominator to the base's own period, and the growth bounded to (0.5, 2] (microcosm#1123).

changelog.d/1123-target-compile-hash-and-receipt.fixed.md

@@ -0,0 +1 @@
+Both UK target kernels hash every module that decides a target value (the shared resolver and the HMRC uprating appliers were missing), and tools/uk_target_surface_receipt.py writes and diffs receipts of the compiled target surface (microcosm#1123).

changelog.d/1123-tenure-share-drift.changed.md

@@ -0,0 +1 @@
+England's census tenure shares drift by ONS SPREE's change in each category's share of the authority's dwellings from 2022 to 2024 (dwellings move shares, never levels); other nations hold their census shares (microcosm#1123).

changelog.d/1123-uc-area-calendar-window.changed.md

@@ -0,0 +1 @@
+UC by area binds the calendar-2025 mean of DWP's monthly series (the window the national UC rows use) and its child bands follow each constituency's caseload; the area series still counts every household on UC while the national rows count paid claims, so the bridge applies the GB paid share (0.921) to every area until a paid-claims area series is pinned; the receipt tool gains a census communal-establishment validation (--communal) (microcosm#1123).

changelog.d/1123-uprating-holds-doctrine.changed.md

@@ -0,0 +1 @@
+Every UK target the calibration-year compile binds from an older fact now carries either a declared uprating index or a declared hold in uk/uprating_holds.json (matched_period, in_year_snapshot, control_rescaled, reviewed_no_index); the compile refuses an undeclared, unsigned, expired or stale hold (a register entry is in force only with an approver, an approval date and the status approved), and a local area target that declares an index is uprated at authoring and at compile as national targets are (microcosm#1123).

docs/evidence/spec-engine/us-f0-coverage.json

@@ -1656,13 +1656,13 @@
           "compiler_ir.node_slices"
         ],
         "expected": {
-          "map_sha256": "7d03cc07e973165f38781d5932d5fe6d16ca0b1e4dc854e7841460737fd043fb",
-          "protocol_sha256": "37da8f68444677850a97bdf958b7f62b426a60da570b80a002eeba8af4861f68"
+          "map_sha256": "bdd339868ee0cec07fa3a52a91c4bd97de707c15aeb0dc224b064be9ce04eb4b",
+          "protocol_sha256": "8d028354d487eadecf3bc4a950d70c95e5c44c792fe7fdf2d52c77e6d86a7886"
         },
         "failures": [],
         "observed": {
-          "map_sha256": "7d03cc07e973165f38781d5932d5fe6d16ca0b1e4dc854e7841460737fd043fb",
-          "protocol_sha256": "37da8f68444677850a97bdf958b7f62b426a60da570b80a002eeba8af4861f68"
+          "map_sha256": "bdd339868ee0cec07fa3a52a91c4bd97de707c15aeb0dc224b064be9ce04eb4b",
+          "protocol_sha256": "8d028354d487eadecf3bc4a950d70c95e5c44c792fe7fdf2d52c77e6d86a7886"
         },
         "status": "covered"
       },
@@ -1677,7 +1677,7 @@
           "compiler_ir.seed_stream_map"
         ],
         "expected": {
-          "implementation_sha256": "37da8f68444677850a97bdf958b7f62b426a60da570b80a002eeba8af4861f68",
+          "implementation_sha256": "8d028354d487eadecf3bc4a950d70c95e5c44c792fe7fdf2d52c77e6d86a7886",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -1698,7 +1698,7 @@
         },
         "failures": [],
         "observed": {
-          "implementation_sha256": "37da8f68444677850a97bdf958b7f62b426a60da570b80a002eeba8af4861f68",
+          "implementation_sha256": "8d028354d487eadecf3bc4a950d70c95e5c44c792fe7fdf2d52c77e6d86a7886",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -2599,7 +2599,7 @@
       "country": "us",
       "schema_id": "country_spec",
       "schema_version": 1,
-      "spec_sha256": "fbf25dbae68242198972f5bef4f1fc20f65ee0769615b8d94639e6a80121f31f"
+      "spec_sha256": "638cd60e97a9b200f8bdfd4f92e67be986f516ac25b9a37508235963e695e640"
     }
   },
   "report_schema_version": 3,
@@ -2609,7 +2609,7 @@
     "country": "us",
     "schema_id": "country_spec",
     "schema_version": 1,
-    "spec_sha256": "fbf25dbae68242198972f5bef4f1fc20f65ee0769615b8d94639e6a80121f31f"
+    "spec_sha256": "638cd60e97a9b200f8bdfd4f92e67be986f516ac25b9a37508235963e695e640"
   },
   "status": "pass"
 }

docs/evidence/uk-target-surface-1123/README.md

@@ -0,0 +1,114 @@
+# Evidence for the UK target surface change (microcosm#1123, PR #1198)
+
+Two receipts of the compiled UK target surface, written by
+`tools/uk_target_surface_receipt.py`, and what they show. The receipts carry
+every bound row (6.5 MB and 7.4 MB), so they stay outside the tree under
+`data/ukds/acceptance/1123-pr-a/receipts/`. The two extracts here are written
+from them by `scripts/extract_surface_receipts.py`.
+
+## The two receipts
+
+- **Before:** `before-51a263726.json`. `main` at `51a263726`, the commit the
+  branch is rebased on, with only the commit that adds the receipt tool (it
+  moves no value), on the feed `main` pins, Chronicle `1ee7dfe`.
+- **After:** `after-cd39d037e.json`. Branch commit `cd39d037e`, on the feed it
+  pins, Chronicle `942a1fa`, with `--communal`.
+
+Both use review date 2026-10-12 and the 2021 output-area ladder of the
+2026-10-04 local build.
+
+**Each receipt records what its working tree added to the commit it names**
+(`code_modifications`): every file under `packages` and `tools` that differs
+from `code_head`, with the SHA-256 of its content, and the diff of the tracked
+ones. The extracts keep the file list and the diff's digest.
+
+- **After** ran on a clean tree: no file differs from `cd39d037e`. The hold
+  register is signed, so the compile needs no overlay.
+- **Before** names six files. `main` does not carry the receipt tool, so the
+  tool's commit was laid over `51a263726`, uncommitted, with the provenance
+  record added to the tool. That overlay is `before-overlay.diff` here; its
+  SHA-256 is the `diff_sha256` that `surface-diff.json` records for the
+  before receipt.
+
+## `surface-diff.json`
+
+What the surface moves between the two receipts.
+
+- **National, bound rows:** 1,177 before and 1,213 after. 36 added, none
+  removed, 552 moved.
+  - Added: the 12 nation household control cells and the 24 Income Tax
+    liabilities Table 2.2 marginal-rate cells.
+  - Moved by this change's own reconciliation: 360 SPI regional cells (the
+    band bridges) and 24 CGT regional cells.
+  - Moved by the re-pin and the household controls: 149 population rows, the
+    10 household-composition rows, 3 land rows, 3 SLC repayment rows, and one
+    row each for DfI, ISC and public sector employment.
+- **Local cells:** 20,885 before and 21,804 after. 919 added (higher rate
+  taxpayers by area), none removed, 18,811 moved. The file gives each target
+  at each grain: cells, totals before and after, and the spread of the
+  relative moves.
+  - 437 of the moved cells move only because a deferred authority no longer
+    leaves its share on its neighbours: the council-tax band A to G cells of
+    London and the South West (406) and Scotland's band H cells (31). The
+    widest move is 0.5%.
+
+The national count is of bound rows, after the measure exclusions. The
+reference register is larger (1,245 active references before, 1,281 after).
+
+## `reconciliation.json`
+
+How the after surface was reconciled.
+
+- **`national_reconciliation.band_bridges`:** the 24 bridges from the UK
+  Table 2.5 bands to the SPI regional cells. Each carries its factor, its
+  declared `max_factor_shift`, and `explained_factor`: Table 3.11's United
+  Kingdom row over the regional cells' sum, which the factor must sit within
+  half a point of. 21 factors equal it to five decimals; the widest gap is
+  0.19 points. The widest factor is income tax at £12,570 to £15,000, 1.0573
+  against a bound of 0.063.
+- **`national_reconciliation.sum_bridges`:** the UK household composition
+  scaled onto the nations' sum (29,003,000 to 29,082,020).
+- **`fanout_sum_bridges`:** each HMRC area bridge at each local grain, read
+  before any reconciliation. Both parts of the factor the cells take are
+  gated.
+  - `source_factor` is the bands over the cells before either side's
+    uprating index: 0.999 to 1.006 at constituency grain and 1.003 to 1.008
+    at local-authority grain, against 2% (`max_factor_shift`).
+  - `index_factor` is the gap between the two sides' indices: 0.997 to 1.014,
+    each inside its bridge's `max_index_shift`.
+  - `applied_factor` is their product, 0.996 to 1.019.
+  - `off_surface_cells` counts the frame's rows for cells that are not bound;
+    the totals include them.
+- **`off_surface_cells`:** the signed cells that are off the surface and
+  still count in their leg. 44 frame rows: 38 deferred cells with a published
+  value, and 6 implied for cells the publisher's table does not carry. Torbay
+  and the Isles of Scilly are implied at 2.3% of the South West's employees;
+  their share of its households is 2.6%. Each implied row carries that
+  `household_share` and its `share_ratio`, which the compile refuses above
+  1.5: the ratios are 0.32 to 0.89. `areas_outside_the_ladder` is empty.
+- **`cross_grain_groups`:** every group's factor by leg. The local-authority
+  legs under the constituency totals (`constituency_over_la`) are 1.018 to
+  1.021 on employment counts and 1.008 to 1.011 on employment amounts. The
+  North East's 1.029 on self-employment amounts is the two tables' own gap
+  at source: that leg is whole at both tiers.
+- **`subset_relations`:** each declared part against its whole on the compiled
+  values. All 20 tests hold and none is skipped. The nine age bands and the
+  two 90-and-over rows are tested on their sum, which equals the UK total.
+- **`uprating_holds`:** the held targets by kind and the earliest expiry,
+  2026-12-11, at both grains.
+- **`partitions`, `communal_validation`:** counts and spreads.
+
+## Reproducing
+
+```
+uv run --no-sync python tools/uk_target_surface_receipt.py \
+    --ledger-facts <chronicle consumer artifact at the pinned commit> \
+    --ladder <uk_oa_ladder_2021.npz> --review-date 2026-10-12 \
+    [--communal] --out <receipt.json>
+python docs/evidence/uk-target-surface-1123/scripts/extract_surface_receipts.py \
+    <before.json> <after.json> docs/evidence/uk-target-surface-1123
+```
+
+Neither input is in the repository: the consumer artifact comes from
+Chronicle's `build-bundle --suite uk` and `build-consumer-artifact` at the
+commit `uk/chronicle_feed.json` pins, and the ladder from a UK local build.