[DTrim99]

Part of #1073 (student debt pilot, PolicyEngine/us-student-debt#1). policyengine-us now defines all four columns on main (policyengine_us/variables/gov/ed/student_loans/), but microcosm's lock pins policyengine-us 2.2.1, which doesn't. So the release tool runs the stage only with --scf-education-debt, the four columns stay out of certified releases until the pin moves, and Max approves any release.

Review of 2026-11-03: what changed

The code changes are in 78928589e, on top of b1218b08c, with no new merge of main. The receipts were rerun there (Modal run 20261103T172225Z-78928589e) and committed in 563ead1a4. The new stage notes moved the spec identity values, so 9edde76d2 re-derives them. The tests and spec checks ran on Modal at the final head; see Tests below. The body's fit and Parent PLUS figures now come from that receipt. The "before" columns are unchanged, and the diagnosis tables still cite their own receipts.

1. Graduate loans for a child who doesn't fit go to the head's own balance

• Donor. A code-3 graduate loan that no listed child fits is now the head's own federal_student_loan_balance, as codes 6, 7 and -7 are, instead of the head's Parent PLUS loan. Parent PLUS loans are made only for a dependent undergraduate (34 CFR 685.200(c)(2)(i)). There are 15 such loans, pooled over the five implicates (3 in implicate 1), or 30,525 weighted loans holding $0.82B, 0.08% of SCF federal balances (source_checks.child_education_readings.loans_moved). The SCF's Parent PLUS share goes from 9.07% to 8.99%.
• Host. A household without an adult child sometimes draws a child share anyway. That share now splits by its drawn child graduate share: the graduate part joins the head's own balance and raises the head's graduate share by its weight, and only the undergraduate part is Parent PLUS. child_graduate_share stays zero there, since the child holds nothing. The draw records both parts (child_graduate_balance_moved_to_head, child_undergraduate_balance_moved_to_parent_plus), and the receipt sums them for the hold-out and the host (child_share_moves). In this receipt both are zero: no household without an adult child draws a child share, in the hold-out or on the host. The second QRF conditions on the number of adult children, and SCF families without one hold no child share. So the split keeps the rule without moving a dollar here. The receipt also checks that its host draw repeats the build's exactly (drawn_total_matches_build).
• Effect on the fit. The first QRF is unchanged, so every household's total is too. The second QRF is refit on donor targets that changed for those three families, and the refit alone moves the composition draws more than the loans do. The host's Parent PLUS share goes from 10.7% to 9.7% (first-receipt setting: 13.0% to 10.1%), the hold-out's from 6.8% to 6.5%, and the host's graduate share from 50.0% to 47.5%. These figures come from one seed, so a point or two in them is draw noise. The hold-out over several seeds stays a follow-up.
• Tests. In test_graduate_share_weights_by_amount_borrowed_with_balance_fallback, the Parent PLUS case now uses an undergraduate loan, and the graduate loan has its own case (the head's own loan, graduate share 1). The routing parametrization adds three graduate cases with no fitting child: no child listed, only a minor and a grandchild, and an adult child too young then. test_a_childs_draw_without_an_adult_child_splits_by_its_graduate_share checks the host split. test_a_childs_draw_goes_to_the_youngest_adult_child now expects a single parent to hold a drawn graduate child loan as their own.

2. The dependent limit

• (a) By loan year. _DEPENDENT_UNDERGRADUATE_AGGREGATE_LIMITS has three tiers:

  • $17,250 before July 1, 1993;
  • $23,000 from July 1, 1993 (Higher Education Amendments of 1992, Pub. L. 102-325);
  • $31,000 from July 1, 2008 (Pub. L. 110-227; today 34 CFR 685.203(e)(1)).

  The SCF records only the year, so a 1993 or 2008 loan counts as borrowed on or after July 1, since most of a year's disbursements come in the fall. That is how the IBR flag already reads 2014. Loan years go back before 1993: the earliest loan for a child is from 1989, and the earliest federal loan from 1983. There are 5 pooled loans for a child before 1993 and 52 from 1993 to 2007. Still, the tiers move no loan in the 2025 file (loan_year_limit_child_to_parent_plus: 0 loans, against a flat $31,000). No code-3 undergraduate loan borrowed before 2008 fits a listed child who could still have been dependent. Four new routing cases pin the tiers: 2007 against 2008, and 1992 against 1993.

• (b) The lean toward Parent PLUS, now in the docstring, stage notes, changelog and Known limits. A dependent student whose parent can't get a PLUS loan, after adverse credit for example, may borrow up to $57,500 (34 CFR 685.203(c)(1)(iii) and (e)(2)). Some students under 24 are also independent (20 U.S.C. 1087vv(d)). The rule still reads every undergraduate loan over the dependent limit, for a child who could have been under 24, as Parent PLUS.

• (c) Sized. Parent PLUS holds 94 pooled loans (19 in implicate 1) for which a listed child fits, because they exceed the dependent limit: 445,458 weighted loans, $26.18B, 2.60% of SCF federal balances. A $57,500 limit would move 46 of them (9 in implicate 1) to the child: 136,788 weighted loans, $3.97B, 0.39% of federal balances. The SCF's Parent PLUS share would go from 8.99% to 8.59%, and child borrowers from 2.35M to 2.47M. The other 48 loans exceed $57,500. The readings table in item 1 of 2026-10-22 has the full row.

3. Ablation table

Rebuilt from the new receipt (Predictor ablation, below). The share, mean, balance-band and MAE columns depend only on the first QRF, so they match the previous receipt, which the body's table predated. The first receipt's mean error, -4.378%, now reads -4.4%. The borrower-age column depends on the second QRF and moves with its refit: 0.118, 0.021, 0.010, 0.032, 0.015 and 0.035.

4. Stale lines

• The first line and the release plumbing section now say that policyengine-us defines the four columns on main while the lock's 2.2.1 doesn't.
• The copied CI head, identity values and 10/23 runs are replaced by pointers to the re-pin commits (Merges with main).
• Item 1 of 2026-10-22 now states the borrower counts net. Item 5 qualifies the 50-61 claim with the new numbers.
• The X8000 counts by loan position and the swap's share of balances are now in the receipt (source_checks.x8000_degree_check, source_checks.x8000_swap).

5. Smaller items

• Digest check. load_scf_2025_education_debt_donor checks each file's SHA-256 against the pinned member (summary_pin, full_pin; on by default, None for fixtures). A local --scf-2025-summary-extract or --scf-2025-full-extract file is held to the same bytes as a fetched one. test_loader_holds_local_files_to_their_pinned_member_digests covers it.
• Children-in-law. SCF code 4 is "CHILD (in-law) (of R or Spouse/Partner)", and the public file has no item that separates in-laws, so the donor side can't drop them. I documented the asymmetry in the docstring and Known limits, and the receipt sizes it on the host. 0.85% of host households have an adult child's spouse present (1.12M people), against 33.6M adult children in 20.6% of households (host.children_in_law).
• Citations. 34 CFR 685.209(b)(13)(ii) now holds the IBR new-borrower definition, replacing 20 U.S.C. 1098e(e). Age 24 is 20 U.S.C. 1087vv(d)(1). The docstring names the programs: associate's (10, 11), bachelor's (12) and professional certification or license (16).
• The income gradient and the borrower shortfall are unchanged, as agreed.

Merges with main

Squash-merge this PR. An early commit, 0cabbc999, contains text that a later commit reworded, and the commits after it carry that text until the rewording. A squash merge keeps it out of main's history.

• Merges. origin/main was merged in 3c4cfe441 (2026-11-02), then in 430a98881 and 8537a9519 (2026-11-03). The first merge's conflicts:
  • the scf_wealth stage notes: main's re-cited source_impute.py lines and the education-debt rules, both kept;
  • the release tool: main's ESI anchor check beside _with_scf_education_debt_stage;
  • the stored-input register: main's county_fips_2023 beside the four student loan inputs;
  • the spec identity values.
• Spec identity values are re-derived from the code after every change that moves them, never by hand, so this body points to the commits instead of copying values that the next merge moves. That covers the frozen source_stages.json digest, sources.yaml, the field-usage counts and claim pins, the inventory digests and counts, the bundle spec_sha256 and the F0 attestation. The latest re-pin is 9edde76d2 (review of 2026-11-03; its message lists what moved), from the documented sequence in tools/repin_us_spec_engine_contracts.py run on Modal (20261103T172238Z-78928589e). Earlier ones are 3297aefd8 and 0caf4907b, and b1218b08c recounts the transport battery's binding modules. A cloud session merges main and re-derives them once more right before this lands.
• CI passed at b1218b08c (10/10). The PR now conflicts with main, so GitHub CI doesn't run on later pushes until that merge. This round's Modal runs are the check (review of 2026-11-03, above).

Review of 2026-10-22: what changed

That round's receipts were rerun at its merged head (60255dd98). The figures in this section now come from the current receipt (review of 2026-11-03), and the before columns are unchanged. FSA figures are its portfolio tables (chronicle#347): Direct Parent PLUS $115.0B of $1,724.5B at FY2026 Q3, and borrowers by age and by debt size at FY2026 Q2, which count the parent on a Parent PLUS loan.

1. Parent PLUS: loans for a child go to a co-resident adult child

	FSA	SCF 2025, before	SCF 2025	Host build, before	Host build
Parent PLUS share of federal balances	6.7% (floor)	13.8%	9.0%	16.8%	9.7%
Parent PLUS balances	$115.0B	$138.3B	$90.4B	$143.9B	$82.8B
Borrowers (people)	44.9M	27.23M	27.24M	21.22M	21.21M
Borrowers aged 24 and younger	13.8%	5.7%	10.9%	5.0%	12.7%
Borrowers aged 25 to 34	31.2%	33.1%	35.3%	29.2%	31.0%
Borrowers aged 35 to 49	33.5%	38.1%	37.2%	37.8%	37.1%
Borrowers aged 50 to 61	14.3%	16.2%	11.2%	20.8%	13.8%
Borrowers aged 62 and older	7.1%	6.9%	5.4%	7.2%	5.4%

"Before" is the previous rule; the host's before column is the previous receipt (2a6e65a). Surveys capture about $1.0T of FSA's $1.7T, so the shares compare and the levels don't. FSA's 42.3M unduplicated recipients count the student instead of the parent.

The rule (module docstring, stage notes, derive_scf_education_debt_targets). The 2025 screener (X7801) leaves out loans of people living elsewhere, so a code-3 loan is either a co-resident child's own loan or the parent's Parent PLUS loan. No education-loan item names the listed person, so the rule uses the household listing (persons 3-12, relationship X108...X226, age X110...X228) with the loan's year (X9332-X9337), program (X9338-X9343) and amount borrowed:

• The child's own loan when the listing has a child (code 4) aged 18 or over who could have been in school when the loan was borrowed: 16 or older that year, at the oldest age the child's age band allows. The public file bands listed ages, so ages 18-27 all read 25.
• Unless only a parent could have borrowed it. That is a loan for an associate's or bachelor's degree or a professional certification or license (programs 10-12 and 16) above the aggregate limit on a dependent undergraduate's own loans in its loan year, borrowed while the child could still have been under 24 and so dependent (20 U.S.C. 1087vv(d)(1)). The limit is $31,000 from July 1, 2008 (34 CFR 685.203(e)(1)), $23,000 from July 1, 1993 and $17,250 before (item 2 of 2026-11-03).
• Never Parent PLUS: a graduate loan, or one borrowed after every fitting child turned 24. Parent PLUS finances only a dependent undergraduate (34 CFR 685.200(c)(2)(i)). A graduate loan that no listed child fits is the head's own loan (item 1 of 2026-11-03).
• Every other code-3 loan is the head's Parent PLUS loan. No listed adult child could have borrowed it, so the student lives elsewhere, or it exceeds the dependent limit. That last reading leans toward Parent PLUS (item 2 of 2026-11-03).

The one judgment call is an undergraduate loan within the limit for a child of dependent age, which could be either; I read it as the child's own, the member the listing names. The receipt's readings table bounds it:

Reading (SCF 2025)	Parent PLUS share	Child's own share	Parent PLUS holders	Child borrowers	Borrowers
Before: every code-3 loan Parent PLUS	13.75%	0.00%	4.38M	0	27.23M
X8000 swap only	13.75%	0.00%	4.38M	0	26.92M
Build	8.99%	4.68%	2.09M	2.35M	27.24M
Within-limit loans for a dependent-age child also Parent PLUS	11.71%	1.96%	4.11M	0.39M	27.08M
Build with the previous flat $31,000 limit	8.99%	4.68%	2.09M	2.35M	27.24M
Over-the-limit loans the child's own up to $57,500	8.59%	5.08%	1.95M	2.47M	27.23M

On the host the child's draw goes to the youngest child of the reference person or partner aged 18 or over (PEPAR1/PEPAR2). The second QRF now conditions on the number of such children (adult_children_in_household: listing code 4 aged 18 or over on the SCF side), so a household without one rarely draws a child's share. If it does, its graduate part joins the head's own balance and the rest becomes the head's Parent PLUS loan, the SCF side's rules for a student who lives elsewhere (item 1 of 2026-11-03). In the current receipt no household does.

Borrower counts barely move, net (SCF 27.23M → 27.24M, host 21.22M → 21.21M, FSA 44.9M). Two changes offset. The X8000 swap alone, which moves loans 4 and 6 to the other partner, takes the SCF from 27.23M to 26.92M, and child routing brings it back to 27.24M. A child takes over a balance a parent held, and most parents whose only federal loan was for the child stop counting as borrowers (on the SCF side, Parent PLUS holders 4.38M → 2.09M and child borrowers 0 → 2.35M). What moves is who the borrowers are, toward FSA's age profile.

2. X8000: verified, and loans 4 and 6 swapped back

I reran the degree test independently, by loan position and across all five implicates (x8000_degree_check in the receipt builder). The test takes completed degree loans coded 1 or 2 in families with a spouse or partner, keeps those consistent with exactly one partner's highest degree (X5931, X6111), and counts the ones consistent with the coded person:

Loans	X8000	Discriminating	Consistent with the coded person
1, 2, 3, 5	not reversed	388	378
1, 2, 3, 5	reversed	543	540
4, 6	not reversed	25	25
4, 6	reversed	54 (10 in implicate 1)	0

Each position fails on its own. The receipt now records them by position (x8000_degree_check, loans 4 and 6). In reversed families, loan 4 matches the coded person on 0 of 39 discriminating loans (0 of 7 in implicate 1), and loan 6 on 0 of 15 (0 of 3). In other families they match on 20 of 20 and 5 of 5. I also tried an age-at-borrowing test, but too few couples have a partner too young to have borrowed, so it can't tell the cases apart.

The fix. _scf_whose_education_codes swaps codes 1 and 2 of loans 4 and 6 when X8000 = 1 (SCF_WHOSE_EDUCATION_UNREVERSED_LOANS). It is tied to the pinned member SHA-256, since the codebook names no exception. test_reversed_families_swap_the_codes_of_loans_4_and_6_back covers both codes, the other four loans, unreversed families, and code 3 staying put. The swap changes the holder of 0.28% of federal balances, $2.78B on 80 pooled loans (16 in implicate 1): 0.23% on loan 4 and 0.04% on loan 6 (source_checks.x8000_swap).

3. IBR new borrowers: an upper bound

The 59.5% is now labelled an upper bound in the receipt row, the module docstring, the stage notes and the changelog. Two reasons:

• the SCF sees only loans still owed, so a borrower whose pre-2014 loans were paid off reads as new;
• a consolidated loan is dated by its newest underlying loan. 29.3% of federal balances dated 2014 or later are on a consolidated or refinanced loan (X9320-X9325).

Parent PLUS stays in the head's flag, citing 685.209(b)(13)(ii).

4. Composition: Parent PLUS is drawn, not left over

The second QRF now draws the Parent PLUS, adult child's, head's and spouse's shares in that order, then normalizes them to sum to one, so Parent PLUS is no longer the residual of the two own shares. A borrower drawn with no share holds its own loan, and whole dollars go to the largest share, so a zero share stays zero.

• test_a_donor_family_without_parent_plus_rarely_draws_one: own debt splits between partners in fractions, and only families with a reference person 55 or older hold Parent PLUS. Under 2% of the others draw any, and a donor with no Parent PLUS never draws it.
• New hold-out column: 2.8% of held-out SCF borrower families observed without Parent PLUS draw some. The hold-out's Parent PLUS share is 6.5% against 9.0% observed, so the draw now errs low.

5. The fit discussion (your point 4)

This round changes who holds the debt, not how much each household has. The first QRF, its predictors and its seed are unchanged, so every household's drawn total is identical, and so is every share-with-debt figure, including the income gradient: bottom quintile 14.3% vs SCF 11.4%, top 14.2% vs 17.9%. The borrower age profile moves toward FSA, since parents' Parent PLUS balances become their children's own loans:

Host borrower age	Before	Now	SCF 2025	FSA
24 and younger	5.0%	12.7%	10.9%	13.8%
50 to 61	20.8%	13.8%	11.2%	14.3%

So the 50-61 excess over FSA is gone (13.8% against FSA's 14.3%): it came from Parent PLUS balances held by parents in that band. Against the SCF itself, the host still has too many borrowers there (13.8% against 11.2%). The income gradient and the borrower-count shortfall (21.2M against SCF 27.2M and FSA 44.9M) remain for our discussion. I haven't tuned toward either.

6. Odds and ends

• Client name: removed from the changelog and docstring in 3f47edf.
• scfp2022s.zip re-release (10/9): nothing in this round reads the 2022 files. The tests use synthetic fixtures, and the receipts and probes read only the 2025 files. Nothing broke.

What this builds

A new US runtime module, us_runtime/scf_education_debt.py, imputes four person inputs from the 2025 SCF:

Column	policyengine-us	What it holds
federal_student_loan_balance	#9721	The person's own federal loans
federal_parent_plus_loan_balance	#9721	Federal loans for a child's education that only the parent could hold
is_income_based_repayment_new_borrower	#9724	Every federal loan the person holds was borrowed in 2014 or later (an upper bound)
federal_student_loan_graduate_share	#9724	Share of the person's own original principal that financed a graduate or professional program

• Donor. The loader joins rscfp2025.dta and p25i6.dta on (y1, yy1) across all five implicates. It refuses a file whose SHA-256 isn't the pinned member's (a local --scf-2025-*-extract file included), a row-count drift, an unmatched implicate, or per-loan balances that do not reproduce edn_inst. Both files are declared as artifacts 3 and 4 of scf_wealth, pinned by zip and member SHA-256 against a fresh Fed download (2026-10-12), with a new scf_2025 vintage.

• Model. One weighted regime-gated QRF draws each household's federal education debt. A second, fit on borrower families and conditioning also on that total and the number of adult children, draws the chained composition: the Parent PLUS, adult child's, reference person's and spouse's shares in that order (normalized to sum to one), then the three graduate shares and new-borrower flags. Both condition on the same predictors (SCF_EDUCATION_DEBT_PREDICTORS):

  • the reference person's age, sex and race;
  • whether a spouse or partner is present;
  • the number of children;
  • wages, and income less capital gains.

  The shared SCF interest-dividend and Social Security-pension predictors are left out. The cause section below says why, and SCF_EDUCATION_DEBT_EXCLUDED_PREDICTORS records each reason. SCF_EDUCATION_DEBT_CANDIDATE_PREDICTORS keeps the full list for the diagnostics. Educational attainment waits for Carry educational attainment as an auxiliary variable (imputation predictor + ACS-calibratable margin) #297.

• People (SCF_EDUCATION_DEBT_RECIPIENT_DEFINITION). The CPS side builds each predictor the way the SCF defines it:

  • The reference person is the CPS householder or, with a spouse or cohabiting partner present, the man of a mixed-sex couple or else the older partner. This is the SCF's ordering of its economically dominant couple.
  • is_married counts a cohabiting partner, as SCF MARRIED does.
  • Children are those of the reference person or partner, as SCF KIDS counts them.
  • Incomes sum over the reference person, spouse or partner and their children. That is the CPS counterpart of the SCF primary economic unit.

  The reference person, the member its A_SPOUSE (else PECOHAB) pointer names, and the youngest child of either aged 18 or over receive the balances. A spouse draw in a household with no spouse or partner goes to the reference person. A child's draw in a household with no adult child splits by its drawn graduate share: the graduate part joins the reference person's own balance, and the rest is the reference person's Parent PLUS loan.

• Release tool. tools/build_us_fiscal_refresh_release.py runs the stage only with --scf-education-debt, after auto loans. That run applies a signal gate and writes a design-weight fit table (artifacts/us_scf_education_debt_fit.json). Default releases are unchanged and do not fetch the 2025 files.

Rules for the reviewer to confirm

1. Federal only. Loans with X7879/X7884/X7889/X7894/X7899/X7994 = 1 count. A blank federal flag (some 2025 "don't know" answers) counts as non-federal.
2. X7179 (total owed on loans beyond the sixth; it has no federal or whose-education item). Each loan 1-6 is scaled by 1 + X7179 / (balance on loans 1-6). That applies the family's federal share of loans 1-6 to X7179, and splits its federal part among people in the same proportions. A family with X7179 but no balance on loans 1-6 contributes nothing; the receipt counts those dollars (none in 2025).
3. Whose education (X7978, X7883, X7888, X7893, X7898, X7993):
   • code 1 (respondent; the public file swaps codes so this is the SCF reference person) → the reference person's federal_student_loan_balance;
   • code 2 (spouse or partner) → the spouse's federal_student_loan_balance;
   • X8000: in reversed families the public file left loans 4 and 6 unreversed, so their codes 1 and 2 are swapped back (review item 2);
   • code 3 (child; the public file folds grandchild and other relative into 3) → a co-resident adult child's own federal_student_loan_balance, or else the reference person's federal_parent_plus_loan_balance, by the rule in review item 1 of 2026-10-22. A graduate code-3 loan that no listed child fits goes to the reference person's own balance (item 1 of 2026-11-03);
   • codes 6 (multiple people), 7 (unrelated person) and -7 (other) → the reference person's own balance. None can be a Parent PLUS loan for one dependent student, and the reference person is the household's default borrower. None occurs on a federal loan in the 2025 public file.
4. IBR new borrower. True when every federal loan the person holds, own and Parent PLUS, was borrowed in 2014 or later. 2014 counts as after July 1, as asked. For a consolidated loan the year is the most recent underlying loan's. The share is an upper bound (review item 3).
5. Graduate share. Programs 13-15 (master's, professional, doctorate) over all own federal loans (the child's too), weighted by amount borrowed (X7805...X7951), falling back to the balance when that is missing. Parent PLUS loans are excluded.
6. The two excluded predictors (below). Wages and income less capital gains stay in, because the issue asks for income and they carry the income gradient.

Known limits:

• The SCF asks about the loans of the family living in the household, so independent adults living in someone else's household are missed unless the family reports the loan as one for a child.
• No loan item names the listed person, and the public file bands listed ages (18-27 read 25), so the child rule works from age bands, and with two or more adult children the youngest holds the loan.
• The over-the-limit rule leans toward Parent PLUS. A dependent student whose parent can't get a PLUS loan may borrow up to $57,500 (34 CFR 685.203(c)(1)(iii) and (e)(2)), and some students under 24 are independent (20 U.S.C. 1087vv(d)), but every undergraduate loan over the dependent limit for a child who could have been under 24 reads as Parent PLUS. Item 2 of 2026-11-03 sizes the other reading.
• SCF listing code 4 is "CHILD (in-law)", and the public file has no item that separates children-in-law. So the SCF's adult-children predictor can count a son- or daughter-in-law that the host's parent pointers (PEPAR1/PEPAR2) never count. Item 5 of 2026-11-03 sizes it.
• The SCF federal flag includes FFEL and Perkins loans that federal_student_loan_balance excludes until consolidated.
• Balances are 2025 survey-date dollars.

Fit vs SCF 2025, before and after

All figures are weighted. "Hold-out" draws each SCF family from models fit on the other four of five folds, grouped by family. "Host" runs the stage with seed 0 on the published default populace-us-2024-spm-20260915, at weights that were calibrated without these columns. The full tables, with FSA balance and age bands, race, income quintiles and medians by group, are in experiments/1073-scf-education-debt-receipts.md (JSON in experiments/receipts/).

Source checks. The loader matches the Fed's Alternate Table 13 exactly: 19.92% of families hold education debt, with a median of $25,500. Federal loans hold 87.4% of balances on loans 1-6. X7179 holds 0.6% of all education debt.

The three host settings:

• First receipt: oldest-adult reference person, A_MARITL marriage, own children only, whole-household income, all candidate predictors.
• v4b: the SCF codings and the couple-and-children income unit, all candidate predictors.
• Build: v4b without the interest-dividend and Social Security-pension predictors.

	SCF 2025	Hold-out (build)	Host: first receipt	Host: v4b	Host: build
Households with federal education debt	18.2%	17.9%	14.4%	14.5%	16.4%
Parent PLUS share of the total	9.0%	6.5%	10.1%	10.4%	9.7%
Mean among borrower households	$41,052	$38,156	$44,483	$42,174	$42,680
Median among borrower households	$25,000	$23,000	$25,000	$25,000	$23,000
Weighted total	$1.006T	$0.919T	$0.786T	$0.747T	$0.858T
Borrowers (reference persons, spouses and adult children)	27.2M	25.8M	18.8M	18.6M	21.2M
Median balance per borrower	$21,000	$21,000	$24,147	$25,000	$22,000
Share with debt, reference person 25-34	36.2%	36.9%	26.7%	27.1%	28.1%
Share with debt, reference person 35-49	27.2%	27.4%	22.3%	20.9%	24.4%
Share with debt, income quintile 4	26.6%	26.3%	20.0%	19.2%	23.1%
IBR new borrowers among borrowers (upper bound)	59.5%	58.0%	59.5%	60.7%	61.2%
Graduate share of own original principal	47.2%	44.7%	50.9%	47.8%	47.5%
Error vs SCF: share of households (pp)		-0.30	-3.74	-3.70	-1.74
Error vs SCF: reference-age-band share MAE (pp)		1.26	3.55	4.17	2.39
Error vs SCF: income-quintile share MAE (pp)		0.68	4.25	4.57	2.87
Error vs SCF: race share MAE (pp)		1.07	2.83	2.57	0.94

Household figures are unchanged from the previous receipt, because the first QRF, its predictors and its seed are unchanged. The composition rows (Parent PLUS, borrowers, medians per borrower, IBR and graduate shares) move with the refit second QRF; see item 1 of 2026-11-03.

The cause: covariate shift in imputed income components

The model reproduced the SCF out of sample but drew too few borrowers on the CPS host. A QRF reproduces its donor's conditional distribution, so a gap that appears only on the host means the host's predictors are distributed differently from the donor's. The diagnosis tested this predictor by predictor (experiments/diagnose_1073_host_fit.py, diagnose_1073_predictor_shift.py).

• Your whole-household income hypothesis did not hold for 25-34. CPS household income there is lower than SCF primary-economic-unit income, not higher: median $76k vs $82k, wages $62k vs $72k. Narrower CPS units are lower still.

• The CPS host carries tax-record imputations of interest and dividends and of Social Security and pensions; the SCF has survey reports. The two disagree most at 25-49, where most borrowers are:

  Share with some	Interest/dividends 25-34	35-49	SS/pensions 25-34	35-49
  CPS host households	42%	43%	18%	20%
  SCF families	16%	23%	6%	12%

  A QRF reads those values as positions in the SCF distribution, so young host households looked like older, asset-holding SCF families. Those families seldom hold education debt.

• Each predictor's shift, measured directly (experiments/receipts/1073-predictor-shift-diagnosis.json). The diagnosis maps one predictor at a time to its SCF distribution at equal rank, within five-year reference-age bins, and redraws the host's borrower share. The as-is share is 14.2% (SCF 18.2%):

  Predictor mapped	Host borrower share
  interest/dividends	15.8%
  household income	15.1%
  SS/pensions	14.7%
  wages	14.5%
  children	14.5%
  all together	17.3%, the hold-out's level

• Codings. Three CPS predictors were also coded differently from the SCF definitions: cohabiting partners, partners' children, and the reference person (the oldest-adult rule picks a different person from the SCF ordering in 13% of households). Fixing them and the income unit moved Parent PLUS from 21.5% to 15.5% but left the borrower share at 14.5% (v4b).

Dropping the two shifted predictors on top of v4b gave the build. The recipient-definition and predictor variants are in experiments/receipts/1073-recipient-definition-variants.json (run before this round, so their Parent PLUS column uses the previous rule):

Variant	Host borrower share	Parent PLUS	Hold-out share error (pp)
v4b	14.45%	15.5%	-0.87
r1: v4b without interest/dividends	16.07%	16.1%	-0.73
r2: also without SS/pensions (build)	16.41%	16.8%	-0.30
r3: r2 with whole-household income	16.47%	21.1%	-0.30

r3 shows the income unit matters for Parent PLUS: with whole-household income it goes back to 21.1%.

Remaining gaps

• Borrower households are about 1.7 points short (16.4% vs 18.2%). Most of the gap is at reference ages 25-34 (28.1% vs 36.2%), with a smaller one at 35-49 (24.4% vs 27.2%).

• Parent PLUS is 9.7% of the host total vs 9.0% in the SCF and 6.7% (a floor) at FSA.

• Borrowers are 21.2M on the host vs 27.2M in the SCF and 44.9M at FSA, and the share with debt is flatter by income than in the SCF (bottom quintile 14.3% vs 11.4%, top 14.2% vs 17.9%).

• The FSA calibration (Calibrate US federal student loan balances to Federal Student Aid portfolio targets and show them on the dashboard #1074) reweights levels by age, state and debt size. It does not fix the split between own loans and Parent PLUS, or which households hold debt.

• What is still shifted at 25-34, under the build's income unit (receipts/1073-host-fit-diagnosis.json):

  • wages: host median $48k vs $72k for SCF primary economic units;
  • spouse or partner present: 45% of host households vs 54% of SCF families.

  These are the likely next levers. I haven't tested whether either one explains the gap.

Predictor ablation (five-fold hold-out on SCF families)

From the current receipt. One seed and no repeated runs, so small differences may be noise. Balance-band TVD is over household balances.

Predictors	Share error (pp)	Mean error	Balance-band TVD	Age-band MAE (pp)	Race MAE (pp)	Income-quintile MAE (pp)	Borrower-age TVD	Rank corr.
shared 8 without age	-0.25	-1.7%	0.023	4.81	0.65	0.67	0.118	0.154
shared 8	-0.53	-4.1%	0.041	1.19	1.08	0.88	0.021	0.173
shared 8 + household income (first receipt)	-0.87	-4.4%	0.036	1.35	1.36	0.92	0.010	0.175
+ SCF educ	-1.47	-5.6%	0.040	1.32	2.07	1.47	0.032	0.208
build (no interest/dividends, SS/pensions)	-0.30	-7.1%	0.030	1.26	1.07	0.68	0.015	0.168
build + SCF educ	-0.92	-7.1%	0.028	1.75	1.79	0.92	0.035	0.207

Dropping the two shifted predictors costs nothing out of sample on the SCF itself. Education is still the only predictor that raises the rank correlation, by about 0.04.

How the receipts were produced

Heavy steps run on Modal through experiments/modal_1073.py. It clones a pushed commit and runs uv sync --all-packages --extra us --frozen. It also fetches the published default (HF policyengine/populace-us@8ab57ffc) and the SCF 2025 zips, and checks every SHA-256. The runner saves each step's log, plus every tracked file the step changed, to a volume; collect brings them back. Use launch, which spawns the run and exits, so a stopped local client cannot cancel it.

Artifact	Modal run	Commit
experiments/1073-scf-education-debt-receipts.md + receipts/1073-scf-education-debt-fit.json	20261103T172225Z-78928589e (receipt)	7892858, this round's code
the loan-year probe behind the dependent-limit tiers (its counts are now in the receipt)	20261103T170646Z-b1218b08c (--script)	b1218b0
previous receipts (the "before" columns)	20261022T153020Z-2a6e65a73	2a6e65a
SCF probes behind the child rule and the X8000 check	20261023T135427Z-3f47edf23, 20261023T140011Z-3f47edf23 (--script)	3f47edf
receipts/1073-predictor-shift-diagnosis.json, receipts/1073-recipient-definition-variants.json	20261020T150445Z-47949111f	4794911
receipts/1073-host-fit-diagnosis.json	local run, 2026-10-12	branch at that time
spec identity values	see Merges with main

Scope: 2025 for education debt only

Net worth, the liquid-asset leaves and auto loans still read the 2022 files; nothing they produce changes. To move the whole scf_wealth stage to 2025 later:

• point fetch_scf_2022_summary_extract / fetch_scf_2022_full_extract (and their load_* callers) at SCF_2025_SUMMARY_EXTRACT / SCF_2025_FULL_EXTRACT, using fetch_scf_public_file;
• drop the two 2022 artifacts from source_stages.json and repoint the scf_2022 vintage;
• re-check the net-worth and asset plausibility bands, then re-derive the frozen digest and the spec-engine identity values as this PR does.

The predictor and target code needs no change. The 2025 summary extract carries every column the shared predictor construction reads (age, hhsex, racecl5, married, kids, wageinc, intdivinc, ssretinc, plus liq, stocks, nmmf, bond, networth). The 2025 codebook still lists the auto-loan items (X2209...X7170). racecl5 and racecl4 fold the new Middle Eastern or North African category into White non-Hispanic.

Release plumbing and the engine contract

policyengine-us defines the four variables on main (policyengine_us/variables/gov/ed/student_loans/), but microcosm's lock pins policyengine-us 2.2.1, which doesn't. So:

• Stored-input register. They join US_STORED_NON_VARIABLE_COLUMNS with the same pending-engine reason parent_1_id/parent_2_id carry. test_us_stored_input_register.py binds them to their producer (US_SCF_EDUCATION_DEBT_OUTPUT_COLUMNS). test_support/microcosm_data/stored_inputs.py lists them as producer-bound, because no file examined for Published US releases store would_claim_wic, which policyengine-us 2.x ignores, so WIC take-up is 100% under policyengine.py 6.1.1 #1026 stores them. The entries leave when the pinned engine carries #9721 and #9724.
• Coverage manifest: not added. assert_release_input_coverage_manifest_current requires every declared column to be a live engine input leaf, and a required column would refuse every default release. I did not work around that check. The entries belong in the PR that moves the policyengine-us pin.
• No certified release from this PR.

Spec identity, re-derived from the code, never by hand. The re-pin commits are listed under Merges with main, above. The four outputs also join the QRF tail-concentration list in calibration.yaml, which skips absent columns, and vintages.yaml gains scf_2025.

Tests

All on Modal (Linux, Python 3.14, --extra us), since GitHub CI won't run while the PR conflicts with main:

• The stage's 52 unit tests at 78928589e (run 20261103T172212Z-78928589e), and again at the final head 9edde76d2 (run 20261103T180422Z-9edde76d2). New since last round:
  • the graduate-loan cases;
  • the loan-year limit cases and test_the_dependent_limit_follows_the_loan_year;
  • the host split test;
  • the loader digest test.
• At the final head 9edde76d2 (run 20261103T180422Z-9edde76d2):
  • the bundle generator and the coverage attestation in --check mode;
  • the engine-free spec-engine, bundle, register, plan, SCF and spine-blindness tests;
  • the release tool's education-debt tests;
  • the engine-contract spec-engine, bundle, register, SCF, lineage and release-input-coverage tests.
• Also at the final head (run 20261103T180435Z-9edde76d2): tools/repin_us_spec_engine_contracts.py --check, the transport battery's evidence-kernel tests, ruff check . and ruff format --check on the changed files.

Every command passed. The coverage check reports 42,489/42,489 configuration fields and 41/41 inventory checks. The suites passed 861 engine-free tests, 2 release-tool tests and 114 engine-contract tests, plus 151 transport evidence-kernel tests.

Follow-ups

• Add the coverage-manifest entries and drop the register entries when microcosm's policyengine-us pin includes #9721 and #9724, then make the stage default.
• Register the stage's two QRF draws in the legacy-v1 seed ledger (spec_engine/seeds.py) when it joins the default graph. Today they use a dedicated SeedSequence([seed, 1073, step]) stream.
• The remaining 25-34 borrower gap: test a quantile-mapped or rank-based wage predictor, and repeat the hold-out over several seeds.
• Repeat the host draw over several seeds too. Refitting the second QRF on three families' changed targets moved the host's Parent PLUS share by a point (review of 2026-11-03), so the composition shares need a noise band.
• The income gradient and the borrower-count shortfall against FSA (review item 5), after we discuss them.
• Add educational attainment as a predictor once Carry educational attainment as an auxiliary variable (imputation predictor + ACS-calibratable margin) #297 lands.
• Race-composition-before/after-calibration table after Calibrate US federal student loan balances to Federal Student Aid portfolio targets and show them on the dashboard #1074, before any race breakdown ships.
• Original principal and the income-driven-plan flag as further columns, if #9720 needs them.
• Post the fit table to PolicyEngine/us-student-debt#1.

🤖 Generated with Claude Code

[MaxGhenis]

Strong diagnosis: the source checks and the covariate-shift work are convincing. Before this leaves draft:

1. Parent PLUS. FSA's loan-type table (chronicle#347) puts Direct Parent PLUS at $115.0B of $1,724.5B at FY2026 Q3, or 6.7%. Consolidated Parent PLUS sits inside the consolidation total, so that's a floor, but the SCF's 13.8% and the host's 16.8% are two to two and a half times it. Your docstring names one cause: an adult child's own loan is coded 3 and lands on the parent. Can you route code-3 loans to a co-resident adult child when there is one, and benchmark the result against FSA?
2. IBR new borrowers. Label the 59% as an upper bound, since paid-off pre-2014 loans and consolidations dated by their newest loan both read as new. Counting Parent PLUS loans in the flag is right, because 685.209(b)(13)(ii) looks at any Direct or FFEL balance.
3. Composition. Parent PLUS is the residual after the two own shares. Add a test that a donor family with no Parent PLUS rarely draws one.
4. Fit. On the host, the share with debt is flatter by income than in the SCF (bottom quintile 14.3% vs 11.4%, top 14.2% vs 17.9%). Borrowers are also 22% short (21.2M vs 27.2M), and too many are aged 50 to 61 (20.8% vs 16.2%). FSA calibration fixes levels by age, state and balance, but not the income gradient. Let's talk about whether that's good enough for the distributional results.
5. Reword the client's name out of the changelog fragment and the module docstring, and get CI green at the final head with the receipts rerun there.

[MaxGhenis]

#1444 merged to main and conflicts with this branch on the spec pins. A cloud session will merge main here and re-derive them the way you did in 3297aef, so CI can run on the merged head. Please pull before you next push; if you push first, the session stops and leaves the branch alone.

Main's changes since your last merge touch none of the SCF stage code, so I'd keep the receipts at 3297aef unless you see a reason to rerun them. #1357 needs the same step once this lands, so you can leave it until then.

[MaxGhenis]

Thanks, David. The stage now routes code-3 loans to a co-resident adult child, returns loans 4 and 6 to the right partner when X8000 = 1, and gives Parent PLUS its own draw. Four things before this merges:

1. Graduate loans with no fitting child. When no listed child fits a code-3 graduate loan, the loan becomes the head's Parent PLUS (scf_education_debt.py:874-877). The code puts all of a $9,000 graduate loan in federal_parent_plus_loan_balance whether the household has no child, only a child aged 17, an adult child too young to have borrowed that year, or an adult grandchild. The docstring (:72-74), the body and the changelog all rule that out, since the Department of Education makes Parent PLUS loans only for "a dependent undergraduate student" (34 CFR 685.200(c)(2)(i)). Sending these loans to the head's own balance, as codes 6, 7 and -7 go, would match the rule. If you'd rather keep them as Parent PLUS, say so wherever the rule appears. The host's documented move does the same at :1587-1595. In a household without an adult child, it moves a drawn child share, graduate part included, into Parent PLUS and sets child_graduate_share to 0 (:1608). test_us_scf_education_debt.py:199-204 pins the current donor behavior (_loan(5_000, whose=3, program=13) with a head graduate share of 0), so its Parent PLUS case needs an undergraduate loan, and the graduate loan needs a case of its own. Could you add these loans' count and dollars to source_checks.child_education_readings, and the host's moved share to the receipt, so their size shows?

2. The dependent limit. The code departs from the loan limits in two ways that move loans between child and parent, and neither the docstring nor the body mentions them.

   • _DEPENDENT_UNDERGRADUATE_AGGREGATE_LIMIT (:390) applies $31,000 to every loan year. Congress raised the aggregate limit on a dependent undergraduate's own loans from $23,000 to $31,000 for loans disbursed from July 1, 2008 (Pub. L. 110-227). So a $25,000 loan from 2006 for a child of dependent age reads as the child's own, though it exceeds the limit a dependent undergraduate then faced. Setting the limit by loan year fixes this; the SCF records only the year, so 2008 needs a stated rule.
   • A dependent student whose parent can't get a PLUS loan, after adverse credit for example, may borrow up to $57,500 (34 CFR 685.203(c)(1)(iii) and (e)(2)). Congress also made some students under 24 independent (20 U.S.C. 1087vv(d)), among them married students, veterans, students with dependents, orphans, emancipated minors and unaccompanied homeless youth. The code reads any undergraduate loan over $31,000 for a child of dependent age as Parent PLUS, so a $45,000 loan from 2016 goes to the parent. Say in the docstring and body that this leans toward Parent PLUS; a reading that gives such loans to the child up to $57,500 would size it.

3. The ablation table. The body's table predates the rerun receipts. Borrower-age TVD differs in five of six rows: the receipt has 0.122, 0.020, 0.031, 0.011 and 0.038 where the body has 0.107, 0.016, 0.023, 0.015 and 0.031. Balance-band TVD differs in three rows, and the receipt's mean error for shared 8 plus household income, -4.378%, rounds to -4.4% against the body's -4.3%. Your fixes for items 1 and 2 will move the receipts again, so rebuild the table from the new receipt.

4. Stale lines in the body.

   • The first line calls this a draft and keeps the four columns out of certified releases "until policyengine-us defines them", and the release plumbing section says they're "not on policyengine-us main". policyengine-us now defines all four on main (policyengine_us/variables/gov/ed/student_loans/), while microcosm's lock pins 2.2.1, which doesn't. The changelog's wording matches the code: the release tool runs the stage only with --scf-education-debt, because the pinned policyengine-us doesn't define the four inputs yet.
   • The CI head (3eb3232), the identity values and the 10/23 receipt runs predate 74837b4's rerun and the merges after it. The receipts now name 3297aef, and the next merge moves the identity values again, so a pointer to the re-pin commit may age better than copied values.
   • "Borrower counts don't move" holds only net: the X8000 swap alone removes 0.31M borrowers (27.23M to 26.92M), and child routing adds them back (27.24M).
   • "The 50-61 excess is gone" holds against FSA's 14.3%, while the host's 13.7% still exceeds the SCF's 11.2%.
   • "0 of 7" and "0 of 3" for loans 4 and 6, and the swap's "0.3% of federal balances", appear in no committed receipt, which groups loans 4 and 6. Commit them or cut them.

Smaller things, none blocking:

• load_scf_2025_education_debt_donor checks no digest, so a run given --scf-2025-summary-extract or --scf-2025-full-extract reads whatever file it gets (tools/build_us_fiscal_refresh_release.py:12607-12617). The X8000 swap rests on the pinned member SHA-256, so checking a local file against SCF_2025_SUMMARY_EXTRACT and SCF_2025_FULL_EXTRACT would keep that tie.
• The SCF lists children-in-law under code 4 ("CHILD (in-law) (of R or Spouse/Partner)"), but the CPS side's PEPAR1/PEPAR2 pointers miss them. So the adult-children predictor can count a son- or daughter-in-law in a donor family but never in a host household.
• scf_education_debt.py:396 cites 20 U.S.C. 1098e(e) for who counts as a new IBR borrower; that subsection sets their repayment terms, and 34 CFR 685.209(b)(13)(ii) holds the definition. Age 24 sits at 1087vv(d)(1), which :386, the docstring and the body cite as (d)(1)(A). The docstring's "certificate" could name program 16 (professional certification or license).

The income gradient and the borrower shortfall from round 1 don't block this PR.

The branch's last four commits merge main twice and re-derive the spec pins, and CI passes at b1218b0 (10/10). Main has moved again since, spec pin files included, so after your fixes a cloud session merges main and re-derives the pins once more, right before this lands. Please pull before you push.

[DTrim99]

Thanks, Max. All four items and the smaller ones are in 9edde76 (four commits on top of b1218b0). I haven't merged main, so your re-pin merge can go on top. The receipts are rerun at 7892858 (Modal run 20261103T172225Z-78928589e), and the body's "Review of 2026-11-03" section has the details.

1. Graduate loans with no fitting child. I took your first option.
   • Donor: if no listed child fits a code-3 graduate loan, it now goes to the head's own federal_student_loan_balance, the way codes 6, 7 and -7 do. In the 2025 file that's 15 pooled loans (3 in implicate 1), $0.82B, 0.08% of federal balances. The SCF's Parent PLUS share goes from 9.07% to 8.99%.
   • Host: when a household without an adult child draws a child share, the share splits by the drawn child graduate share. The graduate part joins the head's own balance and raises the head's graduate share by its weight. The undergraduate part becomes Parent PLUS. In this receipt no household without an adult child draws a child share, on the host or in the hold-out, so the split moves $0. It guards the rule rather than moving money.
   • The test at :199-204 now uses an undergraduate loan for its Parent PLUS case, and the graduate loan has its own case. The routing parametrization adds three head cases, and a new test checks the host split (test_a_childs_draw_without_an_adult_child_splits_by_its_graduate_share).
   • Both sizes are in the receipt: source_checks.child_education_readings.loans_moved and host.child_share_moves, plus the hold-out's.
   • One side effect to flag: refitting the second QRF on those three families' changed targets moves the composition draws by more than the loans themselves. The host's Parent PLUS share goes from 10.7% to 9.7%, and in the first-receipt setting from 13.0% to 10.1%. The host's graduate share goes from 50.0% to 47.5%. Household totals don't move. With one seed, I read a point or two there as draw noise; the multi-seed hold-out is still a follow-up.
   • Docstring, stage notes, body and changelog are updated.
2. Dependent limit.
   • (a) _DEPENDENT_UNDERGRADUATE_AGGREGATE_LIMITS now goes by loan year: $17,250 before July 1, 1993, $23,000 from then (Pub. L. 102-325) and $31,000 from July 1, 2008 (Pub. L. 110-227). A 1993 or 2008 loan counts as on or after July 1, the way 2014 does for the IBR flag. I added the 1993 tier because loan years go back that far (code-3 loans to 1989, federal loans to 1983). It moves no loan in the 2025 file, though: no code-3 undergraduate loan borrowed before 2008 fits a listed child who could still have been dependent. The receipt counts the code-3 loans in each tier.
   • (b) The docstring, stage notes, body and changelog now say the rule leans toward Parent PLUS, citing 685.203(c)(1)(iii) and (e)(2) and 1087vv(d).
   • (c) Over the limit, 94 pooled loans ($26.18B, 2.60% of federal balances) are Parent PLUS although a listed child fits. A $57,500 limit would give 46 of them (9 in implicate 1, $3.97B, 0.39%) to the child. The SCF's Parent PLUS share would go from 8.99% to 8.59%, and child borrowers from 2.35M to 2.47M.
3. Ablation table. Rebuilt from the new receipt. The household columns match the previous receipt, and -4.378% now reads -4.4%. The borrower-age TVD moves with the refit second QRF: 0.118, 0.021, 0.010, 0.032, 0.015, 0.035.
4. Stale body lines.
   • The first line and the release plumbing section now say policyengine-us defines all four columns on main, while the lock's 2.2.1 doesn't, so the stage runs only with --scf-education-debt.
   • The copied CI head, identity values and 10/23 runs are replaced by a pointer to the re-pin commit.
   • "Borrower counts don't move" is now a net statement. On the SCF side the X8000 swap alone moves borrowers from 27.23M to 26.92M, and child routing brings them to 27.24M. The host goes from 21.22M to 21.21M.
   • "The 50-61 excess is gone" is now qualified: the host's 13.8% is below FSA's 14.3% but still above the SCF's 11.2%. Borrowers 24 and younger are 12.7%.
   • "0 of 7", "0 of 3" and the swap's share are now in the receipt, by loan position. In reversed families loan 4 matches the coded person on 0 of 39 discriminating loans (0 of 7 in implicate 1) and loan 6 on 0 of 15 (0 of 3). The swap changes the holder of 0.28% of federal balances ($2.78B): 0.23% on loan 4 and 0.04% on loan 6.
5. Smaller items.
   • The loader checks a local --scf-2025-summary-extract or --scf-2025-full-extract file against the pinned member SHA-256 (summary_pin/full_pin, on by default), with a test.
   • Children-in-law: SCF code 4 has no item that separates in-laws, so the donor side can't drop them. I documented the asymmetry instead, and the receipt sizes it on the host: 0.85% of households have an adult child's spouse present (1.12M people), against 33.6M adult children in 20.6% of households.
   • Citations: 34 CFR 685.209(b)(13)(ii) for the IBR definition, 1087vv(d)(1) for age 24, and program 16 named.

Identity values: the stage notes changed, so 9edde76 re-derives the pins with the documented repin sequence on Modal (run 20261103T172238Z-78928589e). That moved the source_stages.json digest, sources.yaml, three inventory digests, the bundle spec_sha256 and the F0 attestation. The field-usage counts and claim pins didn't move. The body now points to that commit instead of copying values. ruff format also normalized the repinner's single-quoted literals, including the two seed pins from 0caf490; the values are unchanged.

Checks at 9edde76 on Modal: the stage's 52 tests and the spec step (run 20261103T180422Z-9edde76d2), plus the repinner's --check, the transport battery and ruff (run 20261103T180435Z-9edde76d2). All passed: 52 stage tests; generator and coverage --check (42,489/42,489 fields, 41/41 inventory checks); 861 engine-free, 2 release-tool and 114 engine-contract tests; 151 transport tests; ruff. GitHub CI won't run until your merge, since the PR conflicts with main.

[MaxGhenis]

Thanks, David. The stage now sets the dependent limit by loan year, keeps a graduate loan that no listed child fits as the head's own, and splits the child share when a household without an adult child draws one. The loan-year tiers match the law: Congress applied the $23,000 limit to loans first disbursed from July 1, 1993 (Pub. L. 102-325, §432(a)(2)), and the $31,000 limit from July 1, 2008 (Pub. L. 110-227, §2(c)). Three things before this merges:

1. Two age boundaries have no test. A listed child can hold a loan once the oldest age in their band reaches 16 in the loan year (scf_education_debt.py:857), and counts as possibly dependent while the youngest age stays under 24 (:860). No routing case sits on either boundary: change >= to > at :857, or < to <= at :860, and every donor test still passes. Two routing cases would pin them:

   • child code 30 (28-32 in 2025) with a 2021 undergraduate loan of $40,000, over the limit: the youngest in the band had reached 24 by 2021, so the loan stays the child's own;
   • child code 25 (18-27) with a 2014 undergraduate loan of $9,000: the oldest in the band reached 16 in 2014, so the child fits and keeps the loan.

2. The limit applies to each loan, while the law caps a student's total. scf_education_debt.py:862-865 compares each loan's own amount borrowed with the aggregate limit. Two 2016 bachelor's loans of $20,000 for an only child of dependent age both read as the child's own, while one $40,000 loan reads as Parent PLUS. That leans toward the child, opposite to the lean the docstring states (:91-99), and the docstring's rule (:66-72), the stage notes, the changelog and the body leave it out. Could you say so where the rule appears, and have child_education_loan_moves count the code-3 undergraduate loans in families where such loans sum above their year's limit while each stays under it? Summing per family when exactly one adult child fits would also close it.

3. The head's IBR flag after a move has no test. When the stage moves a child share to the head, the head stays a new IBR borrower only if the loan it moves also counts as new (:1709-1712). Both tests that make the move still pass without & child_new: test_a_childs_draw_goes_to_the_youngest_adult_child draws only new child loans, for heads who hold nothing else, and the split test never reads the flag. Setting child_is_ibr_new_borrower = 0 and head_is_ibr_new_borrower = 1 on the split test's donors, and asserting that the head's flag comes out False, would pin it. Donor shares that sum to something other than 1 there would also test the moved-dollar columns (:1731-1737), which come out the same here with or without the division by the share sum.

Smaller things, none blocking:

• The docstring and body limit the parents-only rule to programs 10-12 and 16, while the code tests ~graduate (:843, :862-864) and so also counts any code outside 10-16 as undergraduate. np.isin(program, [10, 11, 12, 16]), or a docstring line covering the other codes, would make them agree.
• The body says the receipt "checks that its host draw repeats the build's exactly". drawn_total_matches_build compares only the weighted drawn total, which the first QRF draws (experiments/build_1073_scf_education_debt_receipt.py:1697-1699), while the child-share moves come from the second. Comparing the four balance columns too, or rewording, would close the gap.
• Item 2(a) of the body says "No code-3 undergraduate loan borrowed before 2008 fits a listed child who could still have been dependent." The receipt shows that the tiers move no loan against a flat $31,000, and fitting loans under their year's tier, or over $31,000, would also give 0. Dropping the sentence, or counting those loans in the receipt, would close it.
• Before July 2008, a dependent student whose parent couldn't get PLUS could borrow up to $46,000 of their own (34 CFR 685.203(e)(2) in the 2007 edition), so the $57,500 reading could use $46,000 for loans from before 2008.
• host_children_in_law counts the partner an adult child's A_SPOUSE names but not a PECOHAB partner (receipt builder :874, :892-900), so the 0.85% sets a lower bound.
• When the draw's shares sum to a subnormal number, drawn_total / sums overflows and the moved-dollar columns come out NaN (:1731-1737). The balances stay correct, and computing part / sums * total avoids the NaN.

The cloud session's merge of main sits on top at 6a9903a and leaves the stage, its tests and the receipt builder unchanged. Please pull before you push.

[MaxGhenis]

Ready for hub review

Head: 6a9903aafe07e2fc2d3b8c4f07438bd7ce0b675f (a fast-forward from 9edde76d2; side branch hub-build/1246-merge-main-1103)
Main merged: 31c89390c0 first, then 79a533c720 (main moved while the first merge was being checked; see judgment call 1). The PR merges cleanly with main at 79a533c720.

Commits on top of 9edde76d2

1. 122623f3 Merge origin/main (31c89390c0): 20 first-parent merges, 164 commits since ea8f409806.
2. f04f0307 Re-derive the spec identity values on the merge with main.
3. 34838725 Count the two modules Publish calibration diagnostics as schema 9, each hierarchy label declared once #1342 adds to the transport bindings' identity (hand edit, later replaced by main's form in commit 4).
4. 6a9903aa Merge origin/main (79a533c720: Count the two modules #1342 added to the transport bindings' identity, and merge main's US re-pin (#1496) #1495, Give a person with no household no household's row, and read malformed holdout rows alike in both guards #1481, Hand staged dataset bundles to the emitter with stage_dataset_bundle #1460).

What main brought beyond the 11 overlapping files

Mostly ACS-local work (#1052, #1054, #1055, #1056, #1058, #1060, #1105), diagnostics schema 9 catalogs (#1342), the US catalog unit-waiver retirement (#1484: it drops the catalog_metadata_waivers field-usage pin and one claim, so claim_count goes from 49 to 48), the person-level coresident_adult transform kind (#1477), the calibration holdout refusal (#1472), the Belgium B4a surfaces (#1463), NZ G8 work (#1456, #1457, #1471), emitter, collector and staging changes (#1403, #1455, #1460, #1346), the run-clock pins (#1479), main's ACS-local re-pin (#1496), the binding-count fix (#1495) and the holdout-row guard (#1481).

Conflicts and how they were resolved

Merge 1 (31c89390c0) had seven conflicts, all on pin lines; none touched code or test logic:

• field_usage.py (EXPECTED_*_FIELD_COUNT), test_spec_engine_field_usage.py and test_spec_engine_coverage_tool.py (counts): took the branch side; step 2 rewrote them.
• tools/spec_engine_coverage.py (EXPECTED_POINTER_INVENTORY_SHA256): branch side, rewritten.
• test_us_multispine_pool_tool.py (spec_sha256): branch side, keeping the Carry SCF education debt into the US build and allocate federal student loan balances to borrowers #1073 comment; the digest was rewritten.
• inventory_coverage.py EXPECTED_HASHES: took main's seed_map/seed_protocol, because only main changed the seed code, and the branch's source_manifest. The repinner rewrote neither value, and the coverage check accepts both.
• docs/evidence/spec-engine/us-f0-coverage.json: branch side, regenerated.
• The four files that auto-merged (tools/us_bundle_generation/core.py, test_transport_evidence_kernels.py, test_us_fiscal_refresh_builder.py, test_us_spine_blindness.py) carry exactly the branch's own delta over the merge base; I compared the diffs.

Merge 2 (79a533c720) had one conflict: the module-count assertion in test_transport_evidence_kernels.py. I kept main's #1495 form with this branch's base: 198 + len(BINDING_MODULES_ADDED_AFTER_BASE) + len(LEAF_ADDED_MODULES), plus the #1073 comment. Against main, the file now differs only by b1218b08c's +1 and its comment.

Re-pin (step 2)

I ran repin --legacy-only, the bundle generator, the repinner, the coverage tool, then the repinner again; the second pass changed nothing. --legacy-only changed nothing because source_stages.json is unchanged (tools/repin_us_spec_engine_contracts.py:425-458). What moved:

• Field-usage counts: 42,394 configuration fields (was 42,489) and 32,609 authored (was 32,704). Also compiler_semantic 27,673, front_end_validation 349 and no_generation0_effect 3,614. Resolved bindings (9,785), legacy_behavior (14,269 / 38,780) and identity_only (103) did not move. As a cross-check: merge base 42,305, plus this branch's 184, minus the 95 authored fields main dropped, gives 42,394.
• Pointer-inventory digest f6832e8d…, bundle spec_sha256 ce8b1865… (multispine test and both F0 fields), and the F0 documentation_sha256 and claim_count (48).
• Unchanged: source_stages.json and its frozen digest, sources.yaml, and the inventory_coverage.py digests.
• ruff format ran only on the changed files; it only switched quotes.
• Merge 2 moved no pins: all three --checks passed unchanged on 6a9903aa.

Hand edits

• 34838725: set the transport module count from 198 to 200 (test_transport_evidence_kernels.py). It observed 223 = 200 + 23. Publish calibration diagnostics as schema 9, each hierarchy label declared once #1342's calibrate.hierarchy_labels and diagnostics.catalogs are reached through microcosm.calibrate's __init__. Main failed the same assertion at 31c89390c0 (engine-free 3.13 and 3.14: 222 == 197 + 23). Merge 2 replaced this edit with Count the two modules #1342 added to the transport bindings' identity, and merge main's US re-pin (#1496) #1495's form, as above.
• No other hand edits.

Checks (on both f04f0307 and 6a9903aa)

• repin_us_spec_engine_contracts.py --check: pass.
• generate_us_bundle_from_constants.py --check: pass, spec_sha256=ce8b1865….
• spec_engine_coverage.py --check: 42394/42394 configuration fields; 41/41 inventory checks.

Tests (one file per process, -p no:cacheprovider, -n 2 or serial)

File	Result
engine_free/shared/test_spec_engine_field_usage.py	14 passed (again on 6a9903aa: 14)
engine_free/shared/test_spec_engine_calibration_semantics.py	12 passed
engine_free/shared/test_spec_engine_compiler_ir.py	10 passed
engine_free/shared/test_spec_engine_loader.py	10 passed
engine_free/shared/test_transport_evidence_kernels.py	155 passed, 1 failed at f04f0307 (the count above); 156 passed at 34838725 and at 6a9903aa
engine_contract/us/test_spec_engine_coverage_tool.py	7 passed
engine_workflow/us/test_us_multispine_pool_tool.py	31 passed
engine_free/us/test_us_scf_education_debt.py	52 passed (serial: the first -n 2 attempt was killed when the container ran out of memory)
engine_free/us/test_us_bundle_core_contracts.py	17 passed
engine_free/us/test_us_stored_input_register.py	28 passed
engine_free/us/test_us_fiscal_refresh_builder.py	352 passed, 2 skipped (lines 4137 and 4342 need MICROCOSM_US_CHRONICLE_FACTS)
engine_free/us/test_us_spine_blindness.py	504 passed

No test file notes a ~15 GB peak, so none was skipped for memory. Apart from the transport and field-usage files, the tests ran at f04f0307/34838725, before merge 2. Merge 2 touched none of those files' modules except via main's own changes, and CI covers them.

CI at 6a9903aa: 10/10 success

lint, wheels, select-countries, integration-uk, engine-uk 3.13 and 3.14, engine-us 3.13 and 3.14, engine-free 3.13 and 3.14. That matches b1218b08c6 (10/10); there were no new failures. engine-free 3.13 was the longest job, at about 1 h 39 min.

Receipts (1073-scf-education-debt-fit.json, commit 78928589e): not rerun

The merge doesn't reach the receipt's code path. Importing experiments/build_1073_scf_education_debt_receipt.py loads 193 microcosm modules. 19 of them are in git diff ea8f409806 79a533c720: country_spec; us_runtime acs_inputs, acs_release_predictors, acs_transfer, hours_worked, immigration and ssi_disability_criteria; calibrate __init__, diagnostics and hierarchy_labels; the diagnostics package (__init__, catalogs, json_schema, schema, writer); the frame adapters policyengine_us and _policyengine_us_source_index; frame concept_mapping; and build staging_storage. All are loaded through package __init__ side effects or importers the receipt never calls:

• scf_education_debt.py:196-208,1620 imports gates (GateResult only), source_manifest, eligibility_inputs, scf_auto_loans, scf_wealth, frame and fit.QRF. Their direct-import closure (47 modules) contains, of the changed files, only the calibrate and diagnostics package, through gates.py:51-53 (calibrate.registry, calibrate.solve and ledger_targets, none of them changed). Main's changes there are the schema-9 diagnostics writer (calibrate/diagnostics.py:426-429,510), which the receipt never calls.
• source_manifest.py:114-116 names derive_hours_worked/derive_immigration_status only as strings, and gates.py:2292 mentions immigration only in a docstring.
• The receipt's host frame reads the H5 with pandas.HDFStore and builds Frame directly (experiments/build_1073_scf_education_debt_receipt.py:932-965), so it never touches the changed PolicyEngine adapter.
• Its only package data is us/source_stages.json (scf_education_debt.py:1917-1918, scf_wealth.py:288), which main didn't change.
• country_spec.py's one change adds measurement_prefit to ALLOWED_GATE_FUNCTIONS (line 134).

Judgment calls

1. Second merge. After I fast-forwarded to 34838725, GitHub still read Impute federal student loan balances from the 2025 SCF (#1073) #1246 as conflicting: Count the two modules #1342 added to the transport bindings' identity, and merge main's US re-pin (#1496) #1495 had landed and touched the line I hand-edited, so CI never started. I merged main again (79a533c720), re-ran the three checks plus the transport and field-usage tests (no pins moved) and fast-forwarded again. The brief named only the start head; I took "so CI can run on the merged head" as the goal.
2. Count edit outside the two re-pin files. The transport count was last set by b1218b08c, not by 9edde76d2 or 3297aefd8. I changed it because it's a count, and engine-free's --maxfail=1 would otherwise have stopped the job at it.
3. seed_map/seed_protocol took main's side in merge 1, as described above.
4. Ran test_us_scf_education_debt.py without xdist after the out-of-memory kill.

---

Generated by Claude Code