Add unified Interactive Brokers Financial Advisor services - Feature 259 fav2

[Farrell-A]

Summary

Production LEAN can connect to an Interactive Brokers Financial Advisor master and can attach IB FA order properties, but currently does not expose a coherent visibility of the underlying managed accounts and unified Allocation Groups. This PR implements opt-in unified Interactive Brokers Financial Advisor account services and allocation-group routing on top of the brokerage-neutral contracts in the companion LEAN PR. This gives advisers granular visibility and control of client accounts, and allows advisers to ensure that client accounts are managed in alignment with the algorithm intent.

This closes: QuantConnect/Lean.Brokerages.InteractiveBrokers#259
** This is part of a coordinated multi-repo feature release. See the attached files for thorough details**

Use cases

• Solves:

  • FA client accounts cannot identify that stats of, or manage, individual client accounts in FA
    groups in live trading. IBKR FA Group allocation causes drift between algorithm intent and actual
    holdings for individual sub accounts across several inevitable edge cases that are currently invisible.
    • Those edge cases cause high-impact events, like actual live trades in Group A for Clients ABC not
      following intent because Client D added money to their brokerage account.
  • Enables unified discovery and management of FA individual client accounts, aliases, and FA groups.

• Enhancements:

  • Enables an advisor to manage client onboarding in and out of groups, allowing end-to-end robo-advisory management from within the algo.
    • I.e. If new client account A with alias Z is discovered that isn't in a group, make account
      A execute orders to make it in alignment with Group B intent and then move the account to Group B.
    • I.e. If client with account B liquidates part of their account through the brokerage, remove it
      from trading for N days so it doesn't immediately trade what was intentionally liquidated.
  • Enables the safe use of user-specified group allocation methods ContractsOrShares, Ratio, and Percent.
    Downstream effect is to be able to create methods similar to setHoldings for groups in an algo that ensures
    each individual sub account is in alignment with algo intent, and not just allocated based on IBKR computed
    methods that lack realistic case-management.
  • Enables the ability to operate multiple allocation groups from within the same deployment. Orders can be
    routed to groups, or individual client accounts that may or may not be in a group.

What changed

• Propagates the deployment-time unified-groups desired state to IBAutomater before Gateway startup and restart.
• Adds serialized complete/scoped snapshots for managed-account topology, account values, exact cash, positions, aliases, and family codes.
• Batches eligible child financial state through transient named-group account summaries with strict validation, mandatory cancellation, and exact per-account fallback.
• Adds optimistic, version-checked group assignment and complete saved-allocation replacement with semantic readback, ambiguity handling, and reconciliation.
• Routes unified group, deployment-filter, and direct-account orders through shared admission/conversion validation while preserving exact supported quantities.
• Filters FA-service callbacks by request ownership without dropping unrelated legacy account data.
• Adds reconnect recovery, stale-state publication, bounded cancellation recovery, unkeyed-request poisoning, and callback/error correlation.
• Retries a timed-out positions response exactly once after canceling and allowing the old stream to drain, using a fresh request ID. If the second response also times out, the service cancels it, rejects the incomplete refresh, and publishes Failed or Stale; LEAN, the brokerage connection, and the worker continue running, and a later refresh can retry.
• Adds comprehensive unit coverage for protocol ownership, snapshot collection, mutation, group order routing, recovery, and compatibility.
• Validates mapped equity currency and primary-exchange identity; mismatched IB contracts remain visible as unmapped positions instead of being assigned to an incorrect LEAN symbol.
• See the attached files for a full inventory.

Compatibility

• Unified FA behavior is opt-in and defaults to disabled.
• Non-FA deployments and legacy FA deployments retain established behavior.
• Existing public constructors remain available; no existing public member is removed or re-signatured.
• Depends on the intentional FA-only QuantConnect.IBAutomater 2.0.93 upgrade and the companion LEAN FA contracts.

Validation

• Coordinated Release build against the fav2 LEAN source and a freshly packed, isolated QuantConnect.IBAutomater 2.0.93 feed: 0 errors.
• Focused brokerage FA core suite: 461 passed, 0 failed.
• Focused brokerage factory suite: 15 passed, 0 failed.
• Combined focused brokerage FA/factory coverage: 476 passed, 0 failed, including the three position-timeout retry cases.
• The coordinated four-PR focused suite passed 543/543 .NET/Python cases plus 16/16 IBAutomater Java assertions.
• The coordinated live-paper campaign recorded 90 final certification outcomes: 87 reached the real Gateway/API and three deliberately rejected invalid deployment configurations before Gateway startup. Eight guarded buy/reverse-sell sequences produced 16 filled parent orders, exact expected child allocations, terminal snapshot reconciliation, and full restoration.
• Targeted live-paper timeout verification passed: the first positions response was withheld, production canceled it, retried with a fresh request ID after 251 ms, accepted the expected retry rows, and published a Ready two-account snapshot with no IB errors. Independent pre/post audits showed zero open orders, zero positions, and unchanged topology.
• InteractiveBrokersBrokerage.cs matches current upstream concurrency counts: 17 lock ( / 3 Interlocked. / 0 Task.Run.

The pre-existing Composer smoke test was not part of the focused run because its implicit job is invalid when no local IB trading-mode configuration is supplied. The focused suites and guarded live-paper matrix cover the FA-specific factory-to-Gateway behavior.

Related PRs and sequencing

The coordinated PRs can be reviewed concurrently, but their release has package and platform dependencies:

1. Merge IBAutomater update and publish QuantConnect.IBAutomater 2.0.93.
2. Merge Lean update, which adds the brokerage-neutral FA contracts, default-safe LEAN configuration, and publish the corresponding LEAN packages.
3. Merge this IB Brokerage PR against the published IBAutomater and LEAN package surfaces.
4. Add the required deployment schema/UI inputs so Local Platform, LEAN CLI, direct cloud API, and QuantConnect Cloud deployments can emit the exact brokerage settings.
5. Merge Documentation-update in alignment with the released implementations and deployment surface.
   The hosted deployment schema/UI must expose the unified-groups and group-management inputs under their exact brokerage-data keys. That platform work is external to this repository.

IBAutomater version: Updated 2.0.93 to be in alignment with the linked PRs. Update required with version drift.

IBAutomater PR ──> publish 2.0.93 ───────────────┐
                                                 ├──> IB brokerage PR ─> brokerage release
LEAN PR ────────> publish LEAN 2.5.x packages ───┘                        │
                                                                          ├─> expose deployment inputs
Platform cloud schema/UI work (add 2 inputs)──────────────────────────────┘
                                                                          │
Documentation PR ─────────────────────────────────────────────────────────┘

Files attached explaining the full fav2 linked PR scope across repos, and testing conducted

fav2_live_verification_report.md
fav2_enhancement_summary.md
enhancement_change_inventory.md
enhancement_goals_findings.md
enhancement_scope.md
test_file_scope.md

Documentation

This update requires documentation changes. A separate PR is open for the documentation changes.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• Refactor (non-breaking change which improves implementation)
• Performance (non-breaking change which improves performance. Please add associated performance test and results)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Non-functional change (xml comments/documentation/etc)

Checklist:

• My code follows the code style of this project.
• I have read the CONTRIBUTING document.
• I have added tests to cover my changes.
• All new tests passed, along with the existing tests that passed without the feature.
• My branch follows the naming convention bug-<issue#>- or feature-<issue#>-