[MaxGhenis]

Moves main's US engine lock from policyengine-us 2.2.1 (core 3.32.5) to policyengine-us 2.60.4 on policyengine-core 3.33.3, so the next certified US Route A build calibrates and scores natively on the current engine. No certified build is started here.

Why

The certified d1386 release (8b0c195) claims policyengine-us==2.2.1. PolicyBench v2 waits for a policyengine.py bundle certified with 2.60.x (ruled 2026-10-23). The short-term bridge is a compatibility_recertification source-enrichment child that the PolicyBench session is building separately; this PR does not touch microcosm.data.contract, source_enrichment, or that tool. This is the long-term half.

Versions (verified on PyPI 2026-10-23)

• policyengine-us 2.60.4, the newest (uploaded 2026-10-23 09:48Z). It requires core >=3.32.27 and spm-calculator >=1.0.0,<=1.0.0.post1.
• policyengine-core 3.33.3, not the newest 3.33.12. US release manifests claim core with ==, and policyengine.py's certification requires the runtime core to be the build core or covered by that claim. policyengine.py 6.10.1 pins core 3.33.3, so a 2.60.x bundle can match without a second core bump, and the UK fork stays on its locked 3.33.3. Core 3.33.4 to 3.33.12 (rate-scale, set_input cache and dataset-membership fixes) is a follow-up to coordinate with policyengine.py.
• spm-calculator stays 1.0.0 (policyengine.py's pin).
• policyengine.py is not a workspace dependency, so no policyengine.py pin moves here.

The lock diff moves only policyengine-us and drops the separate 3.32.5 core entry. APPROVED_UV_LOCK_SHA256 follows.

What 2.60.4 changes for Microcosm

The full surface diff (6,167 to 6,797 variables) was cross-referenced against every tracked file. Evidence is in ~/PolicyEngine/_build_artifacts/engine-lock-pe-us-2.60/.

Removed inputs Microcosm produced: first_home_mortgage_interest, second_home_mortgage_interest (tax unit; policyengine-us#9605).

• 2.2.1 read them only where no person-level home_mortgage_interest was reported.
• On the d1386 release H5, first_home_mortgage_interest equals the person-level sum in every one of the 64,774 units that carry it, second_home_mortgage_interest is zero everywhere, and no unit relied on the fallback. The deduction base is therefore unchanged.
• The PUF tax-detail QRF stops producing both legs. The ACS donor targets, stacked battery, degenerate-column exclusions and spec bundle follow.
• The eCPS parity reference still carries the layers. REFERENCE_ECPS_RETIRED_LAYERS names their successor (home_mortgage_interest). The parity gate skips them and records the skip, and the input-coverage manifest drops the requirement (167 to 166 required columns).
• Because the QRF conditions each target on the ones before it, the predictors for the later origination-year and HSA targets change.

New engine inputs Microcosm already writes: tax_unit_role_input, parent_1_id, parent_2_id.

• They leave the stored non-variable register (51 to 48 entries).
• d1386 already satisfies 2.60's contracts. Every tax unit has exactly one HEAD and at most one SPOUSE, with every member supplied (a malformed unit makes the engine raise for the whole simulation). All 523,150 parent pointers name a co-resident. One person has person_id 0 and cannot be named as a parent; that was already documented in eligibility_inputs.

New take-up flag: takes_up_medicare_part_d_if_eligible (person, default true).

• Added to the take-up contract as rate_unsourced at the engine default. The ASEC has no Part D item; CMS publishes enrollment counts, so a count-calibrated stage is the follow-up.
• 2.60 gates the Part D IRMAA surcharge on Part D enrollment (#10115). With the flag at its default, every Medicare enrollee above the thresholds is still charged, as on 2.2.1.

IRMAA lookback (#10106).

• A single-year release now gets the earliest input year's income, deflated by per-capita CBO AGI, instead of zero.
• The holdout's single-year test now expects the Trustees top tier: $543,850 of lookback MAGI from $600,000 of 2024 wages gives $419.30 (Part B) and $81.00 (Part D) a month.

Other 2.60.4 model changes the pins follow (each checked against the 2.60.4 source).

• HUD gross rent now includes a utility allowance for the counties 2.60 encodes (LA County, the Texas TDHCA area, four Kansas PHAs). A one-bedroom renter in county 06037 with $12,000 rent gets $3,252 a year of allowance, so the housing payment rises from $11,975 to $15,227. The allowance also reads bedrooms, tenant_pays_utilities and is_sro, which the release does not store (engine defaults apply).
• Alimony paid is deducted through a person-level alimony_expense_ald_person, leaving dependents out. The pre-2019 divorce-year test is unchanged, and divorce_year still defaults to 2010, so stored alimony stays deductible.
• weeks_unemployed gains a live consumer, unemployment_compensation_months, for SNAP's work-registration exemption. The release already stores the column.

Reform-coverage probes pinned whole 2.2.1 parameter lists.

• On 2.60.4 they would also have stripped about 45 state SSP items from SNAP unearned income, and undone the educator_expense_ald and traditional_ira_deduction renames, so each probe would have measured a different reform.
• All nine lists are re-derived from the 2.60.4 baseline with only their own item changed. The educator probe now removes educator_expense_ald. Every reason text that states an engine fact was re-checked on 2.60.4.

Post-export watched-formula lists.

• US_POPULATION_AGGREGATE_VARIABLES and POST_EXPORT_BASELINE_BRANCH_READERS are unchanged on the 2.60.4 scan.
• The batched-materialization drift scan finds 30 new formulas. I read each one: 17 compare a record's own status or county with parameter lists (np.isin). The other 13 are household-local joins: parent links resolved among co-residents, family-keyed Wisconsin CTS units, SSI deemor pools, and an error-count .sum().
• None joins the population-aggregate list. The reviewed-source digest moves.

Static consumer index (frame adapter; it gates every generator).

• 2.60.4 had five formula sites it could not resolve. It now reads:
  • starred list items, from module constants and parameter lists;
  • one-argument dict.get with an is None skip;
  • a run-time key into a fully known name table (every value counts as a possible read);
  • helper return values, including tuple unpacking.
• 2.60.4 also exposed four ways the index missed reads without raising. All four are closed, each fails closed on what it cannot resolve, and each has synthetic tests:
  • Package helpers outside variables/. 2.60 moved 77 tax-unit sums onto tax_unit_non_dep_add (tools/general.py), so net_capital_gain lost its form 4952 reader, for example. Every helper the formulas call now needs a review in _policyengine_us_helper_reviews.py: which arguments name variables it reads, what its body reads on its own, and reads made only when an argument is omitted. All 41 helpers 2.60.4 calls were read and reviewed. Each review pins a digest of the helper's code, every package function it uses and the module constants they read (docstrings excluded). An unreviewed or changed helper stops the index. The same reviews cover class-body factories (formula = sum_among_non_dependents("earned_income")).
  • Simulation reads. branch.calculate(name), get_holder(name) and simulation.get_array(name) now record simulation_read receipts (21 calculate sites on 2.60.4, 11 on 2.2.1).
  • Local functions and lambdas. A function defined inside a formula is interpreted at each call, in the caller's scope; one used as a value is interpreted where it is defined, with unknown arguments. Lambda bodies are scanned. This covers the IRMAA lookback's provided() and Oklahoma's applied().
  • Opaque comparisons. period.start.year != 2021 used to count as exactly true, which hid Alabama's 2021 Part II recompute. Equality and membership tests now decide a branch only when both sides are exact data.
• Result on 2.60.4: 771 receipts added, none removed. No generated pin moves (audit, pool contracts, bundle, coverage manifest, concept golden, spec-engine coverage, parity fixture are all current), because none of the new edges reaches those surfaces.
• test_us_pool_input_consumers.py moves from engine_free to engine_contract. It skipped itself when the engine was missing, so CI never ran it, and its 2.60.4 pins had drifted. tools/ci_test_plan.py now rejects that skip pattern.

SSI closure grows from 54 to 96 input leaves. 59 of them run at engine defaults (up from 18): state UI wage inputs (modelled UI applies only when no reported amount exists, and pays nothing at zero wages), SSI living-arrangement and deeming detail, and some pension splits.

Re-derived pins (all observed and written verbatim, none hand-derived)

• Generated-variable audit: 119 to 120 variables (mt_agi).
• Engine ABI lock: 18 take-up programs.
• Pool contracts:
  • SSI closure 54/63/187 to 96/121/351 (input leaves / formula nodes / edges);
  • engine input projection 926 to 1,074 inputs;
  • remaining-stage manifest 1,250 rows.
• Spec bundle (--check passes; spec_sha256 5ff97a0b).
• Frozen generation-0 resources.
• Release input-coverage manifest.
• Concept-coverage golden (mapping reviewed against 2.60.4; it adds 148 uncovered inputs).
• Spec-engine coverage: 43,674/43,674 fields, 41/41 inventory checks.
• H3 parity fixture: it gains the Part D column, and expected.csv is byte-identical.

Invariants (executed)

• Static index superset. On 2.60.4 the new index's receipts include every receipt main's index records (771 added, none removed).
• Static index on 2.60.4. It resolves every site, every helper the formulas call has a current review, and no review is stale (test_policyengine_us_helper_reviews.py).
• Reviewed helper reads (property-based). A reviewed helper's call reads exactly the listed variables and the helper's own reads, for any list.
• Helper digests. A digest ignores docstrings and moves when the helper's code or a constant it reads changes; a changed helper fails until reviewed again.
• Starred display (property-based). It reads exactly the union of its parts, for any lists.
• Fail-closed cases. A helper returning an engine value, a run-time key into get, an unreviewed or changed package helper, a run-time name in calculate, a local function or lambda passed a run-time name, and a class-body call to a formula-module factory all raise.
• Reference-layer retirement (property-based). It partitions every share map: each layer is kept or retired, never both. It retires only registered layers, onto their successor, and refuses an engine that still defines the layer or lacks the successor.
• Reform probes. Each list-valued probe differs from the installed engine's baseline by exactly its declared item (the existing drift test, checked on 2.60.4).
• Mortgage conservation. On d1386, the 2.60 total (home_mortgage_interest + second_residence_mortgage_interest) equals 2.2.1's home_mortgage_interest_tax_unit in every tax unit. This is a data property of the certified file, verified directly.
• Lock. Every US install path resolves policyengine-us 2.60.4, core 3.33.3 and spm-calculator 1.0.0, and every US+UK combination is refused (test_engine_core_pins.py).

Consequences while main is ahead of the certified default

Main's loader enforces each release's == claim. So on this lock, microcosm.data.load("us") refuses the 2.2.1-certified default until the recertification child (or a native 2.60.x build) exists.

Follow-ups (not in this PR)

• Coordinate core 3.33.12 with policyengine.py.
• A count-calibrated Part D take-up stage.
• Declare tax_unit_role_input on the pool input surface, so the SSI agreement simulation reads the constructor's roles. It currently falls back to age ordering, as 2.2.1 did.
• Store bedrooms (and consider tenant_pays_utilities), which 2.60's HUD utility allowance and the payment standard read; the release leaves them at engine defaults.
• spm-calculator defines variables at run time (spm_measurement_adults, spm_measurement_children) that the source index cannot see, so closures stop at them.

Status

Draft. CI on the latest pins and the Sol review are pending (Subfleet lanes reopen about 02:00Z).

axiom: n/a: engine lock and data-pipeline compatibility; no policy rule changes.

🤖 Generated with Claude Code