Spec-driven countries: a third country must render from artifacts alone

[MaxGhenis]

Adding Belgium (#163, #165) showed where the dashboard is not yet spec-driven: the release contract is artifact-driven, but adding a country still touches closed country unions and selector lists, dataset/geography labels, overview and target-browser copy, public/private link behaviour, and page gating. #163 also added a free-form external_validations manifest block rendered "whatever the manifest names" — removed in #165; cross-dataset comparison belongs only to the evaluation bundle (/microcosm/datasets, cross_dataset.frontend_bundle.v1, #164).

Acceptance test (in repo since #165): frontend/lib/microcosm/third-country-conformance.test.ts — a synthetic fourth country zz with four targets, filter-coded facets, a release description, and an unknown Chronicle publisher prefix must render the overview/targets shapes with one COUNTRY_REPO registration as the only country-specific change. Today: 4 assertions pass, 4 are test.todo:

1. client country parsing is still a TypeScript country table;
2. overview shaping does not read a typed artifact presentation block;
3. treemap/source labels do not consume release_manifest.publisher_labels overrides;
4. target shaping does not consume structured dimensions; it needs the legacy filter-pattern adapter.

Schema additions that remove each remaining table are spelled out in docs/spec-driven-countries.md (typed country block with capabilities gating pages instead of country codes; narrow presentation block for existing text slots only; publisher_labels; a dimensions dictionary plus targets[].dimensions; structured targets[].source / targets[].variable). Readers stay backward-compatible while published releases migrate; after migration, name/filter parsing is a legacy adapter selected by artifact schema version, never by country.

Done when all four todos can be enabled without any zz conditional or table, and the cross-dataset page is configured per jurisdiction from the same registry (follow-up PR wires CROSS_DATASET_ARTIFACT_BASE_URL_<CC> and fails closed on the bundle's jurisdictions).

[MaxGhenis]

@anth-volk — heads-up since this touches your August work (#159 harness, the target pages): three PRs landed today for the CAPE/Belgium meeting and I'd value your eyes on the direction.

• Belgium country toggle + EUROMOD external-validation panel (#62) #163 — us | uk | be country toggle (issue Add Belgium as a third country toggle #62); Belgium's release lives in the private HF repo policyengine/populace-be-private, same pattern as the UK.
• Evaluation harness: Belgium jurisdiction with Axiom, EUROMOD-engine, and EUROMOD/SILC sources #164 — the evaluation harness gets a --jurisdictions option (US default unchanged), a generic precomputed-checkpoint adapter (the Yale checkpoint now uses the shared materializer), and Belgium sources scored against 726 Chronicle BE facts: Microcosm-BE v0.4 × Axiom, Microcosm-BE v0.4 × EUROMOD engine, and EUROMOD's own JRC/SILC baseline. Bundle hosted at policyengine/microcosm-evaluation (HF, public); prod env CROSS_DATASET_ARTIFACT_BASE_URL_BE is set and a per-jurisdiction routing PR is in flight.
• Close the manifest escape hatch; Belgium renders like US/UK; third-country conformance test #165 — review pass on Belgium country toggle + EUROMOD external-validation panel (#62) #163: removed a free-form external_validations manifest block that rendered a bespoke EUROMOD panel (wrong grammar — cross-dataset comparisons belong only to your evaluation bundle), and made BE render structurally like US/UK.

Max's ruling for the boundary with the Scorecard (#140): anything comparable to authoritative government facts belongs here and must be visible for other models too; the Scorecard keeps estimates with no such ground truth.

The zz conformance test in #165 is the honest gap list (4 pass / 4 todo) — if you see a better shape for the dimensions / publisher_labels artifact additions, that's the part I'd most like your read on before anyone builds it.

[MaxGhenis]

@anth-volk two things, both on the #166 path.

1. US cross-dataset bundle for production. With #167 merged, the page now reads a per-country bundle; Belgium's is live at policyengine/microcosm-evaluation under be/. For US I want to publish your approved run from #159 — evaluation-02ba5db8abd8414c22eb6625 on snapshot chronicle-7917ea815df710fb20db076b — the same way (us/<run_id>/frontend/ + us/latest.json), then set CROSS_DATASET_ARTIFACT_BASE_URL in prod. I can't find the run or the snapshot anywhere I can reach (not on HF, no CI artifact, not in the repo), and the snapshot id hashes your Chronicle consumer export bytes + commit, so I can't regenerate it byte-for-byte from a fresh Chronicle checkout. Could you either push the run directory (at least frontend/, ideally the whole run + the compiled snapshot) to policyengine/microcosm-evaluation under us/evaluation-02ba5db8abd8414c22eb6625/, or share the directories and I'll publish? I'm adding scripts/publish_evaluation_bundle_to_hf.py so the upload + latest.json pointer is one reproducible command rather than the ad-hoc upload I did for BE.

2. Heads-up before I touch your files. I'm working the four zz todos as two small PRs:

• Registry PR: one isomorphic country registry (lib/microcosm/countries.ts) that latest-artifact.ts, country-context.tsx, the sidebar selector, and nav-items.ts all read from. usOnly becomes a capability (staging, model_coverage, pipeline, variables, external_checks, cross_dataset…) declared on the registration and optionally narrowed by a typed release_manifest.country block (code, label, geography_id, geography_label, repository_visibility, capabilities). No country === "us" checks survive in nav, staging hooks, or link behaviour.
• Artifact PR: typed release_manifest.presentation (overview_intro, targets_intro — the two existing text slots only), release_manifest.publisher_labels, a dimensions dictionary + targets[].dimensions, and structured targets[].source / targets[].variable. Readers stay backward-compatible: the name/filter grammar becomes the adapter for artifacts that don't publish dimensions, selected per artifact, never by country. The per-country overview/targets copy stays as the legacy fallback until the US/UK/BE producers publish presentation; that's a microcosm follow-up, not a dashboard one.

Files of yours this reshapes: microcosm-overview-view.tsx and microcosm-targets-view.tsx (the copy tables → artifact slot + fallback), nav-items.ts, and the row shaping in latest-artifact.ts (rows gain source_label and dimension_adapter; nothing existing is renamed). #115/#116/#117/#119 stay yours unless one falls out of the contract work. Shout if you'd rather see a different shape for dimensions or publisher_labels before the artifact PR goes up.

[MaxGhenis]

Status: the zz conformance suite is fully green on main — 4/4 todos are passing tests, no zz conditional or table outside the one registry entry.

• Country registry + typed release_manifest.country (spec-driven countries 1/2) #168 — country registry (frontend/lib/microcosm/countries.ts) + typed release_manifest.country; capabilities gate nav/staging/link behaviour, an artifact block can narrow a registration but never re-route it.
• Artifact presentation, publisher labels, and structured dimensions (spec-driven countries 2/2) #170 — typed presentation (the two text slots), publisher_labels, a dimensions dictionary + targets[].dimensions, structured targets[].source/targets[].variable. Adapter selection is per artifact/per row (structured → legacy_filter → legacy_name), recorded on every row as dimension_adapter, never by country.
• One-command HF publish for Cross-dataset evaluation bundles #169 — scripts/publish_evaluation_bundle_to_hf.py: verified, idempotent, immutable-run publish of a Cross-dataset bundle to policyengine/microcosm-evaluation (+ latest.json in the same atomic commit).

Verified on production: US/UK/BE releases shape identically (5,659 / 149 / 32 targets), presentation: null for the current artifacts, source_label on every row. The contract as implemented, with validation and merge rules, is in docs/spec-driven-countries.md, along with the producer follow-up list — e.g. the UK release can now fix its "Slc" label with one publisher_labels entry instead of a code change.

Each PR had an adversarial review pass before merge; the catches are in the merged fix commits (presence-checked country.code, env-resolved webhook allowlist, placeholder-safe healthcare card, attested-bytes upload, page-body validation in the bundle verifier).

Still open here: the US bundle publish from your #159 run (comment above), and your read on the dimensions/publisher_labels shapes — both are live in readers now but nothing published uses them yet, so reshaping is still cheap if you see a better grammar.

[anth-volk]

Chronicle already owns the raw dimensions and source identity for Chronicle-backed targets. Are targets[].dimensions and publisher_labels intended to be generated from those Chronicle records during release construction? I agree that the release should be self-contained, but I do not want producers manually maintaining a second copy. Which transformed, combined, or non-Chronicle targets require release-owned overrides?

[MaxGhenis]

US is live — thanks @anth-volk. Verified end to end just now: pulled us/evaluation-8cc5a23adf295c28a535c6ef from HF and ran it through verify_frontend_bundle (every partition hash, page bodies, run/snapshot identity — clean; 46,241 facts, 463 pages, jurisdictions: ["US"], snapshot matches the pinned chronicle-7917ea815df710fb20db076b, Yale at the 382 from #159's acceptance criteria), and production serves it: /microcosm/datasets?country=us renders with all four sources, BE unaffected. With that, both halves of this issue's done-condition hold: 4/4 conformance todos and the per-jurisdiction page with a live bundle on each configured country.

On your question — generated, never hand-maintained. targets[].dimensions and publisher_labels are render-surface compilations of what Chronicle already owns: release construction should derive them from the same pinned Chronicle consumer export the target compiler reads, exactly like the rest of the diagnostics row. The blocks exist so the dashboard renders without a Chronicle join at request time, not to create a second authored copy. The readers are indifferent to how the blocks were produced, and both fall back cleanly when absent (filter/name adapters; the shared label humanizer).

Release-owned values are for the places where a row is not 1:1 with a Chronicle record, which is the list you guessed:

• transformed/aligned targets — an aged cy2022 fact evaluated at 2024 carries dimension values Chronicle doesn't own (the alignment identity lives with the release);
• combined targets — one row summing a record set (the Statbel commune composite pattern from the BE work) needs release-owned dimension values because no single Chronicle record has them;
• non-Chronicle targets — engine-internal rows like selection_mass_protection.* have no Chronicle identity at all;
• publisher_labels overrides — a display-name fix (UK's slc → "Student Loans Company") without waiting on a Chronicle release; if Chronicle later carries publisher display names, generate from there and the override list goes to zero.

So the producer work is one compilation step in release construction, not a maintained table. If you want, the follow-up issue for microcosm can specify it as: emit dimensions/targets[].dimensions/publisher_labels from the consumer export, with explicit release-side values only for the three non-1:1 cases above.

[MaxGhenis]

Closing: both halves of the done-condition hold and are verified on production — the zz conformance suite is 4/4 (#168, #170) and the Cross-dataset page is configured per jurisdiction with live bundles for US and BE (#167, #169).

The producer side is under way in microcosm: PolicyEngine/microcosm#854 / PolicyEngine/microcosm#855 publish schema 7 source/variable/dimensions, and PolicyEngine/microcosm#858 covers the rest (country, presentation, publisher_labels) plus the generated-never-authored rule and the four release-owned exception classes, framed against the node-graph's normative/descriptive split. First consumers of the contract: #180 (structured geography readers) and #175 (New Zealand, registry-only). Deleting the legacy adapters is a follow-up gated on the microcosm issue.