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

changelog.d/1086-per-country-env-docs.changed.md

@@ -0,0 +1 @@
+The agent guide now says that each country keeps its own policyengine-core pin (microcosm#1086), so no environment can hold both engines: uv refuses any sync that asks for an extra that installs policyengine-us (`microcosm-build[us]`, `microcosm-data[us]` or `microcosm-frame[policyengine]`) together with one that installs policyengine-uk, such as `uv sync --all-packages --extra us --extra uk` or `uv sync --all-packages --all-extras`, and each country needs its own `UV_PROJECT_ENVIRONMENT`. The lock-level pin test also checks the workspace-wide US install paths `--all-packages --extra policyengine` and `--all-packages --extra policyengine --extra us`. Each resolves policyengine-core 3.32.5, policyengine-us 2.2.1 and spm-calculator 1.0.0, like the paths it already checked.

docs/agent-guide.md

@@ -23,6 +23,16 @@ uv run pytest <path>     # focused test while developing
 uv run ruff check .      # lint
 ```
 
+Each country keeps its own policyengine-core pin (#1086). The extras that
+install policyengine-us pin the core the certified US default was built with,
+and the extras that install policyengine-uk follow policyengine-uk's own core
+floor. So no environment can hold both engines: uv refuses any sync that asks
+for an extra that installs policyengine-us (`microcosm-build[us]`,
+`microcosm-data[us]` or `microcosm-frame[policyengine]`) together with one that
+installs policyengine-uk, such as `uv sync --all-packages --extra us --extra uk`
+or `uv sync --all-packages --all-extras`. To keep both countries set up, point
+`UV_PROJECT_ENVIRONMENT` at a separate directory outside the checkout for each.
+
 PR CI (`.github/workflows/test.yml`) has `lint`, `engine-free`, `engine-us`,
 `engine-uk`, `integration-uk`, and `wheels` jobs, plus the
 `select-countries` orchestration job.

packages/microcosm-build/tests/engine_free/shared/test_engine_core_pins.py

@@ -93,8 +93,14 @@ def test_every_us_engine_extra_pins_the_us_core(package: str, extra: str) -> Non
 
 
 def _us_install_paths() -> list[tuple[str, ...]]:
+    # Workspace installs name each US extra alone, then all of them together.
+    extra_names = sorted({extra for _, extra in US_EXTRAS})
     return [
-        ("--all-packages", "--extra", "us"),
+        *(("--all-packages", "--extra", extra) for extra in extra_names),
+        (
+            "--all-packages",
+            *(arg for extra in extra_names for arg in ("--extra", extra)),
+        ),
         *(("--package", package, "--extra", extra) for package, extra in US_EXTRAS),
     ]