Skip to content

Add a base mode to parameter uprating - #654

Merged
MaxGhenis merged 11 commits into
masterfrom
feat/base-year-uprating
Nov 13, 2026
Merged

MaxGhenis merged 11 commits into
masterfrom
feat/base-year-uprating

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

Core can now project an indexed amount from its statutory base and round the increase over that base. This opt-in uprating.base mode supports amounts that chained whole-amount rounding cannot express. Chained mode remains the default, and explicit values always win.

Fixes #403.

uprating:
  parameter: gov.example.price_index
  base:
    period: 2025
    value: 23625
    floor: true
  rounding:
    type: downwards
    interval: 50

Base mode computes base + round(base * (index[t] / index[base.period] - 1)), applying the interval to the increase. base.value may be omitted to use the parameter's value at the base period; floor: true prevents 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:

  • All 382 parameter tests passed locally, including independent exact-value, monotonicity, explicit-value, floor and frozen chained-mode differential properties.
  • Three deterministic adjacent-index regressions cover downwards, upwards and nearest rounding, both directly and as Hypothesis examples. All three fail against the prior head and pass with the fix.
  • Ruff formatting, lint and git diff --check pass.
  • An independent GPT-6.1 Sol reviewer approved final head 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.
  • All 19 CI checks pass on final head 115eb338d5616da115c4925ef3aefed44fa5e8d3.
  • An independent in-chat GPT-6 Astra reviewer also approved that exact head with no findings, passed 153 focused tests in 3.70 seconds, and verified the frozen fixture’s bytes. I authorized this review to supersede the old Fable peer requirement and unapproved durable gate 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)

MaxGhenis and others added 3 commits November 9, 2026 13:16
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>
MaxGhenis and others added 6 commits November 11, 2026 16:56
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
MaxGhenis marked this pull request as ready for review November 11, 2026 23:29
@MaxGhenis
MaxGhenis merged commit bbc599c into master Nov 13, 2026
19 checks passed
@MaxGhenis
MaxGhenis deleted the feat/base-year-uprating branch November 13, 2026 12:03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add base year support for parameter uprating

1 participant