PolicyEngine / PolicyEngine/microcosm-dynamics
Reserve trajectory state for balance-sheet primitives; death-basis rules on the exit transition
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1
- Forks
- 1
- Avg merge
- 1h 46m
- Merged PRs (30d)
- 28
Description
Design-stage reservation (cheap now, expensive later)
PolicyEngine/populace#320 + TheAxiomFoundation/axiom-rules-engine#76 move capital gains to a primitives-plus-rules architecture: populace carries asset-class positions and accrued-gain fractions; a realization model converts accrued to realized; the rules engine computes each country's legal gain concept. The static v1 (cross-sectional realization hazard calibrated to admin totals) ships independently of this repo — but its natural permanent home is a dynamics transition process, and two hooks are worth reserving in the trajectory design now:
-
Balance-sheet state on the trajectory. Asset positions and accrued gains are persistent state evolving under per-period transitions (returns, saving, realization). Realization is intrinsically intertemporal — accrual accumulates across periods and the behavioral margin is timing (lock-in, rate anticipation, retirement) — so in the trajectory design it is a per-period hazard over carried state, not a cross-sectional draw. Holding-period-dependent rules (US long/short; any taper/indexation regime) become computable natively from acquisition-to-disposal spans instead of an assumed share.
-
Death is a capital-gains event in both tax systems. US basis step-up (IRC §1014) and UK death uplift both fire at mortality — i.e., at this repo's exit transition. The exit event should be able to carry balance-sheet state and trigger the country's death-basis rule (an Axiom formula), which also opens the estate-tax interaction. This is the concrete coupling point between the mortality process and the tax system.
No implementation asked here yet — just that the trajectory state schema and the exit-transition interface don't foreclose (1) and (2). The capacity-ladder pattern applies: static hazard v1 (populace) → dynamics-native transition process v2, both refereed by the same pre-registration machinery this repo already uses.
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
Start by reading the trajectory state schema and exit-transition interface mentioned in the issue, then review how the pre-registration machinery frames the static hazard v1. Check whether the design can carry balance-sheet state and expose a death-basis hook without implementing either model. Done means the schema and transition interface explicitly preserve these future extension points.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100