Benhabib, Bisin, and Luo (2019): Formalized-tier ballpark entry

.github/ISSUE_TEMPLATE/wanted-ballpark.yml

@@ -0,0 +1,116 @@
+name: Wanted Ballpark Paper
+description: Propose a paper for inclusion in the ballpark catalog.
+title: "[Wanted] <citekey>: <short paper title>"
+labels: ["wanted-ballpark"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for proposing a paper for the ballpark! This issue creates the **Wanted** state — the pre-tier catalog entry that precedes a directory. Once a contributor claims the paper and opens a PR, it enters the **Draft** tier.
+
+        Please review [CONTRIBUTING.md → Before you start](../../blob/master/CONTRIBUTING.md#before-you-start) and make sure the paper meets the eligibility rules (in particular, **≥ 3 Google Scholar citations**).
+
+  - type: input
+    id: citation
+    attributes:
+      label: Full citation
+      description: Include authors, year, title, journal, volume(issue), pages.
+      placeholder: "Benhabib, J., Bisin, A., & Luo, M. (2019). Wealth distribution and social mobility in the US: A quantitative approach. American Economic Review, 109(5), 1623–1647."
+    validations:
+      required: true
+
+  - type: input
+    id: doi
+    attributes:
+      label: DOI or permanent URL
+      placeholder: "10.1257/aer.20151684"
+    validations:
+      required: true
+
+  - type: input
+    id: citekey
+    attributes:
+      label: Proposed citekey
+      description: Used as the directory name under `models/We-Would-Like-In-Econ-ARK/` or `empirical/`. Match the key in your reference manager (e.g. Zotero) if you have one.
+      placeholder: "Benhabib_et_al_2019"
+    validations:
+      required: true
+
+  - type: input
+    id: citations
+    attributes:
+      label: Google Scholar citation count (today)
+      description: Must be ≥ 3 per the eligibility rule. Paste the current number from the paper's Google Scholar page.
+      placeholder: "127"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: track
+    attributes:
+      label: Track
+      description: Structural models go under `models/`; strong empirical evidence that begs for a model goes under `empirical/`.
+      options:
+        - models
+        - empirical
+    validations:
+      required: true
+
+  - type: dropdown
+    id: topic
+    attributes:
+      label: Primary Econ-ARK topic
+      description: Pick the best single match. Additional topics can be listed in the item's frontmatter later.
+      options:
+        - HA-macro
+        - lifecycle
+        - wealth-distribution
+        - monetary
+        - fiscal-policy
+        - optimal-taxation
+        - housing
+        - labor
+        - business-cycles
+        - computational-methods
+        - open-economy
+        - liquidity-trap
+        - demographics
+        - financial-crisis
+        - inequality
+    validations:
+      required: true
+
+  - type: textarea
+    id: pitch
+    attributes:
+      label: Why in-ballpark (≈ 3 sentences)
+      description: Why should Econ-ARK care about this paper? What does it uniquely contribute to the ecosystem's agenda? Keep it short.
+      placeholder: "Canonical example of heterogeneous-returns driving the wealth tail — a headline result in modern HA macro..."
+    validations:
+      required: true
+
+  - type: input
+    id: difficulty
+    attributes:
+      label: Difficulty estimate (optional)
+      description: "One of: good-first-ballpark, stretch, research-grade. Used for course-project scoping."
+      placeholder: "stretch"
+
+  - type: input
+    id: claim
+    attributes:
+      label: Claim (optional)
+      description: If you intend to draft this ballpark entry yourself, mention your name/GitHub handle here. Otherwise leave blank — the issue is a standing invitation.
+      placeholder: "@<your-github-handle>"
+
+  - type: checkboxes
+    id: eligibility
+    attributes:
+      label: Eligibility confirmation
+      options:
+        - label: "Paper has ≥ 3 Google Scholar citations."
+          required: true
+        - label: "Paper is not already in `models/We-Would-Like-In-Econ-ARK/` or `empirical/`."
+          required: true
+        - label: "I have read [CONTRIBUTING.md → Before you start](../../blob/master/CONTRIBUTING.md#before-you-start)."
+          required: true

.gitignore

@@ -70,6 +70,10 @@ docs/_build/
 # MyST Markdown build output
 _build/
 
+# Paper source materials (PDF + LaTeX from MathPix) - do not commit (copyright)
+# Students create source/ inside each paper folder, e.g. models/.../{BALLPARK}/source/
+**/source/**
+
 # PyBuilder
 target/
 

README.md

@@ -28,6 +28,8 @@ As an example of the kinds of things we are looking for, see the [paper](https:/
 
 The papers listed herein are a small subset of the ones that we would welcome into the Econ-ARK. If you want to work on a paper that is not listed here, post an "issue" on the repo asking (and providing a link and bibliographical reference for the paper in question). If it is likely to prove interesting to our audience, we are very likely to encourage you to replicate it.
 
+For what a ballpark item should contain and how to submit one, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## Environment Setup
 
 This repo uses [uv](https://docs.astral.sh/uv/) for dependency management and keeps per-platform environments in directories named `.venv-<os>-<arch>` (matching the pattern used in `HAFiscal-Latest`). Install uv first (`brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh | sh`).

llms.txt

@@ -0,0 +1,58 @@
+# Econ-ARK Ballpark
+
+> A curated catalog of economics papers we would welcome into the Econ-ARK
+> ecosystem as replications ([REMARK](https://github.com/econ-ark/REMARK))
+> or demonstrations ([DemARK](https://github.com/econ-ark/DemARK)). Each
+> entry provides a paper's recursive-problem formulation in explicit form,
+> and where available a modular dynamic-programming (dolo-plus) draft
+> suitable for AI-assisted formalization.
+
+Target audience: graduate students, course instructors, structural-macro
+researchers, and agent systems doing scholarly retrieval. Ballpark entries
+are designed to be the natural starting point for turning a published paper
+into a reproducible, citable Econ-ARK contribution.
+
+## Workflow documents
+
+- [CONTRIBUTING.md](CONTRIBUTING.md): Canonical structure for a ballpark entry — exposition, formalization, and asset layers, plus machine-readable metadata.
+- [README.md](README.md): Project framing and the promotion path from ballpark → REMARK / DemARK → HARK tool.
+- [models.md](models.md): Pointer into the catalog.
+
+## Items
+
+Each item lives at `models/We-Would-Like-In-Econ-ARK/<citekey>/index.md`. Tiers (see [CONTRIBUTING.md](CONTRIBUTING.md#ballpark-tiers)):
+- **Draft** — paper claimed, minimal cataloging.
+- **Primer** — four-notebook exposition layer + explicit recursive model statement.
+- **Formalized** — bellman excerpt, dolo-plus YAML draft, verification, `AGENTS.md`. (Ready for a coder to promote to REMARK/DemARK.)
+
+Most items are currently Draft (legacy slideware format pre-dates the tier system). Refactoring a Draft item to Primer is an explicitly welcome PR and is scoped for ≤2 weekly PhD-course assignments with AI assistance.
+
+- [Benhabib_et_al_2019](models/We-Would-Like-In-Econ-ARK/Benhabib_et_al_2019/): Lifecycle wealth distribution with heterogeneous returns and warm-glow bequests. Topic: wealth-distribution, lifecycle. Tier: Primer.
+- [AHLifeCycleExpenditure](models/We-Would-Like-In-Econ-ARK/AHLifeCycleExpenditure/): Lifecycle expenditure profiles. Topic: lifecycle. Tier: Draft.
+- [ARMonetaryPolicyHABC](models/We-Would-Like-In-Econ-ARK/ARMonetaryPolicyHABC/): Algan–Ragot heterogeneous-agent monetary policy with money in utility. Topic: HA-macro, monetary. Tier: Draft.
+- [clMonetary](models/We-Would-Like-In-Econ-ARK/clMonetary/): Monetary-policy model. Topic: monetary. Tier: Draft.
+- [Fujiwara_Teranishi](models/We-Would-Like-In-Econ-ARK/Fujiwara_Teranishi/): Monetary policy with heterogeneous agents. Topic: HA-macro, monetary. Tier: Draft.
+- [GKKOCWealthTax](models/We-Would-Like-In-Econ-ARK/GKKOCWealthTax/): Optimal wealth taxation with heterogeneous agents. Topic: optimal-taxation, wealth-distribution. Tier: Draft.
+- [GKNMonetaryPolicyHA](models/We-Would-Like-In-Econ-ARK/GKNMonetaryPolicyHA/): Gornemann–Kuester–Nakajima monetary policy with heterogeneous agents. Topic: HA-macro, monetary. Tier: Draft.
+- [Guerrieri_Lorenzoni2017](models/We-Would-Like-In-Econ-ARK/Guerrieri_Lorenzoni2017/): Credit crises, precautionary savings, and the liquidity trap. Topic: HA-macro, liquidity-trap. Tier: Draft.
+- [HKMOHousingChannelMP](models/We-Would-Like-In-Econ-ARK/HKMOHousingChannelMP/): Housing channel of monetary policy with heterogeneous agents. Topic: HA-macro, housing, monetary. Tier: Draft.
+- [HKSWealthDistribution](models/We-Would-Like-In-Econ-ARK/HKSWealthDistribution/): Hubmer–Krusell–Smith quantitative theory of the U.S. wealth distribution. Topic: wealth-distribution, HA-macro. Tier: Draft.
+- [KMVBoomBust](models/We-Would-Like-In-Econ-ARK/KMVBoomBust/): Boom-bust dynamics. Topic: HA-macro, business-cycles. Tier: Draft.
+- [Kumhof_et_al_2015](models/We-Would-Like-In-Econ-ARK/Kumhof_et_al_2015/): Inequality, leverage, and crises. Topic: inequality, financial-crisis. Tier: Draft.
+- [MK3TagTax](models/We-Would-Like-In-Econ-ARK/MK3TagTax/): Optimal tagged taxation. Topic: optimal-taxation. Tier: Draft.
+- [OpenHA](models/We-Would-Like-In-Econ-ARK/OpenHA/): Open-economy heterogeneous-agent model. Topic: HA-macro, open-economy. Tier: Draft.
+- [OptimalTaxHeight](models/We-Would-Like-In-Econ-ARK/OptimalTaxHeight/): Optimal taxation with height as a tag. Topic: optimal-taxation. Tier: Draft.
+- [OptimumDebt](models/We-Would-Like-In-Econ-ARK/OptimumDebt/): Aiyagari–McGrattan optimum quantity of public debt. Topic: HA-macro, fiscal-policy. Tier: Draft.
+- [PopAgingMPtransmission](models/We-Would-Like-In-Econ-ARK/PopAgingMPtransmission/): Population aging and monetary-policy transmission. Topic: demographics, monetary. Tier: Draft.
+- [Ravn_Sterk_2021](models/We-Would-Like-In-Econ-ARK/Ravn_Sterk_2021/): Macroeconomic fluctuations with heterogeneous agents. Topic: HA-macro. Tier: Draft.
+- [Reiter_2009](models/We-Would-Like-In-Econ-ARK/Reiter_2009/): Solving heterogeneous-agent models by projection and perturbation. Topic: computational-methods. Tier: Draft.
+- [SSJ_2021](models/We-Would-Like-In-Econ-ARK/SSJ_2021/): Sequence-space Jacobian methods for heterogeneous-agent models. Topic: HA-macro, computational-methods. Tier: Draft.
+- [TaxingWomen](models/We-Would-Like-In-Econ-ARK/TaxingWomen/): Guner–Kaygusuz–Ventura taxation and female labor supply. Topic: lifecycle, optimal-taxation, labor. Tier: Draft.
+
+## Already in Econ-ARK
+
+- [tools/Already-Partway-In-Econ-ARK](tools/Already-Partway-In-Econ-ARK/): Papers whose methods are partly implemented in HARK.
+
+## Optional
+
+- [models/We-Would-Like-In-Econ-ARK.ipynb](models/We-Would-Like-In-Econ-ARK.ipynb): Legacy notebook surveying housing-and-heterogeneity papers.

models/We-Would-Like-In-Econ-ARK.md

@@ -2,5 +2,21 @@
 
 In this directory are:
 
-1. The [Jupyter notebook](./We-Would-Like-In-Econ-ARK.ipynb) is a collection of a set of papers on housing and heterogeneity compiled by Shujaat Khan
-1. The [We-Would-Like-In-Econ-ARK](./We-Would-Like-In-Econ-ARK) directory contains, in each directory, unstructured information about a specific paper we would like to have in the ballpark
+1. The [Jupyter notebook](./We-Would-Like-In-Econ-ARK.ipynb) — a collection of papers on housing and heterogeneity compiled by Shujaat Khan.
+2. The [We-Would-Like-In-Econ-ARK](./We-Would-Like-In-Econ-ARK) directory — one subdirectory per paper (named by Zotero citekey).
+
+## What goes in each paper subdirectory
+
+See [CONTRIBUTING.md](../CONTRIBUTING.md) for the canonical structure (exposition, formalization, and asset layers) and the pre-merge checklist.
+
+The [Benhabib_et_al_2019](./We-Would-Like-In-Econ-ARK/Benhabib_et_al_2019/) subdirectory is the reference instance of the current structure:
+
+- `index.md` assembling four content notebooks
+- `<citekey>_intro.ipynb` (metadata + provenance)
+- `<citekey>_prior-literature.ipynb`
+- `<citekey>_summary.ipynb` (with an explicit "The Model" recursive formulation)
+- `<citekey>_subsequent-literature.ipynb`
+- Split bib files (`references.bib`, `self.bib`, `subsequent-literature.bib`)
+- Paper as `.pdf` plus optionally `.mmd` for AI ingestion
+
+Older items in this directory follow a legacy "slideware" pattern (a single summary notebook with figures scraped from the paper). Refactoring a legacy item to the canonical structure is an explicitly welcome PR.

models/We-Would-Like-In-Econ-ARK/Benhabib_et_al_2019/.gitignore

@@ -1 +1,7 @@
 _build/
+
+# MyST/Mathpix paper-conversion build artifacts (UUID-named)
+08a6e8af-7a69-44c4-8e23-91ed2e58d762/
+
+# Paper download archive
+Benhabib_et_al_2019.zip

models/We-Would-Like-In-Econ-ARK/Benhabib_et_al_2019/AGENTS.md

@@ -0,0 +1,50 @@
+# Ballpark entry: Benhabib, Bisin, and Luo (2019)
+
+> Structured brief for coding agents (Claude Code, Cursor, etc.). Human-facing content lives in [`index.md`](index.md).
+
+## Paper
+
+- **Citation:** Benhabib, Bisin, and Luo (2019), "Wealth Distribution and Social Mobility in the US: A Quantitative Approach," *American Economic Review* 109(5), 1623–1647.
+- **DOI:** [10.1257/aer.20151684](https://doi.org/10.1257/aer.20151684)
+- **Core model:** Finite-lifetime consumption-savings with warm-glow bequest at $T$; no within-life shocks; heterogeneous $(r, w)$ drawn once per dynasty.
+- **Why in-ballpark:** Canonical example of heterogeneous-returns driving the wealth tail — a headline result in modern HA macro.
+
+## If a user asks to work on this item
+
+1. **Read first:** [`bellman-excerpt.md`](bellman-excerpt.md) — the modular-DDSL Bellman statement with comprehensive symbol table, perch decomposition, stage operators, and EGM channel. This is the authoritative formalization input; a YAML-drafting agent should read this before touching the notebooks.
+2. **For economic context beyond the formalization:** `Benhabib_et_al_2019_summary.ipynb` → "The Model".
+3. **Paper source for AI ingestion:** `Benhabib_et_al_2019.mmd` (Pandoc-converted). Prefer this over `Benhabib_et_al_2019.pdf`.
+
+## Formalization status
+
+- Explicit recursive formulation: **present** in `_summary.ipynb`.
+- `bellman-excerpt.md`: **committed**. Within-lifetime stage problem under the online-Appendix-A.1 model (= the authors' actual numerical solution; see Open Issue #10). Paper-faithful: chain-rule factor on `dV[<]`, β-on-bequest convention, and consumption-bound constraint all reconciled with the appendix. Symbol table carries paper-calibrated values (Tables 1, 4).
+- `dolo-plus-draft.yaml`: **committed**. Canonical stage structure under the appendix-A.1 model; `calibration_family` block carries paper Table 1 (10×6 earnings) and Table 4 values; `population.Pi_r` carries the full 5×5 transition matrix from online Appendix C.1. Three SPECULATIVE blocks (`terminal:`, `calibration_family:`, per-age override mechanism) flagged inline as `# unresolved:` (definitively confirmed UNRESOLVED at the dolo-plus spec level by matsya 2026-04-27).
+- `dynasty-excerpt.md`: **committed**. Dynasty-level / cross-generational composition layer — formalizes the lifetime map $g(\cdot;\tau,r)$, the independent intergenerational Markov chains $\Pi_\tau \otimes \Pi_r$, and the paper's Proposition on stationary distributions / Pareto tails. Sibling of `bellman-excerpt.md`.
+- `dolo-plus-dynasty.yaml`: **committed**. Dolo-plus YAML for the dynasty composition; references `dolo-plus-draft.yaml` for the within-life family. Cross-generational composition syntax is SPECULATIVE throughout (no canonical idiom in dolo-plus per matsya). Reproduces the $\Pi_r$ matrix for self-containment; $\Pi_\tau$ matrix is flagged as UNRESOLVED pending separate fetch from Chetty et al. data tables or BBL replication package.
+- `verification.md`: **committed**. Compares the within-life YAML against the paper (§I + online appendix A.1); paper's description is sufficient; remaining gaps are dolo-plus spec gaps, not paper gaps.
+- `matsya-session.txt`: **committed** (`topics2026-benhabib-demo`, 6 turns).
+
+## Known model features requiring attention in a formalization pass
+
+- **Perch-ready notation convention.** The recursive problem in `_summary.ipynb` → "The Model" → "Recursive Formulation" uses an explicit, perch-ready convention: $a_t$ = beginning-of-period wealth; $m_t \coloneqq (1+r)a_t + w_t$ = cash-on-hand at the decision perch; $a_{t+1} = m_t - c_t$ = savings identity. The paper's own compact statement ($a' = (1+r)a - c + w$ with $0 \le c \le a$) carried an `a`-double-role ambiguity; the notebook's current rewrite resolves it. **A formalizer should build on the notebook's convention, not re-derive from the paper.**
+- **Terminal period under-specified.** Warm-glow $e(a_T) = A a_T^{1-\mu} / (1-\mu)$ is stated, but the budget at $T$ is left implicit (is there a $w_T$? does $e$ apply to savings or to post-return assets?). A complete formalization must resolve this explicitly.
+- **Dynasty-level heterogeneity** is the paper's distinguishing feature: $(r, w)$ fixed within a life, stochastic across generations. A single-agent lifecycle YAML is not sufficient to reproduce the paper's tail-thickness result — you need a dynasty-level wrapper or a parameterized family indexed by $(r, w)$ draws.
+- **Age profile $w_t$** should not flatten to a scalar `w` in the YAML. The period template needs age-varying wage overrides.
+- **Stochastic return process.** $r^n$ is a **finite 5-state Markov chain** in the paper's baseline, with off-diagonal probabilities that decay geometrically away from the diagonal (except the last row, which uses constant off-diagonals); see paper §I and footnote 13. A simple AR(1) or lognormal shock does **not** capture the paper's specification — the YAML's `exogenous` block must accommodate the Markov-chain structure. See `_summary.ipynb` → "The Model" → "Stochastic Structure" for the full specification.
+- **Wealth-dependent return (Section IIID extension).** The paper considers an optional extension in which the Markov state space of $r^n$ depends on the agent's initial wealth $a_1$. Improves fit; a complete formalization should note this as an alternative stage structure rather than silently baking in the independence assumption.
+
+## Common next tasks (grounded)
+
+1. ~~**Produce the formalization layer** (`bellman-excerpt.md`, `dolo-plus-draft.yaml`, `verification.md`, `matsya-session.txt`) from the recursive formulation in `_summary.ipynb`, via the Matsya iteration loop described in the repo-root `CONTRIBUTING.md`.~~ ✅ Done (2026-04-19, refined 2026-04-27).
+2. ~~**Add the terminal-period stage** to the YAML (warm-glow closure).~~ ✅ Done (boundary wiring + $\tilde A = A/\beta$ absorption per Open Issue #9).
+3. ~~**Formalize the dynasty wrapper** — type-indexed family over $(r, w)$ draws.~~ ✅ Done 2026-04-27 (`dynasty-excerpt.md` + `dolo-plus-dynasty.yaml`).
+4. **Convert figures to alt-text-annotated MyST directives** for accessibility and LLM legibility.
+5. **Section IIID variant**: separate dynasty pair for the wealth-dependent $r$ extension. Stage structure unchanged; the $r$-chain becomes state-conditioned on $a$. Currently flagged as out-of-scope in both `bellman-excerpt.md` (Open Issue #6) and the new dynasty pair.
+6. **$\Pi_\tau$ matrix transcription**: the 10×10 chain is described in online Appendix B.2 only by procedure (collapse Chetty et al. 2014's 100×100); reconstruction requires either Chetty et al.'s `online_data_tables.xls` or the BBL replication package at `https://doi.org/10.3886/E113112V1`. Mechanical fetch; closes the only remaining data gap (dynasty-layer, doesn't block the within-life formalization).
+
+## Workflow reminders
+
+- **Matsya session:** use the course convention `topics2026-<slug>` for new work on this item.
+- **Paper verification:** Matsya output must be checked against the paper PDF (or `.mmd`), not only against the ballpark `_summary.ipynb` — the notebook is a summary with known simplifications.
+- **When flagging workarounds in YAML:** use inline `# workaround:` or `# unresolved:` comments rather than silently fudging non-canonical syntax.