Private API

struct RoutingContext

Internal struct to encapsulate routing context.

Holds precomputed mappings used during option routing to avoid passing multiple dictionaries around and improve performance.

Fields

• strategy_to_family::Dict{Symbol, Symbol}: Maps strategy IDs to their family names
• option_owners::Dict{Symbol, Set{Symbol}}: Maps option names to the set of families that own them

Notes

• This struct is immutable and created once per routing operation
• Precomputing these mappings avoids repeated lookups during routing
• Used internally by the routing helper functions

_build_routed_result(
    action_options::Dict,
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}
) -> NamedTuple{(:action, :strategies), <:Tuple{NamedTuple, NamedTuple}}

Build the final routed result structure.

Converts the routing dictionary and action options into the final NamedTuple format expected by the routing system API.

Arguments

• action_options::Dict: Dictionary of extracted action options with OptionValue wrappers
• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary with options per family

Returns

• NamedTuple: Final result with structure (action=..., strategies=...) where:
  • action: NamedTuple of action options with OptionValue wrappers
  • strategies: NamedTuple of strategy options per family (raw values)

Notes

• Converts routing dictionary to nested NamedTuple structure
• Preserves OptionValue wrappers for action options
• Strategy options remain in their raw form for downstream processing
• This is the final step in the routing pipeline

_build_routing_context(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> CTSolvers.Orchestration.RoutingContext

Build routing context with precomputed mappings.

Creates a RoutingContext containing strategy-to-family and option ownership maps to optimize routing performance by avoiding repeated computations.

Arguments

• resolved::ResolvedMethod: Resolved method containing strategy information
• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types
• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

Returns

• RoutingContext: Context containing precomputed mappings for efficient routing

Notes

• Precomputes expensive mapping operations once per routing call
• Strategy-to-family mapping enables quick family lookup from strategy ID
• Option ownership mapping enables quick validation of option routing

_check_action_option_shadowing(
    action_options::Dict,
    option_owners::Dict{Symbol, Set{Symbol}}
)

Check for action option shadowing and emit info messages.

Detects when a user-provided action option also exists in strategy metadata, which means the action option "shadows" the strategy option. Emits informational messages to help users understand the shadowing.

Arguments

• action_options::Dict: Dictionary of extracted action options with OptionValue wrappers
• option_owners::Dict{Symbol, Set{Symbol}}: Maps option names to families that own them

Returns

• Nothing: This function only emits info messages

Notes

• Only checks user-provided options (source === :user), not default values
• Provides helpful guidance on using route_to() for specific strategy targeting
• Uses @info to emit messages without interrupting execution

_collect_suggestions_across_strategies(
    key::Symbol,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry;
    max_suggestions
) -> Vector{@NamedTuple{primary::Symbol, aliases::Tuple{Vararg{Symbol}}, distance::Int64}}

Collect option suggestions across all strategies in the method, deduplicated by primary name. Returns the top max_suggestions results sorted by minimum Levenshtein distance.

_error_ambiguous_option(
    key::Symbol,
    value,
    owners::Set{Symbol},
    strategy_to_family::Dict{Symbol, Symbol},
    source_mode::Symbol,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
)

Helper to throw an informative error when an option belongs to multiple strategies and needs disambiguation. Suggests using route_to syntax with specific examples for the conflicting strategies.

_error_unknown_option(
    key::Symbol,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    strategy_to_family::Dict{Symbol, Symbol},
    registry::CTSolvers.Strategies.StrategyRegistry
)

Helper to throw an informative error when an option doesn't belong to any strategy. Lists all available options for the active strategies to help the user.

_initialize_routing_dict(
    families::NamedTuple
) -> Dict{Symbol, Vector{Pair{Symbol, Any}}}

Initialize the routing dictionary structure.

Creates an empty routing dictionary with one entry per family to collect routed options during the routing process.

Arguments

• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types

Returns

• Dict{Symbol, Vector{Pair{Symbol, Any}}}: Empty routing dictionary with entries for each family

Notes

• Each family gets an empty Vector{Pair{Symbol, Any}} to collect routed options
• The structure enables efficient accumulation of options per family
• Used as the starting point for routing operations

_route_auto!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    value,
    context::CTSolvers.Orchestration.RoutingContext,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry,
    source_mode::Symbol
)

Route a single option automatically based on ownership.

Handles options without explicit disambiguation by checking ownership:

• Unknown option → error with helpful suggestions
• Single owner → auto-route to that family
• Multiple owners → ambiguity error requiring disambiguation

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate
• key::Symbol: Option name being routed
• value::Any: Option value to route
• context::RoutingContext: Precomputed routing mappings
• resolved::ResolvedMethod: Resolved method containing strategy information
• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types
• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup
• source_mode::Symbol: Controls error verbosity (:description or :explicit)

Returns

• Nothing: Modifies routed in-place

Throws

• Exceptions.IncorrectArgument: If option is unknown or ambiguous

Notes

• Uses option ownership mapping to determine routing destination
• Provides detailed error messages with suggestions for unknown/ambiguous options
• Auto-routing only occurs when option has exactly one owner

_route_single_option!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    raw_val,
    context::CTSolvers.Orchestration.RoutingContext,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry,
    source_mode::Symbol
)

Route a single option (dispatcher).

Determines whether the option has explicit disambiguation and routes accordingly. Acts as the main dispatcher for option routing logic.

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate
• key::Symbol: Option name being routed
• raw_val::Any: Raw option value (may be wrapped in RoutedOption)
• context::RoutingContext: Precomputed routing mappings
• resolved::ResolvedMethod: Resolved method containing strategy information
• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types
• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup
• source_mode::Symbol: Controls error verbosity (:description or :explicit)

Returns

• Nothing: Modifies routed in-place

Notes

• Extracts strategy disambiguations from RoutedOption values if present
• Delegates to routewith_disambiguation! for explicit routing
• Delegates to routeauto! for automatic routing
• Central point for all option routing decisions

_route_with_disambiguation!(
    routed::Dict{Symbol, Vector{Pair{Symbol, Any}}},
    key::Symbol,
    disambiguations::Vector{Tuple{Any, Symbol}},
    context::CTSolvers.Orchestration.RoutingContext,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
)

Route a single option with explicit disambiguation.

Handles options wrapped in route_to() with explicit strategy targets. Validates that the target family owns the option or that bypass is used.

Arguments

• routed::Dict{Symbol, Vector{Pair{Symbol, Any}}}: Routing dictionary to populate
• key::Symbol: Option name being routed
• disambiguations::Vector{Tuple{Any, Symbol}}: List of (value, strategy_id) pairs
• context::RoutingContext: Precomputed routing mappings
• resolved::ResolvedMethod: Resolved method containing strategy information
• families::NamedTuple: NamedTuple mapping family names to AbstractStrategy types
• registry::Strategies.StrategyRegistry: Strategy registry for metadata lookup

Returns

• Nothing: Modifies routed in-place

Throws

• Exceptions.IncorrectArgument: If option is unknown or routed to wrong family

Notes

• BypassValue allows routing unknown options without validation
• Validates option ownership to prevent incorrect routing
• Provides helpful error messages for misrouted options

_separate_action_and_strategy_options(
    kwargs::NamedTuple,
    action_defs::Vector{<:CTSolvers.Options.OptionDefinition}
) -> Tuple{Dict{Symbol, CTSolvers.Options.OptionValue}, NamedTuple}

Separate action options from strategy options.

Filters out RoutedOption values from action extraction, processes action definitions, and re-integrates RoutedOption values for strategy routing.

Arguments

• kwargs::NamedTuple: All keyword arguments (action + strategy options mixed)
• action_defs::Vector{<:Options.OptionDefinition}: Definitions for action-specific options

Returns

• Tuple{Dict, NamedTuple}: (actionoptions, strategykwargs) where:
  • action_options: Dict of extracted action options with OptionValue wrappers
  • strategy_kwargs: NamedTuple of remaining kwargs for strategy routing

Notes

• RoutedOption values are excluded from action extraction and preserved for strategy routing
• Action options are wrapped in OptionValue with source tracking
• Strategy options remain in their original form for further processing

_warn_unknown_option_permissive(
    key::Symbol,
    strategy_id::Symbol,
    family_name::Symbol
)

Helper to warn when an unknown option is routed in permissive mode.

build_alias_to_primary_map(
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> Dict{Symbol, Symbol}

Build a mapping from alias names to their primary option names for all strategies in the method.

Arguments

• resolved::ResolvedMethod: Resolved method information (active strategies)
• families::NamedTuple: NamedTuple mapping family names to abstract types
• registry::Strategies.StrategyRegistry: Strategy registry

Returns

• Dict{Symbol, Symbol}: Dictionary mapping alias => primary_name

Example

resolved = resolve_method(method, families, registry)
alias_map = build_alias_to_primary_map(resolved, families, registry)

See also: build_option_ownership_map, resolve_method