policyengine 6.3.2__tar.gz → 6.3.4__tar.gz

{policyengine-6.3.2 → policyengine-6.3.4}/CHANGELOG.md

@@ -1,3 +1,23 @@
+## [6.3.4] - 2026-10-13
+
+### Changed
+
+- `Poverty.rate` is now `None`, not `0.0`, when nobody in the group is measured (its weighted population with a poverty status is zero), for every source. `headcount` and `total_population` are unchanged, and the poverty DataFrame helpers report the rate as missing. Callers that format or subtract rates must handle `None`.
+- US state and congressional-district regions temporarily filter the certified national dataset again, as in 6.2.1, because the ACS-local release lacks source-backed SPM independence and canonical SPM refused every state-region run (PolicyEngine/microcosm#1263).
+
+### Fixed
+
+- Measure SPM poverty on legacy certified US sources that predate SPM measurement-scope declarations, such as the ACS-local Build O release. Following Census's ACS household-population method, ACS group-quarters units are outside the SPM measurement: their SPM results are missing instead of stopping the run with `SPM_COMPOSITION_REQUIRED`, and poverty rates count measured people only. Ordinary tax and benefit results are unchanged.
+- Supply the certified SPM independence role from the national release for the ASEC and PUF records of legacy certified US sources, so independent-teen SPM units are measured instead of stopping SPM calculations.
+
+
+## [6.3.3] - 2026-10-13
+
+### Changed
+
+- `create_datasets` stamps each US year file with the register of renamed stored inputs it was cut under and a year-file format revision. `ensure_datasets` creates a year file again, and `load_datasets` refuses it, unless its stamp matches this release exactly. A year file cut before a rename was registered, which may have lost that input, is therefore not reused. `load_datasets` says why it refuses a file, naming the renames the file may lack when its register is the reason. Year files written before the stamp existed are created again once.
+
+
 ## [6.3.2] - 2026-10-12
 
 ### Changed

{policyengine-6.3.2/src/policyengine.egg-info → policyengine-6.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: policyengine
-Version: 6.3.2
+Version: 6.3.4
 Summary: A package to conduct policy analysis using PolicyEngine tax-benefit models.
 Author-email: PolicyEngine <hello@policyengine.org>
 License:                     GNU AFFERO GENERAL PUBLIC LICENSE

{policyengine-6.3.2 → policyengine-6.3.4}/docs/bundles.md

@@ -147,7 +147,9 @@ python scripts/bundle.py certify-data \
   --model-version <policyengine-us-version>
 ```
 
-US state and congressional-district regions scope one certified ACS-local
+**Temporarily**, state and congressional-district regions filter the certified national dataset (`populace_us_2024`), as in policyengine 6.2.1. The certified ACS-local release has no source-backed SPM independence, so canonical SPM refuses thousands of its SPM units (PolicyEngine/microcosm#1263, PolicyEngine/policyengine-sim-api#747). They move back to the ACS-local dataset with a release whose SPM units all have a classified adult.
+
+When they use it, US state and congressional-district regions scope one certified ACS-local
 Populace dataset with row filters. Pass its non-default local-area release
 manifest through `--regional-manifest-uri`; certification adds the pinned H5
 artifact to `data_releases.us.datasets` and writes both regional path templates

policyengine-6.3.4/docs/engineering/runbooks/us-legacy-spm-sources.md

@@ -0,0 +1,122 @@
+# Legacy US SPM sources (backward compatibility)
+
+> **Backward compatibility, not a data contract.** This layer exists so that
+> certified US sources published *before* SPM declarations existed can still
+> be measured. New certified sources must carry the declarations themselves;
+> do not register them here.
+
+policyengine-us measures SPM poverty only when a source declares two things:
+
+- **Measurement scope:** which SPM units are inside the SPM measurement
+  population (`spm_unit_spm_universe_status`: `INCLUDED`/`OUTSIDE`, the
+  contract of PolicyEngine/microcosm#977).
+- **Independence role:** which 15–17-year-olds independently head their own
+  SPM unit (`is_spm_independent_minor_role`).
+
+A legacy source carries neither. Every SPM calculation on it stops with
+`SPM_COMPOSITION_REQUIRED` ("SPM unit has no classified adult").
+
+The package
+[`policyengine.tax_benefit_models.us.legacy_spm`](../../../src/policyengine/tax_benefit_models/us/legacy_spm/__init__.py)
+derives the missing declarations from evidence a legacy source does carry.
+Nobody is dropped: memberships, weights and every ordinary tax, benefit and
+income calculation are unchanged.
+
+## Registered sources
+
+Sources are keyed by certified SHA-256 in `legacy_spm/registry.py`.
+
+| Source | Scope rule | Independence list |
+| --- | --- | --- |
+| `populace_us_2024_acs_local` Build O (`769756c3…a7ec`) | `acs_household_population` | national release `source_spm_person_independence.csv` (`22b5968d…3ce5`) |
+
+### Scope rule `acs_household_population` (#597)
+
+Census's ACS SPM methodology measures the household population only.
+
+- ACS records with `TYPEHUGQ` 2 or 3 and the matching `RELSHIPP` (37 or 38) are
+  group quarters, so their SPM units are `OUTSIDE`.
+- ACS housing-unit records are `INCLUDED`.
+- Records from the `asec` and `puf_tax_detail` channels are `INCLUDED`.
+
+Age is never used. Unknown channels, missing or inconsistent evidence, and SPM
+units that mix group quarters with household people all raise.
+
+On the full Build O source, 183,206 SPM units are outside the measurement.
+
+### Independence list (#598)
+
+The source's ASEC/PUF records are the same records the certified national
+release carries with a source-backed independence role. The list is joined by
+`person_id` and `person_spm_unit_id`, and the join must be exact:
+
+- every ASEC/PUF person appears once, in the same SPM unit;
+- the list names nobody else.
+
+ACS people keep the model's own fallback (household head or spouse).
+
+On Build O, exactly 28 units change: Census-built units around an independent
+teen.
+
+## How runs get the declarations
+
+| Path | What happens |
+| --- | --- |
+| `create_datasets` / `ensure_datasets` | Year files store the declarations as ordinary input columns, with a `policyengine_legacy_spm_declarations` record. |
+| `Simulation.run()` over a raw legacy source file | The declarations are derived in memory. The file is recognised by its evidence columns and then its SHA-256, which is hashed once per process. |
+| `managed_microsimulation` | The declarations are derived from the loaded tables and set on the simulation and its branches. |
+
+`legacy_spm.model_adapter` then makes the model honour the scope:
+
+- **native:** policyengine-us defines `spm_unit_spm_universe_status`
+  (PolicyEngine/policyengine-us#9462). The declaration is just an input, and
+  nothing is overridden.
+- **override:** policyengine-us 2.2.1 cannot read it. A variable-only reform:
+  - adds the input;
+  - wraps the installed SPM chain so that outside units never reach the
+    canonical provider and every SPM outcome for them is NaN ("not measured").
+
+  Poverty indicators become floats (1.0, 0.0 or NaN). The override wraps the
+  installed formulas, with one exception: `spm_unit_income_decile` ranks
+  units, so it is recalculated over measured units with the installed method.
+  A contract test pins that method. The override refuses to run if the SPM
+  chain no longer has the verified shape.
+
+Poverty rates count measured people only. A group with nobody measured has a
+rate of `None`, not 0.
+
+## Staleness
+
+The record holds a `LegacySPMProfile`: the registry entry plus
+`ADAPTER_REVISION`. Checks are total and exact, like the year-file stamp:
+
+- `ensure_datasets` cuts a year file again, and `load_datasets` refuses it, when
+  its record is absent, unreadable, malformed, or from another profile.
+- `Simulation.load()` refuses an output saved under a different profile.
+
+Raise `ADAPTER_REVISION` whenever a change to derivation or the override means
+existing files must be made again.
+
+## When the model or data changes
+
+- **policyengine-us gains native scope (#9462).**
+  `test_the_installed_model_does_not_read_scope_natively_yet` fails. Check that
+  the native members include `INCLUDED` and `OUTSIDE`, and confirm the native
+  runs in the integration tests. Then delete the override half of
+  `model_adapter` (keep the derivation) and raise `ADAPTER_REVISION`.
+- **The SPM chain changes.** `test_the_override_covers_every_variable_that_depends_on_the_provider`,
+  `test_the_installed_chain_has_the_verified_shape` or
+  `test_the_recalculated_decile_matches_the_installed_method` fails. Re-verify
+  the override against the new chain before bumping the pin.
+- **A rebuilt source declares scope and role itself.** Point the bundle at it.
+  Keep the Build O registry entry only while anything still reads Build O,
+  then delete it.
+
+## Related
+
+- Microcosm #977: scope classification at source.
+- Microcosm #959: independence role in US builds.
+- policyengine-us #9462: native scope.
+- policyengine.py #519: nullable SPM summaries.
+- The year-file and output stamps (#590, and #593/#594 in flight). Fold this
+  record into them once those land.

{policyengine-6.3.2 → policyengine-6.3.4}/docs/microsim.md

@@ -87,6 +87,24 @@ before passing them to the country model. Generic adult/child counts remain
 separate. The native source enrichment is not recalibration, and inherited
 schema-5 calibration diagnostics cannot be relabeled as schema 6.
 
+**Legacy SPM sources (backward compatibility).** Some certified US sources
+predate SPM declarations, for example the ACS-local Build O release. For those
+sources, .py derives the declarations from evidence they carry, following
+Census's ACS SPM methodology, which measures the household population only:
+
+- ACS group-quarters SPM units are outside the SPM measurement. Their SPM
+  thresholds, resources and poverty indicators are missing (NaN).
+- Poverty indicators on those sources are floats: 1.0, 0.0, or NaN for "not
+  measured".
+- Poverty rates count measured people only. A group with nobody measured has
+  a rate of `None`, not 0.
+- The sources' ASEC and PUF records take the certified SPM independence role
+  from the national release.
+
+Ordinary tax, benefit and income results are unchanged. Outputs record the
+declarations they used under `legacy_spm_declarations`. See
+[the runbook](engineering/runbooks/us-legacy-spm-sources.md).
+
 The wrapper's native pandas HDF loader accepts files that store only calibrated
 `household_weight`. It maps missing person and group weight columns through
 native membership IDs in memory, retaining supplied weight columns and the
@@ -401,15 +419,49 @@ The renames applied are recorded as `{old: new}` (`{}` when none applied):
 carried the draw: data that stores neither name runs with the new input's
 default, which for WIC is full take-up.
 
-Files written before this mapping existed have no record, and are not reused:
-
-- A saved US output may have been calculated without the mapped inputs.
-  `load()` refuses it, and `ensure()` runs the simulation again and saves the new
-  output.
-- A year file that `ensure_datasets` or `create_datasets` wrote stores
-  neither name, so the draw is lost from it. `ensure_datasets` creates such
-  year files again, and `load_datasets` refuses them. A year file opened
-  directly, as `PolicyEngineUSDataset(filepath=...)`, is not checked.
+A saved US output written before this mapping existed has no record and may
+have been calculated without the mapped inputs, so `load()` refuses it, and
+`ensure()` runs the simulation again and saves the new output. Saved outputs
+are checked only for the record, not for the register they were calculated
+under.
+
+### Year files
+
+`create_datasets` stamps each year file, after writing everything else, with
+the register it was cut under and a year-file format revision
+(`legacy_inputs.YEAR_FILE_STAMP_H5_DATASET`, UTF-8 JSON
+`{"register": {old: new, ...}, "revision": 1}`). `ensure_datasets` reuses a
+year file only when its stamp equals this release's exactly and its renames
+record lists only renames in the stamped register. Otherwise it logs why and
+creates the year files again; `load_datasets` refuses the file with the same
+reason, which names the renames the file may lack when its register is the
+cause. To decide, both read only the stamp and the record, never the tables
+or the source dataset. `legacy_inputs.year_file_stamp_problem(path)` returns
+the reason, or `None` for a current year file.
+
+A year file is out of date when:
+
+- it has no stamp. Year files that policyengine.py 6.1.1 and earlier cut,
+  with policyengine-us 2.x, from a source storing the draw only as
+  `would_claim_wic` (such as the certified default) store neither WIC take-up
+  name, so the draw is lost from them. Year files written with the renames
+  record but before the stamp are cut again once, and so is a year file whose
+  write did not finish;
+- its register lacks an entry this release has. It may have lost that
+  entry's input, as the older files lost the WIC draw;
+- its register has an entry this release lacks, or maps an old name to
+  another new name. It may store a new name this release's engine does not
+  define, and a run skips any column the engine does not define;
+- it has another format revision, or its stamp or record cannot be read.
+
+So any change to `LEGACY_INPUT_RENAMES` makes every year file out of date,
+and two policyengine.py versions with different registers that share a data
+folder cut each other's year files again. `ensure_datasets` raises, rather
+than cutting the files again, when a year file cannot be opened for reasons
+unrelated to its contents: no permission, a directory at its path, or a lock
+held by another process. A year file opened directly, as
+`PolicyEngineUSDataset(filepath=...)`, is not checked, and saving it again with
+`save()` drops its stamp.
 
 ## Pinned model versions
 

{policyengine-6.3.2 → policyengine-6.3.4}/docs/outputs.md

@@ -167,6 +167,12 @@ rate.run()
 rate.headcount, rate.total_population, rate.rate
 ```
 
+`rate.rate` is `None` when nobody in the group is measured: the group's
+weighted population with a poverty status is zero, for example a filter that
+matches no one, or a group whose members are all outside the SPM measurement
+on a legacy source. That is not a measured rate of zero, so handle `None`
+before formatting or subtracting rates.
+
 For all canonical poverty measures over one simulation:
 
 ```python

{policyengine-6.3.2 → policyengine-6.3.4}/docs/regions.md

@@ -23,9 +23,13 @@ ca_snap = Aggregate(
 ca_snap.run()
 ```
 
-Each state is a region in the US registry. State regions load the ACS-local
-Populace dataset declared by `region.dataset_path`, then scope its rows by
-`state_fips`. They do not require separate state H5 files:
+Each state is a region in the US registry. State regions load the Populace
+dataset declared by `region.dataset_path`, then scope its rows by `state_fips`.
+They do not require separate state H5 files.
+
+**Temporarily**, state and congressional-district regions filter the certified national dataset (`populace_us_2024`), as in policyengine 6.2.1. The certified ACS-local release has no source-backed SPM independence, so canonical SPM refuses thousands of its SPM units (PolicyEngine/microcosm#1263, PolicyEngine/policyengine-sim-api#747). They move back to the ACS-local dataset with a release whose SPM units all have a classified adult.
+
+For example:
 
 ```python
 states = pe.us.model.region_registry.get_by_type("state")
@@ -52,7 +56,8 @@ for row in impacts.district_results:
 
 `district_geoid` is the SSDD integer (state FIPS × 100 + district number;
 at-large districts use `00`). Congressional district regions load the same
-ACS-local file and scope its rows by `congressional_district_geoid`.
+file as state regions (for now the national dataset; see above) and scope its rows by
+`congressional_district_geoid`.
 
 ## UK countries
 

{policyengine-6.3.2 → policyengine-6.3.4}/docs/release-bundles.md

@@ -207,7 +207,8 @@ python scripts/bundle.py certify-data --country us --data-producer populace \
 
 That produces one US bundle manifest entry containing the Populace national
 default dataset and the certified ACS-local regional dataset. State and
-congressional-district simulations use the latter with runtime row filters, so
+congressional-district simulations use one of them with runtime row filters (for now the
+national dataset; see [Regions](regions.md)), so
 derived `states/*.h5` or `districts/*.h5` files are not vendored into
 `data_releases.us.datasets`.
 

{policyengine-6.3.2 → policyengine-6.3.4}/examples/us_budgetary_impact.py

@@ -32,6 +32,11 @@ from policyengine.tax_benefit_models.us import (
 )
 
 
+def _format_rate(rate: float | None) -> str:
+    """Format a poverty rate; ``None`` means nobody in the group is measured."""
+    return "n/a" if rate is None else f"{rate:.4f}"
+
+
 def main():
     year = 2026
 
@@ -147,11 +152,15 @@ def main():
         analysis.reform_poverty.outputs,
         strict=True,
     ):
+        # A rate is None when nobody in the group is measured.
+        change = (
+            "n/a" if bp.rate is None or rp.rate is None else f"{rp.rate - bp.rate:+.4f}"
+        )
         print(
             f"  {bp.metric:30s}  "
-            f"baseline={bp.rate:.4f}  "
-            f"reform={rp.rate:.4f}  "
-            f"change={rp.rate - bp.rate:+.4f}"
+            f"baseline={_format_rate(bp.rate)}  "
+            f"reform={_format_rate(rp.rate)}  "
+            f"change={change}"
         )
 
     print("\n=== Inequality ===")

{policyengine-6.3.2 → policyengine-6.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "policyengine"
-version = "6.3.2"
+version = "6.3.4"
 description = "A package to conduct policy analysis using PolicyEngine tax-benefit models."
 readme = "README.md"
 authors = [

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/core/run_record.py

@@ -193,6 +193,15 @@ def build_simulation_run_record_payloads(
     if renames is not None:
         results_payload["legacy_input_renames"] = dict(renames)
 
+    # BACKWARD COMPATIBILITY (#597, #598): the legacy SPM declarations a
+    # US run applied, which change its SPM results. See
+    # ``policyengine.tax_benefit_models.us.legacy_spm``.
+    legacy_spm_declarations = (
+        getattr(simulation.output_dataset, "metadata", None) or {}
+    ).get("legacy_spm_declarations")
+    if legacy_spm_declarations is not None:
+        results_payload["legacy_spm_declarations"] = dict(legacy_spm_declarations)
+
     return {"reform": reform, "input": input_payload, "results": results_payload}
 
 

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/core/simulation.py

@@ -258,4 +258,12 @@ class Simulation(BaseModel):
         )
         if renames is not None:
             result["legacy_input_renames"] = dict(renames)
+        # BACKWARD COMPATIBILITY (#597, #598): the legacy SPM declarations a
+        # US run applied, which change its SPM results. See
+        # ``policyengine.tax_benefit_models.us.legacy_spm``.
+        legacy_spm_declarations = (
+            getattr(self.output_dataset, "metadata", None) or {}
+        ).get("legacy_spm_declarations")
+        if legacy_spm_declarations is not None:
+            result["legacy_spm_declarations"] = dict(legacy_spm_declarations)
         return result

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/data/bundle/manifest.json

@@ -1,10 +1,10 @@
 {
-  "bundle_version": "6.3.2",
+  "bundle_version": "6.3.4",
   "citation": {
     "publisher": "PolicyEngine",
-    "title": "PolicyEngine bundle 6.3.2",
+    "title": "PolicyEngine bundle 6.3.4",
     "type": "software-bundle",
-    "version": "6.3.2"
+    "version": "6.3.4"
   },
   "countries": {
     "uk": {
@@ -17,7 +17,7 @@
   "data_releases": {
     "uk": {
       "build_id": "policyengine-uk-data-1.58.0",
-      "bundle_id": "uk-6.3.2",
+      "bundle_id": "uk-6.3.4",
       "certification": {
         "built_with_model_git_sha": "4cbedbecca352f52dffe47e849553c2759a00711",
         "built_with_model_version": "2.122.2",
@@ -99,7 +99,7 @@
         "version": "2.126.12",
         "wheel_url": "https://files.pythonhosted.org/packages/4f/3f/0a611e9b25beb75db3f2f521d359eabad0d1ab4e50194b866663355591ff/policyengine_uk-2.126.12-py3-none-any.whl"
       },
-      "policyengine_version": "6.3.2",
+      "policyengine_version": "6.3.4",
       "region_datasets": {
         "national": {
           "path_template": "enhanced_frs_2024_25.h5"
@@ -112,7 +112,7 @@
     },
     "us": {
       "build_id": "populace-us-2024-spm-20260915",
-      "bundle_id": "us-6.3.2",
+      "bundle_id": "us-6.3.4",
       "certification": {
         "built_with_model_version": "2.2.1",
         "certified_by": "policyengine.py bundle certification",
@@ -217,16 +217,16 @@
         "version": "2.2.1",
         "wheel_url": "https://files.pythonhosted.org/packages/5e/09/86ac3968d2a18e28fce3ba1186fc21728e9f299b96a806d6f204f1e0aaed/policyengine_us-2.2.1-py3-none-any.whl"
       },
-      "policyengine_version": "6.3.2",
+      "policyengine_version": "6.3.4",
       "region_datasets": {
         "congressional_district": {
-          "path_template": "populace_us_2024_acs_local.h5"
+          "path_template": "populace_us_2024.h5"
         },
         "national": {
           "path_template": "populace_us_2024.h5"
         },
         "state": {
-          "path_template": "populace_us_2024_acs_local.h5"
+          "path_template": "populace_us_2024.h5"
         }
       },
       "regional_release_manifest_uri": "https://huggingface.co/datasets/policyengine/populace-us/resolve/populace-us-2024-buildo-acs-local-767312d60-20260923T074941Z/releases/populace-us-2024-buildo-acs-local-767312d60-20260923T074941Z/release_manifest.json",
@@ -295,10 +295,10 @@
   "packages": {
     "policyengine": {
       "import_name": "policyengine",
-      "install_requirement": "policyengine==6.3.2",
+      "install_requirement": "policyengine==6.3.4",
       "name": "policyengine",
       "role": "bundle_carrier",
-      "version": "6.3.2"
+      "version": "6.3.4"
     },
     "policyengine-core": {
       "import_name": "policyengine_core",
@@ -334,6 +334,6 @@
       "wheel_url": "https://files.pythonhosted.org/packages/19/a0/c484f69a0ebf88a9b9fd0ac28176f8df66550f46714f1b0c5ec0b360824e/spm_calculator-1.0.0-py3-none-any.whl"
     }
   },
-  "policyengine_version": "6.3.2",
+  "policyengine_version": "6.3.4",
   "schema_version": 2
 }

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/data/bundle/uk.trace.tro.jsonld

@@ -18,18 +18,18 @@
         "schema:url": "https://policyengine.org"
       },
       "schema:dateCreated": "2026-10-07T17:31:53.189867Z",
-      "schema:description": "TRACE TRO for certified runtime bundle uk-6.3.2 covering the bundle manifest, the certified dataset artifact, the country model wheel, and the country data release manifest when it is available.",
+      "schema:description": "TRACE TRO for certified runtime bundle uk-6.3.4 covering the bundle manifest, the certified dataset artifact, the country model wheel, and the country data release manifest when it is available.",
       "schema:name": "policyengine uk certified bundle TRO",
       "trov:createdWith": {
         "@type": "schema:SoftwareApplication",
         "schema:name": "policyengine",
-        "schema:softwareVersion": "6.3.2"
+        "schema:softwareVersion": "6.3.4"
       },
       "trov:hasArrangement": [
         {
           "@id": "arrangement/1",
           "@type": "trov:ArtifactArrangement",
-          "rdfs:comment": "Certified arrangement for bundle uk-6.3.2.",
+          "rdfs:comment": "Certified arrangement for bundle uk-6.3.4.",
           "trov:hasArtifactLocation": [
             {
               "@id": "arrangement/1/location/bundle_manifest",
@@ -75,7 +75,7 @@
             "@type": "trov:ResearchArtifact",
             "schema:name": "policyengine.py bundle manifest for uk",
             "trov:mimeType": "application/json",
-            "trov:sha256": "323b86d959539ed3fbde416387d136161e58483d8f7b6c7b9dc47936e3e18f9b"
+            "trov:sha256": "594d1c8ba2539df9c26ca2b6a7170ab20fb03176e5428b3963dd42e61b707564"
           },
           {
             "@id": "composition/1/artifact/data_release_manifest",
@@ -102,7 +102,7 @@
         "trov:hasFingerprint": {
           "@id": "composition/1/fingerprint",
           "@type": "trov:CompositionFingerprint",
-          "trov:sha256": "c00ff93e4fc59e689bb7c50b979ca5efc749c2eee6c66a3931135fe196c385a1"
+          "trov:sha256": "42003f5d9bda251119c325e8d61d22c05edb1c75bf5b9ad80ab3e497fe548439"
         }
       },
       "trov:hasPerformance": {

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/data/bundle/us.trace.tro.jsonld

@@ -17,18 +17,18 @@
         "schema:name": "PolicyEngine",
         "schema:url": "https://policyengine.org"
       },
-      "schema:description": "TRACE TRO for certified runtime bundle us-6.3.2 covering the bundle manifest, the certified dataset artifact, the country model wheel, and the country data release manifest when it is available.",
+      "schema:description": "TRACE TRO for certified runtime bundle us-6.3.4 covering the bundle manifest, the certified dataset artifact, the country model wheel, and the country data release manifest when it is available.",
       "schema:name": "policyengine us certified bundle TRO",
       "trov:createdWith": {
         "@type": "schema:SoftwareApplication",
         "schema:name": "policyengine",
-        "schema:softwareVersion": "6.3.2"
+        "schema:softwareVersion": "6.3.4"
       },
       "trov:hasArrangement": [
         {
           "@id": "arrangement/1",
           "@type": "trov:ArtifactArrangement",
-          "rdfs:comment": "Certified arrangement for bundle us-6.3.2.",
+          "rdfs:comment": "Certified arrangement for bundle us-6.3.4.",
           "trov:hasArtifactLocation": [
             {
               "@id": "arrangement/1/location/bundle_manifest",
@@ -74,7 +74,7 @@
             "@type": "trov:ResearchArtifact",
             "schema:name": "policyengine.py bundle manifest for us",
             "trov:mimeType": "application/json",
-            "trov:sha256": "323b86d959539ed3fbde416387d136161e58483d8f7b6c7b9dc47936e3e18f9b"
+            "trov:sha256": "594d1c8ba2539df9c26ca2b6a7170ab20fb03176e5428b3963dd42e61b707564"
           },
           {
             "@id": "composition/1/artifact/data_release_manifest",
@@ -101,7 +101,7 @@
         "trov:hasFingerprint": {
           "@id": "composition/1/fingerprint",
           "@type": "trov:CompositionFingerprint",
-          "trov:sha256": "d7ecd868e200c681d97acb264562877d2f86cb9820e2cee5e48b5f3426cae693"
+          "trov:sha256": "0c5fdf655befb2e64f5511bfefd9dc022041a526f1505ac9ee31a7058e349bff"
         }
       },
       "trov:hasPerformance": {

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/outputs/poverty.py

@@ -81,6 +81,21 @@ class Poverty(Output):
 
         # Map poverty variable to target entity if needed
         if poverty_var_obj.entity != target_entity:
+            source = getattr(
+                self.simulation.output_dataset.data, poverty_var_obj.entity
+            )
+            if (
+                target_entity != "person"
+                and pd.isna(source[self.poverty_variable]).any()
+            ):
+                # Mapping onto a group sums members and fills empty groups
+                # with zero, which would count a person outside the SPM
+                # measurement as measured and not poor.
+                raise ValueError(
+                    f"{self.poverty_variable} is missing for units outside "
+                    f"the poverty measurement; summarise it for people, not "
+                    f"for {target_entity} units."
+                )
             mapped = self.simulation.output_dataset.data.map_to_entity(
                 poverty_var_obj.entity,
                 target_entity,
@@ -121,8 +136,13 @@ class Poverty(Output):
         # Calculate results using weighted counts
         self.headcount = float((poverty_series == True).sum())  # noqa: E712
         self.total_population = float(poverty_series.count())
+        # ``None`` means nobody in the group is measured (for example, every
+        # member is outside the SPM measurement population), which is not
+        # a measured rate of zero.
         self.rate = (
-            self.headcount / self.total_population if self.total_population > 0 else 0.0
+            self.headcount / self.total_population
+            if self.total_population > 0
+            else None
         )
 
 

{policyengine-6.3.2 → policyengine-6.3.4}/src/policyengine/tax_benefit_models/common/model_version.py

@@ -417,6 +417,14 @@ class MicrosimulationModelVersion(TaxBenefitModelVersion):
                 RENAMES_RECORD_KEY,
                 read_renames_record,
             )
+            from policyengine.tax_benefit_models.us.legacy_spm import (
+                RECORD_KEY as LEGACY_SPM_RECORD_KEY,
+            )
+            from policyengine.tax_benefit_models.us.legacy_spm import (
+                expected_profile_for_dataset,
+                read_record_value,
+                record_problem,
+            )
 
             with h5py.File(filepath, "r") as stream:
                 raw = (
@@ -442,6 +450,17 @@ class MicrosimulationModelVersion(TaxBenefitModelVersion):
                     "Saved US simulation predates the mapping of renamed "
                     "stored inputs (it has no record of them); run it again"
                 )
+            # BACKWARD COMPATIBILITY (#597, #598): an output is reused only
+            # under exactly the legacy SPM declarations its input needs.
+            recorded_legacy_spm = read_record_value(filepath)
+            legacy_problem = record_problem(
+                recorded_legacy_spm, expected_profile_for_dataset(simulation.dataset)
+            )
+            if legacy_problem is not None:
+                raise ValueError(
+                    f"Saved US simulation output is out of date: {legacy_problem}; "
+                    "run it again"
+                )
 
         if self.country_code == "uk":
             from policyengine.tax_benefit_models.uk.datasets import (
@@ -474,6 +493,10 @@ class MicrosimulationModelVersion(TaxBenefitModelVersion):
             simulation.output_dataset.metadata.update(
                 {"spm_config": recorded["config"], RENAMES_RECORD_KEY: recorded_renames}
             )
+            if isinstance(recorded_legacy_spm, dict):
+                simulation.output_dataset.metadata[LEGACY_SPM_RECORD_KEY] = (
+                    recorded_legacy_spm
+                )
 
         if os.path.exists(filepath):
             simulation.created_at = datetime.datetime.fromtimestamp(