PolicyEngine / PolicyEngine/microcosm-dynamics

Reserve trajectory state for balance-sheet primitives; death-basis rules on the exit transition

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

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:

  1. 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.

  2. 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

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

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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.