Positions, PnL & Real-Time Risk

For one instrument, keep two integers. Position q is signed lots: + long, − short. Cash is −Σ signed_qty × price over every fill: buying costs cash, selling brings it in. Then at any mark price M:

total PnL = cash + q · M          (times the contract multiplier)

That's exact in integer arithmetic and convention-free. It's the number to check limits against, and the number that has to reconcile with your clearing statements.

Realized versus unrealized splits that total, and the split depends on how you match closing trades against opening ones:

• Average cost: one running average entry price. Closing trades realize (price − avg) × closed. This is today's drill.
• FIFO: close the oldest open lots first. Each lot keeps its own entry price.
• LIFO and others: other matching rules, sometimes required for tax or regulatory reporting.

Buy 1 at 100, buy 1 at 110, sell 1 at 120. Average cost realizes 120 − 105 = 15. FIFO realizes 120 − 100 = 20. The total at any mark is identical under both. Choose a convention deliberately, document it, and never set a limit on realized PnL alone. A strategy holding a large unrealized loss can show a healthy realized PnL right up to the moment it closes the position.

A fill does one of five things to a position. It opens one from flat, adds to it on the same side, reduces it, closes it to exactly zero, or flips it, closing the whole position and opening the remainder on the other side in one fill. The average-cost rules:

• Open or add: the new average is the quantity-weighted average of the old position and the fill.
• Reduce or close: realize (px − avg) × closed, signed by the position (a short profits when the price is below its average). The average doesn't change, and it resets when you're flat.
• Flip: realize on the whole old position, then the remainder opens at the fill price.

Flips are where hand-written position keepers go wrong. The fill quantity has to be split into a closing part and an opening part, and the remainder must get a fresh average, not a blend with the old one.

/// Average-cost position keeping for one instrument. Quantities are signed
/// lots (+ long, − short); prices are integer ticks.
pub struct Position {
    qty: i64,
    avg_px: f64,
    realized: f64,
    cash: i64,
}

impl Position {
    pub fn new() -> Self {
        todo!()
    }

    /// Apply a fill: signed_qty > 0 buys, < 0 sells, at `px`.
    ///  • flat or adding to the same side: avg_px becomes the
    ///    quantity-weighted average of the old position and the fill;
    ///  • reducing: realize (px − avg_px) per lot closed, with the sign of
    ///    the position (a short profits when px < avg_px); avg_px is
    ///    unchanged, and resets to 0.0 when you end flat;
    ///  • flipping (selling more than you are long, or vice versa): close
    ///    the whole position as above, then open the remainder at px.
    /// Also keep `cash` exactly: buying costs px·qty, selling earns it.
    pub fn fill(&mut self, signed_qty: i64, px: i64) {
        todo!()
    }

    pub fn qty(&self) -> i64 {
        todo!()
    }

    /// Average entry price of the open position; 0.0 when flat.
    pub fn avg_px(&self) -> f64 {
        todo!()
    }

    /// Realized PnL so far (average-cost convention).
    pub fn realized(&self) -> f64 {
        todo!()
    }

    /// Unrealized PnL at `mark`: qty · (mark − avg_px).
    pub fn unrealized(&self, mark: i64) -> f64 {
        todo!()
    }

    /// Total PnL at `mark`, exact and convention-free: cash + qty · mark.
    /// Invariant: realized + unrealized(mark) ≈ total(mark).
    pub fn total(&self, mark: i64) -> i64 {
        todo!()
    }
}

The drill keeps the average price in f64 because an average of integer prices generally isn't an integer. Production systems handle this in different ways: fixed-point decimals with a documented rounding rule, the open cost kept as an exact integer next to the quantity, or rationals. Whichever you choose, keep the exact cash and qty as the source of truth. If the derived numbers ever disagree with them, the derived numbers are wrong.

Unrealized PnL depends on the mark, and choosing it is a risk decision:

• Last trade: simple, but goes stale in a quiet market and can be moved by a single small print.
• Mid: the usual default for liquid instruments. Undefined for a one-sided book (week 41).
• Liquidation value: longs marked at the bid, shorts at the ask. Conservative: it's roughly what you'd get if you had to exit now, before market impact.
• Settlement price: the exchange's official daily price. For futures it determines daily variation margin, so it's the mark your clearing firm actually uses.

Whichever you choose, guard against bad marks. If the book is crossed, the data is stale or a price jumps by many standard deviations, hold the last good mark and raise an alert. Otherwise one bad tick can trigger a loss limit and halt trading for a move that never happened.

Multipliers convert price points into money. One E-mini S&P 500 future is $50 × the index, so a 10-point move on 2 contracts is $1,000. Forgetting the multiplier is the classic bug that understates risk by 50×.

Updating has to be O(1) per tick. A tick for one instrument changes that instrument's contribution and nothing else, so update the running totals by the delta: Δpnl = mult × q × (new − old), and for gross exposure, mult × (|q·new| − |q·old|). Re-summing thousands of instruments on every tick makes the hot path proportional to the size of the portfolio.

#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Breach {
    MaxLoss,
    MaxGross,
}

#[derive(Clone, Copy, Debug)]
pub struct Limits {
    /// Breach when total PnL ≤ −max_loss.
    pub max_loss: i64,
    /// Breach when gross exposure > max_gross.
    pub max_gross: i64,
}

/// Positions and PnL across instruments, marked to market on every tick.
/// Every update must be O(1): a portfolio can hold thousands of
/// instruments and ticks arrive for one at a time.
pub struct Portfolio {
    // Your fields. Per instrument you need at least: multiplier, mark,
    // qty, cash. Then keep running totals for pnl, gross and net.
}

impl Portfolio {
    /// One slot per instrument: contract multiplier and initial mark.
    pub fn new(multipliers: Vec<i64>, marks: Vec<i64>, limits: Limits) -> Self {
        todo!()
    }

    /// We traded `signed_qty` (+ buy, − sell) of `inst` at `px`. The mark
    /// does not move. Returns the breach (if any) after the update.
    pub fn on_fill(&mut self, inst: usize, signed_qty: i64, px: i64) -> Option<Breach> {
        todo!()
    }

    /// New mark for `inst`. O(1): update the running totals by the delta
    /// for this instrument only. Returns the breach (if any) after it.
    pub fn on_tick(&mut self, inst: usize, mark: i64) -> Option<Breach> {
        todo!()
    }

    /// Σ mult · (cash + qty · mark)
    pub fn pnl(&self) -> i64 {
        todo!()
    }

    /// Σ mult · |qty · mark|
    pub fn gross(&self) -> i64 {
        todo!()
    }

    /// Σ mult · qty · mark
    pub fn net(&self) -> i64 {
        todo!()
    }

    /// Latched kill switch: true once any update has returned a breach,
    /// and it stays true even if the breach clears. (MaxLoss is checked
    /// before MaxGross.)
    pub fn killed(&self) -> bool {
        todo!()
    }
}

Limits apply at several levels: per instrument, per account, per strategy or desk, and firm-wide. They use different measures:

• Net exposure Σ q·M·mult: the directional bet. A long future hedged by a short in a correlated future nets out.
• Gross exposure Σ |q·M·mult|: how much you'd have to unwind. Hedged books can still have huge gross, which matters when the hedge stops working or liquidity disappears.
• Per underlying. Positions in different instruments on the same underlying (future, ETF, basket) belong together. Options would need delta and the other Greeks, which is beyond this week, but the same aggregation structure applies.

Arrange limits hierarchically: a fill updates its account, which updates the desk, which updates the firm, each with its own limits. With incremental deltas the cost stays O(depth of the hierarchy) per fill.

Then reconcile. Your internal position is what you think you did. Exchanges offer drop copy sessions that send an independent copy of every execution, and the clearing firm's statements are the final authority. Compare continuously during the day with drop copy, and at the end of the day with clearing. Any difference is an incident, because it means something (a missed fill, a duplicate, a wrong multiplier) is making your risk view wrong.

Detecting a breach is the easy part. What happens next has to be designed in advance, because nobody will have time to think when it happens:

1. Latch. The kill state stays set until a human resets it, even if the condition clears on the next tick. A price that wobbles around the limit must not switch trading on and off repeatedly.
2. Block new orders for the account immediately. That's week 15's kill switch, now triggered by post-trade state.
3. Cancel resting orders. Many exchanges offer mass-cancel or cancel-on-disconnect, and your exchange should too. Make cancel-all idempotent: sending it twice must be safe, because under stress it will be.
4. Don't flatten automatically without a policy. Aggressively closing a large position in the conditions that just caused the loss can make it much worse. Whether to flatten, hedge or hold is a decision for a person, with information, unless the policy says otherwise and has been tested.
5. Alert with context: what breached, by how much, the positions, the last N fills, and the marks used.

Detection time is part of the design. Checking limits on every fill and every tick, as today's drill does, means a breach is caught within one event. Checking on a timer every second gives a runaway strategy up to a second of trading, and Knight's 45 minutes shows how much damage that kind of window allows.

Position keeping sits on the exchange's critical path. Every trade updates two accounts, and every market-data tick moves marks. To stay within a budget of tens of nanoseconds:

• Dense state. AccountId and InstrumentId are small integers, so index a flat array of (account, instrument) slots directly, or one array per account. A default HashMap uses SipHash, which costs tens of ns per lookup. If you do need a map, use a faster hasher and pre-size it.
• Both sides of each trade. Each Trade event names a taker and a maker order, not accounts. Keep an order → account index, populated when orders are accepted (week 27's slab works well here). One fill then touches two position slots plus the hierarchy totals.
• Integer money, wide enough. Price ticks × quantity × multiplier can overflow i64 for large notionals. Do the per-fill arithmetic in i64 where the ranges are proven small, and accumulate notional and firm-wide totals in i128.
• Single writer. One risk thread applies fills and ticks in the engine's sequence order, so replay gives exactly the same positions (week 9). Dashboards and monitors read snapshots through week 34's seqlock. They never take a lock on the writer's data.