Measure SPM poverty on legacy certified sources: ACS group quarters outside the SPM measurement #597

Problem

Every US calculation on the certified ACS-local source (populace_us_2024_acs_local.h5, revision populace-us-2024-buildo-acs-local-767312d60-20260923T074941Z, SHA-256 769756c31f3ca646d12c272511744dec04c0e68870c6946dd945fbba65b6a7ec) stops with SPMInputError: SPM_COMPOSITION_REQUIRED ("SPM unit has no classified adult").

The source keeps ACS group-quarters residents for ordinary tax and benefit calculations, but it does not declare which SPM units belong to the SPM measurement population. policyengine-us 2.2.1 therefore requests canonical SPM thresholds for every unit, and a single-person group-quarters unit holding a child stops the whole run.

A read-only scan of the full source found:

• 183,206 ACS group-quarters SPM units, all of them single-person;
• of those, 5,246 contain only a child (148 in Utah).

This is the failure behind:

• the real Utah check in Use ACS-local data for US regional simulations policyengine-sim-api#726;
• the beta deploy verification failures after policyengine-sim-api#746 and #750.

Backward-compatible fix

Census's ACS SPM methodology measures the household population only. For this exact source, .py would:

• Classify each SPM unit from its record-type evidence: ACS TYPEHUGQ 2/3 with matching RELSHIPP 37/38 means group quarters. Age is never used, and unknown or inconsistent evidence raises.
• Store that classification in each create_datasets year file, with a record.
• Skip the canonical SPM provider for group-quarters units, and return NaN ("not measured") for their SPM thresholds, resources and poverty indicators. Poverty indicators become floats.

Everyone stays in every ordinary tax, benefit and income calculation. Memberships and weights are unchanged.

When this is no longer needed

This is backward compatibility for a legacy certified source, kept while anything still reads that source. The source-specific derivation can be retired once two things are in the certified bundle:

• a certified ACS-local release that declares SPM measurement scope itself (for example, Declare the US SPM measurement universe from the source record type microcosm#977's helper activated in the release build);
• a policyengine-us release that reads that declaration (Separate SPM measurement scope from ordinary income policyengine-us#9462 or its successor).