Census STC: State income tax collections as baseline claims (#176)

[PavelMakarchuk]

Closes #176.

Summary

New mode-1 lane census-stc: each State's individual income tax collections (Census STC item T40) as claims with PE counterparts, so that App v3 has a baseline check for every State income tax reform.

• Adapter sources/census-stc/ reads the FY2023–FY2025 flat files (stdlib CSV). QC: the header and the 25 items are exact; every cell is whole thousands or X; for every item, the US column equals the sum of the 50 States (the nation excludes DC); the six jurisdictions without T40 are AK, FL, NV, SD, TX and WY.
• Claims: 132 claims (44 jurisdictions × 3 fiscal years), new metric tax_collections (cash collections, kept apart from tax_liability).
  • Dropped, with tallies: the national total (the issue asks for one claim per State) and Tennessee (residual Hall-tax collections; no engine variable).
• Counterparts: pipeline/campaign_us/census_stc.py computes the weighted CY2024 total of each State's own <st>_income_tax, which is the State government's tax, as Census counts it. It records state_income_tax summed over the State's tax units beside it. That sum adds Maryland's county taxes and New York City's tax, and Idaho's own variable adds the $10 Permanent Building Fund tax. It also records the us-6.2.1 calibration target and estimate. 88 results attach to FY2023 (the in-sample fit) and FY2025 (the latest year), all constructed.
• App v3 matching: program and the result's policyengine_variables are the State's own variable (vt_income_tax). App v3 matches a reform's reached variables (depth 6) against these, and state_income_tax is reached by every State's reform. So the per-State name keeps a Vermont reform on Vermont's claims.
• Relationship (relationships.us_source_relationship, now with an optional period): FY2023 is consumed_as_target, because us-6.2.1 targets census_stc.fy2023.individual_income_tax_collections.<st>.t40 for exactly these 44 jurisdictions. FY2024 and FY2025 are held_out.
• Annotations, each with a basis: collections vs liability timing; State fiscal-year ends (NY, TX, AL, MI differ); nonresident tax in collections; FY2023 is a soft target.

For @MaxGhenis: boundary rule

STC collections are administrative outturns. The 2026-08-02 boundary ruling (#6) routes those to Chronicle, never to claims. This PR stages them as claims on purpose, decided on #176, so that App v3 can show them. The populace registry's <st>_admin and irs_soi rows are already claims, so there is a precedent. The ingest docstring and the lane note record the departure. Please confirm, or say if you would rather have both (Chronicle facts plus claims).

Finding (draft microcosm issue ready)

us-6.2.1 measures the Maryland and New York T40 targets with state_income_tax, which includes Maryland's county taxes and New York City's tax. The calibrated estimate equals that sum within 0.12%: 2.15× the MD target and 1.21× the NY target. The State's own variables are 1.30× and 1.01× the targets. A Maryland/New York annotation states this on the claims.

Test plan

• Two builds give the same content hash (2e09d27f…); no drift after the build and the suite
• pytest tests/: 1778 passed, 15 skipped. test_modal_uk_event was deselected locally because it needs Python 3.12. The export pins were updated: US rows 447 → 535, total 5631 → 5719
• New tests/test_census_stc.py (7 tests): the extract equals the adapter output; the QC catches a broken national total; claims, drops and relationships are exact; FY2023 values equal the calibration targets; results attach by State variable only
• ruff format --check; bun test src

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
policyengine-scorecard	Ready	Preview	Oct 16, 2026 1:32pm UTC