SymbolClassifier

What it does

Boot-time symbol-class lookup. SymbolClassifier answers the question "is SPX a stock, an index, or an option-bearing root?" for every downstream routing decision — which Contract::* constructor to use, which tier quota to charge, which upstream historical endpoint to call.

Hydration

Three boot-time upstream historical endpoints populate the classifier:

Source	Result
Upstream stock_list_symbols call	Equity universe.
Upstream option_list_symbols call	Option-chain universe.
Upstream index_list_symbols call	Index universe.

Three HashSet<String> populated once at Client::connect. The classifier is sealed after construction; reads are uncontended.

Lookups

Method	Returns
is_stock(symbol) -> bool	Equity ticker membership.
is_index(symbol) -> bool	Index ticker membership.
has_options(symbol) -> bool	Option-bearing root membership.
classify(symbol) -> SymbolClass	Discriminated Stock / Index / Option / Unknown.

Consumers

• Routing — every subscription consults the classifier to pick a Contract shape.
• Tier gating — the per-asset quota table charges different quotas per asset class.
• Historical endpoint selection — the default upstream historical source picks stock_history_trade_quote vs index_history_price vs the per-contract option endpoint by classifier verdict.

Why boot-time

The upstream symbol universe changes once per session. Hydrating at boot keeps the per-tick hot path free of lookups against a moving target and pins the classifier's behaviour for the whole subscription session — material for the replay-parity contract.