[MaxGhenis]

Resolves #1239. The US PUF donor carried only nonpassive partnership and S-corporation income. This PR has it carry Schedule E line 32 as partnership_income and the section 469 passive subset as a new leaf, passive_partnership_s_corp_income, which feeds the NIIT base in policyengine-us 2.2.1.

Max ruled yes on d1472, d1489 and d2183 (see "Decision"). This PR lands first, then #1259, then #1261.

What was wrong

PolicyEngine-US 2.2.1 counts partnership_income + s_corp_income (= partnership_s_corp_income) in gross income. It documents passive_partnership_s_corp_income as "the section 469 passive subset of partnership_s_corp_income" and adds it to net_investment_income. The calibration targets that bind this column are the line-32 totals: HT2 A26270 and the Table 1.4 partnership and S-corp legs.

The donor built the column from the nonpassive fields only:

• puf_2024.h5 (sha256 7669f5b5…) stores partnership_s_corp_income equal to (E25980 − E25960) + (E26190 − E26180) on all 207,692 regular records (ratio 1.0000 on every nonzero record).
• Microcosm copied that into partnership_income. Its raw-field fallback read the same fields.
• passive_partnership_s_corp_income was never populated, so NIIT saw no pass-through income.

The PUF fields

These come from the IRS SOI General Description Booklet for the 2014 Public Use Tax File. Its annotated Schedule E Part II maps each line 28 column to a field, and the TY2015 file uses the same codes.

Line 28 column	Partnership	S corporation
(f) passive loss allowed (Form 8582)	E25920	E26160
(g) passive income	E25940	E26170
(h) nonpassive loss	E25960	E26180
(i) section 179 expense deduction	E26110	E26100
(j) nonpassive income	E25980	E26190

• Line 32 is E26270: (g) + (j) − (f) − (h) − (i), summed over both entity types.
• The passive subset is (g) − (f). Column (f) is the loss allowed, so the section 469 limit is already applied.
• Section 179 sits under the form's "Nonpassive Income and Loss" heading, so it belongs to the nonpassive remainder.

Checked on the pinned TY2015 file (puf_2015.csv, sha256 0a7fd643…):

• Line 32 equals its columns within rounding. E26270 equals the ten column fields on all 207,692 regular records, to within the booklet's per-field rounding (disclosure step 9: four significant digits above $100K, the nearest $100 or $10 below that, and $2 for nonzero amounts under $5). The weighted absolute residual is $0.135B on a $621.9B total.
• The passive legs are what filers report as investment income. On Form 8960 filers, the weighted regression of investment income on Schedule E legs (E85120 less interest, dividends and gains) gives 0.97 on passive and 0.03 on nonpassive. For filers with only passive pass-through income, the Form 8960 Schedule E amount (E85050, less rent, estate and farm rent) divided by passive has median 1.000 (89% within ±10%); for filers with only nonpassive income, the same ratio has median 0.000.

The change

• New us_runtime/puf_source_schedule_e.py. It reads E26270 and the passive legs from the pinned TY2015 rows and aligns them to the processed tax units by RECID, the same seam puf_source_agi uses for E00100. It fails closed when:
  • a regular record's E26270 departs from its columns beyond the booklet rounding;
  • the processed partnership_s_corp_income is no longer exactly the archived nonpassive sum. That catches a future artifact that already carries line 32, or one that has been uprated.
  • a synthetic bucket does not carry its aggregate row's total.
• The four disclosure aggregate rows. They were replaced upstream by 3,985 synthetic records whose amount columns were calibrated one at a time, so no per-record line 32 exists for them. Each row's line-32 and passive totals are allocated over its records in proportion to their processed nonpassive amounts. This keeps every bucket's totals and each record's sign. It covers about $12B of $677B.
• puf_source_agi.py. The source-year layout is factored out so both seams share it. The E00100 vector stays bit-identical to its pinned hash on the real inputs.
• puf_support.py:
  • The new leaf follows s_corp_income in the chained QRF, so its draw conditions on the drawn total.
  • It is placed on the people who carry the line-32 total, in proportion to the magnitude of each person's own line 32. A person whose line 32 is a loss takes a share; a person with no line 32 takes none.
  • It is zeroed where the unit drew no line-32 total. On the donor this pattern is 27 of 207,692 regular records: 3,120 weighted returns carrying −$14.0M of net passive amounts ($20.5M in absolute value; out/zero_total_passive.txt).
  • It is signed-mass calibrated like the other sparse two-signed leaves.
  • The processed nonpassive column no longer stands for partnership_income. A processed donor without the supplement now fails with "cannot derive".
  • The raw-field path derives each entity's share of line 32 and the passive subset.
• The late ACS transfer now carries the leaf (it joins partnership_income in puf_tax_itemization__batch_3), so _apply_post_transfer_structure applies the same coherence to the cells it fills. The rule zeros a transferred passive amount when the person's own line 32 or the tax unit's line-32 total is zero, and leaves pre-existing cells untouched. The rule is bound into the transfer's execution-contract identity and the imputation schema.
• Both donor loaders (load_puf_tax_unit_donor and the base tool's _puf_tax_unit_donor_from_h5) pass the supplement through and record its receipt under schedule_e_line_32.
• A release reform probe, niit_passive_pass_through_exclusion, drops the leaf from the 2024 NIIT sources and requires a positive NIIT effect of at least $1M. A build that loses the leaf therefore fails as a structural zero.
• tools/graph_us_post_transfer_fixture.py was still loading helpers from a test file that has since moved. It now loads them from test_support/, and the H3 fixture is regenerated: only the pool digest line changes, and the sources and expected outputs are byte-identical.

Dollar basis

Line 32 keeps the processed column's TY2015 dollars. #1248 (evidence PR #1223) owns aging the donor. It already lists partnership income among the columns left at TY2015. Its rebase can age both leaves from TY2015 with the partnership/S-corp series. The drift check above refuses to layer line 32 onto a column that has already been changed.

What this means for #722 (and PR #734)

The PUF observes passivity directly, with the section 469 limit applied, and filers' own Form 8960 agrees with it (above). #722's anchored-prior design (an SCF-shaped passive share, levelled to Form 8960) is unnecessary for the PUF channel. The ASEC channel carries no partnership income, so nothing is left for it to assign. Building #722's share on top of this PR would assign passivity twice.

#722's open note still applies: the engine counts rental_income in NII in full.

Invariants

Invariants 1 to 3 are Hypothesis property tests with 300 examples each. So are the frame coherence rule (200 examples, on both the primary and the transfer paths) and person placement (300 examples). Invariant 4 is tested on fixed fixtures and also has a pinned check on the real inputs.

1. Line-32 identity. E26270 equals (g) + (j) − (f) − (h) − (i) within the booklet's per-field rounding. This is tested after independent disclosure rounding of every field, and a line 32 beyond the bound is refused. It also holds on every regular record of the real file (out/rounding_bound.txt).
2. Conditional dominance. Where a return has no nonpassive loss and no section 179 deduction, passive ≤ line 32 + rounding. In the real file, 9,179 records have both amounts positive and neither deduction; none breaks the rule.
3. Leg bounds. −(f) ≤ passive ≤ (g), and −(all loss columns) ≤ passive ≤ (all income columns).
4. Donor alignment. Every regular processed tax unit carries its record's E26270 and passive amount exactly. Each aggregate bucket's weighted line-32 and passive totals equal its row's. The output is bit-deterministic. The real-input vectors are pinned by hash in a test that runs when the restricted files are present.
5. Frame coherence. No passive amount where the unit drew no line-32 total, after the primary pass and after the late transfer. The transfer also clears a unit whose people's line-32 amounts cancel. Within a unit, the passive amount goes only to people with their own line 32, in proportion to its magnitude, and sums to the unit's draw. The public transfer is tested end to end, including its provenance counts.

"Passive ≤ total wherever both are positive" is not an invariant, by design. A $300 passive gain and a $100 nonpassive loss put $200 on line 32, while Form 8960 counts the $300. The donor carries that pair as it is (test_passive_can_exceed_a_positive_line_32). In the real file, 2,745 records (0.20M weighted returns, $2.6B) have passive above a positive line 32. Each of them either has a nonpassive loss or section 179 deduction, or exceeds line 32 by no more than the PUF's rounding (invariant 2).

Do the tests catch wrong formulas? I seeded 11 mutants into puf_source_schedule_e.py:

• passive missing the S-corp legs;
• passive missing (f);
• section 179 counted as passive;
• line 32 replaced by the archived nonpassive sum (the US frame partnership/S-corp income is nonpassive-only: the donor builds it from E25980-E25960 + E26190-E26180, not line 32 (E26270) #1239 bug);
• rounding bound halved;
• no $2-floor slack;
• drift check removed;
• synthetic passive using the line-32 ratio;
• synthetic line 32 left as nonpassive;
• negative-leg check removed;
• bucket check removed.

Each mutant fails between 1 and 13 tests, and the unmutated module passes (out/mutation-schedule-e.txt).

Three more mutants check the frame-side rules: placing passive by the clipped basis, clearing on the person's own line 32 only, and dropping the transfer hook. Each fails at least one test (out/mutation-r2.txt).

Donor totals (2024 donor weights, TY2015 dollars)

	Before (nonpassive only)	After (line 32)
Net	$642.4B	$676.6B
Positive leg	—	$815.0B
Negative leg	—	−$138.4B
Returns with nonzero amount	7.70M	9.46M
Passive subset, net (positive / negative)	$0	$83.0B ($105.7B / −$22.7B)

HT2 N26270 (TY2022) counts 9.55M returns; the line-32 carrier count is now 1.0% below it (9.46M against 9.55M), against 19.4% below before.

Frame and engine results

Setup

• Treatment. The Route A base stage rebuilt on Modal from Route A's own commit (4b57d15a2) plus this change only. The code is on the evidence branch us-puf-line32-passive-1239-route-a (d02fb2bca), which is not for merge.
  • It used Route A's plan inputs, run line32-1239-base-d02fb2bca843.
  • It completed in 6,446 s for about $5.86 at list price.
  • Base h5 sha256 e0722906…, matching the receipt.
• Control. The certified Route A base (0fb05b67…).
• Weights. Each base is weighted two ways: by its own initial weights, and by the certified Route A final calibrated weights. The release keeps every base household id, and under those weights the control reproduces the release's $1,020.5B exactly.
• Engine. PolicyEngine-US 2.2.1 ran on each base on Modal, loading the dataset the way microcosm's reform validation does (USSingleYearDataset, county SPM).
• These are fixed-weight comparisons. A re-calibrated release was not run: the release stage took 33 hours on the build Mac and is not registered for Modal.

Line 32 against SOI TY2022 (Route A final weights)

	Control	Treatment	SOI
Line 32, net	$1,020.5B	$1,055.7B	HT2 A26270 $1,033.3B
Positive leg	$1,128.5B	$1,212.1B	Table 1.4 net-income legs $1,299.8B (by entity)
Negative leg	−$108.0B	−$156.4B	Table 1.4 net-loss legs −$268.6B (by entity)
Returns with nonzero line 32	11.49M	12.76M	HT2 N26270 9.55M
Passive subset, net (positive / negative)	—	$140.4B ($156.9B / −$16.5B), 5.10M carriers	—

At initial weights the line-32 net goes from $306.9B to $455.3B, the carriers from 4.86M to 6.37M, and the passive subset is $46.2B.

One draw dominates that change. A single tax unit with weight 644 drew a $218.9M line-32 value, a Forbes-tail synthetic donor record, and contributes $141B on its own. The control's draw happened to miss that record. Leaving out the 10 largest contributors in each base, the net rises from $257.1B to $301.6B (+17%). Carrier medians fall, because passive income adds many small carriers.

Engine deltas (treatment − control, Route A final weights)

	Delta	Of which: 10 largest line-32 draws	Rest of the frame
Net investment income	+$140.4B	+$25.8B	+$114.6B
NIIT	+$3.80B (on $60.47B)	+$0.97B	+$2.82B
QBI deduction	−$0.80B (on $229.25B)	+$7.63B	−$8.43B
AGI	+$76.7B	+$83.3B	−$6.6B
Federal income tax	+$29.2B	+$29.4B	−$0.2B

• The robust effect is the passive leg. NII and NIIT move broadly across the frame.
• The AGI and income-tax deltas are the tail draws. Outside them, AGI and income tax barely move.
• QBID falls outside the tail. That comes through the outputs drawn after partnership_income in the chain. At initial weights, UBIA moves −$113.0B, W-2 wages −$13.0B, SSTB self-employment income +$25.6B and SSTB W-2 wages +$24.7B.

Frame invariants and the tail gate

• Frame invariants.
  • No passive amount sits in a unit with zero line 32.
  • No person carries passive income without their own line 32.
  • This base predates the round-2 placement fix, and the receipts stand for two reasons:
    • Every receipt here is a tax-unit or frame total, and the fix only moves amounts between people in a unit.
    • It moves nothing on this frame either. The ASEC half carries no line 32 (its channel's line-32 total is $0 in out/compare_bases.json). So on the PUF clones partnership_income has no person basis and lands on each unit's first person, which is where both the old and the new rule put the passive amount.
  • Passive exceeds a positive line 32 for 0.029M of 1.68M both-positive units (1.7%), against 10% on the donor.
• Tail gate. The release's tail-concentration gate fails a column whose top 100 records hold more than 75% of weighted absolute mass.
  • partnership_income: 0.324 in control (Route A recorded 0.324) and 0.399 in treatment.
  • The new passive leaf: 0.660 at final weights. It passes, but with thin headroom on a sparse column (7,513 carriers).

Why calibration still has to lift the carriers

The certified Route A release's pre-calibration partnership net is $314.7B (out/release_route_a_partnership.json). Three things separate that from HT2's $1,033B:

• Line 32 vs nonpassive (this PR). +5% on the net, +23% on carriers.
• Initial weights split 50/50 across channels. The 184.05M tax units are split 92.03M / 92.03M, and the ASEC channel carries no partnership income. So every PUF-only amount enters calibration at about half its donor level.
• TY2015 dollars (The PUF donor's amounts stop at TY2021 levels, two columns at TY2015, and nothing ages them to the build year #1248).

Pins this moves

These are the values the repo's own checkers observed; nothing was transcribed by hand.

• Late transfer: 19 groups / 71 targets (52 numeric). The new leaf joins partnership_income in puf_tax_itemization__batch_3.
• Stacked surface: 135; post-PUF: 71; PUF-clone producers: 44; full transfer: 119.
• Pool projection provisioning: 762 declared absent / 123 materialized, plus the remaining-stage manifest digest. tools/repin_us_pool_engine_contracts.py --check reports them current.
• Primary QRF target-order digest, and the generator's stage, catalog and graph counts.
• source_stages.json declares the leaf as a PUF stage output; the frozen generation-0 digest is re-pinned in the generator and its test.
• Regenerated spec bundle (US spec_sha256 e38e234b…), engine ABI lock, imputation schema (the new post-transfer feature), field-usage claims, inventory digests and counts, and coverage evidence. tools/spec_engine_coverage.py --check passes 42,236/42,236 fields and 41/41 checks.
• The seed-protocol digests, because the protocol attests puf_support.py's source bytes, and the calibration contract's legacy projection, because the leaf joins its tail-control field list.
• The late-transfer completion receipt's counts are now derived from the canonical partition and surface rather than written as literals. Their sizes stay pinned once at import (19 groups, 71 targets). The docstrings and docs/us-multispine-operator-ordering.md quote the new counts.
• The pool tool's reached runtime graph grows from 74 to 75 modules (puf_source_schedule_e.py). The post-export scorer issues 108 requests (42 smoke probes).
• The reform-probe drift test (engine_scenario) declares the new probe's one removed item. It checks that the probe's NIIT source list differs from the installed engine's baseline by exactly the passive leaf.
• Test pins that enumerate the surface: stacked spine, multispine pool, late DAG, spec bundle, lineage dashboard, release scorer, battery semantics and field usage. Each value is the one the test observed. Also the graph H3 fixture.
• generate_us_bundle_from_constants.py --check is clean.
• The multispine-pool tool spec sha and the minimal-loader golden.

Tests run locally

These ran on head 45a5b9891 with the US-engine venv and pytest -n 4 (out/wide-tests-4.log in the evidence folder):

• The new and changed PUF tests: test_us_puf_schedule_e.py (new; 36 tests, including the restricted-input check through MICROCOSM_RESTRICTED_PUF_DIR), test_us_puf_support.py, test_us_puf_partnership_se_derivation.py, test_us_puf_donor_io.py, test_us_puf_support_base_builder.py, test_us_puf_e19200_decomposition.py and test_us_acs_transfer.py, including the new late-transfer reconciliation tests.
• Every file that pins the surface: test_us_stacked_spine.py, test_us_multispine_pool*.py, test_us_late_producer_dag.py, test_us_spec_bundle.py, test_us_post_export_scoring.py, test_us_release_head_to_head_scorer.py, test_us_spine_blindness.py, the engine_free/shared/test_spec_engine_*.py files, engine_contract/us/, engine_workflow/us/test_us_multispine_pool_tool.py, the engine_scenario reform-probe drift test, and microcosm-graph and microcosm-data.

All pass except two microcosm-graph orrery tests. Those fail with ERR_MODULE_NOT_FOUND, because the @axiom-foundation/orrery npm package is not installed in this worktree; they touch nothing this PR changes. ruff check . is clean.

Review

Six rounds of independent review. Rounds 1, 2 and 4 ran on GPT-6.1 Sol; rounds 3 and 6 ran on Opus 5.5 lanes because the Codex lanes were full or held.

• Rounds 1 and 2: REQUEST CHANGES. The findings were stale pins, the late-transfer coherence rule, passive placement under a negative line 32, and gaps in the tests. All are fixed above.
• Round 3: APPROVE WITH NITS, on f7c1eee74. The nits are fixed in 45a5b9891.
• Round 4: APPROVE, on the delta at 45a5b9891.
• Round 5: APPROVE, on the first merge of main (f59263c2c).
• Round 6: APPROVE, on 49bfd37b1, the merge of main at 846b48a9c. This lane had no shell, so I ran its git checks:
  • The diff touches the same 70 files as before the merge, and the changes beyond this PR's content are re-pins.
  • No draw-channel commit follows e7a3f76d1, so the 12-seed sweep still applies.
  • Every numeric pin keeps this PR's own increment.
• Tail verdict (round 6): Carry Schedule E line 32 and its passive subset on the US PUF donor #1251 alone does not clear the top-tail draws. Carry Schedule E line 32 and its passive subset on the US PUF donor #1251 with Bound each PUF QRF draw by the population slice its recipient stands for #1259 clears them. A certified build should not come from Carry Schedule E line 32 and its passive subset on the US PUF donor #1251 without Bound each PUF QRF draw by the population slice its recipient stands for #1259.

Decision

Max ruled yes on d1472 and d1489 (10/24): land #1251, then #1261, with a fresh review that clears the top-tail draws, then a certified US build. That condition needs #1259, and Max ruled yes on d2183 (10/31), so the order is #1251, #1259, #1261. The certified release is untouched.

Follow-ups

• The PUF donor's amounts stop at TY2021 levels, two columns at TY2015, and nothing ages them to the build year #1248 ages the donor, both leaves included.
• Carry Schedule E line 32 by entity on the US PUF donor; retire the S-corp exact-zero universe #1261 carries the partnership and S-corp shares of line 32 separately, so Table 1.4's entity legs can bind one for one.

axiom: n/a: microdata donor construction; no policy rule changes.

🤖 Generated with Claude Code

[MaxGhenis]

Status at 45a5b9891: four review rounds, the last two APPROVE WITH NITS (nits fixed) and APPROVE; the local suite passes apart from two orrery tests that need an npm package not installed here (out/wide-tests-4.log); CI was queued behind a runner backlog at this writing. The merge is queued for Max as d1472, together with closing PR #734 as superseded for the PUF channel. Merge only on green CI.

[MaxGhenis]

Synced with main (2026-10-21). Head f59263c2c merges origin/main (508 commits) into the r4-approved 45a5b9891.

• Conflicts. Only the four spec-digest pin files conflicted. Each takes main's history with this PR's own counts and digests re-applied: targets 71, inputs 2,746, compiled outputs 229, primary tuples 66, the 38-stage source manifest.
• Recomputed on the merged tree: the seed protocol and map, the US spec digest and the loader golden. spec_engine_coverage.py --check reports 41/41.
• Diff against main. The merged tree differs from main by this PR's 68 files, plus about five lines of pin-history comments.
• Tests. The loader, coverage tool, schedule E, donor IO, spec bundle, spine and post-export suites pass locally.
• Next. A Sol delta review (r5) of the merge commit is running.
• Merge. Still waiting on the d1472 ruling. On merge, Populate passive_partnership_s_corp_income: SCF non-active-business shape, Form 8960 level #734 and Populate passive_partnership_s_corp_income (NIIT passive pass-through leg, pe-us#9306): SCF non-active-business shape, SOI/8960 level #722 close as superseded by this PR's passive subset.

🤖 Generated with Claude Code

[MaxGhenis]

Merged at 0550bb838 on Max's rulings d1472, d1489 and d2183. Round 6 (Opus 5.5 lane) approved 49bfd37b1. The merge of main after it touched no draw-channel file, and same_edit.py and increment_check.py found no pin problem. All 10 checks passed at 0550bb838.