docs

Author: rbeeli

docs/src/glossary.md

@@ -51,10 +51,10 @@ Commission is specified by the active broker profile and converted from quote to
 
 ## Realized P&L
 
-Realized P&L is produced when exposure decreases (`realized_qty`) and is recorded gross of commissions as `fill_pnl_settle`.
+`fill_pnl_settle` is gross fill-settled P&L (commissions excluded).
 
-For principal-exchange settlement, `fill_pnl_settle` equals closed-position realized P&L.
-For variation-margin settlement, it includes both open mark-to-fill settlement and reduce-basis settlement.
+For principal-exchange settlement, `fill_pnl_settle` equals closed-position realized P&L when exposure decreases (`realized_qty`).
+For variation-margin settlement, it includes both open mark-to-fill settlement and reduce-basis settlement, and fills reset `avg_settle_price` to the current mark.
 
 Commissions are separate via `commission_settle`. The actual fill cash movement is always `cash_delta_settle`; for variation margin, `cash_delta_settle = fill_pnl_settle - commission_settle`.
 

docs/src/pitfalls.md

@@ -6,7 +6,7 @@
 - Expiry/liquidation helpers use stored side-aware quotes (`last_bid`/`last_ask`); keep marks updated with `update_marks!`.
 - Multi-currency equity depends on `ExchangeRates` being updated.
 - Register non-base currencies via `register_cash_asset!(acc, CashSpec(:EUR))`.
-- For variation-margin instruments, trade-level additive fill P&L is `fill_pnl_settle` (gross) and `cash_delta_settle` (net of commission).
+- For variation-margin instruments, fills immediately settle to the current mark basis: execution-to-mark (`mark - fill`) hits cash on the fill, and post-fill `avg_settle_price` is the mark. Trade-level additive fill amounts are `fill_pnl_settle` (gross) and `cash_delta_settle` (net of commission).
 - `OrderRejectError` rejection semantics are mainly for `fill_order!`; expiry/liquidation helpers send close-only synthetic fills (`fill_qty = -position_qty`) with `allow_inactive=true`, so they do not hit incremental-margin rejection (`inc_qty == 0`).
 - Fastback currently has no separate bankruptcy state; forced closes can still leave negative balances/equity in stressed scenarios.
 - The package contains optionally loaded `Plots.jl` extension functions (some functions additionally require `StatsPlots.jl`).

src/logic.jl

@@ -200,6 +200,8 @@ restarts the borrow-fee clock based on the post-fill position.
 Throws `OrderRejectError` when the fill is rejected (inactive instrument or risk checks).
 Requires bid/ask/last to deterministically value positions and compute margin during fills.
 Risk checks only reject exposure-increasing fills (`inc_qty != 0`).
+For variation-margin instruments, fills immediately settle execution-to-mark into cash and reset
+the settlement basis (`avg_settle_price`) to the current mark.
 
 Commission is broker-driven by default via `acc.broker`.
 """