Add canonical SPM selection, receipts and native loading to the wrapper

.github/workflows/pr_code_changes.yaml

@@ -10,6 +10,7 @@ on:
       - .github/**
       - changelog.d/**
       - pyproject.toml
+      - uv.lock
       - src/policyengine/data/bundle/manifest.json
   workflow_dispatch:
 
@@ -57,7 +58,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     steps:
       - uses: actions/checkout@v6
       - name: Set up Python ${{ matrix.python-version }}
@@ -68,16 +69,13 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@v8.1.0
       - name: Install package (no country-model extras)
-        # `h5py` is used transitively by policyengine.core.scoping_strategy
-        # but is normally supplied via the [us]/[uk] extras (through
-        # policyengine-core). Install it directly so the smoke import can
-        # exercise the wrapper without the country models, which pin
-        # versions that don't support 3.9/3.10 yet.
-        run: uv pip install --system . h5py
+        run: uv pip install --system .
       - name: Smoke-import core modules
         run: python -c "import policyengine; from policyengine.core import Dataset, Policy, Simulation; from policyengine.outputs import aggregate, poverty, inequality; print('import OK')"
   BundleVerification:
     name: Verify bundle metadata
+    # Private manifest credentials are available only to trusted repository PRs.
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
     runs-on: ubuntu-latest
     env:
       POLICYENGINE_SKIP_COUNTRY_IMPORTS: "1"
@@ -113,14 +111,21 @@ jobs:
           PY
       - name: Check installed package consistency
         run: python -m pip check
+      # Only the reviewed registry lock is a pull-request concern. The
+      # read-only credential, published-measurement and TRACE sidecar gates
+      # are release gates: the release workflow regenerates the sidecars and
+      # publishes the wheels immediately before checking them, so they cannot
+      # be satisfied from a pull request. They run in push.yaml instead.
+      - name: Check the reviewed registry lock
+        run: python scripts/release_lock.py
       - name: Verify bundle packages
         run: policyengine bundle verify --country us --country uk --packages-only --json
   Test:
     runs-on: macos-latest
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
     steps:
         - name: Checkout repo
           uses: actions/checkout@v6

.github/workflows/push.yaml

@@ -43,7 +43,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ['3.13', '3.14']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
     steps:
       - name: Checkout repo
         uses: actions/checkout@v6
@@ -114,22 +114,39 @@ jobs:
           fetch-depth: 0
       - name: Fetch tags
         run: git fetch --tags --force
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.1.0
       - name: Setup Python
         uses: actions/setup-python@v6
         with:
           python-version: '3.13'
+      - name: Install package for TRO verification and regeneration
+        run: uv pip install -e . h5py --system
+      - name: Check reviewed release inputs before versioning
+        env:
+          HUGGING_FACE_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
+        run: |
+          if [[ -z "${HUGGING_FACE_TOKEN:-}" ]]; then
+            echo "::error::Full private release verification requires HUGGING_FACE_TOKEN"
+            exit 1
+          fi
+          python scripts/check_release_credentials.py
+          python scripts/bundle.py check --published-spm --include-tros --strict-tros
+          python scripts/release_lock.py
       - name: Build changelog
         run: pip install yaml-changelog towncrier && make changelog
       - name: Generate derived bundle metadata
         run: python scripts/bundle.py generate
+      - name: Refresh only the release version in the registry lock
+        run: python scripts/release_lock.py --refresh
       - name: Preview changelog update
         run: ".github/get-changelog-diff.sh"
-      - name: Install package for TRO regeneration
-        run: pip install -e . h5py
       - name: Regenerate bundled TRACE TROs
         env:
           HUGGING_FACE_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
-        run: python scripts/bundle.py generate --include-tros
+        run: |
+          python scripts/bundle.py generate --include-tros --strict-tros
+          python scripts/bundle.py check --published-spm --include-tros --strict-tros
       - name: Update changelog, bundle metadata, and TROs
         uses: EndBug/add-and-commit@v9
         with:
@@ -160,6 +177,17 @@ jobs:
       - name: Capture published version
         id: version
         run: bash .github/capture-version.sh
+      - name: Validate complete bundle and registry lock before publication
+        env:
+          HUGGING_FACE_TOKEN: ${{ secrets.HUGGING_FACE_TOKEN }}
+        run: |
+          if [[ -z "${HUGGING_FACE_TOKEN:-}" ]]; then
+            echo "::error::Full private release verification requires HUGGING_FACE_TOKEN"
+            exit 1
+          fi
+          python scripts/check_release_credentials.py
+          python scripts/bundle.py check --published-spm --include-tros --strict-tros
+          python scripts/release_lock.py
       - name: Publish a git tag
         run: ".github/publish-git-tag.sh"
       - name: Build package
@@ -200,10 +228,16 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v6
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
       - name: Wait for release to be visible on PyPI
         env:
           VERSION: ${{ needs.Publish.outputs.version }}
         run: bash .github/wait-for-pypi.sh
+      - name: Validate published SPM bundle before consumer updates
+        run: python -S scripts/bundle.py check --published-spm
       - name: Generate GitHub App token
         id: app-token
         uses: actions/create-github-app-token@v1

README.md

@@ -4,6 +4,8 @@
 
 A Python package for tax-benefit microsimulation analysis. Run policy simulations, analyse distributional impacts, and visualise results across the UK and US.
 
+Requires Python 3.11–3.14.
+
 > **Results are estimates.** PolicyEngine simulates a large, evolving body of tax-benefit law (the US model alone encodes more than 95,000 parameters across 5,500+ variables) over survey microdata calibrated to administrative targets. Treat outputs as estimates, and validate them against the policies relevant to your analysis, the scope of the rules engine, and external or back-of-the-envelope calculations. You can inspect the certified US dataset's calibration at https://calibration-diagnostics.vercel.app/populace.
 
 
@@ -26,13 +28,17 @@ print(uk.household.hbai_household_net_income)  # net income
 us = pe.us.calculate_household(
     people=[{"age": 35, "employment_income": 60_000}],
     tax_unit={"filing_status": "SINGLE"},
-    household={"state_code": "CA"},
+    household={"state_code": "CA", "county_fips": "06037"},
     year=2026,
     reform={"gov.irs.credits.ctc.amount.adult_dependent": 1000},
 )
 print(us.tax_unit.income_tax, us.household.household_net_income)
 ```
 
+US default outputs require observed county FIPS or an explicit national/SPM-area
+choice. See the [SPM household contract](docs/households.md#spm-geography-and-measurement-selection)
+for settings, provenance and the coordinated bundle this release ships.
+
 ### Population analysis
 
 ```python

changelog.d/canonical-certification-guards.fixed.md

@@ -0,0 +1 @@
+Recognise the `microcosm-data` producer name and the `evidence` artifact kind when certifying a US data release, so source-enrichment releases keep the per-artifact reachability check and pin their release-directory sidecars at paths that resolve.

changelog.d/canonical-spm-bundle.changed.md

@@ -0,0 +1 @@
+Validate independently pinned SPM bundle settings, verify published calculator wheel identities, and support explicitly uncertified local-wheel development fixtures ahead of the production promotion that follows this release.

changelog.d/canonical-spm-python.breaking.md

@@ -0,0 +1 @@
+Require Python 3.11–3.14, matching the supported runtime range of the canonical US model bundle. Install checks now cover that complete range.

changelog.d/canonical-spm-release-validation.fixed.md

@@ -0,0 +1 @@
+Require complete authenticated bundle provenance and a registry-only, version-consistent lockfile before automatic release publication.

changelog.d/canonical-spm-review.fixed.md

@@ -0,0 +1,6 @@
+Preserve native entity ID alignment across input/output tables, reject malformed
+group IDs, and retain partial SPM selection semantics through JSON round trips.
+Validate managed SPM settings before dataset materialization, preserve
+dependency-light bundle bootstrap, and enforce published measurement pins in
+the release workflow. Authenticate candidate import sources and correct the
+measurement serialization example.

changelog.d/canonical-spm-wrapper.breaking.md

@@ -0,0 +1 @@
+Use the bundle-pinned canonical SPM configuration across US household and population simulations, require explicit geography for SPM-dependent outputs, reject formula-owned SPM inputs, and retain serialisable selection and calculation provenance across results and replay.

changelog.d/canonical-tuple-pins.changed.md

@@ -0,0 +1 @@
+Pin the canonical PolicyEngine tuple: policyengine-us 2.2.1, policyengine-core 3.32.5 and spm-calculator 1.0.0.

changelog.d/certify-us-populace-us-2024-spm-20260915.changed.md

@@ -0,0 +1 @@
+Certify the US populace data release `populace-us-2024-spm-20260915` (populace_us_2024, policyengine-us 2.2.1) into the PolicyEngine bundle manifest.

changelog.d/native-us-hdf-weights.fixed.md

@@ -0,0 +1 @@
+Load native US pandas HDF datasets that store only calibrated household weights by mapping missing person and entity weights through native membership IDs in memory, preserving source files and supplied weights.

changelog.d/repository-tro-schema.fixed.md

@@ -0,0 +1 @@
+Accept the repository-bundle TRACE emission context and validate all generated country TROs against the packaged schema before writing bundle sidecars.

changelog.d/spm-receipt-comment.fixed.md

@@ -0,0 +1 @@
+Corrected the SPM receipt storage comment, which justified the H5 dataset by an HDF5 attribute-size limit that the supported h5py range does not have.

changelog.d/spm-resource-geography-contract.changed.md

@@ -0,0 +1 @@
+Documented that SPM geography is required only by results that use the measurement: SPM thresholds and poverty always require it, the ordinary resource outputs never do, and the SPM unit's capped housing subsidy and everything downstream of it require it for units allocated housing assistance.

changelog.d/us-household-snapshots-country-uprating.changed.md

@@ -0,0 +1 @@
+Regenerated three US household snapshots for two located country changes: the BLS CPI-U actuals refresh that uprates school meal reimbursement rates, and the California standard deduction whose uprating metadata was un-frozen.

changelog.d/us-model-surface-snapshot.changed.md

@@ -0,0 +1 @@
+Regenerated the US model-version surface snapshot for the pinned country and data package.

changelog.d/us-no-income-snapshot-snap-work-requirements.changed.md

@@ -0,0 +1 @@
+Regenerated the US single-adult-no-income snapshot for the SNAP ABAWD work-requirement changes, and noted that omitting weekly_hours_worked_before_lsr now reads as zero hours.

changelog.d/wrapper-repin-policyengine-us-221.changed.md

@@ -0,0 +1 @@
+Repin the US bundle, registry lock and TRACE sidecars onto policyengine-us 2.2.1, the build-time model the certified data release records. The certified microdata is byte-identical to the superseded `populace-us-2024-spm-20260909` release.

docs/bundles.md

@@ -84,10 +84,10 @@ Derived artifacts are:
 - `src/policyengine/data/bundle/{country}.trace.tro.jsonld`
 - GitHub release assets exported from the bundle manifest
 
-The US model in this bundle uses the SPM calculator 0.3.1 API. The manifest pins
-`spm-calculator==0.3.1` in the US package scaffold and the generated `us`,
-`models`, and `dev` extras. The model formulas and certified dataset artifacts
-remain unchanged.
+The US model in this bundle uses the SPM calculator 1.0.0 API. The manifest pins
+`spm-calculator==1.0.0` as a US runtime dependency, and the generated `us`,
+`models` and `dev` extras carry that pin. The model formulas and certified
+dataset artifacts remain unchanged.
 
 Previously published versions cannot acquire a new dependency constraint. To
 reproduce the historical 5.3.0 US package set, include the compatible calculator

docs/countries.md

@@ -38,7 +38,9 @@ Override in any output with `income_variable=`.
 ## State / regional breakdown
 
 US: Populace row scoping uses `state_fips` and `congressional_district_geoid`.
-`state_code` remains the human-readable input for custom households.
+`state_code` remains the human-readable state input for custom households.
+US resource and poverty calculations also require observed `county_fips` or an
+explicit national or SPM-area choice; see [Households](households.md#spm-geography-and-measurement-selection).
 
 UK: constituency code and local authority code on every household where available.
 
@@ -72,7 +74,7 @@ Most analysis patterns are identical — swap `pe.us` for `pe.uk`:
 pe.us.calculate_household(
     people=[{"age": 35, "employment_income": 60_000}],
     tax_unit={"filing_status": "SINGLE"},
-    household={"state_code": "CA"},
+    household={"state_code": "CA", "county_fips": "06037"},
     year=2026,
 )