PolicyEngine / PolicyEngine/microcosm

PUF stage manifest declares a support_clip op that no execution path honors (dead donor_realized contract)

Open
#482 0 comments 0 reactions 0 assignees View on GitHub

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:

  1. 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.
  2. Mis-shaped: the generic support_clip handler accepts output + numeric lower/upper and 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.