Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification)

[MaxGhenis]

What this does

This PR registers gate_epuf_fill, which scores fills learned from SSA's 2006 Earnings Public-Use File (EPUF) against the career assembler's two fixed fill rules:

• each odd income year from 1997 is the mean of its neighbours;
• nothing counts before max(1968, birth_year + 22).

A gate here is a pass-or-fail test whose rules and thresholds are fixed and published before anything is scored against it.

It is stacked on #509, whose EPUF reader it uses. Merge #509 first.

State: the gate is registered, its floors are built, and three independent referee rounds have run. It is not locked. The lock waits on Max's ratification of the tolerance reading (decision d927). Until then epuf_fill_gate.test_part() refuses to read TEST, and no TEST person has been read.

The gate, in plain words

EPUF records capped taxable earnings every year from 1951 to 2006. The gate hides the years the PSID would be missing (odd years 1997-2005, and years before the career start), fills them, and compares the filled careers with the real ones on held-out persons.

• Split: person-disjoint by salted hash. TRAIN 60%, DEV 20%, TEST 20%.
• Cells: 326 in all.
  • Rank persistence: r1, r2, r3, r4, pr_in, pr_cross, yr_cross.
  • Zero-year rates by age: zint, zexit, wint, pzero, yzero.
  • Levels and positive-share quantiles.
  • The AIME under the statutory 35-year rule, plus a partial AIME through 2006 for later cohorts.
  • Each by sex, age band or cohort, with pooled groups.
• Tolerance: one PSID-2010-size sampling standard error per cell. It comes from 200 pairs of disjoint real DEV samples at the PSID's size, which is the "two halves of real EPUF" floor read at the PSID's scale.
• Bite: both checks hold on DEV.
  • The current odd-year rule fails 96 of 183 gating cells by more than two tolerances.
  • The current pre-career rule fails 112 of 136.
  • On the pooled 1930-45 cohorts, the pre-career rule lowers median AIME by 20% for men and 22% for women.

Full record: docs/amendments/gate_epuf_fill_registration_proposal.md.

Referee rounds (independent Opus 5.5 lanes)

Round	Report	Verdict
1	reviews/gate_epuf_fill_round1_referee_20261004.md	AMEND BEFORE LOCK
2	reviews/gate_epuf_fill_round2_verification_20261004.md	LOCK AFTER LISTED FIXES
3	reviews/gate_epuf_fill_round3_confirmation_20261004.md	LOCK AFTER LISTED FIXES, no rebuild

• Round 1 found a floor priced on the wrong population (now group_rows defines it once). It also asked for pooled cells and a union-mask scoring path.
• Every fix is in the proposal's sections 12, 12a and 12b.

Disclosures

• DEV candidate scores. Candidates were developed on DEV, which is allowed. Every DEV score is committed:
  • docs/amendments/gate_epuf_fill_dev_scores_before_amendment_1.json;
  • ..._after_amendment_1.json;
  • ..._after_round_2.jsonl.
• Dry runs. The TRAIN dry runs are committed as lineage.

Invariants, and where they are tested

• Floors and partition.

  • Every group's floor is priced on exactly the population its cells count. Pool size equals the cells' n.
  • Populations read no cell their own family masks.

  Tests: tests/harness/test_epuf_fill_gate.py, tests/test_epuf_fill_gate_floors.py.

• Scoring path. score_candidate gives every fill both families' masked cells as unknown and refuses any output that:

  • is not finite on its own cells;
  • leaves [0, 1];
  • changes a cell it does not own.

  The scored matrix keeps every other cell true. Tested.

• AIME. aime_35 equals ss.statutory_aime.aime for people born 1929-1945 (Hypothesis differential test).

• Floor estimator. floor_group's sigma estimates the standard error of a mean within 15% (Hypothesis property test).

• Artifacts.

  • The v3 floors recompute from the stored replicates.
  • v3 equals v2 exactly in truth, floors, tolerances and partition.
  • The build is bound to its commit and was clean.
  • epuf_fill_scoring pins v3's SHA-256.

• TEST access. TEST is unreadable except through test_part() after lock. Tested with unlocked and wrong-id gates.yaml files.

Downstream

Nothing downstream changes in this PR. career.py stays byte-identical, sealed by the birth-evidence reducer. The DYNASIM projection comparisons (registered one-shots) keep the current rule. Adopting a learned fill for them needs a new registration, which will be queued once candidates are scored on TEST.

Remaining, after Max's ruling on d927

1. Merge Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509, then this PR.
2. Flip the draft block (docs/design/gate_epuf_fill_block_draft.yaml) into gates.yaml with locked: true.
3. Register the candidates: code commit and fitted-artifact SHA-256.
4. Score TEST once with epuf_fill_scoring.score_registered, and publish the result whether it passes or fails.

axiom: n/a: evaluation infrastructure only; no policy rule is encoded or changed.

Tests

• 93 targeted tests pass on the host. The EPUF and PSID builds are host-only.
• tests/tier_counts.json and tests/README-tiers.md are updated.

Merge method: merge commit only, never squash or rebase. The binding tests diff cb76ad1 (the registered floor build) against HEAD. If that commit drops out of master's history, they skip silently instead of failing.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
social-security-model	Ready	Preview	Oct 4, 2026 4:51pm UTC

[MaxGhenis]

Status at 9f2dd835

• The independent delta review (Opus 5.5 lane, job 20261004-052447-epuf-fill-review-delta) is APPROVE for this head. EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516 is APPROVE at 7de0644d (see its comment).
• CI: shard 1 fails only tests/bridge/test_pe_us_depletion_cut_artifact.py::test__artifact__then_the_recorded_commit_is_this_code (1 failed, 3,446 passed), the depletion-cut pin inherited from Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509's base. Pin the depletion-cut outputs to the generator's own code, not all of src/ #514 fixed it on master (merged 05:46Z); it clears when Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509 merges master.
• Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509 is currently CONFLICTING with master, in tests/tier_counts.json and tests/README-tiers.md only. Its owner merges master into it.
• Merge order, after Max's d927 (ratify the K=1 materiality tolerance): put the draft block (docs/design/gate_epuf_fill_block_draft.yaml) into gates.yaml with locked: true; merge Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509, then this PR, then EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516 on green CI; then run scripts/score_epuf_fill_test.py once against TEST.

[MaxGhenis]

Head aa2928d9: synced with master after #509 landed, reviewed APPROVE (independent in-session Opus 5.5 reviewer with a shell; the Subfleet lane was queued on capacity, so I cancelled it; posted verbatim after the status).

• Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509 merged into master as 492d5a60. aa2928d9 merges master into Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515's branch, and Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515's base is now master. ee1c2f78 merges that into EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516's branch. Both are merges, not rebases, so the registered build commit cb76ad15 and the manifest's code_commit b722382e stay on the history the binding tests diff against.

• Only tests/tier_counts.json and tests/README-tiers.md conflicted. They were recounted against the full collection: Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515 is unit 6,017 / artifact 3,388; EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516 is unit 6,037 / artifact 3,398.

• Merge method: use a merge commit, never squash or rebase (the reviewer's finding 1). A squash or rebase drops cb76ad15 or b722382e from master, and then the binding tests skip silently instead of failing.

• Merge waits on green CI and on Max's d927 (ratify the K=1 tolerance and lock). The tolerance is in the bound rules file, so merging before the ruling could need a rebuild and a refit.

---

Verdicts

• Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515 at aa2928d9: APPROVE. Don't merge until CI is green, and use a merge commit (findings 1 and 2).
• EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516 at ee1c2f78: APPROVE, with the same two conditions.

Findings

1. Use a merge commit for both PRs. This is a merge-method caveat, not a defect. The repo allows merge, squash and rebase. If either PR is squashed or rebased, cb76ad15 or b722382e drops out of master's history. CI checks out with fetch-depth: 0 (.github/workflows/tests.yml:24), so a fresh clone may not have those commits. The two binding checks then skip instead of failing, and the binding stops being enforced with no red check:

   • _assert_bound at tests/test_epuf_fill_gate_floors.py:259-265 skips with "the build's commit is not in this clone".
   • test_the_fill_code_is_unchanged_since_the_fit at tests/test_epuf_fill_candidates_manifest.py:73-80 skips the same way.

   Register gate_epuf against SSA's Earnings Public-Use File (unlocked, report-only) #509 itself went in as a merge commit (492d5a60).

2. CI is not finished. gh pr checks shows pytest-shard (3.14, 2/4) and (4/4) pending on both PRs. Both are MERGEABLE and not drafts.

3. The brief's master delta is understated. Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515's real merge base is 5129ac32, not 65daf03b. Since that base, master also changed docs/design/gate_epuf_block_draft.yaml, scripts/render_gate_epuf_block_draft.py, docs/amendments/gate_epuf_registration_proposal.md, reviews/gate_epuf_round4_confirmation_20261002.md and tests/test_gate_epuf_block_draft.py. None of these overlaps a Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515/EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516 file, and grepping both PRs' files for those names finds nothing. src/ and gates.yaml are unchanged from 5129ac32 to master, so this doesn't matter.

What I verified

• Heads and parents match the brief. aa2928d9 has parents 9f2dd835 and 492d5a60; ee1c2f78 has parents 881f0377 and aa2928d9. 65daf03b is an ancestor of master. cb76ad15 is an ancestor of both heads; b722382e is an ancestor of HEAD.

• Only the tier files were resolved by hand. git show --remerge-diff for both merges touches only tests/tier_counts.json and tests/README-tiers.md. The only files both sides touched since 5129ac32 are those two.

• The merges left the PR content unchanged. Excluding the tier files, diff(5129ac32..9f2dd835) is byte-identical to diff(origin/master..aa2928d9), and diff(9f2dd835..881f0377) is byte-identical to diff(aa2928d9..ee1c2f78). What was reviewed is what is proposed.

• The tier counts add up (tiers are assigned per module, tests/conftest.py:89-104).

  Revision	unit	artifact
  Merge base 5129ac32	5,948	3,361
  Master	5,960	3,361
  aa2928d9 (Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515)	6,017	3,388
  ee1c2f78 (EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516)	6,037	3,398

  • Master, +12 unit: the depletion-cut test file gained 4 plain tests and one 8-case parametrize.
  • Register gate_epuf_fill: learned career fills scored on held-out EPUF (awaiting ratification) #515, +57 unit and +27 artifact: test_epuf_fill_gate.py 47 unit (34 functions plus 13 extra parametrized cases); test_epuf_fill_scoring.py 10 unit; test_epuf_fill_gate_floors.py 27 artifact.
  • EPUF-learned career fills: candidates, PSID-2010 application, registered before TEST #516, +20 unit and +10 artifact: test_epuf_fill.py 14 unit, test_psid2010_epuf_fill.py 6 unit, the manifest test 10 artifact. The edits to test_coordinator.py and test_birth_evidence_artifact.py add no tests.

• Collection matches at HEAD (unit 6,037, artifact 3,398, total 11,516) and on a git archive export of aa2928d9 (6,017 / 3,388); the tier-count test passes on both.

• Targeted tests at HEAD: 234 passed. On the aa2928d9 export: 198 passed, 3 skipped, 3 failed, all three because the export is not a git repo (git rev-parse --show-toplevel exit 128); they pass at HEAD.

• Pinned and bound files are unchanged: cb76ad15..origin/master on epuf_cells.py, epuf_operator.py, data/epuf.py empty (same from 65daf03b); cb76ad15..aa2928d9 and cb76ad15..HEAD on the five bound files empty; b722382e..HEAD on the fit's code files empty; the manifest hashes to 83d17a14f960033c….

• Merging rather than rebasing matches repo practice: 118 of the last 200 master commits are merges, 42 of them "merge master into the branch". CLAUDE.md says nothing about merge method.

What I could not verify

• The git-dependent tests at aa2928d9 exactly (code identical to HEAD, where they pass).
• The final CI result.