Uprate only from inputs, so uprated values don't depend on calculation order

[MaxGhenis]

Stacked on #562 (carry-over order). This PR's change is the top commit only. Merge it after #562, or retarget once #562 lands.

Problem

Simulation._calculate uprates a variable that has uprating and no formula result for a period. It takes the latest earlier period stored in the variable's own unit and scales that value by the index ratio. That period could be one the simulation had calculated itself: an earlier uprated, masked or truncated value. So an uprated value depended on which periods had been calculated first.

Executed on #562's head (index +3.7% a year, input for 2012; 2015 asked alone vs after 2013 and 2014):

Variable	2015 asked alone	2015 after 2013, 2014
int [1001, 77]	[1116, 85]	[1115, 83]: truncation compounds
float [1001.3, 77.7]	1116.6072998046875	1116.607177734375: float32 rounding compounds
float, defined_for False for person 0 in 2013 only	[1115.16, 1115.16]	[0.0, 1115.16]: the 2013 mask carries into 2015

The same drift happens when one of these, cached at an intermediate period, becomes the value uprated:

• a default;
• a monthly input carried into a calculated year;
• the result of a formula that a reform gives an uprated variable up to an end.

#551's path-independence test held only to rel=1e-5, which hid the bitwise drift.

Fix

Uprate only from an input this branch reads. #562 marks every value the simulation caches as derived. Holder.get_input_periods(branch_name), also from #562, lists the periods whose value get_array(period, branch_name) actually reads is an input. It ranks stored keys in get_array's lookup order (the branch, then its ancestors, then default; memory before disk) and leaves out periods stored only under branches this one cannot read. For variables with uprating, the uprating path keeps only the earlier same-unit periods in that set. With no earlier input, control falls through to #562's carry-over or the default, exactly as when the period is asked alone.

It also fixes a crash that was already on master: a period stored only under a branch this simulation cannot read, for example through Holder.set_input(..., "sibling"), used to be picked as the uprating source and read back as None, which raised TypeError. A regression test covers it.

The production diff is one filtered list in simulation.py, plus a comment in #562's no-input branch. The known_periods = holder.get_known_periods() line is unchanged, so #552 (branch-visible known periods) still rebases cleanly.

Invariants

The domain: uprated variables of each value type (float, int, and bool masks via defined_for), inputs in each variable's own unit (or any unit for a variable with no set_input helper), and earlier requests that are plain calculations in either unit, ADD or DIVIDE. Over that domain:

1. Order independence, byte for byte (dtype, shape and bytes, so -0.0 differs from 0.0). What a simulation returns for a period equals what a fresh simulation with the same inputs returns for that period alone. This holds when reading from the simulation, from a branch, or from a nested branch forked after those requests, including a branch that sets its own input. It holds with auto-carry-over on and off.
2. Reference rule. The result is the latest earlier own-unit input × index(period) / index(input period), cast to the variable's type and masked by its own defined_for. With no such input, it is Carry over only inputs, the latest at or before the requested period #562's carry-over input or the default.
3. Inputs still count. An input at an intermediate period is still uprated from. That covers an input set over a period already calculated, one set on a branch over a period the parent calculated, and one stored only under a branch while the parent calculates the same period.

Tests

• tests/core/test_uprating_order.py: 33 regressions with no Hypothesis dependency, so the smoke job runs them too. They cover int truncation, float32 and monthly rounding, defined_for masks and all-false defaults, cached non-zero defaults, cross-unit carried inputs, a reform formula with end, branches and nested branches, branch-only inputs, and over-correction guards.
• tests/core/test_uprating_order_property.py: a derandomized Hypothesis property with 500 examples plus 9 @example rows. It covers invariants 1 and 2 byte for byte. Half the requests target the variable checked, and branches may set their own input. The docstring states the domain.
• tests/fixtures/uprating_order.py: the variables, the reference rule (which rejects inputs it doesn't model) and assert_bitwise_equal. It reuses Carry over only inputs, the latest at or before the requested period #562's simulation helpers.
• Fix variable uprating when the uprating parameter is undefined, and pick the latest earlier period #551's test_result_does_not_depend_on_intermediate_years_computed: now asserts exact equality instead of rel=1e-5.

Base (same test files)	Failures
master b78b0ba9	25 of 33 regressions, the property, and 8 of 8 tightened #551 cases
#562 alone (35e20d9f)	23 of 33 regressions, the property, and 8 of 8 tightened #551 cases
this PR (57c0d36b)	0

The cases that pass on the bases are the over-correction guards.

Mutation check (mutants.py): all 6 mutants of the filter are killed, and the property alone kills all 6. The mutants are: no filter, a filter that ignores the branch, an inverted filter, max over the unfiltered list, dropping the uprating guard, and uprating from the earliest input.

Local runs on this head: full suite 1234 passed, 4 skipped, 1 xfailed. Country-template YAML: 39 passed. ruff format --check: clean.

Independent reviews. A final-commit review (Opus, standard tier, on 2120f78f) returned APPROVE WITH NITS. It found no production defect and passed its own 400-example holder-level differential and 300-example tree property; its nits about stale text are fixed here. An earlier review (GPT-6.1 Sol, hard tier, on a previous head; scripts and report kept with the evidence) also returned APPROVE WITH NITS, with no production defect introduced by this change. That earlier review's test nits are fixed here:

• the comparisons are now byte-level;
• the fixture's domain is stated and enforced;
• the property now covers branch inputs, which the branch-blind mutant had survived;
• the changelog and docstrings no longer claim more than is tested.

Measurements

These are real PE-UK and PE-US microsimulations, with no scaling. Cores compared: master b78b0ba9, #562 and this PR. The full-eCPS and multi-year runs used #562 27d1bc35 with this change at 1e88ee16. A confirmation pass on #562 35e20d9f and this PR a2782333 reran PE-UK single and multi, the PE-US subsample and full-eCPS 2026. Every comparison matched the earlier pass. The final heads (#562 912a4ac5, this PR 2120f78f, whose production code 57c0d36b keeps) changed only #562's carry-over tie-break for equal-extent inputs in another unit. A check of the final heads against the confirmation outputs matched byte for byte: UK 2031-2033 41/41 arrays each year, full-eCPS 2026 30/30, and the 2025-2026 subsample 30/30 each year, for both #562 and this PR. Every run on this PR was repeated with a shadow logger, which left outputs bitwise unchanged; it records each uprating decision where master's rule picks a different source period.

• PE-UK: policyengine-uk 7b9fc379, Enhanced FRS 2024-25, full sample.
• PE-US: policyengine-us 6c5170fd, Enhanced CPS (inputs at 2024), a 3,000-household subsample (seed core-cow-bench) and the full sample.

Single-year simulations (what policyengine.py and the APIs build): no output changes.

Run	master vs #562 vs this PR
PE-UK 2026	41/41 arrays bitwise identical. No uprating decision has an earlier stored period: PE-UK loads every year through 2030 as inputs.
PE-UK 2032	41/41 identical. 97 uprating decisions; master and this PR pick the same source in all of them (the 2030 input).
PE-US 2026, 3,000 households, with MTR branches	31/31 identical. 197 decisions pick a different source, and none changes a value: they are monthly variables with no input, where master chains a cached default.
PE-US 2026, full eCPS	#562 → this PR: 30/30 identical. 99 of 198 decisions pick a different source; none changes a value. (Master → #562 differs in spm_unit_net_income for 14 SPM units: #562's state_fips/FPG fix, see #562.)

Multi-year in one simulation: this PR removes uprated-input drift.

Run	#562 → this PR	Single-year vs multi-year (same year)
PE-UK 2025-2030	41/41 identical every year. 130 decisions pick a different source, 0 change a value.	—
PE-UK 2031-2033	2032: 24 of 41 arrays change, by 1e-7 to 1e-9 relative. Examples: household net income +£41k on £2.03tn, income tax +£14k on £427bn, weights 5e-8. 2033 is similar. These are uprated inputs: weights, employment, self-employment, pension, savings and dividend income. They were chained from cached 2031 values; they now come from the 2030 input.	2032 inputs now match single-year 2032 exactly. Master/#562 differ in 8 input arrays.
PE-US 2025-2026, 3,000 households	2026: 28 of 30 arrays change, by 1e-7 to 1e-8 relative. Example: income tax +$258k on $1,962bn. The cause is the same: inputs uprated through cached 2025 values.	26/30 arrays match single-year 2026 exactly; income tax is identical. Master matches 0/30 and #562 1/30.
PE-US 2025-2026, full eCPS	2026: 28 of 30 arrays change, by 1e-7 to 1e-8 relative. Examples: income tax +$242k on $2,141bn; household net income +$0.73m on $14.46tn; weights 1.6e-8.	Asked alone vs after 2025: income tax differs for 28 tax units (#562: 30,957), household net income for 30 households (#562: 23,034), state income tax for 3 (#562: 24,131). All inputs and weights match exactly. The rest is 24 tax units whose itemization flips in PE-US's persistent branches (the same 24 on #562).

The multi-year differences that remain are not uprating:

• PE-UK 2032+ (12 arrays, incl. child benefit −2.3%, UC, MTR, poverty). PE-UK's current_education formula copies last year's value only if last year happens to be cached, and otherwise imputes from age. That's a PE-UK order dependence. Separate task.
• PE-US 2026 (itemizing outputs: one tax unit's itemization flips, ctc_limiting_tax_liability and tax_liability_if_itemizing for 63-120 units). These are computed in PE-US's persistent itemizing/not_itemizing branches, created in 2025 and reused in 2026. policyengine-us#9738 (get_branch_for_period) re-forks them.
• PE-US 2027 after 2025-2026 raises ParameterNotFoundError (md...informal.rates.UNKNOWN) on Carry over only inputs, the latest at or before the requested period #562 and this PR. It doesn't raise on master, but master's 2026 is wrong there (income tax $33bn, the Carry over only values stored at the variable's definition period #557 age/12 bug). The cause is in PE-US: its county formula reads the default branch's latest period from inside a reused branch. The carry-over session is filing the PE-US fix.
• spm_unit_is_in_spm_poverty raises SPMInputError on every core, master included. This is the known eCPS SPM composition defect, us: name the SPM composition defect in seconds, and refuse it by name in the release microcosm#948. It isn't measured here.

Not in scope

These are pre-existing on master; the review found most of them.

• Stale cached targets after a later set_input: Make set_input on a branch drop values calculated from the input it replaces #560 covers branches; nothing is invalidated for the root simulation, as on master.
• Subsample promoting calculated values to inputs, and STOCK/DIVIDE caches: task_857ef4c2.
• On-disk clones and underscore branch names: Give each disk-backed holder storage its own directory #558, Read only periods the current branch can see when uprating or carrying over #552, task_a9863c4b.
• restore_simulation dropping the input registry, a stale Holder.set_input fast cache, and Enum uprating raising: new task.
• Dumps written before Carry over only inputs, the latest at or before the requested period #562 carry no provenance marks, so a restored calculated period is treated as an input.

axiom: n/a: engine fix to uprating source selection in policyengine-core; no policy rule changes

🤖 Generated with Claude Code