Rebase congressional-district taxable interest onto Table 4.3 as shares of the district file's US row

[MaxGhenis]

Part of #1038 (follow-up from the 2026-09-27 congressional-district concept sweep, lane D). Independent of #1036, #1040 and #1224; it builds on main.

Summary

The congressional-district file (22incd.csv) is TY2022 data that the feed stamps ty2023 (Chronicle#117). Its taxable-interest rows (A00300/N00300) shipped on the default full surface as TY2022 levels.

Historic Table 2's TY2022 interest rows have been rebased onto the latest Pub 1304 control since #518 (#489 adjudication): taxable interest grew x2.35 from TY2022 to TY2023, while interest dollar targets age on the CBO AGI default (x1.12). #518 barred the district file from being a control but left its own rows as levels.

On the pinned feed (51aa40f), after aging:

	district-file US row	its 51 states (sum)	its 436 districts (sum)	national target (Table 4.3 ty2023)
amount, main	$134.59B, compiled as a second national target	$134.59B (0.395x)	$134.59B (0.395x)	$340.43B
returns, main	48,547,160	48,547,160 (0.896x)	48,547,160 (0.896x)	54,167,410
amount, this PR	retired (it is the share denominator)	$340.43B	$340.43B	$340.43B
returns, this PR	retired	54,167,410	54,167,410	54,167,410

The district US row and Table 4.3 materialize the same unfiltered taxable_interest_income sum. On main the surface therefore asked for one quantity at two values 2.53x apart: the contradiction #489 removed for Historic Table 2. #1030's stamp correction moves these levels only about +3%.

What changes (fiscal_targets.py)

Share families. The interest rebase now treats every stale photo as a share family (_SOI_TAXABLE_INTEREST_SHARE_FAMILIES): Historic Table 2, and the district file of any data year (22incd.csv's record sets read congressional_district_2022, the data year).

• Each row ships as its share of its own family's national all-AGI row at its own period, times the Pub 1304 control: one factor per family, quantity and period.
• Each family's national all-AGI row retires, because the control's own row owns the national concept.
• Every share row names its denominator in soi_share_total_source_record_id. This is the key Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 uses for capital gains.

Denominators (_soi_taxable_interest_share_national_totals).

• Keyed by family, so a district row never divides by the Historic Table 2 US row.
• Two different totals under one key refuse the compile (AmbiguousSoiTaxableInterestShareTotalError). Equal totals name the smaller record id, whatever the feed order.

Controls are unchanged. The Table 4.3 control, reached through the declared all_returns -> returns_excluding_dependents universe bridge, applies to the district rows exactly as it does to Historic Table 2's. A share family still never anchors the control; the bar now covers any district file, where main matched only .congressional_district_2022..

Hierarchy. One factor scales a family's states and its districts alike. So the congressional_district_children_scale_to_state_parent rule that runs next reconciles all 872 district interest rows with factor 1.

Stamp-invariance. A share divides the district rows by the district US row of the same restamped package, so the period stamp cancels. The value lands at the control's period (2023) and ages from there on the same link as the Table 4.3 row. This holds while the stamp is no later than the control's period. A family stamped after every control keeps its levels and its US row, as on main; the next district file under the same +1 stamp error would do this, and #1030's restamp prevents it. Tracked in #1236.

One behaviour change in a corner (both families)

A full-range row whose own family has no national total is now dropped when a control is eligible. On main it stayed as a stale TY2022 level beside the control.

• With no control anywhere it still stays (the Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518 no-anchor rule), and an AGI slice without a total still drops.
• This matches capital gains on main, which drops a row whose control exists but whose source total is missing.
• The last block of test_stale_soi_taxable_interest_period_selection_laws pinned the old behaviour and is rewritten.
• It does not occur on the pinned feed, where every family has its US row.

Effect on the pinned feed

Release compile on 51aa40f: target period 2024, aging, packaged CD crosswalk, Medicaid substitution. A diff of every compiled spec against main (51a263726):

	main	this PR
Compiled targets (full)	33,250 (f5bd921d6b21)	33,248 (5bdfa798ad97)
national_state	6,102 (e1f9906bf0e0)	6,102 (1b318eafb174)

• Removed: the district file's two US interest rows.
• Values: the 974 district-file state and district interest rows, by one factor per measure. Amounts move x2.52943223191 ($313.120B / $123.791B raw); returns move x1.115768872989 (54,167,410 / 48,547,160).
• Metadata only: 1,052 Historic Table 2 interest rows gain soi_share_total_source_record_id. 1,034 of them are on national_state, which is that surface's whole change: no national_state value or membership moves.
• Hierarchy: all 872 district interest rows reconcile with factor 1.

The tilt. Historic Table 2's US row includes Puerto Rico and other areas, so its rebased states sum to 0.984 of the control for amounts and 0.992 for returns. The district file has no other-area rows, so its states sum to exactly the control. In aggregate each district-file state target therefore sits about 1.7% (amounts) and 0.8% (returns) above the matching HT2 state share; per state the amount ratio runs from 0.80 (Wyoming) to 1.075 (Rhode Island, Delaware, DC), a spread typical of the CD-vs-HT2 pairs full already carries.

• The model has households in the 50 states and DC only, and the national row on the same surface already asks them for the whole control.
• The alternative, scaling the district file by HT2's 51-state share, would mix two families' totals in one factor and set the district states below the national row.
• Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 proposes the same split for capital gains, pending d539.

ACS-local (tools/build_us_acs_local_release.py on the same feed, main vs this PR):

• state_cd: all 26,425 spec values are identical (max relative difference 4.3e-16). Its counts, the factor band's out-of-band blocks, its drops and its internal-consistency check are all unchanged.
  • state_cd already used district interest rows only as within-state shares of Historic Table 2, so a national factor cancels.
  • Only the receipt's interest rebase-factor summaries move: amounts from 2.35–2.70 to 0.93–1.07 (median 0.977), returns from 1.095–1.116 to 0.981–1.001.
  • docs/us-acs-local-soi-target-surface.md and a comment in tools/us_acs_local_cd_surface.py are updated.
• state / totals / full: irs_soi counts unchanged at 4,227 / 607 / 31,321. On full, the district interest values move as above.

Invariants

• Shares conserve the control.
  • Every share row is raw x control / its own family's US row.
  • A family's states, and each state's districts, sum to control x (Σ states / family US), so never past the control. When the states partition the US row (the district file), they sum to exactly the control.
  • No district-file interest row ships at the country level.
  • Every rebased row's control is a compiled national target.
  • Test: a Hypothesis property over random district packages and their period stamp (2022 or 2023), other-area residuals, HT2 rows, controls, measures, and an equal-valued twin US row sorting before or after us.
• Order-free. The compiled registry (names, values, metadata) is identical in every feed order, and a twin total names the smaller record id. Tests: the property; a parametrized twin-denominator test.
• Own denominator. Every share row divides by, and names, its own family's US row; conflicting totals refuse. With the district file stamped truthfully at 2022, its US row shares period, universe and status with Historic Table 2's, so only the family separates them. Tests: the property; the stamp differential.
• Stamp-invariance. Test: a differential compiles and ages the package stamped ty2023 (as on the feed) and truthfully at 2022. The values are identical and age from the control's 2023 period on the AGI link, exactly as the Table 4.3 row does.
• Coverage band (pinned, two-sided). On the full surface every stale taxable-interest family sums to within [0.85, 1] of the national target it was scaled to: the district file's states and districts, and Historic Table 2's states.
  • The comparison key reads a bridged universe (soi_return_universe_bridge) as the control's universe and drops the materializer's no-op all ledger filters (_is_noop_ledger_filter_value), so all-returns rows compare with the excluding-dependents Table 4.3 row.
  • No compared family may be missing.
  • On main it fails: the district US row is still a country-level target, and the district families sit at 0.395 (amounts) and 0.896 (returns), as computed on the main compile dump.

Tests

Run locally on the engine-free venv; the pinned-feed tests read ~/PolicyEngine/_buildh-runtime/inputs/consumer_facts_us_51aa40f.jsonl. CI has no feed and skips them.

• engine_free/us/test_us_fiscal_targets.py: 182 passed, plus the 3 pinned-feed tests (the receipt, the fences re-pinned at 33,248 / 1b318eafb174, and the new district interest check).

• Neighbouring suites at 2b7164e15, 280 passed with none skipped:

  • test_us_acs_local_sparse_cd.py, including the pinned-feed state_cd contract test;
  • test_us_congressional_district_vintage.py;
  • test_us_soi_state_agi_bands.py;
  • shared/test_release_target_parity.py;
  • test_us_release_gate_preflight.py;
  • test_us_chronicle_feed.py;
  • test_us_acs_local_release_tool.py.

• test_us_fiscal_refresh_builder.py: 327 passed, 6 skipped (they need the US engine extra).

• Mutation run. Each mutant of fiscal_targets.py ran against the interest tests; two also ran against the pinned check. All 8 were killed (failing tests in brackets):

  • the district file not a share family (11, plus the pinned check);
  • share rows not naming their denominator (5);
  • totals stored under the wrong key, so every lookup misses (19);
  • stale levels kept beside a control (3);
  • conflicting totals not refused (1);
  • the district US row surviving (4, plus the pinned check);
  • the district file allowed as a control (7);
  • a family-agnostic key and lookup (1). Only the corrected-stamp case separates the two families' US rows, so 4602d939d adds Historic Table 2 rows to the stamp differential to pin it. Since 8bf49c35e the property also draws that case.

  The mutants and log are in the evidence folder.

• ruff check and ruff format --check clean; tools/ci_test_plan.py verify passes.

• 8bf49c35e was pushed during a host hold. It holds the property rewrite plus docstring and doc edits; CI's engine-free jobs cover it, and the interest and pinned suites re-run locally once the hold lifts.

New tests:

• the district rows are shares of the control, while HT2 rows keep their own denominator;
• the stamp-invariance differential;
• no control keeps levels;
• no family total drops the rows beside a control (district file and HT2);
• conflicting totals refuse;
• an order-free denominator;
• a share-family classification table;
• the Hypothesis property;
• the pinned coverage-band check.

Interplay

• Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 (CD capital gains, d539) and Choose the capital-gains rebase control by concept and period, not feed order #1036 (d468).
  • Same pattern, different column. Here the district rows measure the same concept as the control (taxable interest, A00300); only the vintage is stale. Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's rows proxy for another concept (line 7 for Schedule D), which is why Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 waits on a ruling and this does not.
  • Distinct helper names avoid textual collisions with Choose the capital-gains rebase control by concept and period, not feed order #1036's _soi_record_set_family and Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's _SoiShareTotal.
  • Whichever lands second should fold them together. The two classifiers then disagree only on a hypothetical record set with no data-year suffix: Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 matches a token starting with congressional_district, this PR the substring .congressional_district_.
  • Overlay check (Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 head 90ad595a6 merged into this PR, pinned compile): source files merge clean and no taxable-interest row moves. Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's raw-key invariant still compares 35 of 52 families, none out of band.
  • Its fence numbers re-pin. Under this PR's bridged key the two interest families join, at 37 compared.
  • That key is the interest comparison key, not the materializer's full key. It omits the EITC child-count and positive-EITC filters, source_variable and taxable_only, so it needs those before covering every measure.
• Drop congressional-district SALT and PTC facts read from the wrong IRS column #1224 (CD SALT/PTC columns). Touches the same fences test and ACS-local doc. Textual re-pin only; no semantic overlap.
• Read restamped Chronicle facts at their data year before aging #1030 (source-vintage restamp). Its head already carries the share narrowing (bab55cb97), which admits a rebased restamp whose soi_share_total_source_record_id is a restamp of the same package and stamp.

  • Overlay check (Read restamped Chronicle facts at their data year before aging #1030 head c04a81eba merged into this PR, pinned compile): no refusal; 33,248 targets and 6,102 national_state at 24fdeda1f948.

  • All 974 district interest rows are admitted: uprating_from_period 2023→2022, uprating_to_period stays 2023, aging factor unchanged. No interest value moves.

  • Owed by whichever lands second (pinned tests skip in CI, so CI will not catch either):

    1. re-pin the fences version to 24fdeda1f948;
    2. update Read restamped Chronicle facts at their data year before aging #1030's test_pinned_feed_corrects_the_translated_congressional_district_specs. Its counts become 11,336 / 12,644 / 1,352 / 1,454, because the 487 interest amount rows stop aging on the chained TY2022 bridge and the 2 district US interest rows retire. Its "no restamped share" assertion must allow exactly the 974 district taxable-interest shares.

    The Read restamped Chronicle facts at their data year before aging #1030 session has the details.

Why this lands without a ruling

• The district rows read A00300/N00300: the same concept and column as Historic Table 2's rows and the Table 4.3 control. Their only defects are vintage and processing-window coverage.
• The Taxable-interest HT2 national row exceeds its AGI-bin partition by 9.8%: HT2-vs-CD-table source discrepancy #489 adjudication (Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518) settled both for the same concept: stale rows become shares of their own family's US row, and a stale national row beside the control is a contradiction.
• This applies that ruling to the family Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518 left out. Under Max's 2026-10-02 rule, a fix that corrects targets to the doctrine and source they cite merges on the gates, whatever the change in aggregates.
• Congressional-district capital-gains, SALT and PTC targets on the full surface cross IRS concepts #1038's closing line ("needs a ruling before merge") covers its own concept-proxy items. d539 (capital gains, line 7 for Schedule D) and d1428 (line 8a for line 10) are open because their shares stand in for a different concept with measured proxy error; there is no proxy here.
• Excluding the rows instead would depart from the Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518 precedent and drop the only district-level interest signal.
• This does make taxable interest the first district-file share family on full. cos note-decision on d539 and d1428 records that, so a ruling against the district-US-row denominator, or for dropping district-file rows, gets applied to these rows too.

Review

In-session executed review. Three Opus 5.5 reviewers took distinct lenses: rebase logic, downstream and interplay, and method, tests and claims. An adversarial verifier re-checked each P1/P2 finding. Reports are inhouse-review-*.md and inhouse-verify-*.md in the evidence folder. There was no P1.

• F1 (P2, confirmed). This body's Read restamped Chronicle facts at their data year before aging #1030 section was stale. It is fixed above, and the merged-state obligations are listed.

• F-P2-a (P2, verified down to P3). The tilt cited Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040's unruled P2-3 as precedent, and the body did not say why Congressional-district capital-gains, SALT and PTC targets on the full surface cross IRS concepts #1038's ruling line does not bind. Both are fixed above, and cos notes are on d539 and d1428.

• P3s fixed in 8bf49c35e:

  • the property could not fail its own-denominator and order-free clauses; it now draws the stamp and a twin;
  • "boundary vintage" was the data year;
  • HT2's states are at 0.984 / 0.992;
  • the state_cd doc's interest factors;
  • the bridged key's scope;
  • a mutant label.

• P3s tracked in Taxable-interest rebase: per-row control choice and per-pair bridge retirement can disagree #1236:

  • per-row control choice disagrees with per-pair bridge retirement. This exists on main for HT2, and is reachable for the district family only with Table 1.4 interest older than Table 4.3;
  • a family stamped after every control keeps its levels.

  Neither occurs on the pinned feed.

• Checked fine (executed):

  • every dump-derived number in this body, and a recompile of 4602d939d that is byte-identical to the dump;
  • filing-status slices; HT2 TY2021 beside TY2022; a district US row of 0; Table 1.4 beside Table 4.3;
  • crosswalk translation; hierarchy with short districts; aging and the period contract on the real feed;
  • the irs_interest_distribution coverage requirement (1,016 → 1,015 matches); the parity manifest; target loss weights; the release-gate preflight;
  • Drop congressional-district SALT and PTC facts read from the wrong IRS column #1224 and Choose the capital-gains rebase control by concept and period, not feed order #1036 semantics;
  • every new non-pinned test fails on main, except the no-control test, which pins unchanged behaviour.

• Methodology: all three reviewers judge this a bug fix under Taxable-interest HT2 national row exceeds its AGI-bin partition by 9.8%: HT2-vs-CD-table source discrepancy #489/Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518, not a new modelling choice.

Independent GPT-6.1 Sol review (Subfleet 20261012-103246-review-1229, at 2b7164e15): pending.

Evidence (compile dumps, diff script, state_cd receipts, mutant log): ~/PolicyEngine/_reviews/cd-taxable-interest-20261012/.

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

🤖 Generated with Claude Code

[MaxGhenis]

Heads-up from #1244, which makes the SOI congressional-district guards vintage-free. #1244 changes _is_soi_congressional_district_record_set to a family match (_soi_record_set_family(...) == "congressional_district"), and adds test_district_taxable_interest_never_controls_the_rebase[pinned-cd-2022|hypothetical-cd-2024] in tests/engine_free/us/test_us_soi_congressional_district_vintage.py.

That test asserts main's semantics:

• the district US row compiles;
• an uncontrolled Historic Table 2 band keeps its source value.

This PR retires the US row and drops uncontrolled shares, so those two assertions need updating when the second of the two lands. The controlled case (the band rebases onto Table 4.3, never onto a later-stamped district row) should still hold.

Once this PR and #1040 both land, _is_soi_congressional_district_record_set has no callers left. Consider having _soi_taxable_interest_share_family use _soi_record_set_family rather than the .congressional_district_ substring, so the namespace and segment semantics stay shared.

[MaxGhenis]

#1244 has merged (8fd39a21b). The heads-up above now applies on this PR's next rebase onto main.