Harden Arch target semantics for Microplex eCPS replacement

[MaxGhenis]

Parent plan: PolicyEngine/microplex-us#10

Goal: make Arch the canonical target semantics registry for Microplex national and local replacement builds.

Deliverables:

• Add source/concept exclusions for misleading broad concepts.
• Add explicit target scope labels: filer, full population, recipient, household, tax unit, SPM unit, state, CD, local.
• Export importable target coverage reports by product: mp-national, mp-local-rich, and mp-local-fast.
• Add regression tests for known semantic failures, including proprietors income scope and SSI recipient/value confusion.

Exit criterion: no release-suite target lacks source, scope, and entity provenance.

[MaxGhenis]

Umbrella discussion: PolicyEngine/microplex-us#16

[MaxGhenis]

Progress update from Microplex target hardening work on 2026-05-28:

• Merged Add SOI Table 2.1 itemized deduction details #32 for SOI Publication 1304 Table 2.1 itemized-deduction details.
• Merged Map SOI itemized deduction facts microplex-us#27 to map those facts into Microplex target variables and keep SOI total state/local taxes skipped because it includes personal property taxes outside PolicyEngine's federal salt input.
• Merged Compose SALT targets from Arch components microplex-us#28 to derive the exact PolicyEngine salt itemizer amount target from Arch components (state_and_local_sales_or_income_tax + real_estate_taxes) rather than mapping the broader SOI total.
• Merged Tighten source-backed target profile microplex-us#29 to tighten the pe_native_broad_source_backed profile so semantically impossible cells are no longer counted as source-backed gaps. Excluded cells include the non-itemizer SALT amount/count cells, state SALT cells without exact component sources, and state AGI person counts where loaded SOI sources only provide return counts and AGI amounts.
• Merged Add SOI Table 1.4 alimony facts #33 for SOI Publication 1304 Table 1.4 alimony received/paid amounts and return counts.
• Merged Map Arch SOI alimony targets microplex-us#30 to map those alimony facts into Microplex and promote alimony_expense into the source-backed profile.

Latest coverage artifacts:

• Broad after SALT composite: /Users/maxghenis/CosilicoAI/microplex-us/artifacts/arch_salt_component_composite_20260528/pe_native_broad_2024_coverage_with_salt_composite.json -> 165 / 189.
• Source-backed after alimony: /Users/maxghenis/CosilicoAI/microplex-us/artifacts/arch_soi_table_1_4_alimony_20260528/pe_native_broad_source_backed_2024_coverage_with_alimony.json -> 167 / 167.

Remaining source-backed gaps: none.

The SALT raw/count cells and state AGI person-count cell remain in the broad experimental profile, but no longer block the source-backed profile because current primary sources do not define those exact PolicyEngine target cells.

[MaxGhenis]

Progress update: merged #34 to add BEA NIPA source packages for total wages/salaries, personal income components, and personal income disposition. The package tests explicitly keep broad BEA concepts namespaced as bea_nipa.*, including a guard that BEA proprietors' income is not mapped to self_employment_income. This gives Microplex access to top-level BEA concepts as reference facts without repeating the proprietors-income target pollution issue.

[MaxGhenis]

Progress update: merged #35 to add the CBO February 2026 income-source projection package. The package emits six production Arch consumer facts with R2-backed raw provenance and source-row/source-cell lineage, but keeps them as cbo.*_projection reference concepts rather than mapping broad CBO rows directly into Microplex leaf targets. The tests pin net business income away from self_employment_income and assert exact SHA/size/R2 plus consumer-contract canonical concepts.

[MaxGhenis]

Progress update: merged #36 to add ACS 2024 S0101/S2201 local source packages. Arch now has R2-backed, lineage-valid consumer facts for national/state/congressional-district age-band population from S0101 and congressional-district SNAP household counts from S2201. The district packages cover 437 119th Congress districts, with 7,866 S0101 age facts and 1,311 S2201 SNAP household facts; validate-package and build-suite passed for all four ACS packages.

[MaxGhenis]

Update: merged #37, adding the BEA regional state personal income package.

This gives Microplex/Macro target integration a validated 2024 state-level BEA regional package with 312 consumer facts across personal income, dividends/interest/rent, transfer receipts, wages and salaries, supplements, and proprietors income. The package validates cleanly with zero agent-acceptance errors and preserves raw R2 provenance in the build suite.

Microplex already has adapter coverage/guards for the BEA regional concepts, including blocking broad proprietors-income concepts from being treated as plain self-employment income, so this is ready to use as an Arch source input once Arch is refreshed in the Microplex target build.

[MaxGhenis]

Update: merged #38, adding the IRS SOI 2022 state-data U.S. totals package.

This contributes four validated 2022 tax-year consumer facts for Microplex target ingestion: individual income tax return count, adjusted gross income, EITC three-or-more-child return count, and EITC three-or-more-child amount. The build suite had 4 consumer facts, 668,304 source cells, lineage coverage 1.0, and 0 agent-acceptance errors.

I also verified Microplex can load the generated consumer_facts.jsonl into the expected target shapes: filer count, AGI, EITC 3+ child claims, and EITC 3+ child amount with the relevant filer/EITC child-count filters.

[MaxGhenis]

Update: merged #39, adding the ACS 2023 B01001 state female age 15-44 package.

This contributes 468 validated state-level consumer facts across 52 geographies and 9 female age bands, with 3,752 source cells, lineage coverage 1.0, and 0 agent-acceptance errors. The package covers census_acs.person_count with age and sex constraints.

The generated consumer facts exposed a Microplex adapter gap for sex constraints; that is now fixed and merged in PolicyEngine/microplex-us#39. I verified the generated B01001 consumer_facts.jsonl loads into 468 Microplex person_count targets with age, is_female == 1, and state_fips filters.

[MaxGhenis]

Split out and merged the CMS ACA marketplace package work in #40. It adds CMS 2024 OEP state-level facts, CMS 2022 OEP state-level facts, and CMS 2022 effectuated enrollment / financial-assistance facts. The CMS total enrollment fact now uses canonical concept cms_aca.marketplace_effectuated_enrollment, so Microplex can compose it with the KFF 2024 marketplace effectuated-enrollment target. Local validation covered Arch package validation/build-suite for all three packages plus a Microplex ACA PTC multiplier smoke check producing 51 state rows, with California using the OEP APTC base and Nevada using the effectuated fallback.

[MaxGhenis]

Update: merged #41, adding the CMS Medicaid/CHIP monthly enrollment dataset package from the April 2026 release. It emits December 2025 final state facts for total Medicaid+CHIP, Medicaid, CHIP, child, and adult enrollment: 255 consumer facts over 51 states, 10,608 source rows, 2,288 source cells, lineage coverage 1.0, and 0 agent-acceptance errors. I also verified Microplex can load the built into 51 model-year-2025 state targets through .

[MaxGhenis]

Clarification on the #41 Microplex check: the built consumer_facts.jsonl loads through Microplex ArchConsumerFactJSONLTargetProvider into 51 model-year-2025 state medicaid_total_enrollment targets.

[MaxGhenis]

Update: merged #42, adding the focused CMS ACA 2025 OEP source package. It passed local Arch validation/build-suite and same-repo CI, so the CMS ACA split now covers the 2022 OEP, 2022 effectuated, 2024 OEP, and 2025 OEP packages outside the broad draft PR.

[MaxGhenis]

Update: merged #43, adding the Census 2023 national population projections source package. It emits 86 CY2025 national age-population consumer facts with 2,580 source rows, 273 source cells, full lineage, and zero agent-acceptance errors. Microplex target ingestion for this Arch concept landed separately in PolicyEngine/microplex-us#40.

[MaxGhenis]

Update: merged #44, adding the HHS ACF LIHEAP FY2023 National Profile source package. It builds one FY2023 household energy-assistance target with full lineage coverage, matching the existing FY2024 LIHEAP package pattern; Microplex smoke-loaded the built consumer fact as an SPM energy subsidy recipient-count target.

[MaxGhenis]

Update: merged #45, adding the IRS SOI 2022 congressional district source package. It preserves all 4,791 CSV source rows and builds 1,440 all-return facts: return count, filer-individual count, and AGI for the US total, 51 state totals, and 428 117th-congressional-district geographies, with full source-row/source-cell lineage. Companion Microplex PR PolicyEngine/microplex-us#41 is also merged, normalizing 5001700US district IDs so these facts map to congressional_district_geoid targets.