US calibration does not pin federal income tax or AGI; base undershoots income tax ~18% — add SOI fiscal targets + a macro-realism gate

[MaxGhenis]

Summary

The US calibration profile does not pin federal income tax or AGI as hard targets, and the certified base undershoots actual income tax by ~18%. Every downstream score that nets against federal income tax inherits a low base.

Evidence

Running the certified populace_us_2024.h5 straight through PolicyEngine-US (standard path, no consumer-side value scaling), 2024:

quantity	populace	actual (approx)	gap
federal income tax	$1,991B	~$2.4T (Treasury FY2024 individual)	~18% low
AGI	$14,901B	~$16T (extrapolated SOI)	~7% low
Social Security	$1,523B	~$1.45T	~+5%

The build (packages/populace-build/src/populace/build/us/__init__.py) compiles a versioned target registry plus an inline SCF net-worth target; no federal income-tax or AGI aggregate appears in the target surface. This is consistent with #30 ("the US target profile needs full-population and program-admin controls… SOI is essential for filer/tax-form controls") and #29 (no gate that the target profile covers the needed source families).

Why the composition matters (not just a level fix)

The income-tax undershoot (~18%) is more than double the AGI undershoot (~7%). Income tax is convex in income, so a base that is light on top-of-distribution and capital income misses tax far more than it misses AGI. A single "AGI total" target would not close this — the fix needs AGI by source and/or bracket (or the income-tax aggregate directly) so the income composition is right and tax falls out correctly. This is the same lesson the CRFB taxation-of-benefits long-run build relied on: scale economic values to source-level admin aggregates (earnings to SSA taxable payroll cap-aware, etc.) with demographics carried in the weights, rather than letting reweighting alone hit dollar totals.

Note populace does not have the opposite (over-calibration) pathology that eCPS showed over the long run — it is modestly low, not inflated. So this is about adding the fiscal target, not undoing a distortion.

Proposed fix

1. Add SOI fiscal hard targets to the US profile: AGI by source (wages, business/partnership/S-corp, capital gains, dividends, interest, pensions, Social Security) and, where used as a control, total federal income tax — sourced from the SOI/admin coverage contract (adjacent to the Use Arch US poverty/nonfiler coverage contract in Populace target gates #29/Add NIPA and program-admin nonfiler controls to the US target profile #30 admin-target work).
2. Add a macro-realism release gate: assert income-tax/GDP, AGI/GDP, and the poverty rate land in believable bands on every build (generalizes the income-tax-%-of-GDP sanity check; complements the SPM diagnostic gate in Add a Populace US poverty/SPM diagnostic gate for resource distribution and negative-income tails #33). This would have caught the ~18% undershoot before publication.

Relationship to existing issues

Adjacent to #29 (target-profile source-coverage gate) and #30 (NIPA/admin nonfiler controls) — those center on poverty/nonfiler resources; this is specifically the income-tax / AGI fiscal controls and the macro-realism gate. Complements #33 (SPM diagnostic gate) on the validation side.

[MaxGhenis]

Update: this is a regression from eCPS, not a greenfield gap — and eCPS already had the right mechanism to port

Checked the predecessor build (policyengine-us-data, policyengine_us_data/calibration/unified_matrix_builder.py). eCPS did calibrate income tax, via a tax-expenditure mechanism:

• reform_id = 1 means "neutralize the target variable and fit the income-tax delta, matching the legacy ECPS JCT target semantics" (_calculate_neutralized_expenditure_values, ~L599-628). For each tax provision in reform_variables, the loss matrix carries the per-record income-tax change from neutralizing that provision, calibrated to JCT's tax-expenditure estimate for it.
• This pins both the level and the composition of federal income tax (every major provision's modeled revenue effect must match JCT), which is exactly the composition problem flagged above — the 18% tax undershoot vs 7% AGI undershoot.
• eCPS also targeted state income tax (tests/test_database_build.py::test_state_income_tax_targets).

So populace's missing income-tax calibration is a regression introduced in the rebuild, and the fix has a concrete reference implementation: port the JCT tax-expenditure target family (neutralize-provision → fit income-tax delta) and the state income-tax targets from unified_matrix_builder.py into the populace target registry, rather than designing from scratch.

Recommended target set to restore/port:

1. Federal JCT tax-expenditure targets (the neutralize-and-fit-income-tax-delta family) — disciplines income-tax composition + level.
2. State income tax targets.
3. (From the original issue) the macro-realism release gate as the backstop that would have caught the regression.

Not yet verified here: the exact JCT provision list and target values (they live in the eCPS targets DB/artifact, not inline), and an apples-to-apples eCPS-vs-populace base income-tax/GDP number (the live eCPS file carries an unrelated miscellaneous-income inflation that would confound a direct run). The mechanism and the regression are clear from the build code regardless.