Repository navigation
Add a base mode to parameter uprating - #654
Merged
Merged
Conversation
An `uprating.base` block ({period, value}) makes uprating compute each
value after the parameter's last explicit one as the base amount plus
the rounded increase the index implies since the base period:
base + round(base * (index[t] / index[base] - 1))
Statutes such as 26 U.S.C. 63(c)(7)(B)(ii), 24(i)(3) and 213(d)(10)(B)(i)
round the increase over a stated base, which chained mode (round the
uprated amount, chained from the last explicit value) cannot express.
Chained mode stays the default and is unchanged.
Refs #403.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Tests: - Example tests reproduce Rev. Proc. 2026-35 sections 3.15 (standard deduction) and 3.29 (long-term care premium limits) and cover each rounding form, the base-period default, scales, cloned subtrees, reforms applied before uprating and every error path. - Hypothesis property tests check that the increase is a whole number of intervals, brackets the exact increase, rises with the index, matches chained mode without rounding, and leaves explicit values alone. - A differential test checks chained mode against a frozen copy of the 7c84d94 implementation (tests/fixtures/chained_uprating_reference.py). Fixes found by those tests: - The fixed 1e-9-interval snap missed large exact multiples: $572,903.25 raised by 2,032 / 186 is exactly 22,743,643 quarter-dollar intervals above its base, which floats put 4e-9 intervals short. The snap now widens to 16 machine epsilons of the amounts. - An infinite base, such as a scale's -inf lowest threshold, raised an error; it now stays infinite. Docs: a new "Uprating" section in docs/usage/parameters.md covers both modes, how they differ (with the Rev. Proc. examples) and how base mode meets reforms. UpratingSchema documents `rounding` and `base`, replacing a `type` key that uprating never read, and gains UpratingBase. Refs #403. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
`base.floor: true` keeps the index ratio at or above 1, so a positive base never projects below itself. Statutes that add "the percentage (if any) by which" an index exceeds its base-year level, such as 26 U.S.C. 1(f)(3), floor the cost-of-living adjustment this way. The floor applies to the ratio, as the statute's percentage does, rather than to the projected value or the rounded increase; the two differ only for a negative base, which a test pins. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The first independent review found three faults in base mode's rounding, all from computing the increase in binary floats and then snapping it: - nearest sent an exact half whichever way float error pointed: 375 * (523.8 / 202.5 - 1) is exactly $595 but 594.9999999999999 in floats, which gave $965 instead of $975; - the snap tolerance (1e-9 intervals, or 16 eps of the amounts) could move an exact non-multiple a full interval: 24,567.87 at 325.882 / 315.605 gave $25,367.87 instead of $25,317.87; - the tests could not see either, because the property oracle imported the tolerances and the chained reference imported live helpers. Base mode now computes the increase in rational arithmetic on the decimals the base, index values and interval print as, rounds an exact half up (as PE-US's hand-coded projections did), and snaps only within float error of a computed index: 64 machine epsilons of the uprated amount, capped at 1e-6 intervals. Validation: missing or non-string `parameter` raises a named ValueError (in both modes, where it raised KeyError); base.period must be a year, date or period string naming a real date; the index must be positive; `rounding` rejects keys other than type and interval; an overflowing projection raises a named error. Tests: the chained reference is now the whole 7c84d94 module verbatim, with three chained outputs pinned as literals; the property oracle is exact and self-contained; the review's counterexamples and new error paths are pinned. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Mutation testing of 2504cf1 showed three tests too weak: - a half-to-even tie rule failed one test, because exact arithmetic made most tie examples odd halves, where both rules agree; $5 and $45 on a $10 interval now pin half up; - nothing tested the 1e-6-interval cap the docs state; a $10m amount on a one-cent interval, 5e-6 intervals below a multiple, now pins it; - only the Hypothesis differential caught chained nearest rounding down; a chained literal (117 to 120) now pins it too. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review run 2 showed that a fixed 64-epsilon allowance can snap a short decimal input that lies a few billionths of an interval from a multiple (1,819,252.81 at 395.69 / 370.811, rounded down to $5, moved by $5). Inputs that print with at most 15 significant digits are exact decimals, so their increase now rounds exactly. Only when some input prints with more digits, as a computed index does, may the increase snap to a multiple within 64 machine epsilons of the uprated amount, capped at a millionth of an interval. Tests now pin literal cases for each rule, so all 26 mutants of the rounding, allowance, validation and overflow code fail at least one test (a 15-digit short base and a computed index 1e-8 intervals short of a multiple kill the last two). The rounding docstrings and the usage docs say which mode rounds half to even (chained) and which half up (base). Validation now names the parameter for a missing index name, an index that fails to load, an impossible base date, extra rounding keys, a non-string rounding type, an out-of-range integer and a non-finite result. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review run 3 (APPROVE WITH NITS at 4d803a2) found: - The digit count normalized a Decimal, which rounds to the caller's decimal context: at precision 10 a computed index lost its allowance, and an Inexact trap raised a bare exception. It now counts digits in the printed string. Ints count as exact, whatever their length, and the docs now say so. - An infinite base times an index ratio that underflows to zero gave NaN. The ratio of two positive index values is positive, so an infinite base now stays as it is. - Unknown keys of mixed types raised TypeError from sorted(), and a base.period past the C int range raised a bare OverflowError. Both now raise the named ValueError. - A stated base.value matched within an absolute 1e-9 as well as one part in a billion; it now matches to one part in a billion, as documented. - The docstring gave the unrounded value in a different evaluation order from the code. New literal tests pin the allowance for each of the four inputs (base, both index values, interval), the 64-epsilon constant from both sides and its scaling with the index ratio, and a 15-digit whole-number base whose trailing ".0" is no significant digit. All 41 mutants of the base-mode code now fail at least one of the 147 base-mode tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review run 3's second round found three digit-count mutants that no test caught: counting an int's digits, keeping leading zeros, and counting the exponent. Three literals now pin each: a 16-digit int base 1e-7 intervals below a multiple, and 15-digit indices below 1 written with leading zeros and with an exponent. All 44 mutants of the base-mode code fail at least one of the 150 base-mode tests. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Review run 3, round 3: the comment said 1e-12 intervals; the increases are $1e-12 below $100, which is 1e-14 intervals. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis
marked this pull request as ready for review
November 11, 2026 23:29
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Core can now project an indexed amount from its statutory base and round the increase over that base. This opt-in
uprating.basemode supports amounts that chained whole-amount rounding cannot express. Chained mode remains the default, and explicit values always win.Fixes #403.
Base mode computes
base + round(base * (index[t] / index[base.period] - 1)), applying the interval to the increase.base.valuemay be omitted to use the parameter's value at the base period;floor: trueprevents the index ratio falling below one. The period names the index's own period, which may label the preceding calendar year's prices.Rounding uses exact rational arithmetic on the decimals the inputs print as. Exact nearest ties round upwards. Every recorded decimal is exact, including the printed value of a computed float: an index producer must supply its intended precision. This rule avoids guessing precision from digit count, which could make an adjacent higher index lower an amount by a full rounding interval. Without rounding, the existing floating-point calculation order is preserved.
The docs cover supported metadata, validation errors, infinite scale thresholds and reforms applied before uprating. Base-mode projections follow their base rather than a later reform's last value; countries that apply reforms before uprating must choose that behavior deliberately. PolicyEngine US applies reforms after uprating. Its adoption remains a separate draft, #10783 in PolicyEngine/policyengine-us.
Validation at
4c7b402f22134f8849bfa16764087871dc09ef4a:git diff --checkpass.115eb338d5616da115c4925ef3aefed44fa5e8d3, resolved the monotonicity finding, reran the 153 base-mode tests and independently recomputed all 12 revised computed-input literals. The last commit changes two comment/prose lines only.115eb338d5616da115c4925ef3aefed44fa5e8d3.20261112-025838-pr-6d1d7074. The historical peer job never launched and supplied no Subfleet approval.The frozen chained fixture is the complete module from
7c84d941b, so its differential tests share no changed arithmetic helpers. Existing integer bare-rounding errors and ties-to-even behavior in chained mode stay unchanged.No final-head US parameter-parity claim is made: earlier comparisons tested a different rounding rule. The US adoption draft must renew its comparison and pin a published core release before merging.
axiom: n/a: projection infrastructure (no policy encoded)