Power-law PF-decay tails for buffer-stock consumption functions: correct tail law, theory module, diagnostics, and a certified grid-extent criterion

[llorracc]

What this PR does

Buffer-stock consumption functions approach their perfect-foresight asymptote
c → MPCmin·(m + hNrm) as a power law in x = m + h, not exponentially: the gap
g(x) = MPCmin·(m+h) − c(m) decays like x^(−min(1, q*)), where q* solves
E[ψ^(1+q)] = (R/Γ)·Þ_Γ^q. (A prudent consumer always collects at least today's
Arrow–Pratt premium, so the gap can never decay faster than 1/x — exponential tails
are asymptotically impossible.) HARK's existing decay_extrap uses an exponential
form; above the top gridpoint this systematically mis-extrapolates, and in the 2D
aggregate-shock solvers the per-state cFunc slices had no decay limits at all
(naive-linear extrapolation). This PR fixes the tail law end to end, all strictly
opt-in:

1. LinearInterp(decay_extrap_form='powerlaw') — the power-law tail, level- and
   slope-matched at the top knot exactly like the exponential form; default remains
   'exp' (byte-for-byte unchanged).
2. Keyword-only decay_extrap_Q — attach the tail with an EXPLICIT exponent
   (theory value min(1, q*)) instead of the fitted 2-knot estimator; also rescues
   the B ≤ 0 fallback cases where fitted decay had to be disabled.
3. Opt-in PF-asymptote machinery for ConsAggShockModel — pf_mpc_min,
   pf_human_wealth_markov, and make_cFunc_slice attach per-Markov-state decay
   toward MPCmin·(m + hNrm[i]), with a Carroll–Kimball concavity guard. With the
   new solver arguments at their None defaults, behavior is byte-for-byte unchanged.
4. HARK.ConsumptionSaving.pf_decay — the theory module (numpy-only, no solve):
   q*, realized exponent min(1, q*), h = 1/(R/Γ − 1) (excludes current income —
   the module documents and avoids HARK's two-convention hNrm trap), closed-form
   tail amplitude B_ψ (at q* > 1), near-resonance multiplier, the dual (Kesten)
   wealth-tail root ζ*, GIC/RIC/FHWC flags; refuses cleanly (nan/None + filterable
   warnings) outside the theorem's hypotheses.
5. powerlaw_tail_diagnostic — a cheap post-solve wrong-exponent detector
   (CONFIRMED / PRE_ASYMPTOTIC / INCONSISTENT / UNMEASURABLE) for grid-quality audits.
6. A certified grid-extent criterion — rel_gap_at + aXtraMax_from_tail_tol:
   two routes to the m where the relative gap reaches a chosen tolerance — at
   q* > 1 a closed-form GUARANTEE x_top = sqrt(B_ψ/(MPCmin·tol)) (the compensated
   gap climbs monotonically to B_ψ, so B_ψ/x bounds the gap from above); at
   q* ≤ 1 a measured-reference inversion of gap/c ∝ x^(−(1+q)). Beyond that top,
   ANY level-matched monotone below-line tail (in particular the power-law form) is
   within gap(m_top) of the truth pointwise (Carroll–Kimball concavity), so the grid
   may certifiably stop there; the ex-post check is one rel_gap_at call. Measured on
   the anchor calibrations: HS 0.40× tol, College-top 0.98×, GIC-cap (closed form)
   0.69×.
7. tools/update_theorem_refs.py — the code cites its theorem program via pinned
   THEOREM-REF[repo @ sha :: file :: section :: label] comment tags; the tool
   verifies/re-pins them (on public CI without the private theorem repo it degrades
   gracefully to syntax checking).
8. DecayTailInterp — the decay tail as a COMPOSABLE wrapper over ANY 1D
   interpolant (the decoupling of tail law from in-grid representation): at/below a
   handoff x_cut it delegates to the wrapped body; above, it applies the same tail
   family, guards, and stable evaluation as LinearInterp's built-in machinery,
   sourced from the body's level/slope at the cut — byte-identical to the baked-in
   tails over a bare linear body (unit-gated), and it composes with CubicInterp
   (which has only the legacy exponential decay), econforge interpolants, or any
   bare callable (explicit-exponent mode needs no derivative). Supports off-knot
   cuts (certified truncation of a solved cFunc). LEVEL CONTINUITY AT THE CUT IS
   AN INVARIANT (owner ruling 2026-07-11): every attachable tail is level-matched
   — there is deliberately no amplitude-override hook, and make_cFunc_slice's
   former jump-permitting ('amplitude', B) mode was removed in the same ruling.
   Its 'exp' form is deprecated at birth (warns) while LinearInterp's legacy
   default stays untouched. Explicit-exponent tails default to the C1 TWO-TERM
   attachment (decay_extrap_terms=2; one-term opt-in) — level- AND
   slope-matched with the theory exponent leading — SPECIFICALLY to guard
   against Jacobian problems in SSJ-type (sequence-space Jacobian) approaches,
   where policy derivatives are primitive inputs and the one-term kink makes
   them discontinuous at the attachment point.

What this PR deliberately does NOT do

An importance-weighted gridpoint-PLACEMENT scheme built on the same theory was
prototyped under a pre-registered validation program with hard accept/kill gates. It
failed its gates (its near-constraint Euler accuracy lost 2× to
make_grid_exp_mult's kink-stacking on one anchor calibration, despite winning the
distribution/moment metrics broadly) and was dropped per the pre-registered kill
provision. Only the components that passed everywhere ship here (the tail law and the
extent criterion). This is why there is no grid_placement module in this PR.

Guarantees

• Everything is opt-in; with no new arguments used, HARK is byte-for-byte unchanged
  (the AggShock machinery's defaults keep the prior bare-LinearInterp behavior;
  adversarially re-verified: additive-only commits, no runtime callers of the new
  functions).
• Test suites: 249 passed (test_pf_decay 66, test_AggShock_pf_decay,
  test_interpolation, test_theorem_refs). THEOREM-REF tags 44/44 resolve at their pins.
• No new dependencies (pf_decay is numpy-only).

Commits

• 208f78f1 opt-in PF-asymptote decay machinery (AggShock)
• fed6f368 power-law decay form on LinearInterp
• 6c4af317 power-law as the AggShock machinery's decay default + tests
• 4909c5c8 pf_decay theory module + tests
• d8afd272 explicit-exponent decay_extrap_Q
• 30606d81 theory-informed tail policy threading (decay_theory/decay_Q)
• b04e70d6 powerlaw_tail_diagnostic
• d8c0d277 THEOREM-REF updater tool + tag set
• e81ff286 root-finder hardening near the r = g knife-edge
• 64e83bfa certified grid-extent criterion
• 5a167515 extent-criterion hardening per adversarial review (closed-form q*>1
  route; empty-input and bad-safety fail-closed fixes; corrected q_eff rationale)
• 4e46ee73 qstar_probe (the operator eigen-probe: numerical q* from the model's
  own one-period step — for model variants with no closed-form eigen-equation;
  validated to 5.6e-6..5.0e-5 vs the analytic roots) + mNrm_stable_points
  (classical targets + the mortality-adjusted R→LivPrb·R twins that exist in the
  pure-GIC case, with end-of-period-asset images)
• 45ff3ab8 aXtraMax_from_wealth_mass + dual_root(..., LivPrb): the grid top as
  a measured stationary wealth quantile with the mortality-augmented dual root ζ_L as
  existence test and patience dial; certified protocol reproduces dense-truth
  quantiles to 0.1–3.4% (theorem-repo battery 11/11)
• e126dd65 DecayTailInterp: the decay tail as a composable wrapper over any 1D
  interpolant (the owner's decoupling principle) — byte-identical to the baked-in
  LinearInterp tails over a linear body, composes with cubic/econforge/bare-callable
  bodies, off-knot certified truncation; 'exp' deprecated at birth in the new
  class; adversarially refuted pre-commit (one real ZeroDivisionError boundary bug
  found and fixed); theorem-repo battery verify_decaytail_checks.py 14/14
• 8e93c68e level continuity at the top knot made an INVARIANT of the decay
  machinery (owner ruling 2026-07-11): DecayTailInterp's amplitude override and
  make_cFunc_slice's jump-permitting ('amplitude', B) mode removed (tuple form
  raises, pointing at the level-matched decay_Q=1.0; B_ψ keeps its diagnostic
  amplitude-ratio log); life-cycle and infinite-horizon tails use the SAME
  level-matched form family (exponent min(1, q*) vs exactly 1 per age)
• d6af964c the C1 TWO-TERM attachment as the explicit-exponent DEFAULT
  (decay_extrap_terms=2|1, threaded as decay_terms; owner ruling 2026-07-11,
  motivation = SSJ-type Jacobian robustness): gap = A·z^(−Q) + A2·z^(−(Q+1))
  with F11 closed forms, level- AND slope-matched (C1 residual ~2e-16 at the
  theorem anchors), exact collapse stored as one-term (byte-identical), warned
  one-term fallback at non-finite or theory-infeasible fitted rates
  (adversarially hardened; second refuter pass); theorem-repo battery 24/24,
  two-term accuracy 2.3e-4 at the HS handoff
• b6285f0a decay_extrap_form='moderation_tail' on DecayTailInterp (+ required
  x_min): guard-free C1 tail in Method-of-Moderation coordinates (tail-only; NOT
  the full Method of Moderation) — level- and slope-matched at ANY cut including the
  Q_fit >= Q+1 region where the two-term form must fall back; bounds built in;
  same asymptotic power law gap ~ (x - x_min)^-Q; exact collapse to the pinned
  chi-line at chip_cut == Q; moderation-premise violations raise. Two-term
  guard-trip warnings (LinearInterp + DecayTailInterp) now name cause and remedies,
  and print the exact steepness decomposition Q_fit = s_mu*(1 + hEx/mEx) with the
  guard-safe boundary mEx > Q*hEx when x_min is supplied. 11 new tests
  (suite 166/166); cross-verified at machine precision (<= 4.4e-16) against the
  downstream Method-of-Moderation implementation of the same form
• a5c70684 CHANGELOG: the moderation_tail family + enriched guard diagnosis

Related planned work (2026-07-12; neither item changes this PR's current content)

• Primitives-based aXtraMax default — a separate, independent PR (no
  required merge order in either direction). Buffer-stock asset-grid tops
  will default to human-wealth scale (max(20, hNrm), with a documented
  fallback of 1000 when FHWC fails and hNrm is infinite; explicit user
  values always win). Motivation: the local decay exponent measured at any
  grid top equals the gap's intrinsic log-slope times a coordinate
  amplification factor 1 + hEx/mEx, so conventional tops (aXtraMax = 20)
  sit deep in the pre-asymptotic regime and slopes fitted there are
  amplified artifacts — including the fitted rates that trip this PR's
  two-term guard. Complementary to this PR's aXtraMax_from_tail_tol: that
  tool certifies where a grid may STOP (tolerance-based); the default sets
  where the top must REACH for top-knot slopes and fitted attachments to be
  meaningful. Shared surface is limited to the CHANGELOG; the integration
  test (guard no longer trips at the new default) is import-guarded and
  activates only when both PRs are merged, in either order.
• A third tail family for DecayTailInterp
  (decay_extrap_form='moderation_tail'), riding this branch. The
  two-term C1 attachment is guarded by Q_fit < Q+1, and at human-wealth-
  dominated grid tops the guard trips generically, falling back to the
  C0 one-term tail (an MPC kink of order (Q_fit − Q)·G/x_cut at the
  attachment point). The planned family attaches in Method-of-Moderation
  coordinates (tail-only — NOT the full Method of Moderation solution
  representation): level- and slope-matched at ANY cut with no guard,
  bounded between the pessimist and optimist lines by construction, and
  asymptotically the same power law x^(−Q). LANDED on this branch as
  b6285f0a + a5c70684 (see Commits); if it is ever split into its own
  PR instead, that PR requires this one and must merge strictly after it.

🤖 Generated with Claude Code

[alanlujan91]

Chris - I went through this systematically: all four production files, the test suite, and the ref-tooling. The engineering discipline is genuinely impressive in places - the byte-exact backward-compatibility pins, the eager construction-time option validation (a typo'd decay_extrap_form can never silently mean None), and the centralized warning pattern in ergodic_grid_report are better than most of what's in HARK today. But the review surfaced one outright bug that blocks the AggShock half, several silent-failure paths, and a few structural issues. Ranked, with details in inline comments:

Blocking

1. The AggShock power-law tail's intercept is expressed in the wrong coordinate - exactly zero on every default calibration, so no existing test can see it, and it contaminates the guard meant to catch wrong references (inline at ConsAggShockModel.py).
2. time_inv_ gains ten names unconditionally, so out-of-tree AggShockConsumerType subclasses that don't route through your __init__ now hit KeyError on solve (inline).
3. The AggShock theory branch uses decay_theory.q without checking .valid, while the IndShock path raises in the same situation (inline).
4. The tail diagnostic's one-sided INCONSISTENT band is wrong when q* < 1 (inline at pf_decay.py).
5. The kappabar bottom tail can silently fail to attach all the way to convergence, with no signal (inline at ConsIndShockModel.py).
6. The grid-sizing functions - your own "operative quality rule" - return bare nan on five distinct failure modes, and the tail_tol clamp silently certifies a looser target than the user requested (inline).

Important
7. The solver swap living in pre_solve means the new options are silently inert on every subclass that overrides pre_solve without super() - roughly a dozen in-tree - while those subclasses still accept and echo the parameters. Same root cause as the Jacobian/SSJ path concern. Plus the auto-computed exponent uses t=0 primitives with no time-variation check on lifecycle calibrations (inline).
8. Test-calibration gap: every q* < 1 calibration in the suite gets there via patience with sigma_psi^2 = 0.003; there is no solved-model test of variance-driven q* < 1 (E[psi^2] > R*PhiTilde), which is the regime where the verdict band and grid-fit behavior differ qualitatively. And no AggShock test runs with IncUnemp > 0 - the single test that would have caught blocking item 1 (inline).
9. The THEOREM-REF tooling is out of sync with its own tags: running tools/update_theorem_refs.py --check on this branch yields 35 of 61 tags MALFORMED (5-field tags against a max-4 grammar), so test_check_without_theorem_repo_degrades_gracefully should be failing on this branch as shipped. The tool's own defaults also name HAFiscal-Latest while every tag says BufferStockTheory-Latest (inline).
10. .agents/prompts_local/... is an AI work-order document with machine-specific paths and shouldn't ship in a library's history (inline).

Smaller, cheap fixes: pf_mpc_min warns on RIC violation but returns a non-positive MPCmin that make_cFunc_slice never refuses (needs an explicit if not (MPCmin > 0): return LinearInterp(...)); the amplitude-ratio diagnostic goes through logging.info, which is invisible under Python's default logging config, contradicting its own "visible in production logs" docstring (ConsAggShockModel.py:508); none of the five new warnings.warn calls pass stacklevel=, so they all report HARK-internal lines; tol = 1e-8 * max(1, |c_top|) gates level_diff, a quantity that legitimately vanishes on well-extended grids, silently reverting to naive-linear extrapolation exactly when the user sizes their grid correctly - this wants a relative criterion; and GATE_HS_TWO_ROLES_TOP was lowered on the CI platform itself without a cross-platform measurement motivating it.

Two design questions rather than findings: whether HARK is the right home for ~60 citations resolvable only against a private repo (public CI validates syntax but never resolution, so rot is invisible to every contributor without your checkout); and whether the AggShock option surface - MPCmin/hNrm as agent parameters colliding with ConsumerSolution field names that carry the other h-convention - should be reworked before it hardens into API.

Several of these are one-line fixes, and the blocking item has a clean per-slice fix (pass hNrm_i + BoroCnstNat_vec[n] inside the slice loop). Happy to go through any of it on a call.

[alanlujan91]

Blocking: this slice is built in the shifted coordinate x = m - BoroCnstNat (undone at evaluation by VariableLowerBoundFunc2D), but make_cFunc_slice sets intercept_limit = MPCmin * hNrm, so the attached tail decays toward MPCmin*(m - BoroCnstNat + hNrm) instead of the PF asymptote MPCmin*(m + hNrm). The correct intercept in this coordinate is MPCmin*(hNrm + BoroCnstNat_vec[j]).

Why nothing catches it: with HARK's default IncUnemp = 0 the worst transitory draw is zero, so aNrmMin collapses to 0 and BoroCnstNat_vec is identically zero - the bug is exactly zero on every default calibration and every test built from one. With unemployment insurance on (IncUnemp > 0), aNrmMin < 0 and the tail's PF line sits too high by MPCmin*|aNrmMin| across the whole extrapolated region. Worse, the guard is contaminated too: level_diff is overstated, so the Carroll-Kimball raise under-fires and healthy over-fires, and Q_fit is biased in both factors - the check meant to catch a wrong MPCmin/hNrm reference is built on the wrong reference.

In solve_ConsAggMarkov a scalar intercept computed outside the slice loop can't be right at all (BoroCnstNat varies within the loop); the fix has to move inside: pass hNrm_i + BoroCnstNat_vec[n] per slice. A regression test at IncUnemp > 0 asserting the extrapolated cFunc approaches MPCmin*(m + hNrm) in m-space would have caught this and should accompany the fix.

[alanlujan91]

Backward-compat break: solve_one_cycle builds its solve dict via a hard agent.__dict__[parameter] subscript over time_inv, so any out-of-tree AggShockConsumerType subclass whose __init__ doesn't route through yours now raises KeyError: 'MPCmin' on solve. The in-repo __init__ guard only covers instances that go through it. This contradicts the byte-for-byte-unchanged framing for anything outside the HARK tree (REMARKs, DemARKs, user code). Consider defaulting these attributes at class level or guarding their inclusion.

[alanlujan91]

This branch checks np.isfinite(decay_theory.q) but never decay_theory.valid. Per pf_decay's own docs, a GIC-violated calibration reports valid=False with a finite (E)-root that is explicitly outside the theorem's scope - and this code will use it as the tail exponent for the whole solve. The IndShock path (_setup_decay_extrap) raises in exactly this situation; the asymmetry looks unintentional. Suggest gating on .valid here the same way, or re-emitting the recorded condition warnings once per slice build. (The healthy-case-only test coverage in test_AggShock_pf_decay.py means a GIC-violated decay_theory fed to this path is currently untested.)

[alanlujan91]

The one-sided verdict band conflates two different ceilings. Prop A0 forbids a gap fading faster than 1/x, i.e. local exponents above 1. But the INCONSISTENT branch triggers on any local exponent steeper than min(1, q*) - and when q* < 1, the region (q*, 1] is not forbidden by A0 and is exactly where a true solution's local exponent sits below the floor-to-tail crossover (the 1/x forced mode dominates until the suppressed x^{-q*} mode's amplitude wins). In my own experiments a correct solve in that regime shows local exponents near 1 over the entire practical range - which this band would flag INCONSISTENT ("broken grid / wrong reference / non-converged") on a healthy solution. The claim "migration toward min(1, q*) only ever comes from BELOW" holds for the patience-driven q* < 1 calibrations in your test suite (HS-type, where I can confirm the local exponent sits below q* and the diagnostic verdicts are correct), but not in the variance-driven regime. Suggest: make the steep side of the band conditional on q* >= 1 (where it genuinely coincides with A0), or downgrade steep-side hits to PRE_ASYMPTOTIC when q* < 1 with a note about the crossover scale.

[alanlujan91]

Silent no-op: try_make deliberately never raises (right call for transient iterates), but this consumer has no else branch, no counter, and writes nothing to the solution recording whether the tail attached. If the corridor/exposure gate keeps failing through convergence - e.g. the grid bottom is too coarse, exactly the condition aXtraMin_from_tail_tol exists to fix - the final solution silently uses the plain EGM secant, and a user who requested decay_extrap_form_lower='kappabar' can only discover it via isinstance. The coarse ce_psi_regime gate one level up warns properly (ConstraintEndRegimeWarning), so the pattern exists; this finer gate just doesn't use it. Suggest tracking attachment on the final solve and warning (or exposing a bilt-style field) when the requested tail never took effect.

[alanlujan91]

Two silent paths in the module's own "operative ex-post quality rule": (1) five distinct failure modes (non-finite/non-positive inputs) all collapse to a bare float('nan') - unlike qstar_root/dual_root, which return (value, reason). These functions feed user grid construction directly, so the nan surfaces far downstream with an error that doesn't point back here. Suggest the (value, reason) convention or a warning on the failure branch. (2) The tail_tol clamp to the 1e-6 certifiable floor is well-motivated but fires silently: a user requesting a grid certified to 1e-10 receives the materially smaller 1e-6 grid top, labeled as certified, with no signal they were downgraded. One PFDecayGridWarning when the clamp changes the value fixes it.

[alanlujan91]

Two issues rooted in the swap living in pre_solve: (1) every subclass that overrides pre_solve without calling super() inherits the three decay_extrap_* parameters via the defaults dict, accepts them in assign_parameters, echoes them in describe_parameters - and does nothing. The raise guard fires only for subclasses that inherit pre_solve, i.e. exactly the ones that already work. Roughly a dozen in-tree types are affected; the options are silently inert there. (2) The auto-computed exponent uses t=0 primitives, as the docstring notes, but there's no runtime check for time-varying Rfree/PermGroFac/LivPrb/shock processes - a lifecycle user gets a single age-0 exponent baked into every period's Euler recursion with no warning. Suggest moving the swap (or at least a validity check) into the solver-construction path, and warning when auto-computing on a calibration with time-varying primitives.

[alanlujan91]

Calibration-space gap: every q* < 1 calibration in the suite (HS here, CTOP/CCAP in test_pf_decay.py) reaches it via patience, with sigma_psi^2 capped at 0.003 throughout; the one large-Var(psi) distribution in the suite is used only for bottom-regime classification. There is no solved-model test of variance-driven q* < 1 (E[psi^2] > R*PhiTilde), which is a qualitatively different mechanism - the mode lives on the discretized psi lattice and the reachable-grid behavior differs (see my comment on the verdict band in pf_decay.py). One fat-psi calibration exercised through the full top-tail fit would close it. Separately: an AggShock regression at IncUnemp > 0 would have caught the intercept-coordinate bug flagged in ConsAggShockModel.py - as it stands, every AggShock test runs where the bug is identically zero.

[alanlujan91]

I ran this tool's --check against the tags actually shipped in this branch: field-count distribution {5: 35, 4: 25, 3: 1} - 35 of 61 tags MALFORMED under this max-4 grammar, exit 1. Most tags append a 5th ::-separated field (the GitHub Pages URL), which the grammar doesn't admit. So test_check_without_theorem_repo_degrades_gracefully, which asserts "0 malformed" on the no-repo path public CI runs, should be failing on this branch as shipped. Two more sync issues in the same apparatus: the tool's docstring and the test's default THEOREM_REPO path name HAFiscal-Latest (a worktree path) while every tag and URL in the codebase says BufferStockTheory-Latest - one of them is a generation behind; and the test docstring says "the PR landed 22 [tags]" with MIN_EXPECTED_TAGS = 20, while the actual count is 61. The rot-prevention tooling is currently out of sync with more than half of its own subject matter, which is worth fixing before merge precisely because this system is the thing that's supposed to prevent that.

[alanlujan91]

This is an AI work-order/coordination document - status metadata ("PENDING owner release"), machine-specific paths (/home/shared/github/...), and an explicit "Audience: an AI" header. It doesn't belong in a library's permanent git history. If the substantive technical content (the theory background, the what-already-exists inventory) is worth keeping, a stripped-down design note under docs/ or the PR description is the right home; this file should be dropped from the PR either way.

[Copilot]

Pull request overview

Adds opt-in, theory-backed power-law extrapolation for buffer-stock consumption functions, related diagnostics, and grid-sizing utilities.

Changes:

• Adds composable upper and lower tail interpolators.
• Integrates optional tails into individual and aggregate-shock solvers.
• Adds theory utilities, diagnostics, documentation, and extensive tests.

Reviewed changes

Copilot reviewed 11 out of 13 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
.agents/prompts_local/20260715-0900h_prompt_notebook-and-binding-gate.md	Records implementation requirements.
HARK/ConsumptionSaving/ConsAggShockModel.py	Adds aggregate-shock PF tails.
HARK/ConsumptionSaving/ConsIndShockModel.py	Adds opt-in individual-shock tails.
HARK/ConsumptionSaving/pf_decay.py	Implements theory and diagnostics.
HARK/interpolation.py	Adds power-law tail interpolators.
docs/CHANGELOG.md	Documents new APIs.
examples/ConsIndShockModel/PowerlawExtrapolation.ipynb	Demonstrates tail behavior.
tests/ConsumptionSaving/test_AggShock_pf_decay.py	Tests aggregate-shock integration.
tests/ConsumptionSaving/test_pf_decay.py	Tests theory utilities.
tests/ConsumptionSaving/test_powerlaw_extrap.py	Tests solver-tail fidelity.
tests/test_interpolation.py	Tests interpolation behavior.
tests/test_theorem_refs.py	Tests citation checking.
tools/update_theorem_refs.py	Verifies and updates theorem references.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[alanlujan91]

Following up on my review with a design observation rather than a bug: this guarded_fit branch - fitting Q from the boundary geometry, Q_fit = (slope_top - MPCmin)(m_top + hNrm)/level_diff - is a measured local exponent, and it is the arm of this architecture I would trust most. It requires no theory input, no regime classification, and it automatically tracks the pre-asymptotic transit that a fixed theory Q cannot (on the calibrations I have measured, the true local exponent reaches its asymptote only at many multiples of human wealth, non-monotonically, with an overshoot). The theory value of q is exactly right as a diagnostic target - the thing the fitted exponent should migrate toward as grids deepen, which powerlaw_tail_diagnostic already operationalizes - but as the imposed extrapolation exponent it is only correct where the fit already agrees with it. Concretely: consider making guarded_fit the default arm and 'theory' the opt-in, rather than the reverse. The fallback here is better than the headline mode, and the module's own diagnostic machinery is the right home for q*.