Cache ADD and DIVIDE results only where a plain read returns them

[MaxGhenis]

Summary

ADD and DIVIDE previously cached results where a later plain read could return a different value or raise. This change caches only compatible MONTH/FLOW → YEAR and YEAR/FLOW → MONTH results whose dtype matches the variable. Accepted writes use derived=True, preserve the input visible to a plain read, and allow an existing derived aggregate to refresh after native inputs change. Found while reviewing #562 (soundness review, finding 5).

STOCK entries, dtype-changing boolean/integer FLOW entries, and unsupported multi-period option entries no longer enter known-period lists, dumps, or computed-variable exports. Accepted aggregates remain derived and cannot become input-only carry-over or uprating sources. Automatic invalidation of dependent values immediately after set_input remains outside this change; refresh tests explicitly rerun the option.

Master merge and combined behavior

Head: 77df88302596d0552a9b065a1ab112701b0fa1a8.

Merged canonical master at b853f4989e973a25160698e28b8b3d57a580c654 in merge commit 693754220ce5b246676e6cc7ff5c32be095ff8ed. Git reported no textual conflicts. The merge preserves #558's holder storage directories and #561's per-tier supplied-input records, tier-aware cache invalidation/replay, recorded-input exports, and portable compound-period filenames.

Ten new combined provenance regressions cover ADD and DIVIDE in memory and disk storage, including deleted target inputs and supplied disk inputs hidden by derived memory values. They verify that accepted option caches remain derived, create no supplied-input records, stay out of input-only dataframe exports, disappear during invalidation, and leave recorded native inputs available for replay. A refreshed memory aggregate can coexist with a recorded disk input; invalidation restores the supplied disk value for a later plain read.

Updated the helper docstring and regression comments to describe the merged input-record behavior, including deletion and dump restoration. Documentation review: no separate API documentation is required for this internal cache repair. Documentation impact: low; confidence: high. The existing towncrier fragment is retained.

Validation

Required focused files: 297 passed, 2 xfailed, no failures across 15 files. Each file ran separately in the foreground with uv run pytest -q -p no:cacheprovider.

Coverage	Files	Passed	Xfailed
#571 option regressions and properties, including ten new combined cases	3	36	0
#561 supplied-input and portable-filename files	8	186	0
#558 disk-storage and directory files	4	75	2

The two expected failures cover the documented lifetime limit when a parent removes a storage directory that a forked child still uses.

• Complete core suite, run once in the foreground on this head: 2,090 passed, 1 skipped, 3 xfailed, no failures, in 1,236.12 seconds (20 minutes 36 seconds).
• Ruff format and lint passed across 167 files.
• Runtime validation uses CPython 3.13.15, pytest 9.1.1, and Hypothesis 6.168.3. The interrupted initial option-property attempt is excluded from these counts; the complete rerun passed both tests.

Core A/B and country microsimulations remain deferred to the hub. Historical validation counts and source reviews are not presented as validation of this head; current-head CI and hub checks remain open.

A documentation build was not run: this merge updates the internal helper's docstring and test comments, while the API reference continues to generate from source.

Impact

Hub A/B microsimulation, PE-US, current head. The hub ran PolicyEngine-US main 0a8c3c2c43 on the default dataset twice for each year. One run used Core master b853f4989e, the merge base; the other used this PR's head 77df883025. The runs went one at a time under the shared heavy-job lock.

Output	2025 change	2026 change	Records changed
household_net_income	0	0	0
income_tax	0	0	0
state_income_tax	0	0	0
household_benefits	0	0	0
household and person-household IDs	0	0	0

Every compared array is identical. Run time was 177s against 173s (2025) and 177s against 185s (2026), with the same peak footprint on both cores (11,264 MB and 12,288 MB). PE-UK isn't microsimulated here. CI's "Test Core and country packages" jobs exercise it, and all 19 checks pass at this head.

Composition and hold

Merge order remains #576 → #561 → #571 → #581. The option-cache helper retains the eligibility and visible-input protection contract needed by #581. #581 was not modified and retains its separate d899 hold and dumper reconciliation with #576.

Max's d899 approved landing this PR third in that order, on the hub gates.

axiom: n/a: core engine caching, no policy encoding

[MaxGhenis]

US + core hub merge audit, core#571 at 77df88302596d0552a9b065a1ab112701b0fa1a8 (squash): ADD and DIVIDE results are cached only where a plain read returns them.

• Order: Max's d899 sets Restore inputs as inputs, evict the fast cache on holder writes, reject non-numeric uprating and defined_for #576 → Keep the record of set_input values in step with storage #561 → Cache ADD and DIVIDE results only where a plain read returns them #571 → Count only inputs as already set when a set_input helper splits a longer period #581. Restore inputs as inputs, evict the fast cache on holder writes, reject non-numeric uprating and defined_for #576 and Keep the record of set_input values in step with storage #561 are merged.
• Review: hub review r1 APPROVE at this head (Opus via Subfleet; static read; no methodology choice). Its two P3s are a speed-only note and a test comment.
• Master merge: b853f498 (with Give each disk-backed holder storage its own directory #558 and Keep the record of set_input values in step with storage #561) merged without conflicts; ten combined regressions were added. The full core suite passed in the merge round: 2,090 passed, 1 skipped, 3 xfailed. Master hasn't moved since.
• Gates checked live at merge:
  • every check passes (19 of 19, including native Windows);
  • MERGEABLE;
  • not a draft;
  • no CHANGES_REQUESTED review;
  • head pinned.
• Impact: a hub A/B microsim of PE-US main 0a8c3c2c43 on the default dataset, Core b853f4989e against this head, for 2025 and 2026. Every compared array is identical, and run time is unchanged (table in the body).
• --admin: used only because a required approving review is the sole block.