Add brokerage Financial Advisor account services - Feature 9707 fav2

[Farrell-A]

Summary

This PR adds brokerage-neutral Financial Advisor account-state and group-management capabilities to LEAN. The services are optional, immutable at their public boundaries, installed before algorithm initialization, and unavailable to brokerages that do not implement them. FA algorithms can currently have drift in client accounts from algorithm intent that are not visible to LEAN or the algorithm. This PR extends the integration with the IBKR API and adds additional functionalities for FA accounts.

This closes: QuantConnect/Lean#9707
** 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 state of, or manage, individual client accounts in FA
    groups in live trading. Current 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
    from within an algorithm.

• Enhancements:

  • Enables an advisor to manage client onboarding in and out of groups from within an algorithm,
    enabling algorithms to implement end-to-end robo-advisory workflows.
    • 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 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

• Adds immutable account snapshots, account-directory entries, group topology, account positions, unmapped positions, and asynchronous mutation result models.
• Adds optional interfaces for account-state refresh, managed-account group assignment, and complete saved-allocation replacement.
• Exposes snapshot reads, scoped/complete refresh requests, group assignment, and allocation replacement through QCAlgorithm in C# and Python.
• Wires optional services into the engine before Initialize and revokes mutation authority during engine teardown without modifying the protected engine files.
• Adds focused C# and Python interoperability tests for contracts, validation, lifecycle wiring, and decimal allocation input.
• See the attached files for a full inventory.

Compatibility

• Existing brokerages and algorithms are unaffected unless they opt into and implement the new interfaces.
• No existing public member is removed, renamed, retyped, or re-signatured.
• The API remains brokerage-neutral; Interactive Brokers protocol and Gateway behavior live in the companion brokerage PR.

Validation

• dotnet build QuantConnect.Lean.sln in Release configuration: 0 errors.
• Focused C# account-contract, snapshot, lifecycle, and consumer suite: 58 passed, 0 failed.
• Focused Python FA interoperability suite: 11 passed, 0 failed.
• The coordinated four-PR focused suite passed 548/548 .NET/Python cases plus 26/26 IBAutomater Java assertions.
• A C# live lifecycle consumer proved service availability during Initialize, unavailable mutation authority there, and complete/scoped Ready snapshots, then exited cleanly.
• 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. It included eight guarded buy/reverse-sell sequences (16 filled parent orders) and restored the paper estate to zero orders and zero positions.
• Protected files are byte-identical to current upstream: AlgorithmManager.cs, BrokerageTransactionHandler.cs, LocalObjectStore.cs, and Brokerage.cs.

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 this Lean update PR, which adds the brokerage-neutral FA contracts, default-safe LEAN configuration, and publish the corresponding LEAN packages.
3. Merge Lean.Brokerages.InteractiveBrokers update 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. Publish 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: 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#>-