NB-EGM: breakpoint-aware EGM solver for non-convex, discrete-continuous budgets

[hmgaudecker]

Summary

This PR has grown into the complete public and runtime surface for breakpoint-aware
endogenous-grid solving in pylcm. It adds the one-margin NBEGM solver and the nested
two-margin NNBEGM solver, but it also changes how models declare piecewise grids,
institutional boundaries, case-specific formulas, and solver-readable constraints. It
then carries that topology through continuation values, feasibility, simulation, native
envelope kernels, persistence, documentation, benchmarks, and CI.

The branch is based on the structural solver/constraint-routing work merged in #390.
Against current main, this PR changes 287 files (+40,474/-1,893).

User-facing API changes

Piecewise grids: breakpoint-first API (breaking)

PiecewiseGridSegment(interval=..., n_points=...) has been removed from the public API.
PiecewiseLinSpacedGrid and PiecewiseLogSpacedGrid now declare one closed domain plus
explicitly owned interior breakpoints:

from lcm import GridBreakpoint, PiecewiseLinSpacedGrid

grid = PiecewiseLinSpacedGrid(
    start=0.0,
    stop=100.0,
    breakpoints=(
        GridBreakpoint(value=10.0, owner="right"),
        GridBreakpoint(value=40.0, owner="left"),
    ),
    points_per_segment=(20, 50, 30),
)

This replaces interval-string parsing with a single canonical geometry:

• outer endpoints are closed;
• every interior breakpoint appears exactly once;
• owner="left" / "right" says which adjacent segment contains equality;
• the open side begins at the adjacent representable floating-point value;
• each point count is the number of output nodes contributed by that nominal segment;
• invalid counts and breakpoint layouts raise deterministic GridInitializationErrors.

The same ownership model is shared with NBEGM's feasibility and continuation topology,
including coincident left/right boundaries and strict constraints at an outer endpoint.
There is no compatibility shim for PiecewiseGridSegment; callers must migrate to
GridBreakpoint plus start, stop, breakpoints, and points_per_segment.

Structural declarations for non-smooth formulas

New decorators let model code retain the structure NBEGM needs without changing the
callable's behavior under GridSearch:

• boundary(...) and case_boundary(...) declare a named comparison surface, its
  equality owner, and whether it is a continuous kink, jump, or hard constraint;
• piece(...) attaches the smooth formula used on either side of a case predicate;
• affine_breakpoint(...) and piecewise_affine(...) declare a piecewise-affine
  schedule, including indexed and MappingLeaf thresholds;
• smooth_helper(...) distinguishes smooth numerical helpers from undeclared
  piecewise primitives.

The branch also exports fixed-form accounting declarations for the kernels it can prove
by identity: cash_on_hand_with_subsidy, liquid_law_from_savings, and
liquid_law_from_resources.

Constraints are planned, not implicitly discharged

NBEGM is integrated with the structural constraint route ledger. Every constraint must
be evaluated at a stage with all required inputs, proved by construction, compiled into
a boundary program, or rejected during model construction. Matching
post_decision_lower_bound declarations can be proved from the savings grid; suitable
Condition / ref(...) comparisons can be compiled into feasibility boundaries; an
opaque callable is accepted only where it is directly evaluable.

The NBEGM route keeps feasibility provenance and boundary ownership through the
within-period envelope, published continuation carry, nested NNBEGM solve, and simulated
policy. It covers intersections, one-sided constraints, coincident equalities in either
conjunction order, and strict lower/upper endpoint germs. Unsupported compositions fail
early instead of silently weakening the feasible set.

The new solver-selection documentation starts from the model author's question—when a
plain callable is enough and when retained Condition structure is needed—and then
explains which solvers can consume it.

Additional public surface

• NBEGM and NNBEGM are exported from lcm.solvers.
• SimulationResult.load_solution(directory=...) restores only saved value-function
  arrays, without loading the per-subject simulation checkpoint or metadata payload.
• Phased now documents and enforces the perceived-law-versus-simulated-truth boundary,
  including phase-invariant constraints and restrictions on stochastic next-state reads.

Solver implementation

NBEGM

NBEGM solves a one-dimensional consumption/savings problem whose budget or feasible
set has declared institutional breakpoints. Its lowering and numerical paths cover:

• case-piece budgets such as eligibility cliffs and notches;
• piecewise-affine schedules with kinks, jumps, floors, indexed thresholds, and
  ride-along states;
• discrete actions that enter utility, co-states, liquid laws, regime transitions, or
  schedule variables;
• smooth and zero-breakpoint budgets;
• secondary kinks from discrete choices;
• stochastic continuation values and distributed state arrays.

Each smooth case is solved by EGM. Boundary-targeting and corner candidates are added
explicitly, then all case and discrete branches are combined with a query-side upper
envelope. jump_read="one_sided" publishes duplicated one-sided carry rows at value
jumps; "bridged" keeps an ordinary finite-grid continuation for faster approximate
reads.

NNBEGM

NNBEGM adds a finite outer keeper/adjuster search around an inner NBEGM solve. It is
the two-margin counterpart of NEGM: declared liquid kinks, jumps, and hard constraints
retain NBEGM treatment for every outer candidate, while the durable/illiquid margin is
searched on an exogenous grid plus the no-adjustment candidate.

Recursive preferences, arithmetic, and memory controls

• NBEGM supports nonlinear Epstein–Zin recursion by applying the certainty equivalent
  to the joint regime-by-shock lottery, including composite single-power flow utility.
  The unsupported Epstein–Zin plus EV1 taste-shock combination is rejected explicitly.
• Envelope ownership supports certified double-double comparison and a faster ordinary
  working-precision mode.
• Fixed-width maps and separate batching controls for stochastic nodes, intervals,
  ride-along cells, discrete branches, candidate segments, and NNBEGM outer candidates
  bound intermediates without changing admitted results.
• Parameter-dependent scope checks run once on first solve. Affinity and
  interval-constancy probes fail closed by default; probe_failure="assume_declared"
  is the explicit opt-out for models validated by another oracle.

Native kernels, examples, and operational tooling

The exact-affine CPU/CUDA kernels are now treated as an installed package payload rather
than an artifact left in the source tree. Ordinary and editable builds include a native
manifest fingerprinted by sources, Python ABI, platform, JAX/jaxlib, compiler toolchain,
CUDA toolchain, and architecture flags. Runtime/CI probes distinguish a missing or stale
payload (reinstall once) from an unloadable payload (fail).

This PR also:

• adds a full NBEGM user guide and solver-selection guide;
• rewrites the piecewise-grid documentation for the breakpoint-first API;
• updates the Mahler–Yum example and benchmark to the current regime/grid surface;
• pins and preflights the ACA benchmark dependency so API drift fails before ASV;
• introduces declarative CI capability, coverage, resource, isolation, and tier markers;
• bounds GPU PR coverage and shards the slow CPU solution suite in fp32 and fp64;
• preserves JAX compilation caches and uploads policy/native/JUnit evidence.

Validation

The solver tests compare values, policies, marginals, discrete choices, and boundary
ownership against dense brute-force and independent envelope oracles. Coverage includes
case order, both equality owners, strict endpoint boundaries, carried feasibility,
one-sided and bridged jump reads, NNBEGM nesting, Epstein–Zin joint lotteries, batching
invariance, fp32/fp64 behavior, native-kernel capability, and distributed continuation
paths.

At exact branch tip 017fbcb1b5ee155615f662e953af63aa677d9ce7, the current GitHub
check set is green: Ubuntu fp32/fp64 (including all slow-solution shards), macOS,
Windows, GPU32, GPU64, ty, pre-commit, notebooks, documentation, benchmarks, Codecov,
and the ACA compatibility preflight.

[read-the-docs-community]

Documentation build overview

📚 pylcm | 🛠️ Build #34240649 | 📁 Comparing abe354d against latest (f03c1c9)

  🔍 Preview build  

44 files changed · + 7 added · ± 37 modified

+ Added

• adding-a-solver/index.html
• age-specialized/index.html
• choosing-a-solver/index.html
• continuous-integration/index.html
• credits/index.html
• epstein-zin/index.html
• nbegm/index.html

± Modified

• index.html
• approximating-continuous-shocks/index.html
• architecture/index.html
• benchmarking/index.html
• benchmarking-1/index.html
• beta-delta/index.html
• continuous-stochastic-processes/index.html
• conventions/index.html
• debugging/index.html
• defining-models/index.html
• and 27 more...

[github-actions]

Benchmark comparison (main → HEAD)

Comparing 88ce51dc (main) → abe354de (HEAD)

Benchmark	Statistic	before	after	Ratio	Alert
aca-baseline	execution time	10.208 s	9.991 s	0.98
	peak GPU mem	604 MB	601 MB	1.00
	compilation time	437.84 s	426.17 s	0.97
	peak CPU mem	10.43 GB	10.55 GB	1.01
aca-baseline-debug	execution time	36.832 s	35.450 s	0.96
	peak GPU mem	602 MB	603 MB	1.00
	compilation time	481.65 s	463.03 s	0.96
	peak CPU mem	6.53 GB	6.36 GB	0.97
Mahler-Yum	execution time	4.747 s	3.031 s	0.64
	peak GPU mem	788 MB	685 MB	0.87
	compilation time	15.97 s	21.75 s	1.36	❌
	peak CPU mem	1.35 GB	1.50 GB	1.11	❌
Precautionary Savings - Solve	execution time	26.2 ms	27.2 ms	1.04
	peak GPU mem	34 MB	34 MB	1.00
	compilation time	2.33 s	2.34 s	1.00
	peak CPU mem	1.07 GB	1.07 GB	1.01
Precautionary Savings - Simulate	execution time	62.0 ms	66.2 ms	1.07
	peak GPU mem	328 MB	328 MB	1.00
	compilation time	4.88 s	4.99 s	1.02
	peak CPU mem	1.23 GB	1.23 GB	1.00
Precautionary Savings - Solve & Simulate	execution time	100.1 ms	98.7 ms	0.99
	peak GPU mem	1.68 GB	1.68 GB	1.00
	compilation time	7.04 s	7.20 s	1.02
	peak CPU mem	1.25 GB	1.25 GB	1.00
Precautionary Savings - Solve & Simulate (irreg)	execution time	233.4 ms	231.0 ms	0.99
	peak GPU mem	2.20 GB	2.20 GB	1.00
	compilation time	7.51 s	7.55 s	1.01
	peak CPU mem	1.32 GB	1.32 GB	1.00
IskhakovEtAl2017DCEGMSimulate	execution time	236.9 ms	221.4 ms	0.93
	compilation time	7.54 s	7.40 s	0.98
	peak CPU mem	1.47 GB	1.46 GB	1.00
IskhakovEtAl2017DCEGMSolve	execution time	1.906 s	1.886 s	0.99
	compilation time	7.15 s	7.23 s	1.01
	peak CPU mem	1.39 GB	1.37 GB	0.99
IskhakovEtAl2017Simulate	execution time	225.2 ms	234.2 ms	1.04
	compilation time	7.74 s	7.56 s	0.98
	peak CPU mem	1.22 GB	1.21 GB	1.00
IskhakovEtAl2017Solve	execution time	53.9 ms	52.2 ms	0.97
	compilation time	2.63 s	2.62 s	1.00
	peak CPU mem	1.11 GB	1.12 GB	1.01
IskhakovEtAl2017DCEGMSimulateGpuPeakMem	peak GPU mem	440 MB	440 MB	1.00
IskhakovEtAl2017DCEGMSolveGpuPeakMem	peak GPU mem	0 MB	0 MB	1.00
IskhakovEtAl2017SimulateGpuPeakMem	peak GPU mem	440 MB	440 MB	1.00
IskhakovEtAl2017SolveGpuPeakMem	peak GPU mem	67 MB	67 MB	1.00

[hmgaudecker]

Round-4 external audit repairs (ledger: pr400-round4/REPAIRS.md in the audit archive):

• F1 (serious) — the EZ kernels were discontinuous one ULP from gamma = 1 / rho = 1 (the log(sum)/(1-gamma) form lost ~47% at nextafter(1, inf)). The transform partials are now a quint (anchor, weight sum, anchored deviation sum, marginal log-scale, marginal mantissa); inversion is log nu = a + [log(W) + log1p(E/W)]/(1-gamma), exact and smooth through both unit limits. The auditor's suggested weight normalization was rejected: regime blends can carry genuinely sub-unit mass, so log(W) must be preserved. One-ULP tests at nextafter(1, ±inf) are permanent (0e44a2a8, b95b8727).
• Full suite at b95b8727: 2030 passed, 56 skipped, 2 xfailed.

🤖 Generated with Claude Code

https://claude.ai/code/session_01BNQkLG5QzXcgGdpgH6sN4u

[codecov]

Codecov Report

❌ Patch coverage is 93.15315% with 114 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.61%. Comparing base (88ce51d) to head (abe354d).

Files with missing lines	Patch %	Lines
hatch_build.py	51.66%	29 Missing ⚠️
src/_lcm/simulation/simulate.py	89.51%	13 Missing ⚠️
src/_lcm/solution/nnbegm.py	95.20%	12 Missing ⚠️
src/_lcm/egm/nbegm_validation.py	87.64%	11 Missing ⚠️
src/_lcm/egm/upper_envelope/_exact_affine/ffi.py	82.45%	10 Missing ⚠️
benchmarks/preflight.py	0.00%	5 Missing ⚠️
src/lcm_examples/mahler_yum_2024/__init__.py	82.14%	5 Missing ⚠️
src/_lcm/egm/continuation.py	69.23%	4 Missing ⚠️
src/_lcm/grids/piecewise.py	96.49%	4 Missing ⚠️
src/_lcm/regime_building/finalize.py	92.72%	4 Missing ⚠️
... and 10 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #400      +/-   ##
==========================================
+ Coverage   91.43%   92.61%   +1.18%     
==========================================
  Files         249      279      +30     
  Lines       24630    29135    +4505     
==========================================
+ Hits        22520    26983    +4463     
- Misses       2110     2152      +42     

Flag	Coverage Δ
cpu-python	92.61% <93.15%> (?)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

???

[timmens]

Happy with all the changes. I only found three remaining small blockers

Blocking: Use the declared lower savings endpoint in the interval route

Placement: src/_lcm/egm/nbegm_step.py, _interval_corner_candidates

_interval_corner_candidates constructs its lower corner as s = 0: consumption is
corner_coh_grid, the continuation is read from interval_value[0], and the resulting
policy therefore implies zero savings. The public contract accepts a positive savings
lower bound and checks post_decision_lower_bound(...) against savings_grid[0].

A public ride-along model with a declared lower bound of 1 and a savings grid starting
at 1 passes model construction and log_level="debug". The interval route can then
publish an infeasible zero-savings choice; its solved value differs from GridSearch by
up to 2.9586 in the witness.

Could this corner use savings_grid[0] consistently for consumption, value, policy,
and feasibility, with a regression through the public interval-specific route?

Blocking: Probe affinity and unit slope inside every resolved interval

Placement: src/_lcm/solution/nbegm.py, _liquid_affinity_samples and
_liquid_slopes

The budget preflight does not verify every interval that the kernel reconstructs.
Second derivatives are sampled at liquid-grid nodes and their midpoints, without using
the resolved economic breakpoints. The all-jump unit-slope check ignores those samples
and evaluates the slope only at liquid values 1 and 2.

An all-jump schedule whose cash-on-hand slope is 1 below a threshold at 10 and 2
above it passes the check. NBEGM reconstructs the upper branch with unit slope, and the
accepted two-period model differs from GridSearch by up to 0.8676 under
log_level="debug".

Could the parameter check resolve each branch's breakpoint partition for the current
draw and evaluate both curvature and required slope at an interior point of every
nonempty interval?

Blocking: Replay the outer candidate selected by NNBEGM

Placement: src/_lcm/solution/nnbegm.py, _NNBEGMPeriodKernel.__call__

NNBEGM solves the outer decision over NNBEGM.outer_grid, then returns no simulation
policy. Simulation performs a fresh grid search over the regime's outer action grid,
which can represent a different candidate set from the one used during solution.

Changing only that action grid leaves the supplied solved value unchanged while
changing the simulated result:

                         narrow action grid   wide action grid
Solved value                 -7.8459              -7.8459
Simulated value              -9.9077              -7.8841
Chosen outer action            0.01                 5.00

Could NNBEGM publish and replay the joint outer and inner policy, or validate during
model construction that the simulation action grid represents exactly the solver's
candidate set?

[hmgaudecker]

Thanks — all three blockers are addressed:

• The interval corner now uses the declared savings-grid lower endpoint consistently, with public ride-along/cliff regressions (78dfa1a).
• Budget validation now resolves the economic breakpoint partition and checks curvature plus required unit slope inside every live interval, including the threshold-at-10 witness in fp32/fp64 (12ce852).
• NNBEGM now publishes its aligned keeper-plus-outer joint candidate bank and simulation replays the solved winner independently of the simulation action grid; the scalar oracle, batching/refinement checks, and runtime/memory gates are green (3758232).

The exact-tip blocker witnesses pass 7/7; all-file ty and commit hooks are green.

[timmens]

Blocking: Carry the NNBEGM replay policy through a separate solve and simulate

Placement: src/lcm/model.py, Model.solve and Model.simulate

The new candidate replay works when simulate() performs a fresh solve internally.
The documented separate workflow still cannot use it:

values = model.solve(...)
model.simulate(..., period_to_regime_to_V_arr=values)

solve(return_simulation_policy=True) can return the required policy mapping, while
simulate() has no argument that accepts it. Supplying value arrays therefore leaves
period_to_regime_to_sim_policy=None and silently restores the foreign action-grid
maximization. The original witness remains unchanged:

                         narrow action grid   wide action grid
Solved value                 -7.8459              -7.8459
Simulated value              -9.9077              -7.8841
Chosen outer action            0.01                 5.00

Could simulate() accept the policy mapping already returned by
solve(return_simulation_policy=True) and pass it through the existing internal
channel? When caller-supplied values require an NNBEGM replay policy and none is
provided, simulation should raise clearly before entering the forward loop. The
regression should pass the exact (values, policies) returned by one solve and compare
that simulation with the automatic solve-and-simulate path. The current regression
asserts that policies exist, discards them, and triggers a second automatic solve.

A SolutionResult bundling values and policies would give the cleaner long-term API
and persistence story. The explicit policy argument plus fail-closed validation is a
bounded fix for this PR and preserves value-only solution reads for comparisons and
warm starts.

Blocking: Rank the reconstructed NNBEGM candidates by canonical Q

Placement: src/_lcm/simulation/simulate.py, _replay_nnbegm_candidates

Replay currently interpolates every candidate's stored actions and stored solve value,
selects the largest interpolated stored value, and evaluates canonical Q only for that
winner. Interpolation can change the relationship between the stored value and the
value attained by the emitted action. The selected action can therefore be strictly
dominated by another reconstructed candidate already present in the replay bank.

In the public smooth toy at (wealth, illiquid) = (1.0467, 2.04):

current replay:       target 2.8571, consumption 0.9067, value -18.8542
canonical bank winner: target 4.2857, consumption 0.6695, value -18.1265
independent oracle:    target 4.2857, consumption 0.7768, value -18.0981

Across 651 off-grid states, the interpolated-value winner and canonical-Q winner
differed 62 times. The largest attainable-Q gain was 0.7277.

Could replay canonically score every represented joint candidate, apply canonical
feasibility and finiteness, and then select the largest Q with the existing solve-order
tie rule? If no candidate is valid, the current NaN action and -inf value sentinels
can remain. The simulation action grid should not become a fallback because it
represents a different candidate set.

The existing candidate batching machinery can bound this calculation. This also
matches the canonical associated-action/value principle used by the earlier nested
replay implementation. Once this is correct, replacing candidate_value with a
representation mask could be considered separately to reduce policy storage.

Blocking: Make the NNBEGM outer-action inversion contract explicit

Placement: src/_lcm/solution/nnbegm.py,
_NNBEGMPeriodKernel._candidate_outer_actions

NNBEGM solves in outer post-decision target space and later recovers the user's outer
action by evaluating the target function at actions zero and one and treating their
difference as a global affine slope. OuterContinuousMargin currently declares no
affinity or inverse requirement.

A valid nonlinear parameterization such as

def new_illiquid(illiquid, investment):
    return illiquid + investment**3

solves with finite values because the kernel binds new_illiquid directly. During
simulation, the affine reconstruction fails its round-trip, every affected adjuster is
converted to NaN, and the tested subjects silently keep their current illiquid stock.

Could we choose and enforce the supported contract here? Two coherent possibilities
seem available:

1. Require NNBEGM's outer target map to be affine in the outer action with nonzero
   slope, conditional on its other inputs. Check that the function depends on the
   action and raise an actionable error whenever the existing forward round-trip
   fails.
2. Support general invertible mappings through an explicit user-supplied inverse, for
   example an action_from_post_decision entry on OuterContinuousMargin, and verify
   its result through the forward map.

The earlier nested replay deliberately used grid fallback for a non-affine or
unresolvable mapping. That fallback is unsafe for NNBEGM because the regime action grid
and NNBEGM.outer_grid need not represent the same targets. Early rejection is a
sufficient bounded fix if general inversion belongs in a follow-up PR.

Regression cases should cover a cubic mapping, zero slope, and a supported affine map
such as new = old + 2 * action.

Discussion: Define the NNBEGM contract for Phased declarations

Placement: src/_lcm/solution/nbegm.py, model-stage declaration validation, and
src/_lcm/regime_building/processing.py, regime_declares_phased

There are two separate problems in the current phase handling:

• Phased(solve=utility, simulate=utility) fails during model construction with an
  internal beartype violation because NBEGM validation passes unresolved Phased
  objects to a callable-only helper.
• The replay eligibility scan omits koopmans_aggregator, so a genuinely
  phase-varying aggregator can receive an NNBEGM replay marker even though the replay
  contract requires phase-invariant aggregation.

The earlier EGM design deliberately retained grid argmax when phase variation changes
the simulation FOC. For NNBEGM, that grid path may search a different outer candidate
set from the solver. Could we therefore make the capability boundary explicit?

A bounded contract would be:

• resolve declaration pools before NBEGM validation;
• treat Phased(solve=f, simulate=f) as invariant when both sides are the same object;
• include the Koopmans aggregator in phase-variation detection;
• reject genuinely phase-varying NNBEGM models with a clear domain error until their
  simulate-phase inner and outer decisions can be replayed or reoptimized over the
  correct candidate set.

If genuine phase variation is intended to remain supported through grid maximization,
the PR needs to explain how the simulation grid is guaranteed to represent the
NNBEGM candidate set.

Non-blocking follow-up: Complete solution object

The replay work demonstrates that value arrays alone are not always sufficient to
reproduce a solver's forward policy. A separate PR could introduce a public
SolutionResult that bundles value functions and any solver-published replay artifacts
and is consumed directly by simulate() and persistence. The current value-only load
path should remain available for value comparisons and warm starts without loading
large policy banks.

The same interface question is already raised under
“Return and consume one complete solution artifact” in the review of PR 407.

[hmgaudecker]

Thanks — the three blocking fixes outside the Phased item are now pushed on feat/nb-egm:

• Separate solve/simulate: simulate(..., policies=...) consumes the mapping returned by solve(return_simulation_policy=True) and fails closed when supplied values need a missing replay policy (6eef61f9, with the fp32 inversion tolerance follow-up in cbecc3a2).
• Canonical ranking: replay scores every represented, feasible reconstructed joint candidate by canonical Q before applying the existing first-in-bank tie rule (e699cd3a).
• Outer inversion: NNBEGM now rejects nonlinear and zero-slope target maps and verifies supported affine recovery (9df8d622).

The Phased contract is being handled in its separate bounded repair. The complete-solution-object follow-up is tracked in #428. Focused fp32/fp64 batteries are green; the canonical-ranking GPU gate was also green (-4.07% warm runtime, 0% peak-device-memory change).

[hmgaudecker]

Final follow-up on the Phased item: this is now closed.

• NNBEGM-family validation consumes one normalized solve-phase declaration pool.
• Phase variation is classified by exact object identity across functions, states, state transitions, the regime transition, and the Koopmans aggregator.
• Bare declarations and Phased(solve=f, simulate=f) are accepted when both fields contain the same object.
• Genuine phase variation and carried-only states are rejected during Model(...) construction, before period-kernel construction or replay-policy publication.
• The follow-up architecture repair carries the normalized solve functions and phase-variation paths in the solver contexts, so solver runtime no longer imports regime-declaration topology.

The bounded repair landed in d2c78143; the final context-boundary repair is fa85227f. Verification includes 49/49 focused tests at fp64 and fp32, 86/86 bounded integration tests, hooks and whole-tree typing, and the final cross-platform CPU, fp32/fp64 GPU, notebook, and typing CI—all green.

[timmens]

Only one last comment!

Blocking: Reconstruct NNBEGM outer actions at the realized state

Placement: src/_lcm/solution/nnbegm.py, _candidate_outer_actions, and
src/_lcm/simulation/simulate.py, NNBEGM candidate replay

The new inversion guard proves recovery only at solve-state grid nodes. Simulation
later interpolates the recovered actions. Inversion and interpolation do not generally
commute, so an accepted conditional-affine map can emit a target outside the candidate
set that NNBEGM ranked:

def new_illiquid(illiquid, investment):
    return illiquid + (1 + 0.1 * illiquid) * investment

This map is affine in investment with a finite, nonzero slope conditional on its
other input, so it satisfies the contract stated by the new error. The public
two-period toy accepts it, and its solved value arrays are exactly equal to those under
the baseline parameterization. At the off-grid state
(wealth, illiquid) = (1.0467, 2.04), replay produces:

NNBEGM target selected during solution: 4.285714
exact action at the realized state:      1.865211
interpolated action used by simulation:  1.901299
target actually reached:                 4.329164

The resulting target lies outside both the keeper state and the declared
NNBEGM.outer_grid candidates, which violates the candidate-faithfulness invariant
asserted by the existing simulation regression. The reported Bellman value also changes
from -18.126415 to -18.104359, even though the two parameterizations produce
identical solved-grid values.

Could the replay payload retain each candidate's target identity, or enough metadata to
reconstruct it, and derive the outer action at the realized simulation state before
canonical-Q scoring? The replay path can then apply a forward round-trip check and
score the action that actually realizes the solve candidate. The keeper/outer-major
ordering and existing tie rule can remain unchanged.

If realized-state inversion is outside this PR's scope, a bounded alternative is to
define and enforce a narrower contract under which the inverse action surface is
represented exactly by replay interpolation. A constant action slope alone is
insufficient when the affine intercept is nonlinear in another interpolated state; a
jointly affine target map over the continuous replay coordinates with a
state-independent action coefficient would be one simple sufficient restriction.

A public solve-to-simulate regression could use the function above and assert in fp32
and fp64 that every emitted target remains either the realized keeper target or an
NNBEGM.outer_grid node.

[hmgaudecker]

Fixed in abe354de. The replay payload now retains each candidate’s outer-target identity instead of its solve-grid action (so there is no additional full candidate bank), resolves the simulate-phase target DAG per period, reconstructs the outer action at the realized state, forward-round-trips it, and only then applies canonical-Q ranking. Keeper/outer-major/discrete order and first-tie behavior are unchanged.

The public state-dependent-slope witness now passes in fp32 and fp64; the final affected battery is 44/44 in each precision, with Ruff, formatting, full ty, and commit hooks green.