PolicyEngine / PolicyEngine/microcosm
PUF stage manifest declares a support_clip op that no execution path honors (dead donor_realized contract)
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 4
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 94
Description
Found during the #462 fix-3b diagnostic. The PUF stage manifest declares
{"kind": "support_clip", "range": "donor_realized"}
(source_stages.json:111-114) but the declaration is dead twice over:
- Bypassed: the production builder reads the PUF HDF5 and calls the QRF chain directly (
build_us_puf_support_base.py:981-989,:1811-1829); nothing routes this stage's ops through the generic runtime. - Mis-shaped: the generic
support_cliphandler acceptsoutput+ numericlower/upperand does not implement"range": "donor_realized"(us_runtime/source_runtime.py:1050-1083) — so even a routed invocation would fail.
Also: even as intended, a donor-realized min/max clip would not have prevented the #462 tail defect ($594,483.64 is an observed donor value, well under the $5.96M donor max).
Same disease class as the never-invoked capital_gain_distributions stage fixed in #480: a declared operation that no execution path honors. Options: implement donor_realized in the handler AND route the stage through it, or delete the declaration and let the #462 per-target weighted-quantile bound (which subsumes the useful part of the intent, with real tail semantics) be the recorded contract. Either way the manifest must stop declaring machinery that never runs — a spec-validation guard of the #477 no-hardcoded-counts kind would prevent the class recurring.
Relates #462, #480.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Read source_stages.json:111-114 alongside build_us_puf_support_base.py:981-989 and :1811-1829, then inspect us_runtime/source_runtime.py:1050-1083 to confirm the declared operation has no honored execution path. Resolve whether to route and implement donor_realized or remove the declaration, and add the proposed spec-validation coverage. Done means the manifest no longer declares machinery that execution cannot honor.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, data-engineering
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100