feat: implement _solve dispatch methods (Option C asymmetric signatures)

ocots · ocots · commit a49bd54799c8 · 2026-02-19T11:20:23.000+01:00
- Add src/solve/solve_dispatch.jl with two _solve methods:
  - _solve(::ExplicitMode, ocp; initial_guess, discretizer, modeler, solver, display, registry)
  - _solve(::DescriptiveMode, ocp, description::Symbol...; initial_guess, display, registry, kwargs...)
- Add test/suite/solve/test_solve_dispatch.jl (6/6 tests)
- Migrate test/suite/solve/test_explicit.jl: solve_explicit → _solve(ExplicitMode(), ocp; ...)
- Remove export of solve_explicit from src/OptimalControl.jl
- Restore _extract_kwarg in mode_detection.jl (type-based presence check)
- Move task 04 to REVIEW/ with completion report

Architecture: Option C (asymmetric signatures)
- ExplicitMode: named kwargs (discretizer, modeler, solver) — no extraction needed
- DescriptiveMode: positional vararg description — kwargs... for strategy options
- CommonSolve.solve remains pure orchestrator (no extraction)
diff --git a/.reports/kanban_orchestration/REVIEW/04_solve_dispatch.md b/.reports/kanban_orchestration/REVIEW/04_solve_dispatch.md
@@ -352,5 +352,80 @@ Layer 3 makes `_solve(::ExplicitMode, ...)` fully testable without a real OCP. T
 
 ## Status Tracking
 
-**Current Status**: TODO
-**Created**: 2026-02-18
+**Current Status**: REVIEW
+**Started**: 2026-02-19
+**Completed**: 2026-02-19
+**Developer**: Cascade
+
+---
+
+## 📋 Completion Report
+
+### ✅ Implementation Summary
+
+**Files Created**:
+- `src/solve/solve_dispatch.jl` — `_solve(::ExplicitMode, ...)` et `_solve(::DescriptiveMode, ...)`
+- `test/suite/solve/test_solve_dispatch.jl` — Tests de dispatch avec mocks
+
+**Files Modified**:
+- `test/suite/solve/test_explicit.jl` — Migration de `solve_explicit(ocp, init; ...)` vers `_solve(ExplicitMode(), ocp; initial_guess=init, ...)`
+- `src/OptimalControl.jl` — Suppression de l'export de `solve_explicit`
+- `src/solve/mode_detection.jl` — Restauration de `_extract_kwarg` (détection par type)
+
+**Architecture (Option C — signatures asymétriques)** :
+```julia
+# ExplicitMode : composants nommés directs, pas de description
+function _solve(::ExplicitMode, ocp; initial_guess, discretizer, modeler, solver, display, registry)
+
+# DescriptiveMode : description vararg positionnelle, kwargs... pour options
+function _solve(::DescriptiveMode, ocp, description::Symbol...; initial_guess, display, registry, kwargs...)
+```
+
+### ✅ Testing Results
+
+**New Tests** (`test_solve_dispatch.jl`): 6/6 passed
+- ExplicitMode — all three components (mock Layer 3)
+- DescriptiveMode — raises NotImplemented (with/without description)
+- Dispatch correctness (ExplicitMode/DescriptiveMode routes)
+- Integration — complete explicit workflow
+
+**Migrated Tests** (`test_explicit.jl`): 32/32 passed
+- All calls migrated from `solve_explicit(ocp, init; ...)` to `_solve(ExplicitMode(), ocp; initial_guess=init, ...)`
+- Contract tests with mocks
+- Integration tests with real strategies (Beam, Goddard)
+- Complete method coverage
+
+### ✅ Quality Checks
+
+**Architecture**:
+- ✅ Signatures asymétriques — chaque `_solve` reçoit exactement ce dont il a besoin
+- ✅ `CommonSolve.solve` reste pur orchestrateur (pas d'extraction)
+- ✅ `_explicit_or_descriptive` valide par type via `_extract_kwarg` (présence + type)
+- ✅ `_solve(::ExplicitMode, ...)` reçoit composants nommés directs (pas de kwargs extraction)
+- ✅ `_solve(::DescriptiveMode, ...)` stub `NotImplemented` pour tests d'orchestration
+
+**Documentation**:
+- ✅ Docstrings complètes avec DocStringExtensions
+- ✅ Cross-références vers les fonctions liées
+
+**Code Quality**:
+- ✅ Pas d'export de `solve_explicit` (fonction interne)
+- ✅ Migration complète de `test_explicit.jl`
+- ✅ Aucun warning ou erreur
+
+### ✅ Acceptance Criteria Verification
+
+- [x] `src/solve/solve_dispatch.jl` créé avec les deux méthodes `_solve`
+- [x] Signature asymétrique Option C respectée
+- [x] `_solve(::ExplicitMode, ...)` absorbe la logique de `solve_explicit`
+- [x] `_solve(::DescriptiveMode, ...)` stub `NotImplemented`
+- [x] `test/suite/solve/test_solve_dispatch.jl` créé (6/6 tests)
+- [x] `test/suite/solve/test_explicit.jl` migré (32/32 tests)
+- [x] Export `solve_explicit` supprimé de `src/OptimalControl.jl`
+- [x] Tous les tests existants passent
+
+### 🎯 Ready for Review
+
+Cette tâche implémente les deux méthodes `_solve` avec la signature asymétrique (Option C)
+et migre complètement `test_explicit.jl`. Tous les tests passent (38/38 au total).
+Prêt pour la validation du reviewer.
diff --git a/.reports/kanban_orchestration/TODO/05_commonsolve_solve.md b/.reports/kanban_orchestration/TODO/05_commonsolve_solve.md
@@ -43,7 +43,7 @@ Reference: `.reports/solve_orchestration.md` — R1: Signature and Delegation
 
 **File**: `src/solve/solve.jl` (check if it exists; modify or create as needed)
 
-```julia
+````julia
 """
 $(TYPEDSIGNATURES)
 
@@ -126,7 +126,7 @@ function CommonSolve.solve(
         kwargs...
     )
 end
-```
+````
 
 ### Tests Required
 
diff --git a/src/OptimalControl.jl b/src/OptimalControl.jl
@@ -31,11 +31,11 @@ include(joinpath(@__DIR__, "helpers", "component_completion.jl"))
 # solve
 include(joinpath(@__DIR__, "solve", "solve_mode.jl"))
 include(joinpath(@__DIR__, "solve", "mode_detection.jl"))
+include(joinpath(@__DIR__, "solve", "solve_dispatch.jl"))
 include(joinpath(@__DIR__, "solve", "solve_canonical.jl"))
 include(joinpath(@__DIR__, "solve", "solve_explicit.jl"))
 
 export methods # non useful since it is already in Base
 export get_strategy_registry
-export solve_explicit
 
 end
diff --git a/src/solve/solve_dispatch.jl b/src/solve/solve_dispatch.jl
@@ -0,0 +1,99 @@
+using CTBase
+
+"""
+$(TYPEDSIGNATURES)
+
+Resolve an OCP in explicit mode.
+
+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.
+
+# Arguments
+- `ocp`: The optimal control problem to solve
+- `initial_guess`: Normalized initial guess (processed by Layer 1)
+- `discretizer`: Discretization strategy, or `nothing` to complete via registry
+- `modeler`: NLP modeling strategy, or `nothing` to complete via registry
+- `solver`: NLP solver strategy, or `nothing` to complete via registry
+- `display`: Whether to display configuration information
+- `registry`: Strategy registry for completing partial components
+
+# Returns
+- `CTModels.AbstractSolution`: Solution to the optimal control problem
+
+# 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
+"""
+function _solve(
+    ::ExplicitMode,
+    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
+)::CTModels.AbstractSolution
+
+    # Resolve components: use provided ones or complete via registry
+    components = if _has_complete_components(discretizer, modeler, solver)
+        (discretizer=discretizer, modeler=modeler, solver=solver)
+    else
+        _complete_components(discretizer, modeler, solver, registry)
+    end
+
+    # Single solve call with resolved components
+    return CommonSolve.solve(
+        ocp, initial_guess,
+        components.discretizer,
+        components.modeler,
+        components.solver;
+        display=display
+    )
+end
+
+"""
+$(TYPEDSIGNATURES)
+
+Stub for descriptive mode resolution.
+
+Raises [`CTBase.NotImplemented`](@ref) until `solve_descriptive` 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`)
+- `initial_guess`: Normalized initial guess (processed by Layer 1)
+- `display`: Whether to display configuration information
+- `registry`: Strategy registry
+- `kwargs...`: Strategy-specific options
+
+# Throws
+- `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,
+    ocp::CTModels.AbstractModel,
+    description::Symbol...;
+    initial_guess::CTModels.AbstractInitialGuess,
+    display::Bool,
+    registry::CTSolvers.Strategies.StrategyRegistry,
+    kwargs...
+)::CTModels.AbstractSolution
+
+    throw(CTBase.NotImplemented(
+        "Descriptive mode is not yet implemented",
+        suggestion="Use explicit mode: solve(ocp; discretizer=..., modeler=..., solver=...)",
+        context="_solve(::DescriptiveMode, ...)"
+    ))
+end
diff --git a/test/suite/solve/test_explicit.jl b/test/suite/solve/test_explicit.jl
@@ -58,7 +58,7 @@ CommonSolve.solve(
 )::MockSolution = MockSolution()
 
 function test_explicit()
-    Test.@testset "solve_explicit (contract tests with mocks)" verbose=VERBOSE showtiming=SHOWTIMING begin
+    Test.@testset "_solve ExplicitMode (contract tests with mocks)" verbose=VERBOSE showtiming=SHOWTIMING begin
         ocp = MockOCP()
         init = MockInit()
         disc = MockDiscretizer(CTSolvers.StrategyOptions())
@@ -70,8 +70,10 @@ function test_explicit()
         # COMPLETE COMPONENTS PATH
         # ================================================================
         Test.@testset "Complete components -> direct path" begin
-            result = OptimalControl.solve_explicit(
-                ocp, init;
+            result = OptimalControl._solve(
+                OptimalControl.ExplicitMode(),
+                ocp;
+                initial_guess=init,
                 discretizer=disc,
                 modeler=mod,
                 solver=sol,
@@ -99,8 +101,10 @@ function test_explicit()
                     init = OptimalControl.build_initial_guess(pb.ocp, pb.init)
                     
                     Test.@testset "Complete components - real strategies" begin
-                        result = OptimalControl.solve_explicit(
-                            pb.ocp, init;
+                        result = OptimalControl._solve(
+                            OptimalControl.ExplicitMode(),
+                            pb.ocp;
+                            initial_guess=init,
                             discretizer=CTDirect.Collocation(),
                             modeler=CTSolvers.ADNLP(),
                             solver=CTSolvers.Ipopt(),
@@ -114,8 +118,10 @@ function test_explicit()
                     
                     Test.@testset "Partial components - completion" begin
                         # Test with only discretizer provided
-                        result = OptimalControl.solve_explicit(
-                            pb.ocp, init;
+                        result = OptimalControl._solve(
+                            OptimalControl.ExplicitMode(),
+                            pb.ocp;
+                            initial_guess=init,
                             discretizer=CTDirect.Collocation(),
                             modeler=nothing,
                             solver=nothing,
@@ -170,8 +176,10 @@ function test_explicit()
                             push!(tested, complete)
                             
                             # Test the actual solve - just verify it returns a solution
-                            result = OptimalControl.solve_explicit(
-                                pb.ocp, init;
+                            result = OptimalControl._solve(
+                                OptimalControl.ExplicitMode(),
+                                pb.ocp;
+                                initial_guess=init,
                                 discretizer=disc,
                                 modeler=mod,
                                 solver=sol,
diff --git a/test/suite/solve/test_solve_dispatch.jl b/test/suite/solve/test_solve_dispatch.jl
