Target: QuantConnect/Lean

Issue: QuantConnect/Lean#6360

PR: QuantConnect/Lean#9539

Field Lab: https://github.com/scarab-systems/scarab-field-lab

This field test targeted an option portfolio target sizing bug in QuantConnect Lean.

The issue concerned PortfolioTarget.Percent, which is used to calculate target quantities from a requested portfolio percentage.

The visible failure was serious for option strategies:

• a user requested a target percentage for an option position
• Lean calculated a target quantity
• the final filled position could exceed the requested target weight
• the discrepancy was tied to the option bid/ask spread
• long option targets could be sized from a mid/last price even though the executable buy side was the ask

That is not just a small math mismatch.

For portfolio construction, target sizing is part of the risk contract.

If a user asks for a 10% option target, but the final filled position can land materially above that target because the sizing path used the wrong side of the quote, the engine has crossed a real boundary.

The diagnostic question was not:

How do we make all security target sizing use bid and ask?

The better question was:

Where does Lean price option premium/margin for target quantity calculation, and which quote side should that option-specific path use when quotes are available?

Field Lab record

The public case record for this field test is available in the Scarab Field Lab:

https://github.com/scarab-systems/scarab-field-lab

SDS result

This field test was recorded as a diagnostic-proof-and-repair case against QuantConnect Lean.

The useful result was a bounded pricing boundary.

The failure touched several tempting surfaces:

• portfolio construction
• PortfolioTarget.Percent
• buying power calculation
• option margin pricing
• quote data
• bid/ask spread
• order fill behavior
• final portfolio weight

That is exactly the kind of bug where a repair can drift.

A patch could try to change portfolio construction broadly.

A patch could try to change generic buying power behavior for every security type.

A patch could try to compensate after fill.

A patch could try to adjust target quantities in the execution layer.

But the owned repair surface was narrower.

For options, target sizing depends on the buying power model’s initial margin requirement. That option-specific margin path was using security.Price, which may reflect a last, mark, or mid-like value instead of the executable side of the quote.

For a long option target, the executable buy side is the ask when an ask is available.

For a short option target, the executable sell side is the bid when a bid is available.

That is the repair boundary.

Failure shape

The failure shape was a quote-side mismatch.

The user requested a target percentage.

Lean calculated a quantity using an option margin pricing path.

That path used security.Price.

But for options, the last or mark price can differ materially from the ask or bid.

So a long option target could be sized as if the option cost less than the price actually required to buy it.

Then, when the order filled closer to the ask, the final holdings cost could exceed the requested target weight.

In plain English:

the target calculation used a price that was not the executable buy-side price

That is why the error scaled with the bid/ask spread.

The wider the spread, the larger the possible gap between the sizing price and the actual fill-side price.

That makes this a finance-engine correctness issue, not a cosmetic pricing issue.

Boundary

The boundary here is:

option target margin pricing versus generic security price behavior

Lean should not need to rewrite PortfolioTarget.Percent for every security type to handle this case.

It should not need to change generic buying power behavior for all assets.

It should not need to force all target sizing to use quote-side logic universally.

But options have a specific pricing reality.

When an option quantity is positive, the target is increasing long exposure or buying premium. If an ask is available, the ask is the relevant executable side.

When an option quantity is negative, the target is selling or reducing from the opposite side. If a bid is available, the bid is the relevant executable side.

When quotes are not available, Lean should preserve the existing fallback behavior.

That is the clean boundary:

• positive option quantity: use ask when available
• negative option quantity: use bid when available
• no quote available: fall back to existing last/mark behavior
• keep the change local to option margin pricing

That is the repair lane.

What changed

The PR updates option margin pricing so target option quantities use available executable quote prices.

The change is intentionally local:

• positive option quantities use the ask price when available
• negative option quantities use the bid price when available
• existing last/mark price behavior remains the fallback when quotes are unavailable

That means the repair does not change generic buying power behavior for other security types.

It does not rewrite portfolio target construction.

It does not alter execution models.

It corrects the option-specific pricing path used when calculating premium/margin value for a target option quantity.

The patch also adds regression coverage for both sides of the option quote boundary:

• long-option ask pricing
• short-option bid pricing

That matters because the bug was not simply “use ask.”

The correct side depends on the sign of the target quantity.

A long-side target and a short-side target should not be priced the same way.

Why this was not a generic portfolio construction fix

The visible symptom appeared through PortfolioTarget.Percent.

That makes it tempting to repair the portfolio construction layer.

But PortfolioTarget.Percent was not the true ownership surface.

The target helper depends on the security buying power model to calculate the quantity needed to reach a portfolio percentage.

For options, the buying power model’s initial margin path is where the premium/margin value is priced.

That is where the quote-side mismatch lived.

So the repair stayed there.

That is important.

Portfolio construction should not need to know every option bid/ask pricing detail.

Execution should not be responsible for repairing a quantity that was undersized or oversized before the order was placed.

The option margin model already owns option-specific premium/margin pricing.

That is where the patch belongs.

Why the fallback mattered

The fallback behavior is important.

The repair does not assume that bid and ask are always populated.

Market data can be incomplete.

Backtests can have different data shapes.

Some option securities may not have fresh quotes at the exact moment target sizing runs.

So the patch uses executable quote prices when available, but preserves the existing last/mark behavior when quotes are unavailable.

That keeps the repair narrow and compatible.

It improves the case where quote data is present without breaking the existing behavior for cases where quote data has not been populated.

That is the right kind of platform patch:

use better truth when the engine has it, preserve the old path when it does not

Why the diagnostic result mattered

This case is useful because it sits inside a high-stakes financial calculation.

A target percentage is not just a display value.

It is part of the algorithm’s risk expression.

If the engine calculates the wrong quantity from that target, the algorithm can take more exposure than requested.

That matters especially for options because spreads can be wide, prices can move quickly, and executable quote-side pricing can differ meaningfully from last or mark values.

The diagnostic posture helped keep the repair framed around the actual contract:

• the user expresses a target weight
• Lean calculates a target quantity
• the option margin path prices the quantity
• available quote data should align that price with the executable side
• the final position should not exceed the requested target because sizing used a stale or non-executable price

That framing kept the patch small.

It avoided a broad portfolio construction rewrite.

It avoided execution-layer compensation.

It avoided changing generic security behavior.

It repaired the option-specific margin pricing boundary.

Validation

Validation was completed in QuantConnect’s foundation container.

The release build passed.

Focused option-margin tests passed:

41/41

The new regression coverage includes:

• long-option ask pricing
• short-option bid pricing

A full local arm64 suite run had two unrelated failures.

Both failures reproduced on unchanged upstream master in the same foundation-container environment, so they were documented in the PR rather than claimed as branch failures.

That is the correct validation posture.

The focused option-margin coverage passed, the release build passed, and the unrelated local full-suite failures were not hidden or misrepresented.

At the time of this report, the PR is reopened and marked ready for review.

Field test result

This was a bounded option margin pricing repair candidate for QuantConnect Lean.

The issue reduced to:

• PortfolioTarget.Percent calculates target quantities from a requested portfolio percentage
• for options, that calculation depends on initial margin pricing
• the existing option margin path used security.Price
• security.Price could reflect a last, mark, or mid-like price
• long option targets could therefore be sized below the actual ask-side cost
• the final filled position weight could exceed the requested target
• the repair uses ask for positive option quantities when available
• the repair uses bid for negative option quantities when available
• the existing last/mark behavior remains the fallback when quotes are unavailable
• focused tests cover long ask pricing and short bid pricing
• release build and focused option-margin validation passed

That is the repair lane.

This patch does not claim to redesign portfolio construction.

It does not claim to change generic buying power behavior for all security types.

It does not claim to alter execution models.

It does not claim to guarantee exact final weights under every fill condition.

It fixes the option-specific margin pricing boundary where target quantity calculation should use the executable side of the quote when that quote is available.

Public claim

The correct claim for this field test is:

Scarab/SDS helped drive a bounded repair candidate for QuantConnect/Lean#6360, where PortfolioTarget.Percent could size option targets using security.Price instead of the executable side of the quote. For long option targets, that could understate cost when the ask was higher and allow the final position weight to exceed the requested target. The upstream PR updates option margin pricing so positive option quantities use the ask price when available, negative option quantities use the bid price when available, and existing last/mark behavior remains the fallback when quotes are unavailable. Release build validation passed, focused option-margin tests passed 41/41, and new regression tests cover long-option ask pricing and short-option bid pricing. This does not claim to redesign portfolio construction or generic buying power behavior; it fixes the option margin pricing boundary used during target quantity calculation.

Disclosure: This field report was prepared with AI-assisted editing from my own field-test notes, public issue and PR records, validation summary, and Field Lab record. The technical claims and final wording were reviewed before publication.