[anth-volk]

Fixes #236

Summary

Stacked on #220, which is stacked on #223, in GitHub stack #230; #239 sits on top. Base: calibration-tree-package. After #220's review fix (ca4edf5), gh stack rebase --no-trunk replayed this branch onto #220 without conflicts; the first commit is now 6931416. Two review fixes follow it (commits 2 and 3 below).

This PR checks the UK calibration views that #223 doesn't change, using the shapes UK data has today:

• tagged builds of microcosm-uk-2024-25-national;
• the dense release, which exists only as a tag;
• local-area staged diagnostics named <dataset>.diagnostics.json;
• the geography levels of UK targets.

One view was still wrong, and this PR fixes it. A UK constituency and a local authority with the same name were merged into one geography.

The fix

The dashboard groups, filters and lists targets by the geography's label. UK local-area builds calibrate constituencies and local authorities side by side, and 115 labels belong to one of each. As a result:

• the calibration fit map's geography view showed one "Ashfield" tile, holding 18 constituency and 26 local-authority targets;
• its Geography filter, /microcosm/targets and the Staging comparison maps selected both areas at once.

buildCalibration now gives any label that more than one level uses its level as well, for example "Ashfield (constituency)" and "Ashfield (local authority)" (new module geography-labels, exported as @policyengine/calibration-tree/geography-labels). Two kinds of label are left as published:

• A label used at only one level.
• The country's own national label. A target whose geography can't be resolved falls back to it at the national level, and it still means the whole country. The existing test "legacy UK geography metadata resolves GSS identifiers across target-name formats" caught a first version that split "United Kingdom" into country and national entries.

Every view reads its rows from buildCalibration: the explorer and its published trees, the targets page, the live Staging trees and comparisons, and the treemap route. So they all change together. Target matching between builds uses target names and identities, not geography labels, so comparisons are unaffected.

What changes in published output: I checked the filter index of all 45 trees published today (28 US, 2 Belgian, 15 UK). Only the three UK local candidates from September have labels at more than one level, 115 labels each. Every US, Belgian and UK national tree has none, so the new function returns its input unchanged for them. The golden record still reproduces byte for byte.

Before merging: trees already published keep merged labels

A tree's build ID comes from its inputs, not from the builder's code, and published trees are never rebuilt. So:

• The three September UK local-candidate trees keep their merged tiles. They are staging builds. If one ever needs a repair (a stored part has gone missing), the rebuilt index differs from the digest the manifest records, and the publisher refuses it with "Rebuilt staging index differs from immutable manifest entry".
  • Correction: an earlier version of this description gave the release message, "Rebuilt calibration index differs …", and didn't say what the refusal did next.
  • Before commit 2, reconcileStagingBuilds threw at that run, so every UK staging run after it would have stayed unpublished on every later run of the publisher.
  • Since commit 2, the refusal is recorded as that run's failed outcome, the remaining runs are still reconciled, and the publisher then exits with an error naming the failed run.
• The same applies to anything Publish Microcosm UK release cuts, open the UK page on the national line, and show local candidates on Staging #223's rollout publishes before this PR deploys. That includes the dense release and the October local candidates. A refused repair of a release build, such as the dense release, still stops release reconciliation, which commit 2 doesn't change. To publish those with separate areas, keep tree publishing paused until this PR is deployed. Publishing is paused now: CALIBRATION_TREE_BUILD_ENABLED=FALSE was set on 2026-10-19 at 20:58 UTC, and it pauses every country. The plan keeps it paused until Keep same-named UK constituencies and local authorities apart in the calibration views #237 and Compare UK local-area Staging candidates with the local-area release #239 are deployed.

Commits

1. Keep same-named UK areas at different geography levels apart (6931416; earlier ffd5b9e, then 6e65097)

   • Red: 3 of 4 new tests in shared-geography-labels.test.ts failed, each with both areas under "Ashfield":

     • the row labels;
     • the targets page's Geography list and filter;
     • the explorer's geography tiles (one tile with 2 targets) and its filter options.

     The fourth test, which checks that UK national labels are unchanged, passed, as intended.

   • Green: 4 of 4 passed. Rerun after the commit across 5 files, 113 passed and 0 failed: the new tests, the package boundary test (now including the new export), latest-artifact.test.ts (84), and both golden suites (16, unchanged record).

   • bun run lint (dashboard and package typecheck): clean.

2. Record a staging build that cannot be reconciled and keep going (19699ac, from review)
   • Why: see "Before merging" above. Any error for one finalized run (a refused repair, a declared diagnostics file that is missing or has the wrong digest, a size limit) stopped staging reconciliation at that run, so every run after it stayed unpublished until someone intervened.
   • Choice: record and continue, rather than leave the throw. The refusal itself is unchanged, so immutable data is still never overwritten. The workflow still fails, so the failure stays visible, but one bad run no longer blocks the others. Errors before the per-run loop (an unavailable repository, incompatible runs) still stop reconciliation. Release reconciliation is unchanged: it still stops at the first release it can't publish or repair.
   • Change:
     • each run's error becomes that run's failed outcome, with the error as reason, and the loop continues;
     • after printing the report, runPublisher throws "N of M staging sources failed to reconcile: .", so the command exits with status 1;
     • reconcileStagingBuilds is exported and takes the CalibrationManifestStore that release reconciliation already takes, and runPublisher accepts that store, so both can be tested without Vercel Blob. The Blob store is the default, and it makes the same calls as before.
   • Docs: docs/calibration-tree-artifacts.md lists the failed outcome and when it occurs.
   • Red: 2 of 2 new tests in publish-calibration-tree-golden.test.ts failed. For this run, the store parameter had already been added (no behavior change), so the file loaded.
     • "a refused staging repair is recorded as that run's failure, and the runs after it are still published": the call rejected with "Rebuilt staging index differs from immutable manifest entry aaaa…".
     • "the publisher prints every staging outcome, then exits with an error naming the failed run": runPublisher ignored the store and stopped at "Vercel Blob: Invalid token". No request was sent.
   • Green: 2 of 2. Rerun at the commit: 44 passed across 5 files (both publisher suites, the builder golden suite, the harness test and the boundary test); bun run lint clean.
   • The test serves a UK staging repository with two finalized runs, using the harness's recorded UK version 2 run under each run ID (new harness helper ukStagingRepositoryFiles). The newer run has a manifest entry with a missing index and a stale digest. The golden record is unchanged.
3. Document level-qualified geography labels (0820b3f, from review; documentation only, so no red step)
   • docs/calibration-map-hierarchy.md no longer says the dashboard doesn't construct labels for schema 8. A new section, "Geography labels shared by several levels", gives the rule:
     • which labels get their level;
     • how the level is written;
     • that the national label is never qualified (the release manifest's country.geography_label, or else the registration's geography);
     • that rows without a level keep their label;
     • that labels and levels are compared after trimming whitespace.
   • docs/calibration-tree-artifacts.md ("Filtering indices") says geography postings use those labels, and that a tree published before the rule keeps one merged label, so a repair of it is refused.

What I checked in the other UK views

Data used

• Real data, read without credentials: the production dashboard's public API. It runs main, without Publish Microcosm UK release cuts, open the UK page on the national line, and show local candidates on Staging #223, so it reads only the national release folder, not the tagged builds. I read its UK release list, target diagnostics, tree manifest, tree indexes and filter indexes, and one staging comparison.
• Real data, read with the locally configured Hugging Face login: the UK staging repository's run manifests and staged-file receipts. Nothing was printed or stored except the downloaded JSON.
• Not readable locally: the UK release repository (policyengine/populace-uk-private). The local login gets 404 there, so the tagged builds and the local-area diagnostics themselves were checked only through the shapes above and the tests.

Findings

• /microcosm calibration fit map. The page renders the explorer (calibration-explorer-map) over published calibration trees. calibration-map.tsx and /api/microcosm/target-treemap aren't rendered or called by any page. A tagged build resolves through its tree manifest entry, which Publish Microcosm UK release cuts, open the UK page on the national line, and show local candidates on Staging #223 adds, so this map works for UK tagged builds once the publisher has run.
  • The national release's geography levels are country and region, 15 labels, all distinct.
  • Local-area builds have constituency, country, local_authority and region: 1,006 labels, of which 115 were merged (fixed here).
• The explorer's geography filter is built from each tree's own filter options, with no fixed level list. It works for both UK shapes apart from the merged names.
• /microcosm/targets. Production's UK national response lists levels country and region and the 15 geographies. Its level and geography lists come from the data.
• Staging target-change map. The live comparison reads a local candidate's <dataset>.diagnostics.json through Publish Microcosm UK release cuts, open the UK page on the national line, and show local candidates on Staging #223's staged-bundle reader; the receipt of uk-local-candidate-f100-s42-20261019T000432Z-ee5c2dbe records microcosm_uk_2024_25_local.diagnostics.json.
  • The comparison baseline is now in Compare UK local-area Staging candidates with the local-area release #239. Every UK candidate, national or local-area, was compared with the latest release, which after Publish Microcosm UK release cuts, open the UK page on the national line, and show local candidates on Staging #223's rollout is the current national build. Production compares the September local candidate's published tree (21,523 targets) with the national release (1,168): 634 targets match, 20,889 are added and 534 removed. Compare UK local-area Staging candidates with the local-area release #239 compares local-area candidates with the most recently published build of the local-area release instead.
• calibration-diagnostics#69 is superseded.
  • The files it changes no longer exist.
  • The fixed US level list it replaced is gone.
  • Both the explorer's and the targets page's level lists now come from the data, and UK targets carry real levels.

Tests run

• Locally, at commit 1: only this branch's new and changed test files and the golden suites that prove outputs didn't change (113 tests, 5 files), plus bun run lint.
• Locally, at the head after the restack (0820b3f): every test file this branch adds or changes, plus both golden suites, the boundary test and the harness test. That is 132 passed and 0 failed across 7 files: shared-geography-labels, latest-artifact, package-boundary, calibration-tree-golden, publish-calibration-tree-golden, publish-calibration-tree and test-support/calibration-tree-golden-cases. bun run lint was clean.
• Not run locally: the full suites and next build, because the machine is shared. CI runs them.

Environment variables

This PR changes no workflow, deploy script or configuration, and the code reads no new variables. Commit 2 changes how the publisher run by publish-calibration-tree.yml ends: the command exits with an error after a failed staging run, instead of stopping at it. So here is the publish job's wiring, which is unchanged:

Variable	Read by	Provider and wiring	Verified
CALIBRATION_TREE_BUILD_ENABLED	publish job if:	Repository variable, FALSE since 2026-10-19 at 20:58 UTC, so the job is skipped	Value read with gh variable list
BLOB_READ_WRITE_TOKEN	runPublisher	Repository secret, mapped in the publish job's env: and inherited by bun run publish:calibration-tree	Name listed by gh secret list
HF_TOKEN	Hugging Face reads of the release repository	Repository secret, publish job env:	Name listed
POPULACE_UK_STAGING_HF_TOKEN	UK staging reads (the registration's token_env)	Repository secret, publish job env:	Name listed
HUGGINGFACE_TOKEN, CALIBRATION_TREE_MAX_RAW_BYTES, CALIBRATION_TREE_MAX_GZIP_BYTES, repository overrides	publisher	Optional; not set in the workflow, so defaults apply	Not applicable

Unverified: the secret values. Only their names are visible, and this PR doesn't change them.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
calibration-diagnostics	Ready	Preview	Oct 20, 2026 2:55pm UTC