Repository navigation
Spec-driven countries: a third country must render from artifacts alone #166
Description
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:
- client country parsing is still a TypeScript country table;
- overview shaping does not read a typed artifact
presentationblock; - treemap/source labels do not consume
release_manifest.publisher_labelsoverrides; - 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).
Activity
MaxGhenis commentedon Aug 23, 2026
@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.
us | uk | becountry toggle (issue Add Belgium as a third country toggle #62); Belgium's release lives in the private HF repopolicyengine/populace-be-private, same pattern as the UK.--jurisdictionsoption (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 atpolicyengine/microcosm-evaluation(HF, public); prod envCROSS_DATASET_ARTIFACT_BASE_URL_BEis set and a per-jurisdiction routing PR is in flight.external_validationsmanifest 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
zzconformance test in #165 is the honest gap list (4 pass / 4 todo) — if you see a better shape for thedimensions/publisher_labelsartifact additions, that's the part I'd most like your read on before anyone builds it.MaxGhenis commentedon Aug 23, 2026
@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-evaluationunderbe/. For US I want to publish your approved run from #159 —evaluation-02ba5db8abd8414c22eb6625on snapshotchronicle-7917ea815df710fb20db076b— the same way (us/<run_id>/frontend/+us/latest.json), then setCROSS_DATASET_ARTIFACT_BASE_URLin 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 leastfrontend/, ideally the whole run + the compiled snapshot) topolicyengine/microcosm-evaluationunderus/evaluation-02ba5db8abd8414c22eb6625/, or share the directories and I'll publish? I'm addingscripts/publish_evaluation_bundle_to_hf.pyso the upload +latest.jsonpointer 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
zztodos as two small PRs:lib/microcosm/countries.ts) thatlatest-artifact.ts,country-context.tsx, the sidebar selector, andnav-items.tsall read from.usOnlybecomes a capability (staging,model_coverage,pipeline,variables,external_checks,cross_dataset…) declared on the registration and optionally narrowed by a typedrelease_manifest.countryblock (code,label,geography_id,geography_label,repository_visibility,capabilities). Nocountry === "us"checks survive in nav, staging hooks, or link behaviour.release_manifest.presentation(overview_intro,targets_intro— the two existing text slots only),release_manifest.publisher_labels, adimensionsdictionary +targets[].dimensions, and structuredtargets[].source/targets[].variable. Readers stay backward-compatible: the name/filter grammar becomes the adapter for artifacts that don't publishdimensions, selected per artifact, never by country. The per-country overview/targets copy stays as the legacy fallback until the US/UK/BE producers publishpresentation; that's a microcosm follow-up, not a dashboard one.Files of yours this reshapes:
microcosm-overview-view.tsxandmicrocosm-targets-view.tsx(the copy tables → artifact slot + fallback),nav-items.ts, and the row shaping inlatest-artifact.ts(rows gainsource_labelanddimension_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 fordimensionsorpublisher_labelsbefore the artifact PR goes up.MaxGhenis commentedon Aug 23, 2026
Status: the
zzconformance suite is fully green on main — 4/4 todos are passing tests, nozzconditional or table outside the one registry entry.frontend/lib/microcosm/countries.ts) + typedrelease_manifest.country; capabilities gate nav/staging/link behaviour, an artifact block can narrow a registration but never re-route it.presentation(the two text slots),publisher_labels, adimensionsdictionary +targets[].dimensions, structuredtargets[].source/targets[].variable. Adapter selection is per artifact/per row (structured→legacy_filter→legacy_name), recorded on every row asdimension_adapter, never by country.scripts/publish_evaluation_bundle_to_hf.py: verified, idempotent, immutable-run publish of a Cross-dataset bundle topolicyengine/microcosm-evaluation(+latest.jsonin the same atomic commit).Verified on production: US/UK/BE releases shape identically (5,659 / 149 / 32 targets),
presentation: nullfor the current artifacts,source_labelon every row. The contract as implemented, with validation and merge rules, is indocs/spec-driven-countries.md, along with the producer follow-up list — e.g. the UK release can now fix its "Slc" label with onepublisher_labelsentry 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_labelsshapes — 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 commentedon Aug 27, 2026
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 commentedon Aug 28, 2026
US is live — thanks @anth-volk. Verified end to end just now: pulled
us/evaluation-8cc5a23adf295c28a535c6effrom HF and ran it throughverify_frontend_bundle(every partition hash, page bodies, run/snapshot identity — clean; 46,241 facts, 463 pages,jurisdictions: ["US"], snapshot matches the pinnedchronicle-7917ea815df710fb20db076b, Yale at the 382 from #159's acceptance criteria), and production serves it:/microcosm/datasets?country=usrenders 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[].dimensionsandpublisher_labelsare 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:
selection_mass_protection.*have no Chronicle identity at all;publisher_labelsoverrides — a display-name fix (UK'sslc→ "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_labelsfrom the consumer export, with explicit release-side values only for the three non-1:1 cases above.MaxGhenis commentedon Sep 3, 2026
Closing: both halves of the done-condition hold and are verified on production — the
zzconformance 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.