Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface

changelog.d/1035-capital-gains-control-concept.fixed.md

@@ -0,0 +1 @@
+Rebase Historic Table 2 capital-gains rows only onto the Table 1.4 Schedule D taxable-net-gain control, the concept `capital_gains_gross` measures. Feed order no longer picks the control: congressional-district and Historic Table 2 rows (Form 1040 line 7, gain or loss) never qualify, a tie between matched records refuses the compile, and a line-7 row with no usable control is dropped instead of shipping as a level. On the pinned feed the 51 `national_state` state return-count targets move from 29,599,604 (2.39x the national target) to 12,289,836 (microcosm#1035).

changelog.d/1038-cd-capital-gains-shares.fixed.md

@@ -0,0 +1 @@
+On the `full` target surface, congressional-district capital-gains rows now enter as shares of the district file's own US row scaled to the Table 1.4 Schedule D control, as Historic Table 2 rows do; the file's US row retires, and every capital-gains share row names its denominator in `soi_share_total_source_record_id`. On the pinned feed the district file's states and districts each move from 29,845,710 returns (2.41x the national target) and $1,522.2B (1.198x) to 12,392,020 and $1,270.9B, and no congressional-district family sums past its national target on `full` (microcosm#1038).

changelog.d/1038-cd-source-column-exclusions.fixed.md

@@ -0,0 +1 @@
+The US fiscal-target compiler drops congressional-district SOI facts read from an IRS column their measure id does not mean, through a new reviewed register keyed by (measure id, IRS column), `US_FISCAL_TARGET_SOURCE_COLUMN_EXCLUSIONS`: N18425/A18425 (state and local income taxes, Schedule A line 5a) published as the limited SALT deduction, and N85530/A85530 (additional Medicare tax, Form 8959 line 24) published as the premium tax credit. It replaces the hard-coded congressional-district PTC-amount check, refuses a listed district fact that names no column, and appears in the exclusion receipt and the release coverage report. On the pinned feed the full surface loses the 976 district SALT specs, which summed to 1.98x the national target, and the 488 district PTC-return specs (microcosm#1038).

docs/us-acs-local-soi-target-surface.md

@@ -79,6 +79,20 @@ their role is `soi_fiscal_distribution`, so `totals` is unchanged:
 | **Admin specs** | **4,380** | **760** | **31,474** |
 
 With the 487 population marginals `state` now calibrates to 4,867 targets.
+
+**Since microcosm#1038** the compiler drops the district file's facts read
+from the wrong IRS column (`US_FISCAL_TARGET_SOURCE_COLUMN_EXCLUSIONS` in
+`us_runtime/fiscal_targets.py`): the SALT rows read from N18425/A18425
+(state and local income taxes) and the premium-tax-credit rows read from
+N85530/A85530 (additional Medicare tax). `state` and `state_cd` are
+unchanged. `totals` loses the 487 district-file premium-tax-credit return
+rows and `full` loses those and the 974 district-file SALT rows:
+
+| Family | `state` | `totals` | `full` |
+|---|---:|---:|---:|
+| `irs_soi` | 4,227 | 120 | 29,860 |
+| **Admin specs** | **4,380** | **273** | **30,013** |
+
 The rest of this section describes the 2026-09-22 measurement.
 
 The 487 population marginals (51 states and 436 congressional districts) are
@@ -104,8 +118,12 @@ congressional-district file. The feed-gated test
 
 ### What `totals` contains, and what it does not
 
-All 607 SOI specs that `totals` keeps are ACA premium tax credit measures (547
-returns, 60 amounts), 454 of them at congressional-district geography.
+All 607 SOI specs that `totals` kept on 2026-09-22 are ACA premium tax credit
+measures (547 returns, 60 amounts), 454 of them at congressional-district
+geography. Since microcosm#1038 it keeps 120 (60 returns and 60 amounts,
+all Historic Table 2: the 51 states and the 9 at-large district copies), 18
+of them at district geography: the 487 district-file return rows read
+N85530, additional Medicare tax, not the premium tax credit.
 `_soi_target_role` in `us_runtime/fiscal_targets.py` gives named roles only to
 country-level all-income-range facts, the all-income-range PTC measures and
 the W-2 tip items; every other SOI fact gets `soi_fiscal_distribution`,
@@ -199,8 +217,11 @@ district rows, are mostly 1.00 to 1.10.
   chained SOI and CBO series (about 1.120). The smallest amount factor,
   1.03, is that aging ratio alone. Correcting the district file's stamp
   (#1030) would remove the aging part only.
-- **Two factors reflect known level differences:** taxable interest (2.35 to
-  2.70, the Table 4.3 rebase) and capital-gains amounts (0.77 to 1.00).
+- **Taxable interest reflects a known level difference** (2.35 to 2.70, the
+  Table 4.3 rebase). Capital-gains factors sit near 1: since microcosm#1038
+  (#1040) both files' capital-gains rows are shares of the same Table 1.4
+  control (amounts 0.93 to 1.20, median 0.98; before, 0.77 to 1.00; returns
+  0.98 to 1.00).
 - **The largest single-state factors** were on qualified and ordinary
   dividends (Hawaii, 2.68 and 2.17), tax-exempt interest (Utah, 1.43) and
   rental income (New York, 0.72), where the two tables disagree about one
@@ -292,21 +313,23 @@ bridged state row records its sibling and bridge factor.
 
 | Rows | Specs on the pinned feed | Why |
 |---|---:|---|
-| District-file `limited_state_local_taxes_*`, both geographies | 974 | Column A18425/N18425 is state and local income taxes, not the limited SALT deduction (microcosm#1038) |
-| District-file `premium_tax_credit_returns`, both geographies | 487 | Column N85530 is the additional Medicare tax, not the premium tax credit (microcosm#1038) |
+| District-file `limited_state_local_taxes_*`, both geographies | 974 | Column A18425/N18425 is state and local income taxes, not the limited SALT deduction (microcosm#1038). Since #1038 the compiler drops them first; `STATE_CD_DEFECTIVE_CD_FILE_MEASURES` stays as a second fence |
+| District-file `premium_tax_credit_returns`, both geographies | 487 | Column N85530 is the additional Medicare tax, not the premium tax credit (microcosm#1038); dropped first by the compiler, as above |
 | District `tax_filer_individual_count` | 436 | No state parent in either vintage, so it could not nest in a bound state target |
 | District rows of states with one district on the 117th plan (AK, DE, DC, MT, ND, SD, VT, WY) | 459 | The SOI file has no sub-state rows there. These rows are the state total copied, or for Montana split by population, so they carry no district information |
 | Historic Table 2 rows copied to at-large districts | 360 | The same copies from the other vintage |
 | District-file state rows for concepts Historic Table 2 carries | 2,295 | Second vintage of a state concept |
 | District rows of the four out-of-band rebase blocks | 34 | The factor band (above) |
 | Bridged state rows whose sibling ratio is out of band | 4 | The factor band (above) |
 
-PR #1040 (awaiting a ruling) excludes the same SALT and PTC columns in the
-compiler and rescales the district file's capital-gains rows by one national
-factor. `state_cd` already takes district capital gains as within-state
-shares of Historic Table 2, which a national factor does not move, so their
-level changes only when Historic Table 2's own capital-gains rows do
-(#1036).
+Since microcosm#1038 the compiler excludes the same SALT and PTC columns
+(`US_FISCAL_TARGET_SOURCE_COLUMN_EXCLUSIONS`, #1224) and rescales the
+district file's capital-gains rows by one national factor per measure
+(#1040). `state_cd` takes district capital gains as within-state shares of
+Historic Table 2, which a national factor does not move, so their level
+changes only when Historic Table 2's own capital-gains rows do (#1036). Its
+capital-gains rebase factors move by the reciprocal of that factor, and no
+factor-band verdict or contract count changes.
 
 North Carolina's district rows are bound. Before #1043 the packaged
 117th→119th crosswalk was built from NC's 2016 plan rather than the 2019 plan
@@ -556,7 +579,10 @@ record one of the four modes, before any release directory exists.
   calibrate stage's peak is the artifact write.
 - A checkpoint written before the sparse matrix (measures as dense H5
   columns) is refused by `--stage calibrate`; re-run `--stage materialize`.
-- To reproduce the 2026-09-22 hours rebuild (#974), pass `--soi-mode totals`.
+- To reproduce the 2026-09-22 hours rebuild (#974), pass `--soi-mode totals`
+  on a compiler from before microcosm#1038; after it, `totals` no longer
+  carries the 487 district-file premium-tax-credit return rows that run
+  calibrated to.
   To reproduce a build that ran as `full` after `b7922b089`, pass
   `--soi-mode full`.
 - A checkpoint materialized under an earlier default records its own mode and

docs/us-chronicle-feed-repin.md

@@ -202,6 +202,31 @@ compiled register goes from 32,867 to 32,843 targets, and the
 count, the only change: 32,842 compiled targets and 5,694 in
 `national_state` (`d315c75804ef`).
 
+**Erratum (27 September 2026, microcosm#1035).** Row order changed too. The
+new feed is sorted by the re-derived `aggregate_fact_key`s, and the
+capital-gains rebase kept the first of two equal-period controls. The
+congressional-district US row (TY2022 data stamped ty2023) now sorted ahead of
+Table 1.4 ty2023. It took over the returns control and raised the 51 Historic
+Table 2 state return counts from 12,289,836 to 29,599,604. The control is now
+chosen by concept and period alone
+([us-soi-capital-gains-concepts.md](us-soi-capital-gains-concepts.md)). The
+counts are unchanged and `national_state` is `65e4dde11c83` on this feed. On
+the 2026-10-04 `51aa40f` re-pin, whose capital-gains cells are identical, the
+same 60 return counts move and `national_state` goes from `e1f9906bf0e0` to
+`882f4764a248` at 6,102 targets.
+
+**Follow-up (microcosm#1038).** On the `full` surface, the
+congressional-district file's capital-gains rows are shares of its US row
+scaled to the same control, and the US row retires (#1040). The package's
+four mislabeled columns are dropped (#1224): N18425/A18425 (state and local
+income taxes), read as the limited SALT deduction, and N85530/A85530
+(additional Medicare tax), read as the premium tax credit. On the `51aa40f`
+feed that leaves 31,784 compiled targets, all of them on `full`
+(`6e1ac91262bc`). `national_state` keeps its 6,102 targets and values and
+moves from `882f4764a248` to `84504a7afd57` only because its 102 Historic
+Table 2 capital-gains rows now name their share denominator in
+`soi_share_total_source_record_id`.
+
 The labelled feed exposed one latent defect in microcosm, fixed in this
 change: `apply_us_medicaid_enrollment_substitutions` built Rhode Island's
 substituted spec by cloning a neighbouring state's spec and kept that state's

docs/us-fact-to-target.md

@@ -204,6 +204,19 @@ should calibrate, add its id to `US_FISCAL_TARGET_EXCLUSION_VINTAGE_BYPASSES`
 with a reason. `us_source_coverage.json`'s `fiscal_target_exclusion_receipt`
 lists the ids each rule dropped or allowed in a release.
 
+A fact whose package reads the wrong IRS column for its measure id is a
+different defect: every fact read from that column is wrong, at every
+geography and vintage, while the same measure read from the right column is
+fine. `US_FISCAL_TARGET_SOURCE_COLUMN_EXCLUSIONS` is keyed by (measure id,
+`layout.source_column_id`) for these, so a package corrected to read the
+right column passes untouched; its receipt rule is
+`source_column_concept_exclusion` (microcosm#1038). Check the column against
+the IRS documentation guide before adding an entry, and list a column there
+only when it carries another concept. A column that is a component or a
+superset of the measure's concept (the district file's line 8a mortgage
+interest under `interest_paid_deduction_*`, its line 7 capital gains) needs a
+share-or-drop decision instead.
+
 ## 5. Add a reform-coverage probe
 
 Probes are **generated data**: author them in