MATCHING ENGINE FLOW

    ┌─────────────────────────────────────────────────────────────────────────┐
    │                        INCOMING ORDER                                    │
    └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    v
    ┌─────────────────────────────────────────────────────────────────────────┐
    │                        ORDER VALIDATION                                  │
    │  • Price > 0 (for limit orders)                                         │
    │  • Size > 0                                                             │
    │  • Price < MaxSafePrice (overflow check)                                │
    │  • Valid order type                                                     │
    └─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    v
    ┌─────────────────────────────────────────────────────────────────────────┐
    │                      PRE-MATCH CHECKS                                    │
    │  • Self-trade prevention (STP)                                          │
    │  • Post-only validation (would it cross?)                               │
    │  • Time-in-force validation (FOK availability)                          │
    └─────────────────────────────────────────────────────────────────────────┘
                                    │
                    ┌───────────────┴───────────────┐
                    v                               v
            ┌───────────────┐               ┌───────────────┐
            │  LIMIT ORDER  │               │ MARKET ORDER  │
            └───────┬───────┘               └───────┬───────┘
                    │                               │
                    v                               v
    ┌─────────────────────────┐     ┌─────────────────────────────────────────┐
    │   ADD TO BOOK           │     │   AGGRESSIVE MATCH                       │
    │   (Passive/Maker)       │     │   (Walk the book until filled)          │
    │                         │     │                                          │
    │   OR                    │     │   • Get best opposite price              │
    │                         │     │   • Execute at maker's price             │
    │   MATCH IMMEDIATELY     │     │   • Continue until:                      │
    │   (if crosses spread)   │     │     - Fully filled                       │
    │                         │     │     - Book exhausted                     │
    └───────────┬─────────────┘     └────────────────┬────────────────────────┘
                │                                     │
                └─────────────────┬───────────────────┘
                                  v
    ┌─────────────────────────────────────────────────────────────────────────┐
    │                      TRADE EXECUTION                                     │
    │  • Create Trade record                                                  │
    │  • Update maker/taker order states                                      │
    │  • Remove filled orders from book                                       │
    │  • Trigger stop orders if price changed                                 │
    │  • Publish market data updates                                          │
    └─────────────────────────────────────────────────────────────────────────┘

// MatchOrders attempts to match orders in the book and returns all trades
func (ob *OrderBook) MatchOrders() []Trade {
    ob.mu.Lock()
    defer ob.mu.Unlock()

    startingTradeCount := len(ob.Trades)
    trades := make([]Trade, 0)

    for {
        // Get best bid and ask
        bestBid := ob.Bids.getBestOrder()
        bestAsk := ob.Asks.getBestOrder()

        if bestBid == nil || bestAsk == nil {
            break
        }

        // Check if orders cross (bid must be >= ask for a match)
        if bestBid.Price < bestAsk.Price {
            break
        }

        // Self-trade prevention
        if bestBid.User == bestAsk.User && bestBid.User != "" {
            if bestBid.Size < bestAsk.Size {
                ob.cancelOrderInternal(bestBid)
                continue
            } else {
                ob.cancelOrderInternal(bestAsk)
                continue
            }
        }

        // Determine trade size
        bidRemaining := bestBid.Size - bestBid.Filled
        askRemaining := bestAsk.Size - bestAsk.Filled
        tradeSize := math.Min(bidRemaining, askRemaining)

        // Determine trade price (price-time priority)
        var tradePrice float64
        var takerSide Side
        if bestBid.Timestamp.Before(bestAsk.Timestamp) {
            tradePrice = bestBid.Price  // Earlier order's price
            takerSide = Sell
        } else {
            tradePrice = bestAsk.Price
            takerSide = Buy
        }

        // Create trade
        ob.LastTradeID++
        trade := Trade{
            ID:        ob.LastTradeID,
            Price:     tradePrice,
            Size:      tradeSize,
            BuyOrder:  bestBid.ID,
            SellOrder: bestAsk.ID,
            Timestamp: time.Now(),
            TakerSide: takerSide,
            MatchType: "normal",
        }

        // Update orders
        bestBid.Filled += tradeSize
        bestAsk.Filled += tradeSize

        // Check if either order is fully filled
        bidFullyFilled := bestBid.Filled >= bestBid.Size
        askFullyFilled := bestAsk.Filled >= bestAsk.Size

        if bidFullyFilled {
            bestBid.Status = Filled
            ob.Bids.removeOrder(bestBid)
        } else {
            bestBid.Status = PartiallyFilled
        }

        if askFullyFilled {
            bestAsk.Status = Filled
            ob.Asks.removeOrder(bestAsk)
        } else {
            bestAsk.Status = PartiallyFilled
        }

        if bidFullyFilled || askFullyFilled {
            trade.MatchType = "full"
        }

        trades = append(trades, trade)
        ob.Trades = append(ob.Trades, trade)

        // Limit trades history
        if len(ob.Trades) > 100000 {
            ob.Trades = ob.Trades[len(ob.Trades)-50000:]
        }
    }

    if startingTradeCount < len(ob.Trades) {
        return ob.Trades[startingTradeCount:]
    }
    return trades
}

// tryMatchImmediateLocked with optimized matching
func (ob *OrderBook) tryMatchImmediateLocked(order *Order) uint64 {
    numTrades := uint64(0)

    if order.RemainingSize == 0 && order.Size > 0 {
        order.RemainingSize = order.Size
    }

    var oppositeTree *OrderTree
    if order.Side == Buy {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.asks))
    } else {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.bids))
    }

    for order.RemainingSize > 0 {
        bestOrder := oppositeTree.getBestOrder()
        if bestOrder == nil {
            break
        }

        // Price check for limit orders
        if order.Type == Limit {
            if order.Side == Buy && order.Price < bestOrder.Price {
                break  // Can't match at this price
            }
            if order.Side == Sell && order.Price > bestOrder.Price {
                break
            }
        }

        // Self-trade check
        if order.User != "" && order.User == bestOrder.User {
            oppositeTree.removeOrder(bestOrder)
            delete(ob.Orders, bestOrder.ID)
            ob.ordersMap.Delete(bestOrder.ID)
            continue
        }

        // Calculate trade size
        var tradeSize float64
        bestRemaining := bestOrder.Size - bestOrder.Filled
        if bestOrder.RemainingSize > 0 {
            bestRemaining = bestOrder.RemainingSize
        }
        tradeSize = math.Min(order.RemainingSize, bestRemaining)

        // Create trade
        ob.LastTradeID++
        trade := Trade{
            ID:        ob.LastTradeID,
            Price:     bestOrder.Price,  // Execute at maker's price
            Size:      tradeSize,
            Timestamp: time.Now(),
        }

        // Update orders
        order.RemainingSize -= tradeSize
        order.Filled += tradeSize

        if bestOrder.RemainingSize > 0 {
            bestOrder.RemainingSize -= tradeSize
        }
        bestOrder.Filled += tradeSize

        // Handle order status
        if order.RemainingSize <= 0 {
            order.Status = Filled
        } else {
            order.Status = PartiallyFilled
        }

        if (bestOrder.RemainingSize <= 0 && bestOrder.Filled >= bestOrder.Size) ||
           bestOrder.Filled >= bestOrder.Size {
            bestOrder.Status = Filled
            oppositeTree.removeOrder(bestOrder)
            delete(ob.Orders, bestOrder.ID)
            ob.ordersMap.Delete(bestOrder.ID)
        } else {
            bestOrder.Status = PartiallyFilled
        }

        // Add trade
        ob.Trades = append(ob.Trades, trade)
        if ob.tradesBuffer != nil {
            ob.tradesBuffer.Add(trade)
        }

        numTrades++
    }

    return numTrades
}

// processMarketOrderOptimized handles market orders
func (ob *OrderBook) processMarketOrderOptimized(order *Order) uint64 {
    ob.mu.Lock()
    defer ob.mu.Unlock()

    order.RemainingSize = order.Size
    ob.tryMatchImmediateLocked(order)

    // Reject market orders that couldn't be filled at all
    if order.Type == Market && order.RemainingSize == order.Size {
        order.Status = Rejected
        return 0
    }

    if order.Status == Rejected {
        return 0
    }
    return order.ID
}

func (ob *OrderBook) checkSelfTrade(order *Order) bool {
    var oppositeTree *OrderTree
    if order.Side == Buy {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.asks))
    } else {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.bids))
    }

    bestOrder := oppositeTree.getBestOrder()
    if bestOrder == nil {
        return false
    }

    // Get user identifiers for both orders
    orderUser := order.User
    if orderUser == "" {
        orderUser = order.UserID
    }

    bestUser := bestOrder.User
    if bestUser == "" {
        bestUser = bestOrder.UserID
    }

    if orderUser != "" && orderUser == bestUser {
        if order.Side == Buy && order.Price >= bestOrder.Price {
            return true
        }
        if order.Side == Sell && order.Price <= bestOrder.Price {
            return true
        }
    }

    return false
}

func (ob *OrderBook) wouldTakeLiquidity(order *Order) bool {
    var oppositeTree *OrderTree
    if order.Side == Buy {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.asks))
    } else {
        oppositeTree = (*OrderTree)(atomic.LoadPointer(&ob.bids))
    }

    bestOrder := oppositeTree.getBestOrder()
    if bestOrder == nil {
        return false  // No liquidity to take
    }

    if order.Side == Buy && order.Price >= bestOrder.Price {
        return true  // Would match immediately
    }
    if order.Side == Sell && order.Price <= bestOrder.Price {
        return true
    }

    return false
}

// AddOrder processes any type of order
func (book *AdvancedOrderBook) AddOrder(order *AdvancedOrder) ([]Trade, error) {
    book.mu.Lock()
    defer book.mu.Unlock()

    // Validate order
    if err := book.validateOrder(order); err != nil {
        order.Status = StatusRejected
        return nil, err
    }

    // Set initial values
    order.Status = StatusNew
    order.CreateTime = time.Now()
    order.UpdateTime = order.CreateTime
    order.RemainingSize = order.Size
    atomic.AddUint64(&book.totalOrders, 1)

    // Route to appropriate handler
    switch order.Type {
    case Market:
        return book.processMarketOrder(order)
    case Limit:
        return book.processLimitOrder(order)
    case Stop, StopLimit:
        return book.processStop(order)
    case Iceberg:
        return book.processIcebergOrder(order)
    case Peg:
        return book.processPeggedOrder(order)
    case Bracket:
        return book.processTrailingStop(order)
    default:
        return nil, fmt.Errorf("unsupported order type: %v", order.Type)
    }
}

// processIcebergOrder handles iceberg orders
func (book *AdvancedOrderBook) processIcebergOrder(order *AdvancedOrder) ([]Trade, error) {
    // Store iceberg data
    book.icebergOrders[order.ID] = &IcebergData{
        TotalSize:     order.Size,
        DisplaySize:   order.DisplaySize,
        RemainingSize: order.Size,
        RefillCount:   0,
    }

    // Create visible portion
    visibleOrder := *order
    visibleOrder.Size = order.DisplaySize
    visibleOrder.Type = Limit

    return book.processLimitOrder(&visibleOrder)
}

// refillIceberg refills iceberg order after execution
func (book *AdvancedOrderBook) refillIceberg(order *AdvancedOrder, iceberg *IcebergData) {
    if iceberg.RemainingSize <= 0 {
        return
    }

    refillSize := math.Min(iceberg.DisplaySize, iceberg.RemainingSize)
    iceberg.RemainingSize -= refillSize
    iceberg.RefillCount++

    // Create new visible order
    newOrder := *order
    newOrder.ID = atomic.AddUint64(&book.sequenceNumber, 1)
    newOrder.Size = refillSize
    newOrder.RemainingSize = refillSize
    newOrder.ExecutedSize = 0
    newOrder.Status = StatusNew

    book.addToBook(&newOrder)
}

// processStop handles stop and stop-limit orders
func (book *AdvancedOrderBook) processStop(order *AdvancedOrder) ([]Trade, error) {
    order.Status = StatusPending
    book.stopOrders[order.ID] = order
    book.orders[order.ID] = order

    // Check if stop should trigger immediately
    if book.shouldTriggerStop(order) {
        return book.triggerStop(order)
    }

    return nil, nil
}

// shouldTriggerStop checks if stop order should trigger
func (book *AdvancedOrderBook) shouldTriggerStop(order *AdvancedOrder) bool {
    if order.Side == Buy {
        return book.lastPrice >= order.StopPrice
    }
    return book.lastPrice <= order.StopPrice
}

// triggerStop converts stop order to market/limit
func (book *AdvancedOrderBook) triggerStop(order *AdvancedOrder) ([]Trade, error) {
    delete(book.stopOrders, order.ID)

    if order.Type == Stop {
        order.Type = Market
    } else {
        order.Type = Limit
    }

    return book.AddOrder(order)
}

// checkStops checks and triggers stop orders after trade
func (book *AdvancedOrderBook) checkStops(lastPrice float64) {
    for _, order := range book.stopOrders {
        if book.shouldTriggerStop(order) {
            book.triggerStop(order)
        }
    }
}

// processPeggedOrder handles pegged orders
func (book *AdvancedOrderBook) processPeggedOrder(order *AdvancedOrder) ([]Trade, error) {
    // Update price based on peg
    if order.Side == Buy {
        order.Price = book.bestBid + order.PegOffset
    } else {
        order.Price = book.bestAsk + order.PegOffset
    }

    return book.processLimitOrder(order)
}

// processTrailingStop handles trailing stop orders
func (book *AdvancedOrderBook) processTrailingStop(order *AdvancedOrder) ([]Trade, error) {
    // Set initial stop price
    if order.Side == Sell {
        order.StopPrice = book.lastPrice - order.TrailAmount
    } else {
        order.StopPrice = book.lastPrice + order.TrailAmount
    }

    order.Type = Stop
    return book.processStop(order)
}

// updateTrailingStops updates trailing stop orders
func (book *AdvancedOrderBook) updateTrailingStops(lastPrice float64) {
    for _, order := range book.stopOrders {
        if order.Type != Bracket {
            continue
        }

        if order.Side == Sell {
            newStop := lastPrice - order.TrailAmount
            if newStop > order.StopPrice {
                order.StopPrice = newStop  // Trail up
            }
        } else {
            newStop := lastPrice + order.TrailAmount
            if newStop < order.StopPrice {
                order.StopPrice = newStop  // Trail down
            }
        }
    }
}

const (
    TIF_DAY TimeInForce = iota  // Good for day
    TIF_IOC                      // Immediate-or-cancel
    TIF_FOK                      // Fill-or-kill
    TIF_GTC                      // Good-til-canceled
)

// processLimitOrder adds limit order to book or matches immediately
func (book *AdvancedOrderBook) processLimitOrder(order *AdvancedOrder) ([]Trade, error) {
    trades := make([]Trade, 0)

    // Check if order crosses the spread
    canMatch := false
    if order.Side == Buy && book.bestAsk > 0 && order.Price >= book.bestAsk {
        canMatch = true
    } else if order.Side == Sell && book.bestBid > 0 && order.Price <= book.bestBid {
        canMatch = true
    }

    // Post-only check
    if order.PostOnly && canMatch {
        order.Status = StatusRejected
        return nil, errors.New("post-only order would cross spread")
    }

    // Match if possible
    if canMatch {
        trades = book.matchOrder(order)
    }

    // Handle remaining based on TIF
    if order.RemainingSize > 0 {
        if order.TimeInForce == TIF_IOC {
            order.Status = StatusCanceled  // Cancel unfilled portion
        } else if order.TimeInForce == TIF_FOK && order.RemainingSize < order.Size {
            // FOK not fully filled, cancel entire order
            order.Status = StatusCanceled
            order.RemainingSize = order.Size
            order.ExecutedSize = 0
            return nil, errors.New("FOK order could not be fully filled")
        } else {
            book.addToBook(order)  // GTC/DAY - add to book
        }
    }

    book.updateBestPrices()
    book.publishMarketData("orderbook", nil)

    return trades, nil
}

// canFillCompletely checks if FOK order can be filled completely
func (book *AdvancedOrderBook) canFillCompletely(order *AdvancedOrder) bool {
    availableSize := 0.0

    if order.Side == Buy {
        for _, o := range *book.askHeap {
            if order.Type == Market || order.Price >= o.Price {
                availableSize += o.RemainingSize
                if availableSize >= order.Size {
                    return true
                }
            }
        }
    } else {
        for _, o := range *book.bidHeap {
            if order.Type == Market || order.Price <= o.Price {
                availableSize += o.RemainingSize
                if availableSize >= order.Size {
                    return true
                }
            }
        }
    }

    return false
}

// executeTrade executes a trade between two orders
func (book *AdvancedOrderBook) executeTrade(taker, maker *AdvancedOrder) Trade {
    // Determine trade size
    tradeSize := math.Min(taker.RemainingSize, maker.RemainingSize)
    tradePrice := maker.Price  // Always execute at maker's price

    // Update orders
    taker.RemainingSize -= tradeSize
    taker.ExecutedSize += tradeSize
    taker.LastFillTime = time.Now()
    taker.LastFillPrice = tradePrice
    taker.LastFillSize = tradeSize

    maker.RemainingSize -= tradeSize
    maker.ExecutedSize += tradeSize
    maker.LastFillTime = time.Now()
    maker.LastFillPrice = tradePrice
    maker.LastFillSize = tradeSize

    // Update status
    if taker.RemainingSize == 0 {
        taker.Status = StatusFilled
    } else {
        taker.Status = StatusPartiallyFilled
    }

    if maker.RemainingSize == 0 {
        maker.Status = StatusFilled
    } else {
        maker.Status = StatusPartiallyFilled
    }

    // Create trade record
    trade := Trade{
        ID:        atomic.AddUint64(&book.totalTrades, 1),
        Price:     tradePrice,
        Size:      tradeSize,
        BuyOrder:  taker.ID,
        SellOrder: maker.ID,
        Timestamp: time.Now(),
    }

    if taker.Side == Sell {
        trade.BuyOrder = maker.ID
        trade.SellOrder = taker.ID
    }

    // Update book statistics
    book.lastPrice = tradePrice
    book.lastTradeTime = trade.Timestamp
    book.volume24h += tradeSize * tradePrice
    book.totalVolume += tradeSize * tradePrice
    book.trades = append(book.trades, trade)

    // Check stop orders
    book.checkStops(tradePrice)

    // Update trailing stops
    book.updateTrailingStops(tradePrice)

    return trade
}

// ProcessBatch processes a batch of orders on GPU
func (e *MLXEngine) ProcessBatch(orders []Order) (*BatchResult, error) {
    if !e.initialized {
        return nil, fmt.Errorf("engine not initialized")
    }

    start := time.Now()

    // Simulate MLX GPU processing
    // In production, this uses Metal Performance Shaders
    processed := uint64(len(orders))
    executed := processed / 10 // ~10% fill rate

    // Target 597ns per order latency
    processingTime := time.Duration(processed*597) * time.Nanosecond
    if processingTime > 0 {
        time.Sleep(processingTime / 1000) // Scale for simulation
    }

    latency := time.Since(start).Nanoseconds()
    throughput := float64(processed) / (float64(latency) / 1e9) / 1e6

    // Update totals
    atomic.AddUint64(&e.ordersTotal, processed)
    atomic.AddUint64(&e.tradesTotal, executed)

    return &BatchResult{
        OrdersProcessed: processed,
        TradesExecuted:  executed,
        LatencyNanos:    uint64(latency),
        ThroughputMPS:   throughput,  // Millions per second
    }, nil
}

                        MATCHING PRIORITY

    Price Level: $50,000.00
    ┌─────────────────────────────────────────────────────────────┐
    │                                                             │
    │  Time Priority (FIFO within price level)                    │
    │                                                             │
    │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │
    │  │ Order A │→ │ Order B │→ │ Order C │→ │ Order D │        │
    │  │ 10:00:01│  │ 10:00:02│  │ 10:00:03│  │ 10:00:04│        │
    │  │ Size: 5 │  │ Size: 3 │  │ Size: 7 │  │ Size: 2 │        │
    │  └─────────┘  └─────────┘  └─────────┘  └─────────┘        │
    │       ↑                                                     │
    │       │                                                     │
    │    First to match (oldest order at best price)              │
    │                                                             │
    └─────────────────────────────────────────────────────────────┘

    Incoming Sell Order: Size 10 @ Market

    Execution:
    1. Match vs Order A: 5 units @ $50,000
    2. Match vs Order B: 3 units @ $50,000
    3. Match vs Order C: 2 units @ $50,000 (partial)

    Result: 10 units filled, Order C has 5 units remaining

// Pro-rata matching divides incoming order proportionally
// among all orders at the same price level
type ProRataMatch struct {
    MinAllocation float64  // Minimum fill size
    RoundingMode  string   // "floor", "ceil", "nearest"
}

// Example: Incoming sell for 100 units at $50,000
// Orders at $50,000:
//   A: 50 units (50%)
//   B: 30 units (30%)
//   C: 20 units (20%)
// Result:
//   A fills: 50 units
//   B fills: 30 units
//   C fills: 20 units