Add broker-neutral derivative identity and IBKR OPT/FOP discovery capabilities

[felipecsl]

Context

The recent NQ/NDXP options workflow required raw IBKR scripts to discover exact contracts. The current shared BrokerClient intentionally covers basic account and market-data reads, while option commands bypass it through the full Schwab client. The installed IBKR option model is OSI/equity-option oriented and does not carry enough identity for futures options or alternate index trading classes.

Examples that must be represented without symbol heuristics:

• NQ futures options: assetClass=FOP, trading class such as QN3, exchange, multiplier 20.
• NDX vs NDXP: same underlying family but different trading class and settlement behavior.
• Broker conids are useful for immediate API calls but must not become the durable domain identity.

Goal

Introduce capability-specific derivative contracts and extend the IBKR client boundary so the CLI can resolve equity options, index options, and futures options consistently.

Proposed model

A normalized derivative identity should include at least:

• asset class (OPT or FOP)
• underlying
• expiration
• strike
• right
• trading class
• exchange
• multiplier
• settlement/exercise metadata when available
• optional broker-scoped contract reference

Keep durable semantic identity separate from IBKR conids/OCC encoding.

Prefer capability interfaces such as DerivativeDiscoveryClient over adding every optional operation to the existing shared BrokerClient.

Scope

• Define normalized derivative request, contract, expiry, quote, and data-availability types.
• Generalize @huskly/ibkr-client discovery beyond OSI/OPT assumptions.
• Support the stateful IBKR security-definition discovery flow for OPT and FOP.
• Resolve exact trading class, exchange, multiplier, and broker contract reference.
• Normalize missing, delayed, frozen, and unavailable market data.
• Add an adapter/capability resolver in this repository.
• Document which fields are durable and which are broker-local.
• Do not add live order submission in this issue.

Acceptance criteria

• NQ Aug 21 2026 puts can be resolved as FOP contracts with an explicit trading class and multiplier.
• NDX and NDXP contracts with the same expiry/strike remain distinguishable.
• Contract selection fails closed when trading class or contract identity is ambiguous.
• Conids remain at the IBKR adapter/client boundary.
• Missing or unusable chains produce explicit errors rather than empty-success output.
• Unit fixtures cover NQ FOP and NDX/NDXP resolution.
• Public TypeScript APIs contain no any and compile under the repository's strict settings.
• No broker write endpoint is called by discovery tests.

Non-goals

• Spread payoff calculations.
• What-If/order preview.
• Live order submission.
• Generic raw IBKR request access from the CLI.