[MaxGhenis]

Corrects experiments/982-puf-self-prediction/README.md on main. Refs #982, #940, #1033.

Problem

The README's "Returns by size of proxy AGI" table and its Colorado figures weight the PUF-clone half ×2 ("as if this half were the whole population", score_variants.py) and compare that with SOI Table 1.1. In the real pool, the survey half (clone index 0) carries the other 50% of the weight and has no units at $5M+ proxy AGI. So the real pool before calibration, and before main's capital-gains tail stage, is about half of SOI at $5M+ after #1033, not at SOI. Corrections are already posted on #982, #940 and #1033.

Change

• actual_pool_bands.py (new). This is the recovered lane script (~/PolicyEngine/_recovered/lane958-958-964-982-archive-20260926/982/), restyled to pass ruff: functions, a docstring, and imports of SOI_TABLE_1_1, INCOME and COLORADO_SOI_INCOME_ABOVE_1M_BN from the sibling score_variants.py, so the two scorers share one set of bands. The computation is unchanged. I ran the original and the restyled script in three runs of a synthetic harness, each with a different synthetic clone frame (checkpoint loading stubbed). Both gave byte-identical JSON and stdout; no microdata was loaded.
• results/actual_pool_bands.json (new). A byte-identical copy of the recorded output.
• README:
  • Adds a section, "Real pool at frame weight", with the table below.
  • Retitles the two existing ×2 tables "PUF-clone half ×2 (distribution check, not a level comparison)". The Evidence intro now says why they are not levels.
  • Rewrites the Colorado item in Known limits. The real pool is 2.1× SOI with one record at 81%, not about 4× with that record at 84%. The record's frame weight is 434; the 867 shown before was its ×2 weight.

Band	Old design	#1033	SOI Table 1.1
$1M–1.5M returns	701k (1.90×)	483k (1.31×)	369k
$5M–10M returns	11.8k (0.24×)	24.3k (0.49×)	49.3k
$10M+ returns	4.1k (0.13×)	17.0k (0.56×)	30.4k
$10M+ AGI	$92B (0.10×)	$519B (0.57×)	$908B
Colorado income above $1M	$20.2B (0.64×; largest record 28%)	$66.3B (2.1×; largest record 81%)	$31.7B (Historic Table 2, via #940)

Compared with the table posted in the corrections, this one adds ratios for the old design and the $10M+ AGI row. It also puts each Colorado largest-record share in its own design's cell and labels Colorado's $31.7B reference as SOI Historic Table 2, following score_variants.py, because it does not come from Table 1.1.

Review

An independent Opus 5.5 review (in-session, read-only) approved. It recomputed every figure, compared the two scripts line by line, reran the synthetic harness, and checked the mechanism claims against puf_support.py, support_provenance.py and puf_capital_gains_tail.py. Its one minor finding and two nits are addressed in the second commit: the $1.5M–5M range now covers AGI as well as returns, "roughly quadruples" is now "nearly quadruples (3.9×)", and the ×2 wage totals in the prose are marked. Subfleet lanes had no capacity at either tier, so the review ran in-session.

A second independent review (Opus 5.5, at a35cb06, in a fresh context) recomputed the README's figures from the recorded JSON and found them correct. It asked for two fixes: the Colorado limit said #940's targets had yet to enter calibration, though #1102 added them on 2026-10-11, and the scope sentence omitted #1251 and #1259. 094aaa9 makes both and applies the review's four wording notes.

Verification

• A scratch checker parsed the README and recomputed every cell of the table, plus each derived figure in the prose, from results/actual_pool_bands.json and results/scores_8_trees.json: 35 of 35 checks pass. It confirmed:
  • $174B→$675B and 15.9k→41.3k at $5M+; 52% and 54% of SOI.
  • At $5M+, the real-pool figures are exactly half the ×2 ones.
  • Bands between $1.5M and $5M sit at 0.59–0.84× SOI in returns and 0.52–0.83× in AGI.
  • The survey half holds 284k returns at $1M–1.5M (77% of SOI) in both designs.
  • The Colorado record's frame weight is 867/2. Its share of the state's income above $1M computes to exactly the JSON's 0.8132, which shows it is the same record.
• The mechanism claims were checked against main's code:
  • The two-channel weight split and clone index 1 = PUF_TAX_DETAIL_CLONE_INDEX are in us_runtime/puf_support.py and support_provenance.py. The 50/50 share is also observed in clone0_weight_share.
  • compare_predictors.py fits the QRF only and never runs the tail stage.
• ruff check and ruff format --check pass on experiments/982-puf-self-prediction/ with the locked ruff 0.15.16.
• No builds were run and no microdata was loaded.

Limitation, disclosed in the README: the survey half's proxy AGI sums 11 of the 15 items, because the 15-item list's estate, farm, partnership and S-corporation columns are not on its person table.

axiom: n/a: documentation and experiment receipts only; no policy change.

🤖 Generated with Claude Code

[MaxGhenis]

I merged this at 094aaa9 after CI passed on that commit and an independent AI code review agreed with it.