Redesign the solver seam as an ABC (GridSearch + DCEGM stub).

Replace the `type(solver)`-keyed builder registry with a polymorphic `Solver`
ABC. The engine now calls `solver.validate(context)` then
`solver.build_period_kernels(context)` — no `SOLVER_KERNEL_BUILDERS` dict, no
`BruteForce | DCEGM` union, no standalone DC-EGM guard.

- `_lcm/solution/contract.py` (new): the `Solver` ABC (abstract
  `build_period_kernels`, default no-op `validate`), `SolverBuildContext`, and
  `SolverKernels`. An engine leaf — imports nothing that reaches `lcm.solvers`,
  so the façade can re-export it without an import cycle.
- `_lcm/solution/solvers.py` (new): `GridSearch(Solver)` (the relocated
  grid-search builder, with function-local `jax`/`get_max_Q_over_a` imports) and
  `DCEGM(Solver)` (the published config; `validate` raises the not-yet-available
  guard, so a regime requesting it is rejected at model build).
- `lcm/solvers.py` → thin re-export façade; `registry.py` deleted; the
  `processing` dispatch and `Regime.solver` field updated.
- Rename the default solver `BruteForce` → `GridSearch` (more descriptive;
  alpha permits the break).

Faithful to dcegm-solver-seam-abc-design.md (ABC, not Protocol). Layer 2
(generic KernelResult) does not apply here — the stub seam has no EGM fork.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: hmgaudecker

src/_lcm/regime_building/processing.py

@@ -45,7 +45,7 @@
     collect_stochastic_state_transitions,
 )
 from _lcm.regime_building.V import VInterpolationInfo, create_v_interpolation_info
-from _lcm.solution.registry import SOLVER_KERNEL_BUILDERS, SolverBuildContext
+from _lcm.solution.contract import SolverBuildContext
 from _lcm.state_action_space import create_state_action_space
 from _lcm.typing import (
     ArgmaxQOverAFunction,
@@ -79,7 +79,7 @@
 from lcm.ages import AgeGrid
 from lcm.exceptions import ModelInitializationError
 from lcm.regime import Regime as UserRegime
-from lcm.solvers import DCEGM, BruteForce
+from lcm.solvers import Solver
 from lcm.transition import (
     MarkovTransition,
 )
@@ -114,8 +114,6 @@ def process_regimes(
         The processed canonical regimes.
 
     """
-    _fail_if_dcegm_solver_requested(user_regimes)
-
     # The canonical specs hold every law in target-granular form, resolved per
     # phase: the simulate slice additionally holds every carried-only state
     # and its law of motion, so the canonical mapping carries the law toward
@@ -240,29 +238,6 @@ def process_regimes(
     return ensure_containers_are_immutable(canonical_regimes)
 
 
-def _fail_if_dcegm_solver_requested(
-    user_regimes: Mapping[RegimeName, FinalizedUserRegime],
-) -> None:
-    """Reject the not-yet-available DC-EGM solver at model build.
-
-    The `DCEGM` configuration is published so a model can name the solver and
-    its parameters, but the solver engine is not yet wired in; a regime that
-    requests it cannot be solved. `BruteForce` is the only available solver.
-    """
-    dcegm_regimes = sorted(
-        name
-        for name, user_regime in user_regimes.items()
-        if isinstance(user_regime.solver, DCEGM)
-    )
-    if dcegm_regimes:
-        msg = (
-            "The DC-EGM solver is not yet available. Regime(s) "
-            f"{dcegm_regimes} request `solver=DCEGM(...)`; use `BruteForce()` "
-            "(the default) until DC-EGM is wired in."
-        )
-        raise NotImplementedError(msg)
-
-
 def _build_solution_phase(
     *,
     spec: PhasedRegimeSpec,
@@ -279,7 +254,7 @@ def _build_solution_phase(
     ages: AgeGrid,
     enable_jit: bool,
     has_taste_shocks: bool,
-    solver: BruteForce | DCEGM,
+    solver: Solver,
 ) -> SolutionPhase:
     """Build all compiled functions for the backward-induction (solve) phase.
 
@@ -301,8 +276,8 @@ def _build_solution_phase(
         enable_jit: Whether to jit the internal functions.
         has_taste_shocks: Whether the regime declares EV1 taste shocks on its
             discrete actions.
-        solver: The regime's solver configuration; selects the per-period
-            kernel builder dispatched through `SOLVER_KERNEL_BUILDERS`.
+        solver: The regime's solver; the engine calls `validate` then
+            `build_period_kernels` on it to obtain the per-period kernels.
 
     Returns:
         Complete solve functions container.
@@ -372,20 +347,19 @@ def _build_solution_phase(
             enable_jit=enable_jit,
         )
 
-    # Dispatch the per-period kernel build on the regime's solver
-    # configuration. `BruteForce` builds the max-Q-over-a grid-search kernels;
-    # other solvers register their own builders in `SOLVER_KERNEL_BUILDERS`.
-    solver_kernel_builder = SOLVER_KERNEL_BUILDERS[type(solver)]
-    solver_kernels = solver_kernel_builder(
-        solver=solver,
-        context=SolverBuildContext(
-            state_action_space=state_action_space,
-            Q_and_F_functions=Q_and_F_functions,
-            grids=all_grids[regime_name],
-            enable_jit=enable_jit,
-            has_taste_shocks=has_taste_shocks,
-        ),
+    # Dispatch the per-period kernel build polymorphically on the regime's
+    # solver: `validate` rejects out-of-scope configurations at build time,
+    # then `build_period_kernels` returns the per-period kernels. `GridSearch`
+    # builds the max-Q-over-a grid-search kernels.
+    context = SolverBuildContext(
+        state_action_space=state_action_space,
+        Q_and_F_functions=Q_and_F_functions,
+        grids=all_grids[regime_name],
+        enable_jit=enable_jit,
+        has_taste_shocks=has_taste_shocks,
     )
+    solver.validate(context=context)
+    solver_kernels = solver.build_period_kernels(context=context)
     max_Q_over_a = solver_kernels.max_Q_over_a
 
     return SolutionPhase(

src/_lcm/solution/contract.py

@@ -0,0 +1,74 @@
+"""The solver contract: what every regime solver provides to the engine.
+
+A regime's `solver` field selects its backward-induction algorithm. The engine
+dispatches polymorphically on the solver instance — `solver.validate(context)`
+then `solver.build_period_kernels(context)` — with no switch on solver type.
+Add a solver by subclassing `Solver` and implementing `build_period_kernels`;
+override `validate` for a build-time model-contract check (the default is a
+no-op). `SolverBuildContext` carries everything a solver may read to build one
+regime's kernels; `SolverKernels` is what it hands back.
+
+This module is an engine leaf: it imports only `_lcm.engine` / `_lcm.grids` /
+`_lcm.typing` (none of which reach `lcm.solvers`), so the public solver façade
+can re-export it without forming an import cycle.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from _lcm.engine import StateActionSpace
+from _lcm.grids import Grid
+from _lcm.typing import MaxQOverAFunction, QAndFFunction, StateOrActionName
+
+
+@dataclass(frozen=True, kw_only=True)
+class SolverBuildContext:
+    """Everything a solver may read to build one regime's kernels.
+
+    Bundled so the solver method signature stays stable as solvers with
+    different needs are added; each solver reads only the fields it uses.
+    """
+
+    state_action_space: StateActionSpace
+    """The regime's state-action space."""
+
+    Q_and_F_functions: MappingProxyType[int, QAndFFunction]
+    """Immutable mapping of period to Q-and-F closures."""
+
+    grids: MappingProxyType[StateOrActionName, Grid]
+    """Immutable mapping of the regime's variable names to grid objects."""
+
+    enable_jit: bool
+    """Whether to JIT-compile the kernels."""
+
+    has_taste_shocks: bool
+    """Whether the regime declares EV1 taste shocks on its discrete actions."""
+
+
+@dataclass(frozen=True, kw_only=True)
+class SolverKernels:
+    """Per-period solve kernels produced by a solver."""
+
+    max_Q_over_a: MappingProxyType[int, MaxQOverAFunction]
+    """Immutable mapping of period to max-Q-over-actions kernels.
+
+    Empty for solvers that replace the grid search with their own kernels.
+    """
+
+
+class Solver(ABC):
+    """Base class for regime solvers — the polymorphic dispatch target.
+
+    The engine calls `validate` then `build_period_kernels` on the instance,
+    matching the engine's own polymorphism (`Grid(ABC)`, the stochastic
+    processes). Subclasses are frozen dataclasses carrying the solver's
+    configuration.
+    """
+
+    @abstractmethod
+    def build_period_kernels(self, *, context: SolverBuildContext) -> SolverKernels:
+        """Build the regime's per-period solve kernels."""
+
+    def validate(self, *, context: SolverBuildContext) -> None:  # noqa: B027
+        """Check the regime is in scope for this solver. Default: no-op."""