Document per-country engine environments and test every workspace US install path (#1086)

[MaxGhenis]

Follow-up to #1143, which carried out the ruling on #1086 (Max's decision d816, option 2: each country keeps its own policyengine-core pin). It fills two gaps left against that ruling. The PR changes no engine version, no lock and no generated file.

Changes

• Agent guide, Commands section. It now says that no environment can hold both engines, because uv refuses any sync that asks for a US extra together with a UK extra (for example uv sync --all-packages --extra us --extra uk, or --all-packages --all-extras). Each country needs its own UV_PROJECT_ENVIRONMENT. The guide asks to be updated whenever test commands change, and Give each country its own policyengine-core pin (#1086) #1143 didn't touch it.
• Lock-level pin test. _us_install_paths() checked --all-packages --extra us and each per-package US extra. It now also checks --all-packages --extra policyengine and --all-packages --extra policyengine --extra us. The first of these is the path the 2 October trial found drawing core 3.32.12. Both new paths resolve the certified trio. The test goes from 14 to 16 cases.
• Changelog fragment changelog.d/1086-per-country-env-docs.changed.md.

Install paths at head 328a558, main a224dc1 merged in (uv sync --locked --dry-run, empty env)

install path	result
--all-packages --extra us	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--package microcosm-data --extra us	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--package microcosm-build --extra us	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--package microcosm-frame --extra policyengine	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--all-packages --extra policyengine	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--all-packages --extra us --extra policyengine	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--all-packages --extra us --extra axiom	core 3.32.5, policyengine-us 2.2.1, spm-calculator 1.0.0
--package microcosm-frame --extra us, --all-packages	no engine
--all-packages --extra uk, --package microcosm-{data,build,frame} --extra uk, --all-packages --extra uk --extra axiom	core 3.32.19, policyengine-uk 2.122.2
--all-packages --extra us --extra uk, --all-packages --extra policyengine --extra uk, --package microcosm-frame --extra policyengine --extra uk, --package microcosm-data --extra us --extra uk, --all-packages --all-extras	refused (exit 2, "incompatible with the declared conflicts")

uv lock --check exits 0, and APPROVED_UV_LOCK_SHA256 equals shasum -a 256 uv.lock (f65a01fb…). Since this PR doesn't touch the lock, in-progress resumable builder runs keep their identity.

Microcosm's own loader functions (_resolve_certified_release), compared with these resolutions:

• The certified US default populace-us-2024-spm-20260915 requires policyengine-us >=2.0.0,<2.3 and core ==3.32.5. Pass.
• The certified UK default populace-uk-2023-dd68c73-4aa4b14-20260619T023711Z requires policyengine-uk ==2.89.2 and core ==3.27.1. Fail, unchanged from before Give each country its own policyengine-core pin (#1086) #1143: main had already moved past both at 2.100.0. Its next certified UK build fixes this.

Context: PolicyEngine/policyengine-uk#2021 (BRMA from region)

• #2021 is still an open draft. No policyengine-uk release from 2.104.0 to 2.125.0 (68 wheels, through 2.125.0 of 2026-10-09 22:25Z, each checked against PyPI's sha256) gives brma a formula: I read policyengine_uk/variables/household/BRMA.py in every wheel and found neither def formula nor REGION_DEFAULT_BRMA, both of which #2021's diff adds.
• When #2021 does ship, microcosm data doesn't change. frs_brma stores brma for every household. On 2026-10-02, brma was byte-identical per year with and without #2021: on the pinned eFRS (2024–2027, 2030, 2032) and on the certified candidate (2023–2026, 2028, 2030). See policyengine-uk 2.102.4+ needs policyengine-core 3.32.9+, which the certified US default refuses #1086.
• The eFRS parity reference stays at engine 2.89.0 (145 layers; 13 formula-owned overrides, without brma). The ruling kept the change to the lock, and past bumps (including UK: port the remaining uk-data fixes tracked in #1095, engine items included #1121) left the reference alone. brma joins the formula-owned list only at a future re-pin.

Invariants

• Every US install path resolves policyengine-core 3.32.5, policyengine-us 2.2.1 and spm-calculator 1.0.0. test_every_us_install_path_resolves_the_certified_us_engine checks 6 paths, up from 4.
• uv refuses every US × UK install: test_uv_refuses_every_us_and_uk_combination, and the declared and locked conflict sets are equal.
• Not applicable here: brma per-year byte identity (no engine change), generator determinism (no generator run), and build_uk_efrs_parity_reference.py --check (no re-pin).

Docs that name both engines

--all-extras and --extra us --extra uk appear on main only in root journals and experiment receipts that record past runs (PROGRESS_BUILDJ.md:27, PROGRESS.md:480, out.md:263, experiments/355-uk-dataset-size-receipts.md:633,756, experiments/amendment-20-keyed-draws-receipts.md:273). The guide treats root journals as history, so they stay as written. No live instruction needs changing.

Testing

Re-run at head 328a558 (after merging main a224dc1; the PR's own hunks are unchanged):

• test_engine_core_pins.py, test_ci_integration_job.py and test_ci_test_plan.py (engine-free env, uv sync --all-packages --locked): 56 passed.
• tools/ci_test_plan.py verify: ok.
• ruff check .: clean. ruff format --check on the changed Python file: clean. (ruff format --check . flags about 50 untouched files already on main; CI's lint job runs only ruff check ..)
• I didn't run the full country suites locally. This PR changes no engine-side code; CI runs every lane on the merge ref.

Review

Independent GPT-6.1 Sol review (subfleet): round 1 at e6aa357 approved with nits, and nit 1 (name the extras that install policyengine-us) is applied in 0797555. Round 2 approved 0797555. Round 3 approved the merge head 328a558 and confirmed that its PR diff equals the round-2 diff. It also checked the nine conflict pairs, the lock digest and the parity reference. Its sandbox couldn't run uv or reach PyPI, so the runtime rows above are from this host.

🤖 Generated with Claude Code