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.

Notes

• Also searches the registry for strategies not in the current method that have this option, suggesting the user may have chosen the wrong strategy.

_find_option_in_registry(
    key::Symbol,
    resolved::CTSolvers.Orchestration.ResolvedMethod,
    families::NamedTuple,
    registry::CTSolvers.Strategies.StrategyRegistry
) -> Vector{Tuple{Symbol, Symbol}}

Search for an option in all strategies of the registry, excluding strategies in the current method.

This helper function checks if an unknown option exists in strategies that are not part of the current method, enabling helpful error messages that suggest the user may have chosen the wrong strategy.

Arguments

• key::Symbol: The option name to search for
• resolved::ResolvedMethod: Resolved method containing current strategy IDs
• families::NamedTuple: NamedTuple mapping family names to family types
• registry::Strategies.StrategyRegistry: Strategy registry containing all registered strategies

Returns

• Vector{Tuple{Symbol, Symbol}}: Vector of (strategyid, familyname) tuples for strategies that have this option

Notes

• Strategies in the current method are excluded from the search
• Uses try/catch around metadata() for robustness against incomplete strategy definitions
• Results are not ordered; caller should sort if needed

_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