State how PolicyEngine-US taxes estate_income in the export-mass notes

packages/microcosm-build/src/microcosm/build/us_runtime/fiscal_targets.py

@@ -151,10 +151,19 @@ def _us_hierarchy_seed(
     # floating export-input columns. Income legs sum the positive part of the
     # signed model variable, loss legs the negative-part magnitude
     # (see _signed_component), matching SOI's returns-with-net-income vs
-    # returns-with-net-loss split. estate_income/miscellaneous_income do not
-    # currently add to AGI (loss-cap / catch-all only), but they are the export
-    # columns the export-mass gate tracks, so pinning them identifies those
-    # dimensions.
+    # returns-with-net-loss split. Both are export columns that hold reviewed
+    # exclusions in US_EXPORT_INPUT_MASS_REVIEWED_EXCLUSIONS
+    # (tools/build_us_fiscal_refresh_release.py), so the export-mass gate does
+    # not check their drift; pinning them to these SOI lines identifies those
+    # dimensions. Both move federal income tax. In policyengine-us 2.2.1 and
+    # 2.23.2 a non-dependent's positive miscellaneous_income is gross income;
+    # estate_income losses are deducted above the line through loss_ald,
+    # subject to the section 461(l) limit; and estate_income counts toward
+    # qualified business income while estate_income_would_be_qualified is true
+    # (the default). From 2.23.2 (PolicyEngine/policyengine-us#9633) a
+    # non-dependent's positive estate_income is also gross income, and so AGI,
+    # and a non-dependent's signed estate_income plus the Schedule K-1
+    # (Form 1041) box 14 code H adjustment enters net investment income.
     "estate_trust_net_income_amount": "estate_income",
     "estate_trust_net_loss_amount": "estate_losses",
     "other_income_net_income_amount": "miscellaneous_income",

tools/build_us_fiscal_refresh_release.py

@@ -7739,9 +7739,19 @@ def _ecps_parity_gate(
         "ABOVE the true SOI level: a correctly calibrated column cannot pass "
         "this parity check. The reference value is an incidental artifact of "
         "the incumbent weight solve (nothing pinned this column before Build "
-        "H). estate_income does not feed AGI in PolicyEngine-US (loss-cap "
-        "input only), so pinning it identifies the export dimension without "
-        "moving revenue (PolicyEngine/microcosm#299 Build H)."
+        "H). Pinning it can move revenue, because estate_income feeds "
+        "federal income tax. In policyengine-us 2.2.1 (the uv.lock pin) it "
+        "is not a gross-income source, but loss_ald deducts its negative "
+        "part above the line under the section 461(l) limit, whose ceiling "
+        "its positive part raises, and it counts toward qualified business "
+        "income while estate_income_would_be_qualified is true. From "
+        "policyengine-us 2.23.2 (PolicyEngine/policyengine-us#9633) a "
+        "non-dependent's positive estate_income is also gross income and "
+        "AGI, and a non-dependent's signed estate_income plus the Schedule "
+        "K-1 (Form 1041) box 14 code H adjustment input is net investment "
+        "income for the NIIT (estate_net_investment_income). The exclusion "
+        "rests on the band math above, not on revenue neutrality "
+        "(PolicyEngine/microcosm#299 Build H)."
     ),
     "non_sch_d_capital_gains": (
         "Identified by SOI Table 1.4 capital gain distributions reported on "