refactor(solve): Option B - rename _solve dispatch to solve_explicit/solve_descriptive

ocots · ocots · commit ca254e286af0 · 2026-02-19T14:38:38.000+01:00
- Replace _solve(::ExplicitMode, ...) with solve_explicit(...)
- Replace _solve(::DescriptiveMode, ...) with solve_descriptive(...)
- dispatch.jl: explicit if/else + component extraction by type via _extract_kwarg
- mode.jl: restored cleanly, mode_detection.jl: types removed
- Tests: fix outer-scope names (test_dispatch, test_mode), update all call sites
- 76/76 tests passing
diff --git a/.reports/kanban_orchestration/DOING/05_commonsolve_solve.md b/.reports/kanban_orchestration/DOING/05_commonsolve_solve.md
@@ -309,5 +309,6 @@ When `solve_descriptive` is implemented, this test will be updated.
 
 ## Status Tracking
 
-**Current Status**: TODO
-**Created**: 2026-02-18
+**Current Status**: DOING
+**Started**: 2026-02-19
+**Developer**: Cascade
diff --git a/src/OptimalControl.jl b/src/OptimalControl.jl
@@ -10,6 +10,7 @@ module OptimalControl
 using DocStringExtensions
 using Reexport
 using CTBase
+using CommonSolve
 
 # Imports
 include(joinpath(@__DIR__, "imports", "ctbase.jl"))
@@ -32,6 +33,7 @@ include(joinpath(@__DIR__, "helpers", "component_completion.jl"))
 # solve
 include(joinpath(@__DIR__, "solve", "mode.jl"))
 include(joinpath(@__DIR__, "solve", "mode_detection.jl"))
+include(joinpath(@__DIR__, "solve", "dispatch.jl"))
 include(joinpath(@__DIR__, "solve", "canonical.jl"))
 include(joinpath(@__DIR__, "solve", "explicit.jl"))
 include(joinpath(@__DIR__, "solve", "descriptive.jl"))
diff --git a/src/solve/canonical.jl b/src/solve/canonical.jl
@@ -24,17 +24,17 @@ function CommonSolve.solve(
     display::Bool                                   # Explicit value (no default)
 )::CTModels.AbstractSolution
     
-    # 1. Discretize the optimal control problem
-    discrete_problem = CTDirect.discretize(ocp, discretizer)
-    
-    # 2. Display configuration (compact, user options only)
+    # 1. Display configuration (compact, user options only)
     if display
         OptimalControl.display_ocp_configuration(
             discretizer, modeler, solver;
             display=true, show_options=true, show_sources=false
         )
     end
     
+    # 2. Discretize the optimal control problem
+    discrete_problem = CTDirect.discretize(ocp, discretizer)
+
     # 3. Solve the discretized optimal control problem
     return CommonSolve.solve(
         discrete_problem, initial_guess, modeler, solver; display=display
diff --git a/src/solve/descriptive.jl b/src/solve/descriptive.jl
@@ -1,14 +1,12 @@
 """
 $(TYPEDSIGNATURES)
 
-Stub for descriptive mode resolution.
+Stub for descriptive mode resolution (Layer 2).
 
-Raises [`CTBase.NotImplemented`](@ref) until `solve_descriptive` is implemented.
+Raises [`CTBase.NotImplemented`](@ref) until descriptive mode is implemented.
 This stub allows testing the orchestration layer (mode detection, dispatch routing)
 before the descriptive mode handler exists.
 
-The `description` vararg will be forwarded to `solve_descriptive` when implemented.
-
 # Arguments
 - `ocp`: The optimal control problem to solve
 - `description`: Symbolic description tokens (e.g., `:collocation`, `:adnlp`, `:ipopt`)
@@ -21,16 +19,14 @@ The `description` vararg will be forwarded to `solve_descriptive` when implement
 - `CTBase.NotImplemented`: Always — descriptive mode is not yet implemented
 
 # See Also
-- [`DescriptiveMode`](@ref): The dispatch sentinel type
 - [`CommonSolve.solve`](@ref): The entry point that dispatches here
 """
-function _solve(
-    ::DescriptiveMode,
+function solve_descriptive(
     ocp::CTModels.AbstractModel,
     description::Symbol...;
     initial_guess::CTModels.AbstractInitialGuess,
     display::Bool,
-    registry::CTSolvers.Strategies.StrategyRegistry,
+    registry::CTSolvers.StrategyRegistry,
     kwargs...
 )::CTModels.AbstractSolution
 
diff --git a/src/solve/dispatch.jl b/src/solve/dispatch.jl
@@ -0,0 +1,81 @@
+using CTBase
+
+"""
+$(TYPEDSIGNATURES)
+
+Main entry point for optimal control problem resolution.
+
+This function orchestrates the complete solve workflow by:
+1. Detecting the resolution mode (explicit vs descriptive) from arguments
+2. Normalizing the initial guess
+3. Creating the strategy registry
+4. Dispatching to the appropriate `_solve` method based on the detected mode
+
+# Arguments
+- `ocp`: The optimal control problem to solve
+- `description`: Symbolic description tokens (e.g., `:collocation`, `:adnlp`, `:ipopt`)
+- `initial_guess`: Initial guess or `nothing` for automatic generation
+- `display`: Whether to display configuration information
+- `kwargs...`: Additional keyword arguments (explicit components or strategy options)
+
+# Returns
+- `CTModels.AbstractSolution`: Solution to the optimal control problem
+
+# Examples
+```julia
+# Descriptive mode (symbolic description)
+solution = solve(ocp, :collocation, :adnlp, :ipopt)
+
+# Explicit mode (typed components)
+solution = solve(ocp; discretizer=CTDirect.Collocation(), 
+                     modeler=CTSolvers.ADNLP(), solver=CTSolvers.Ipopt())
+```
+
+# See Also
+- [`_explicit_or_descriptive`](@ref): Mode detection and validation
+- [`ExplicitMode`](@ref), [`DescriptiveMode`](@ref): Dispatch sentinel types
+- [`_solve`](@ref): Mode-specific resolution methods
+"""
+function CommonSolve.solve(
+    ocp::CTModels.AbstractModel,
+    description::Symbol...;
+    initial_guess=nothing,
+    display::Bool=__display(),
+    kwargs...
+)::CTModels.AbstractSolution
+
+    # 1. Detect mode and validate (raises on conflict)
+    mode = _explicit_or_descriptive(description, kwargs)
+
+    # 2. Normalize initial guess ONCE at the top level
+    normalized_init = CTModels.build_initial_guess(ocp, initial_guess)
+
+    # 3. Get registry for component completion
+    registry = get_strategy_registry()
+
+    # 4. Dispatch — asymmetric signatures:
+    #    ExplicitMode: extract typed components by type from kwargs (default nothing)
+    #    DescriptiveMode: description forwarded as vararg positional arguments
+    if mode isa ExplicitMode
+        discretizer = _extract_kwarg(kwargs, CTDirect.AbstractDiscretizer)
+        modeler     = _extract_kwarg(kwargs, CTSolvers.AbstractNLPModeler)
+        solver      = _extract_kwarg(kwargs, CTSolvers.AbstractNLPSolver)
+        return solve_explicit(
+            ocp;
+            initial_guess=normalized_init,
+            display=display,
+            registry=registry,
+            discretizer=discretizer,
+            modeler=modeler,
+            solver=solver
+        )
+    else
+        return solve_descriptive(
+            ocp, description...;
+            initial_guess=normalized_init,
+            display=display,
+            registry=registry,
+            kwargs...
+        )
+    end
+end
diff --git a/src/solve/explicit.jl b/src/solve/explicit.jl
@@ -1,11 +1,10 @@
 """
 $(TYPEDSIGNATURES)
 
-Resolve an OCP in explicit mode.
+Resolve an OCP in explicit mode (Layer 2).
 
-Receives typed components (`discretizer`, `modeler`, `solver`) as named keyword arguments
-(pre-validated by [`_explicit_or_descriptive`](@ref)), then completes missing components
-via the registry before calling Layer 3.
+Receives typed components (`discretizer`, `modeler`, `solver`) as named keyword arguments,
+then completes missing components via the registry before calling Layer 3.
 
 # Arguments
 - `ocp`: The optimal control problem to solve
@@ -22,18 +21,16 @@ via the registry before calling Layer 3.
 # See Also
 - [`_has_complete_components`](@ref): Checks if all three components are provided
 - [`_complete_components`](@ref): Completes missing components via registry
-- [`ExplicitMode`](@ref): The dispatch sentinel type
-- [`_explicit_or_descriptive`](@ref): Validates and routes to this method
+- [`_explicit_or_descriptive`](@ref): Mode detection that routes here
 """
-function _solve(
-    ::ExplicitMode,
+function solve_explicit(
     ocp::CTModels.AbstractModel;
     initial_guess::CTModels.AbstractInitialGuess,
     discretizer::Union{CTDirect.AbstractDiscretizer, Nothing},
     modeler::Union{CTSolvers.AbstractNLPModeler, Nothing},
     solver::Union{CTSolvers.AbstractNLPSolver, Nothing},
     display::Bool,
-    registry::CTSolvers.Strategies.StrategyRegistry
+    registry::CTSolvers.StrategyRegistry
 )::CTModels.AbstractSolution
 
     # Resolve components: use provided ones or complete via registry
diff --git a/src/solve/mode.jl b/src/solve/mode.jl
@@ -1,43 +1,39 @@
 """
 Abstract supertype for solve mode sentinel types.
 
-Concrete subtypes are used for multiple dispatch on `_solve` to route
-resolution to the appropriate mode handler without `if/else` branching.
+Concrete subtypes are used to route resolution to the appropriate mode handler
+without `if/else` branching in mode detection.
 
 # Subtypes
 - [`ExplicitMode`](@ref): User provided explicit components (discretizer, modeler, solver)
 - [`DescriptiveMode`](@ref): User provided symbolic description (e.g., `:collocation, :adnlp, :ipopt`)
 
 # See Also
 - [`_explicit_or_descriptive`](@ref): Returns the appropriate mode instance
-- [`_solve`](@ref): Dispatches on mode
 """
 abstract type SolveMode end
 
 """
 Sentinel type indicating that the user provided explicit resolution components.
 
-An instance `ExplicitMode()` is passed to `_solve` when at least one of
-`discretizer`, `modeler`, or `solver` is present in `kwargs` with the
+An instance `ExplicitMode()` is returned by [`_explicit_or_descriptive`](@ref) when at
+least one of `discretizer`, `modeler`, or `solver` is present in `kwargs` with the
 correct abstract type.
 
 # See Also
 - [`DescriptiveMode`](@ref): The alternative mode
 - [`_explicit_or_descriptive`](@ref): Mode detection logic
-- [`_solve(::ExplicitMode, ...)`](@ref): Handler for this mode
 """
 struct ExplicitMode <: SolveMode end
 
 """
 Sentinel type indicating that the user provided a symbolic description.
 
-An instance `DescriptiveMode()` is passed to `_solve` when no explicit
-components are found in `kwargs`. The symbolic description (e.g.,
-`:collocation, :adnlp, :ipopt`) is forwarded via `kwargs`.
+An instance `DescriptiveMode()` is returned by [`_explicit_or_descriptive`](@ref) when
+no explicit components are found in `kwargs`.
 
 # See Also
 - [`ExplicitMode`](@ref): The alternative mode
 - [`_explicit_or_descriptive`](@ref): Mode detection logic
-- [`_solve(::DescriptiveMode, ...)`](@ref): Handler for this mode
 """
 struct DescriptiveMode <: SolveMode end
diff --git a/test/suite/solve/test_dispatch.jl b/test/suite/solve/test_dispatch.jl
@@ -49,12 +49,11 @@ function test_solve_dispatch()
         registry = OptimalControl.get_strategy_registry()
 
         # ====================================================================
-        # CONTRACT TESTS - ExplicitMode: complete components (mock Layer 3)
+        # CONTRACT TESTS - solve_explicit: complete components (mock Layer 3)
         # ====================================================================
 
-        Test.@testset "ExplicitMode - all three components" begin
-            result = OptimalControl._solve(
-                OptimalControl.ExplicitMode(),
+        Test.@testset "solve_explicit - all three components" begin
+            result = OptimalControl.solve_explicit(
                 ocp;
                 initial_guess=init,
                 display=false,
@@ -65,13 +64,12 @@ function test_solve_dispatch()
         end
 
         # ====================================================================
-        # CONTRACT TESTS - DescriptiveMode: stub raises NotImplemented
+        # CONTRACT TESTS - solve_descriptive: stub raises NotImplemented
         # ====================================================================
 
-        Test.@testset "DescriptiveMode - raises NotImplemented" begin
+        Test.@testset "solve_descriptive - raises NotImplemented" begin
             Test.@test_throws CTBase.NotImplemented begin
-                OptimalControl._solve(
-                    OptimalControl.DescriptiveMode(),
+                OptimalControl.solve_descriptive(
                     ocp, :collocation, :adnlp, :ipopt;
                     initial_guess=init,
                     display=false,
@@ -80,65 +78,20 @@ function test_solve_dispatch()
             end
         end
 
-        Test.@testset "DescriptiveMode - empty description raises NotImplemented" begin
+        Test.@testset "solve_descriptive - empty description raises NotImplemented" begin
             Test.@test_throws CTBase.NotImplemented begin
-                OptimalControl._solve(
-                    OptimalControl.DescriptiveMode(),
+                OptimalControl.solve_descriptive(
                     ocp;
                     initial_guess=init,
                     display=false,
                     registry=registry
                 )
             end
         end
-
-        # ====================================================================
-        # CONTRACT TESTS - Dispatch correctness
-        # ====================================================================
-
-        Test.@testset "Dispatch correctness - ExplicitMode route" begin
-            # Verify that ExplicitMode actually routes to the ExplicitMode method
-            function _dispatch_route(mode::OptimalControl.ExplicitMode)
-                return :explicit
-            end
-            function _dispatch_route(mode::OptimalControl.DescriptiveMode)
-                return :descriptive
-            end
-
-            Test.@test _dispatch_route(OptimalControl.ExplicitMode()) == :explicit
-        end
-
-        Test.@testset "Dispatch correctness - DescriptiveMode route" begin
-            # Verify that DescriptiveMode actually routes to the DescriptiveMode method
-            function _dispatch_route(mode::OptimalControl.ExplicitMode)
-                return :explicit
-            end
-            function _dispatch_route(mode::OptimalControl.DescriptiveMode)
-                return :descriptive
-            end
-
-            Test.@test _dispatch_route(OptimalControl.DescriptiveMode()) == :descriptive
-        end
-
-        # ====================================================================
-        # INTEGRATION TESTS - End-to-end dispatch
-        # ====================================================================
-
-        Test.@testset "Integration - complete explicit workflow" begin
-            result = OptimalControl._solve(
-                OptimalControl.ExplicitMode(),
-                ocp;
-                initial_guess=init,
-                display=false,
-                registry=registry,
-                discretizer=disc, modeler=mod, solver=sol
-            )
-            Test.@test result isa MockSolution
-        end
     end
 end
 
 end # module
 
 # CRITICAL: Redefine in outer scope for TestRunner
-test_solve_dispatch() = TestSolveDispatch.test_solve_dispatch()
+test_dispatch() = TestSolveDispatch.test_solve_dispatch()
diff --git a/test/suite/solve/test_explicit.jl b/test/suite/solve/test_explicit.jl
diff --git a/test/suite/solve/test_mode.jl b/test/suite/solve/test_mode.jl
diff --git a/test/suite/solve/test_orchestration.jl b/test/suite/solve/test_orchestration.jl
