Drop congressional-district SALT and PTC facts read from the wrong IRS column

[MaxGhenis]

Part of #1038. Split out of #1040 so this bug fix can land on its own; #1040 keeps the congressional-district capital-gains share change, which needs Max's ruling.

Summary

Chronicle's congressional_district_2022 package (22incd.csv) reads two measure pairs from IRS columns that mean something else. The IRS documentation guide (22incddocguide.docx) is the reference.

Measure id	Column the package reads	What the guide says it is	Column the measure id means
limited_state_local_taxes_returns / _amount	N18425 / A18425	State and local income taxes (Schedule A line 5a), before the $10,000 limit	N18460 / A18460, limited state and local taxes (line 5e), which Historic Table 2 reads and salt_deduction measures
premium_tax_credit_returns / _amount	N85530 / A85530	Additional Medicare tax (Form 8959 line 24)	N85770 / A85770, total premium tax credit, which Historic Table 2 reads and assigned_aca_ptc measures

TY2022 US values in the file itself:

• A18425 is $250.4B against $121.2B for A18460.
• N85530 is 6,848,330 returns and $14.2B, against 7,713,000 returns and $53.1B for N85770.

On the default full target surface:

• The district SALT amount rows summed to 1.98x the national target.
• The PTC return rows counted additional-Medicare-tax payers as PTC recipients.
• The PTC amount was already dropped, by a hard-coded check whose comment called A85530 "not the same gross annual PTC control"; it is not PTC at all.

Of the package's 56 measures, 50 have a twin in a Historic Table 2 package, and these four are the only ones that read a different column from their twin.

What changes

• US_FISCAL_TARGET_SOURCE_COLUMN_EXCLUSIONS (fiscal_targets.py): a reviewed register keyed by (measure id, layout.source_column_id). It drops every SOI fact read from a listed column, at every geography and vintage, before selection.
  • The IRS column is the definition, so a package corrected to read N18460/N85770 passes untouched. A chip is filed for the Chronicle remap.
  • A congressional-district fact of a listed measure that names no column refuses the compile (MissingSoiSourceColumnError), so a feed schema change cannot quietly lift the exclusion.
  • Each entry's reason quotes the guide definitions and the file's values.
• Receipt. us_fiscal_target_exclusion_receipt gains a source_column_concept_exclusion rule, which the release's us_source_coverage.json carries. The coverage report also lists the register (fiscal_target_source_column_exclusions).
• Removed: _is_soi_cd_premium_tax_credit_amount_conflict, now covered by the register with the right reason.
• state_cd. Its STATE_CD_DEFECTIVE_CD_FILE_MEASURES stays as a second fence; the comment now says the compiler drops these first.
• Docs:
  • docs/us-fact-to-target.md: when to use the column register, and when a component column needs a share-or-drop decision instead.
  • docs/us-acs-local-soi-target-surface.md: the ACS-local mode counts.
  • The changelog fragment.

Not in the register: interest paid. interest_paid_deduction_* in the same package reads N19300/A19300, line 8a mortgage interest. That is a component of the line-10 deduction the measure id means, not another concept, so it needs a share-or-drop decision of its own; a chip is filed. It also feeds state_cd's itemized bridge.

Effect on the pinned feed

Release compile on 51aa40f: target period 2024, aging, packaged CD crosswalk, Medicaid substitution.

	main (123927679)	this PR
Compiled targets, all on full	33,250 (f5bd921d6b21)	31,786 (f38dbd749180)
national_state	6,102 (e1f9906bf0e0)	6,102 (e1f9906bf0e0), byte-identical
District SALT amount, sum on full	$272.3B (1.98x the national $137.4B)	none

• Removed: 1,464 specs, all congressional-district, all on full:
  • 976 SALT (US row, 51 states and 436 districts per measure);
  • 488 PTC returns.
• Nothing else changes: no spec is added, and no value or metadata moves.

ACS local release:

• state and state_cd are unchanged. (state_cd already dropped these rows itself.)
• --soi-mode totals goes from 607 to 120 SOI specs, losing the 487 district PTC-return rows.
• --soi-mode full goes from 31,321 to 29,860.

Invariants

• Exact. A fact is dropped if and only if its (measure id, IRS column) is registered. The same measure read from the right column compiles. Unit tests cover district and state rows, both directions.
• Receipt completeness. For any sub-feed of the synthetic five-rule feed, each receipt rule lists exactly the facts it drops or allows. This is the existing Hypothesis property, extended to the new rule.
• Fail closed. A listed congressional-district fact with no column refuses the compile and the receipt. The Historic Table 2 US package, which publishes no column ids, still compiles.
• Pinned.
  • No district SALT or PTC target compiles; the Historic Table 2 rows of those measures still do.
  • The receipt lists exactly 4 × 488 ids.
  • national_state is byte-identical (e1f9906bf0e0).

Tests

These runs were local, on the pinned 51aa40f feed, run sequentially with peak RSS 3.3 GB. CI has no feed and skips the pinned-feed tests.

• engine_free/us/test_us_fiscal_targets.py: 172 passed, none skipped. That includes three pinned-feed tests: the exclusion receipt (4 × 488 ids), the fences (31,786 / f38dbd749180 / e1f9906bf0e0) and the new "no district target reads an excluded column".
• The ACS-local release tool, the state_cd sparse surface (its feed-gated contract test included), source coverage, release target parity, the Chronicle feed and the fiscal refresh builder, run with MICROCOSM_US_CHRONICLE_FACTS set: 495 passed, none skipped.
• The ACS-local contract test now pins totals at 120 SOI specs (Historic Table 2 PTC only) and full at 29,860. These were measured with state_admin_specs on the pinned feed.
• tools/ci_test_plan.py verify passes. ruff check and ruff format --check are clean on the touched files.

New tests:

• the exact drop (district and state rows; the corrected N85770/A18460 facts compile);
• every register reason names both its column and the right column;
• the missing-column refusal, in the compile and in the receipt, with the Historic Table 2 US package without columns still compiling;
• the receipt rule added to the five-rule synthetic feed and its Hypothesis completeness property;
• the pinned checks above.

axiom: n/a: microsim target compilation, no policy rule changes.

🤖 Generated with Claude Code