Publish calibration hierarchy schema 8

.github/workflows/test.yml

@@ -6,6 +6,11 @@ on:
   pull_request:
     branches: [main]
 
+# Cancel outdated PR runs; give each main push its own independent group.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
   changes:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -39,6 +39,10 @@ shard's real wheel, install into a clean uv-export-constrained venv, assert
 the wheel/import boundary and spec digests, and run the suite against installed
 wheels.
 
+New commits to a PR cancel older unfinished CI runs for that same PR.
+Each main-push run has a unique concurrency group, so all main-push runs
+remain independent and can finish validating their merged changes.
+
 `requires_us` and `requires_uk` are registered pytest markers. Mark new tests
 that need a live PolicyEngine engine with the appropriate marker; the root
 collection hook skips them when that engine is absent, and the marker also
@@ -101,8 +105,22 @@ historicize any currency claims in it ("nothing was pushed", "do not merge",
 readers. Adjudicated verdicts belong in `experiments/` or the tracking issue,
 with the journal pointing to them.
 
+## Shared constants
+
+Before adding a module-local mapping, enumeration, identifier, or display
+label, search for an existing definition and follow
+[`docs/shared-constants.md`](docs/shared-constants.md). Human contributors and
+AI assistants must import shared static data from its domain-specific constants
+module instead of copying it or reconstructing alternate views in consumers.
+
 ## Review this file
 
 Update this guide in the same PR whenever the workspace layout, test
 commands, or release flow change. If you find it contradicting the repo,
 trust the repo and fix this file.
+
+UK size experiments use `tools/build_uk_rowwise_candidate.py --dataset-households`
+with the same pool inputs as the dense candidate. The flag changes exported
+support, not clone K. Sizes remain candidate-only until their matched comparison
+and promotion scorecard are adjudicated; see
+[the size plan](docs/uk-dataset-size-plan-355.md).

DESIGN.md

@@ -133,6 +133,9 @@ assembled/transferred/simulated stage boundaries bind the stack manifest,
 fraction, seed, realized counts, and clone controls, so a smaller rung or a
 different draw cannot reuse another build's evidence.
 
+Every bound UK local calibration family compiles from the sha-pinned Chronicle
+consumer feed; geography ladders assign rows and provide diagnostics only.
+
 After gap-fill, one PUF QRF pass and the clone-2 capital-gains-tail operator
 run over both survey origins. Publication is terminally gated by complete
 declared-input coverage and a live-digested, explicit per-column by-origin

changelog.d/875-cgt-observation-year.fixed.md

@@ -0,0 +1,9 @@
+Measure CGT in FY2024–25 while retaining the 2025 calibration index and 2024
+exported data. Pin individual HMRC gains, taxpayer count and liability facts;
+retain the replaced OBR cash forecast as optional diagnostic provenance with
+explicit availability. Retire its obsolete fit exemption, preserve its signed
+history, update live compile-parity receipts and publish aggregate fit evidence.
+
+Retain the merged upstream claimant-role graph prerequisite without duplicate
+commits. Compose the retired fit exemptions and document that the recorded
+national comparison predates main's changed fitting surface and gate disposition.

changelog.d/882-uc-build-diagnostics.fixed.md

@@ -0,0 +1 @@
+Pass benefit-unit head and parent roles into the UK source graph's UC capital stage, fixing its scoped execution after the relationship repairs. Extend UC matrix diagnostics with verified comparison controls, original-source concentration and paid-claim joint support, and document the remaining empty and single-source cells.

changelog.d/uk-census-households-chronicle-887.changed.md

@@ -0,0 +1 @@
+Bind UK constituency and local-authority census household targets from the pinned Chronicle feed, and replace Northern Ireland's postcode-inferred constituency mapping with NISRA's published DZ2021-to-PARLCON24 lookup. The NISRA lookup reader declares openpyxl through the `microcosm-build[uk]` extra, and the households-only candidate scope applies the same per-grain A15 factor as the joint scope.

changelog.d/uk-dataset-sizes-355.added.md

@@ -0,0 +1,6 @@
+Add exact-household-count UK rowwise candidates using contribution-informed L0 initialization, protected target carriers, fixed-size sampling and refitting. Preserve the dense pool doctrine and local gates, export compact linked entities, and record selection provenance without promoting candidates to the certified dense release or changing dataset defaults.
+A size run also ships the dense joint solve it was cut from (`dense_reference_diagnostics.csv`, a `dense_reference` summary under `solve.dataset_size`) and the selection itself (`dataset_size_selection.csv`: pool row, design weight, inclusion probability, Horvitz–Thompson baseline, refit weight), and `--selection-seed` re-draws the selection on one pool and one dense reference. The exact-count draw's certainty threshold is a recorded candidate-run knob (`--selection-pi-hi`, default 1), and a refused draw carries the measured gate mass and the feasible alternatives instead of a bare error.
+Compose each bound PIPR mean monthly private rent into an annual total using 12 months and the matching A17-uprated private-renter household count, with the inputs and adjudication recorded in the cross-grain receipt.
+The size selection's L0 budget search stops only on a probe whose gate probabilities admit the exact-count draw at the requested certainty threshold (`feasible_draw_pi_hi`, verdicts from the new `exact_k_design_feasibility`), recording every probe in the size receipt; a size run checkpoints the dense solve and the search before the draw (`size_selection_checkpoint.{npz,json}`) and `--resume-size-checkpoint` continues at the draw on the re-derived pool after verifying the checkpoint's identity, rebuilding both results through the new `rebuild_calibration_result`.
+The UK doctrine solve reports progress through the calibrator's callback seam: a loss line every hundred epochs of the dense solve, each budget probe and the refit, one line per finished probe with its drawability verdict (new `budget_probe` and `budget_search_done` events), and one when the search stops; the candidate driver writes them to stderr.
+After review: the checkpoint identity carries the solve doctrine and a resume asserts the restored options against it; a stale checkpoint in `--out` refuses before the solve; `microcosm.calibrate.gates` and `microcosm.calibrate.initialization` join the attested seed-protocol sources and the pre-best-iterate oracle runs with a frozen gate module; the size receipt reports `certainty_share`, `boundary_draws` and `zero_target_rows`; the manifest distinguishes the realized stretch against the refit's reference from the stretch against the pool design.

changelog.d/uk-uc-average-hold-metadata.fixed.md

@@ -0,0 +1,4 @@
+Use explicit source-window averaging for the five UK UC paid child-count targets,
+removing misleading December-to-annual hold annotations while preserving target
+values and selected observations. Clarify the allowance-based family proxy and
+the separate source-compilation and population-comparison receipts.

changelog.d/uk-uc-lp-evidence.added.md

@@ -0,0 +1 @@
+Add authenticated producers and exact replay checks for the named, full-supported and bounded-redistribution UC linear-program diagnostics, with aggregate provenance and synthetic tests.

changelog.d/uk-uc-stale-fit-deferrals.fixed.md

@@ -0,0 +1 @@
+Remove five obsolete UK release-fit deferrals and restore the unchanged 25% check for those targets. Retain the separate CGT deferral and keep unsupported UC payment-tail targets release-blocking.

changelog.d/uk-uc-support-diagnostics.added.md

@@ -0,0 +1 @@
+Add a receipted UK Universal Credit matrix-support diagnostic with clone-aware source concentration, no-refit source removal, and explicitly scoped capacity and feasibility checks.

docs/calibration-target-hierarchy.md

@@ -0,0 +1,167 @@
+# Calibration target hierarchy
+
+Microcosm diagnostics schema 8 publishes a fixed sequence of hierarchy tier
+types for every registry-backed calibration target:
+
+1. provider
+2. category
+3. geography
+4. zero or more dimensions
+5. target
+
+The number of dimension entries is variable. The hierarchy is represented as
+one ordered array of dimension records rather than recursively nesting an
+arbitrary number of dimension objects in the authoring contract.
+
+## Authoring contract
+
+A country target contract uses `schema_version: 2`. It declares provider and
+category labels once in normalized catalogs and gives every flat target a
+`category_id`:
+
+```json
+{
+  "schema_version": 2,
+  "hierarchy": {
+    "providers": {
+      "obr": {"label": "Office for Budget Responsibility"}
+    },
+    "categories": {
+      "obr.efo_receipts": {
+        "provider_id": "obr",
+        "label": "Economic and fiscal outlook receipts"
+      }
+    }
+  },
+  "targets": [
+    {
+      "target_id": "obr.income_tax",
+      "label": "Income tax",
+      "category_id": "obr.efo_receipts"
+    }
+  ]
+}
+```
+
+Provider is therefore level 1 and the referenced category is level 2. The
+category owns the provider relationship, so a target cannot independently
+declare an inconsistent provider. Contract validation rejects missing provider
+or category labels, unknown category references, and categories that reference
+unknown providers.
+
+The optional target `label` is Microcosm-owned. It is required whenever the
+compiled target combines facts, transforms a fact value, or uses a different
+period from its source fact. The UK contract declares it for every target so a
+future operation or period change cannot introduce another metadata location.
+
+Generated UK target-reference resources keep the same normalized catalogs and
+add `hierarchy.target_categories` and `hierarchy.target_labels` lookups keyed by
+`contract_target_id`.
+Individual scalar rows already carry `metadata.contract_target_id`, so the
+generated local rows do not repeat labels. Smaller country resources may carry a
+direct `category_id` on a reference. Loading either form resolves the immutable
+provider/category seed on `LedgerTargetReference`.
+
+The UK release assembler also derives `release_manifest.publisher_labels` from
+this provider catalog. Do not add a second UK provider or category label map in
+the calibration package or release tooling.
+
+## Chronicle inheritance
+
+Geography, dimensions, and direct-target labels come from the Chronicle
+consumer fact selected by a reference. These fields are required source
+metadata, not hints for constructing display text.
+
+- Geography uses Chronicle's `geography.level`, `geography.id`, and
+  `geography.name`. The level and identifier must be explicit and constant.
+  When `name` is absent, Microcosm may resolve only a known identifier through
+  its shared authoritative geography catalog. An unknown identifier or missing
+  identity fails compilation; neither condition is interpreted as UK.
+- Every selected Chronicle fact must have a non-empty `label`. A same-period,
+  identity-operation, single-fact target uses that label. A multi-fact,
+  transformed, or period-adjusted target uses its explicit Microcosm target
+  label because an individual member-fact label does not describe the compiled
+  target.
+- `layout.groupby_dimension` is first when it has a value. Its categorical
+  value label comes from `layout.groupby_value_label`.
+- Remaining Chronicle `dimensions` ids are sorted. Chronicle must supply
+  exactly one non-empty `dimension_labels` entry and one non-empty
+  `dimension_value_labels` entry for each selected dimension and value.
+  Missing or conflicting labels fail compilation.
+- A layout dimension and a fact dimension merge only when their identifiers
+  are exactly equal. Similar labels do not establish identity.
+- A multi-fact aggregate inherits only dimensions present with the same value
+  on every member fact. Varying dimension ids are serialized in
+  `metadata.ledger_aggregation_varying_dimensions` as provenance.
+
+Dimensions are therefore automatic for new Chronicle facts, while their labels
+remain Chronicle-authored. Authors define a provider/category once, select a
+category for a new target, and define the target label once in the target
+declaration. They do not maintain a separate visualization path.
+
+Every declared calibration target must provide a non-empty `ledger_selector`.
+Reference authoring rejects both missing selectors and target declarations that
+contain `materialization`. If Chronicle does not yet publish the required fact,
+add the source fact to Chronicle before declaring the Microcosm target. Do not
+construct an observed target value from a Microcosm runtime input.
+
+## Propagation stages
+
+The expected data flow is:
+
+1. The country contract validates normalized provider/category ownership.
+2. Reference generation selects one or more Chronicle facts and rejects
+   missing or conflicting source-owned labels.
+3. A scalar reference retains its category relationship and the declared
+   Microcosm target label.
+4. `LedgerTargetReference` resolves the catalog relationship to a typed seed.
+5. Chronicle geography and dimensions complete `CalibrationHierarchy` while
+   compiling a Chronicle-backed `TargetSpec`.
+6. Registry format 3 serializes and reloads that hierarchy. Format 2 remains
+   readable for historical artifacts.
+7. Solver compilation carries the hierarchy unchanged from `TargetSpec` to
+   `Target`.
+8. Diagnostics schema 8 serializes `targets[].hierarchy` without constructing
+   provider, category, geography, dimension, or target labels.
+9. Release validation requires every schema-8 tier and label.
+10. The calibration dashboard selects its parser from top-level
+    `schema_version` and builds navigation from the ordered hierarchy.
+
+## Three representative UK targets
+
+### OBR income tax
+
+`obr.income_tax` references `obr.efo_receipts`. Chronicle contributes the UK
+geography, the `obr.efo_line` dimension, the `income_tax` value and label, and
+the fact label. If the source fact already represents the 2025 target without a
+value transformation, its fact label names the target. Otherwise the declared
+Microcosm label `Income tax` names the compiled target.
+
+### HMRC employment income band
+
+The HMRC SPI declaration references `hmrc.survey_of_personal_incomes`.
+Chronicle's `hmrc.total_income_band` layout dimension is ordered first and uses
+its authored band label. A distinct raw dimension such as
+`total_income_lower_bound` remains a separate dimension because the ids are not
+equal.
+
+### DWP Universal Credit payment distribution
+
+All fan-out scalar rows from the Universal Credit payment-distribution
+declarations reference `dwp.universal_credit`; no row-specific classification
+table is required. Each selected Chronicle cell supplies the relevant household
+type and payment-band dimensions. The target declaration supplies one label for
+the transformed target, while future cells inherit their dimensions and labels
+automatically.
+
+## AI assistant checks
+
+When changing calibration targets, verify the declaration, generated scalar
+reference, compiled `TargetSpec`, registry round trip, diagnostics row, release
+validation, dashboard parser, and resulting tree in that order. Do not add a
+dashboard label fallback for schema 8. Do not infer category membership from a
+target name, Chronicle measure id, or display label. If a new target fails
+generation because `category_id` is absent, add or reuse a normalized category
+in the country declaration. If compilation reports missing Chronicle labels,
+correct the Chronicle source adapter and refresh the pinned consumer artifact;
+do not add identifier-humanization logic in Microcosm.

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

@@ -736,8 +736,8 @@
         "legacy_sinks": [],
         "mode": "compiler_semantic",
         "pointer_class": "all",
-        "pointer_count": 824,
-        "pointer_sha256": "7537385c3fd399a2dbb7dcd8ed7cf1ff2481ed336db621eafcbfd741d5792f40",
+        "pointer_count": 826,
+        "pointer_sha256": "7ff2d5d1c2fd8026d17a57244f969dc0e9625a9e47304b693ad15df329041282",
         "rationale": null,
         "relative_sink_prefix": null,
         "source_prefix": "/resolved/seed_protocol",
@@ -772,21 +772,21 @@
         "verifier": "vintages"
       }
     ],
-    "configuration_field_count": 42154,
-    "consumed_field_count": 42154,
+    "configuration_field_count": 42156,
+    "consumed_field_count": 42156,
     "generation0_effect_counts": {
       "legacy_behavior": 38476,
-      "no_generation0_effect": 3678
+      "no_generation0_effect": 3680
     },
     "mode_counts": {
-      "compiler_semantic": 27715,
+      "compiler_semantic": 27717,
       "front_end_validation": 348,
       "identity_only": 103,
       "legacy_behavior": 13988
     },
     "multiple_primary_use_field_count": 0,
-    "pointer_inventory_sha256": "3fc6b9480ea81b9635bd0db56e180c2daf32a5cd2006a70d350586c570f96754",
-    "resolved_binding_field_count": 9770,
+    "pointer_inventory_sha256": "2c0423a08dc16bf5f142134804a1a6545f887e32ca5c991c856a2f8bcfaea0f0",
+    "resolved_binding_field_count": 9772,
     "unused_field_count": 0
   },
   "inventory_coverage": {
@@ -1656,13 +1656,13 @@
           "compiler_ir.node_slices"
         ],
         "expected": {
-          "map_sha256": "c94a5af8eb24866156b8cd4b77b93dc497b7df5b025204fe1022f80b1d8446ea",
-          "protocol_sha256": "1c53f1d9b3e185a41181fbe861f9b08d56c83880710fd1e18d7a4ceb5d6a354e"
+          "map_sha256": "87ba50531d9fa6683096ecb39a31655b331ab8acff3a5876c2f62b33562a0885",
+          "protocol_sha256": "fd3e4b06f11be4e8c13ea19fef9469ab95cbbe3e2dcfce351e860dd3e00709e4"
         },
         "failures": [],
         "observed": {
-          "map_sha256": "c94a5af8eb24866156b8cd4b77b93dc497b7df5b025204fe1022f80b1d8446ea",
-          "protocol_sha256": "1c53f1d9b3e185a41181fbe861f9b08d56c83880710fd1e18d7a4ceb5d6a354e"
+          "map_sha256": "87ba50531d9fa6683096ecb39a31655b331ab8acff3a5876c2f62b33562a0885",
+          "protocol_sha256": "fd3e4b06f11be4e8c13ea19fef9469ab95cbbe3e2dcfce351e860dd3e00709e4"
         },
         "status": "covered"
       },
@@ -1677,7 +1677,7 @@
           "compiler_ir.seed_stream_map"
         ],
         "expected": {
-          "implementation_sha256": "1c53f1d9b3e185a41181fbe861f9b08d56c83880710fd1e18d7a4ceb5d6a354e",
+          "implementation_sha256": "fd3e4b06f11be4e8c13ea19fef9469ab95cbbe3e2dcfce351e860dd3e00709e4",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -1698,7 +1698,7 @@
         },
         "failures": [],
         "observed": {
-          "implementation_sha256": "1c53f1d9b3e185a41181fbe861f9b08d56c83880710fd1e18d7a4ceb5d6a354e",
+          "implementation_sha256": "fd3e4b06f11be4e8c13ea19fef9469ab95cbbe3e2dcfce351e860dd3e00709e4",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -2599,7 +2599,7 @@
       "country": "us",
       "schema_id": "country_spec",
       "schema_version": 1,
-      "spec_sha256": "8b1546bc97b540afd525fe88f36a315de18b4d57bd9fab73035dacd8962e302e"
+      "spec_sha256": "35a02b6b19c921faba1407d441e0b9d9623c496e2cd5b711be014def281a95c6"
     }
   },
   "report_schema_version": 3,
@@ -2609,7 +2609,7 @@
     "country": "us",
     "schema_id": "country_spec",
     "schema_version": 1,
-    "spec_sha256": "8b1546bc97b540afd525fe88f36a315de18b4d57bd9fab73035dacd8962e302e"
+    "spec_sha256": "35a02b6b19c921faba1407d441e0b9d9623c496e2cd5b711be014def281a95c6"
   },
   "status": "pass"
 }