[anth-volk]

Fixes #238

Summary

Stacked on #237 (which is stacked on #220 and #223), in GitHub stack #230. Base: uk-calibration-views. After review fixes to #220 and #237, gh stack rebase --no-trunk replayed commit 1 without conflicts; five review fixes follow it (commits 2 to 6 below).

The Staging page now compares like with like:

• UK local-area candidates are compared with the local-area release.
• National candidates are still compared with the current national build, the one latest-national.json names through the dashboard manifest's latest release.
• US and Belgium are unchanged.

How a candidate's kind is decided

The kind is decided from a field the run records, without parsing names:

• What I checked. In the UK staging repository, I read the run manifests, staged-dataset receipts and fit summaries of the 19 Oct national attempt and the 19 Oct local candidate, plus the receipt of a September local candidate.
• No dataset role is recorded. Neither the run manifest nor the receipt records a dataset role.
• The dataset file name isn't stable. The local dataset file was microcosm_uk_2025_local.h5 in September and microcosm_uk_2024_25_local.h5 in October.
• What is stable is the run manifest's pipeline.id. The staging contract validates it and checks that it matches progress.json. It is uk-local-candidate for local-area candidates and uk-frs-calibration for national attempts.

The UK's staging registration in countries.ts now lists local_area_pipelines: ["uk-local-candidate"]. A run whose recorded pipeline id is in that list is a local-area candidate. No other country lists any, so for them the run manifest is never read.

Which local-area build is used

The local-area (dense) release has no pointer file and is never promoted, so there is no "current" build. The comparison uses its most recently published build, chosen as follows:

1. Which releases are local-area: the dataset roles in the release manifests (dataset_role: "non_default_local_area"), read the same way as for the release picker, for folder releases and for tagged builds at their commits.
2. Which build is newest: the publication time the dashboard manifest records for each of those releases' builds (createdAt, else updatedAt).

If the dashboard's build manifest lists no local-area release build, the candidate is compared with the current release, and the page says that this release calibrates a different set of targets. That includes a local-area release published on Hugging Face whose calibration tree the dashboard has not built yet (commit 8).

What the page shows

For a local-area candidate:

• Candidate-validation table: the "Current release" column becomes "Local-area release", and a note names the build and explains why it is used.
• Calibration map: the "Change from current release" tab becomes "Change from local-area release", with the same note.
• Target-change map and target detail: the detail's eyebrow, estimate, error, chart series, caption and summaries, and the "Reported error change" help, name the local-area release instead of the current release (commit 3). The candidate-fit map's target detail does too.
• Comparison map's "From" selector: it starts at that build when the build is published, instead of the manifest's latest release. Until the user picks a build, it follows the comparison as it arrives (commit 2 fixes the version that kept the national build).

If the user picks a different "From" build, the labels still name the compared release. That was already so for "Current release", and this PR doesn't change it.

/api/microcosm/staging/compare adds a comparison_release field (release_id, basis, local_area_candidate) only for local-area candidates. Responses for US, Belgian and UK national candidates are unchanged. The README documents the field, how release=latest resolves, and local_area_pipelines (commit 6).

Effect on published tree bytes

None, including after commits 2 to 6.

• The publisher doesn't use the comparison baseline. It builds each tree from one build's own diagnostics. Comparison trees are built on request from two published builds that the page or the API names.
• The registration field isn't serialized into trees.
• The golden suites pass unchanged (16 tests).

Commits

1. Compare UK local-area candidates with the local-area release (6fb5ee6; earlier 53fa9d3, then 966523b)
   • Red: all 3 new or changed test files failed to load, because the exports they test didn't exist yet (stagingLocalAreaPipelines, createStagingCompareHandler, defaultComparisonBuildArtifactId). 0 tests passed.
   • Green: 17 of 17 across those 3 files:
     • staging-comparison-release.test.ts (7): the registration, the newest local-area build from a UK-shaped manifest, the US and Belgian path (which never reads the run's pipeline), UK national, UK local-area, the fallback when none is published, and reading the pipeline id from a run manifest;
     • calibration-selection.test.ts (5 existing and 2 new): the map's default build, and the page labels and notes;
     • staging/compare/route.test.ts (3): the US response unchanged, the UK local-area response, and an explicitly requested release.
   • Rerun after the commit: 64 passed across 6 files, which adds countries.test.ts, staging-artifact.test.ts and the package boundary test.
   • Also: the golden suites, 16 passed; bun run lint (dashboard and package typecheck) clean.
2. Move the comparison map's From build to the local-area build when the comparison arrives (810bda1, from review)
   • Bug: the panel stored "From" in state and replaced it only when the stored value wasn't a published build. The build manifest usually responds before /microcosm/staging/compare, so the panel stored the manifest's latest (national) build first and kept it when the comparison then named the local-area release. microcosmStagingTargetChangeSourceParameters prefers build, so the "Change from local-area release" tab showed the national comparison.
   • Fix: the panel stores only the builds the user picks (from and to, null until picked). comparisonMapBuilds, in lib/microcosm/calibration-selection.ts, replaces defaultComparisonBuildArtifactId. It works out both selectors on every render from the picks, the build manifest and the comparison, and no effect writes defaults into state.
     • A pick that is no longer a published build is ignored.
     • A pick of the live candidate as "To" now holds when the manifest is fetched again; before, the effect replaced it.
   • Tests, at the state level and in the order the page loads:
     • nothing loaded;
     • the manifest only, which gives the national build;
     • the comparison naming the local-area release, which gives the local-area build, so microcosmStagingTargetChangeSourceParameters sends build=<local-area build>;
     • the reverse order;
     • a pick that holds while the comparison loads or changes, and a stale pick that gives way;
     • the "To" defaults and picks;
     • the fallbacks when the comparison's release has no published build.
   • Red: calibration-selection.test.ts failed to load because comparisonMapBuilds didn't exist; 0 passed. The old logic lived inside the component's effect, which no test could call, so this red is a load failure rather than a wrong value. The first test's third step encodes the reported failure: it expects the local-area build where the panel kept the national one.
   • Green: 11 of 11 in that file; 5 new tests replace the single default-build test. bun run lint clean.
3. Name the local-area release in the target-change map and target detail (965c8e0, from review)
   • What: for a local-area candidate, the map's eyebrow "Current release calibration target" and its help "removed targets subtract their current-release contribution" now name the local-area release. So do the target detail's estimate, error, chart series, caption and summaries. The detail appears in the target-change map and in the candidate-fit map. National, US and Belgian candidates keep "Current release"; their help now reads "subtract their contribution in the current release".
   • How:
     • stagingComparisonBaseline's columnLabel is now releaseLabel, because the maps use it too;
     • StagingTargetChangeMap takes comparisonReleaseLabel;
     • stagingTargetDetailPresentation takes it as an optional fourth argument and returns the eyebrow;
     • targetChangeModeHelp(label), in lib/microcosm/target-change-visualization.ts, replaces the MODE_HELP constant.
   • Red: 4 tests failed on wrong labels: 3 in staging-target-detail-presentation.test.ts and 1 in calibration-selection.test.ts. target-change-visualization.test.ts failed to load because targetChangeModeHelp didn't exist. 10 passed.
   • Green: 22 of 22 across those 3 files; bun run lint clean.
4. Order local-area builds with the calibration build sort the map uses (2e0dc12, from review; a refactor, so no red step)
   • buildPublishedInstant and calibrationBuildsNewestFirst gave the same order: createdAt, else updatedAt; an undated or unparseable timestamp last; ties by build ID.
   • The package can't import from the dashboard, so calibrationBuildsNewestFirst and its 2 tests move into the package's calibration-tree-manifest module. newestPublishedLocalAreaRelease and the map panel both use it.
   • Before and after: 23 of 23 across staging-comparison-release.test.ts, calibration-tree-manifest.test.ts and calibration-selection.test.ts; the 2 moved tests count in both runs. The boundary test passes; bun run lint clean.
5. Type the comparison the staging compare route loads (1814155, from review)
   • loadComparison returned Promise<object>. It now returns StagingComparison, which the package exports as the type loadStagingComparison returns. The route test's stub carries only available, run_id and a.release_id, and says so with an explicit cast.
   • Red: bun run lint reported 1 error: the route test's stub didn't match StagingComparison.
   • Green: bun run lint clean; route.test.ts and staging-comparison-release.test.ts, 10 of 10.
6. Document the local-area comparison and local_area_pipelines (753fb5c, from review; documentation only, so no red step)
   • The README's API table and a new paragraph below it explain:
     • that release=latest resolves for each candidate;
     • that a local-area candidate (its pipeline.id is in staging.local_area_pipelines) is compared with the newest published local-area build;
     • the fallback when none is published;
     • the comparison_release fields;
     • that an explicit release=<id> adds no field.
   • The README's staging configuration paragraph documents local_area_pipelines.

Re-review fix (2026-10-20)

A re-review of a869fc9 found the five earlier review findings fixed. It also found that the fallback note misstated its condition. The note said "No local-area release has been published" whenever the dashboard's build manifest lists no local-area release build. That also happens when the dense release is published on Hugging Face but the dashboard has not built its calibration tree yet. Tree publishing is paused until this PR deploys, so this is the state straight after the deploy.

7. Test that the local-area fallback note does not claim nothing was published (e5367a0, test only)
   • Red: calibration-selection.test.ts, 9 passed and 1 failed. The new test expected "The dashboard has no published calibration build of a local-area release, so …" and received "No local-area release has been published, so …".
8. Say the dashboard has no local-area build, not that none was published (b51b5c5)
   • stagingComparisonBaseline's fallback note now states the condition the code checks. The README's description of release=latest and of basis says the same, in terms of the tree manifest.
   • Green: calibration-selection.test.ts, 10 of 10.
   • Rerun after the commit: 38 passed, 0 failed across the 6 test files this branch adds or changes. bun run lint clean.

Not changed by this fix:

• After the user picks a different "From" build, the labels and the note still name the compared release. Which wording to use for an arbitrary "From" build is still an open decision.

Tests run

• Locally: only the new and changed test files listed above, plus the golden suites and lint.

• At the head after the restack (753fb5c): 107 passed and 0 failed across 12 files:

  • every test file this branch adds or changes;
  • countries, staging-artifact, use-microcosm and the boundary test;
  • both golden suites, because package code changed.

  bun run lint was clean.

• Not run locally: the full suites and next build, because the machine is shared. CI runs them.

Real-data checks still to do

The production dashboard runs main, and the local Hugging Face login can't read the UK release repository. After #223's rollout publishes the dense release, check the following:

• the 19 Oct local candidate's comparison names microcosm-uk-2024-25-dense-20261019T000432Z-ee5c2dbe;
• the 19 Oct national attempt's comparison names the current national build.

Environment variables

This PR changes no workflow, deploy script or configuration, and reads no new variables.

🤖 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 4:51pm UTC