docs(exchange): document FOK ghost-id contract + proptest (N7)

FOK rejections return a `SubmitResult` with a valid, monotonically
assigned `order_id` and `status == OrderStatus::Cancelled`, but the id
is never inserted into the book — `get_order(id)` returns `None`. This
is intentional (keeps the id sequence gap-free for deterministic
replay) but was previously only hinted at by a single comment in
`submit_limit_internal`.

Make it a first-class part of the public contract:

- Add a "FOK rejection contract (ghost `OrderId`)" block on
  `Exchange::submit_limit` explaining exactly what callers must check
  before querying `get_order`.
- Add two proptest invariants in `tests/proptest_invariants.rs`:
  * `fok_rejected_id_is_ghost`: FOK against an empty book — rejected,
    id is `> 0`, `get_order(id) == None`, quantities and trades match
    the rejection invariants.
  * `fok_rejected_against_insufficient_liquidity`: same, but with
    some liquidity resting that is strictly less than the FOK size.

No behavior change.

Author: ricardofrantz

src/exchange.rs

@@ -62,6 +62,22 @@ impl Exchange {
     /// - **GTC**: Rests on book until filled or cancelled
     /// - **IOC**: Cancelled (never rests)
     /// - **FOK**: If cannot fill entirely, order is rejected (no trades)
+    ///
+    /// # FOK rejection contract (ghost `OrderId`)
+    ///
+    /// An order rejected under `TimeInForce::FOK` (no full fill available)
+    /// returns a [`SubmitResult`] with a valid, monotonically-assigned
+    /// `order_id` and `status == OrderStatus::Cancelled`, but that id is
+    /// **not** retrievable via [`Self::get_order`] — the order is never
+    /// inserted into the book and is logically non-existent. The id is
+    /// consumed so the exchange's id sequence stays gap-free for
+    /// deterministic replay; callers must not treat it as a handle.
+    ///
+    /// Callers MUST branch on `result.status` (or check
+    /// `result.filled_quantity`, `result.cancelled_quantity`) before
+    /// calling `get_order(result.order_id)`. The invariant
+    /// "`status == Cancelled` with `filled_quantity == 0` ⇒
+    /// `get_order(order_id) == None`" holds for FOK rejections.
     pub fn submit_limit(
         &mut self,
         side: Side,

tests/proptest_invariants.rs

@@ -6,7 +6,7 @@
 //! These tests use proptest to verify that key invariants hold
 //! across randomly generated scenarios.
 
-use nanobook::{Exchange, Price, Side, StopStatus, TimeInForce};
+use nanobook::{Exchange, OrderStatus, Price, Side, StopStatus, TimeInForce};
 use proptest::prelude::*;
 
 /// Generate a valid price (positive, reasonable range)
@@ -184,6 +184,63 @@ proptest! {
         );
     }
 
+    /// FOK rejection contract: a rejected FOK returns a valid monotonic
+    /// `order_id` whose status is `Cancelled`, but the id is NOT retrievable
+    /// via `get_order`. See `Exchange::submit_limit` doc.
+    #[test]
+    fn fok_rejected_id_is_ghost(
+        side in side_strategy(),
+        price in price_strategy(),
+        qty in quantity_strategy(),
+    ) {
+        let mut exchange = Exchange::new();
+
+        // Empty book on the opposite side => FOK cannot fill => rejected.
+        let result = exchange.submit_limit(side, price, qty, TimeInForce::FOK);
+
+        // Rejected with nothing filled and nothing resting.
+        prop_assert_eq!(result.status, OrderStatus::Cancelled);
+        prop_assert_eq!(result.filled_quantity, 0);
+        prop_assert_eq!(result.resting_quantity, 0);
+        prop_assert_eq!(result.cancelled_quantity, qty);
+        prop_assert!(result.trades.is_empty());
+
+        // The id was consumed (monotonic) but not stored.
+        prop_assert!(result.order_id.0 > 0, "FOK rejection should still burn an id");
+        prop_assert!(
+            exchange.get_order(result.order_id).is_none(),
+            "FOK-rejected id {:?} leaked into the book",
+            result.order_id
+        );
+    }
+
+    /// The ghost-id invariant also holds when there IS liquidity on the
+    /// opposite side but not enough to fully fill the FOK quantity.
+    #[test]
+    fn fok_rejected_against_insufficient_liquidity(
+        price in price_strategy(),
+        resting_qty in 1u64..100u64,
+        extra in 1u64..1000u64,
+    ) {
+        let mut exchange = Exchange::new();
+
+        // Resting ask with limited size.
+        exchange.submit_limit(Side::Sell, price, resting_qty, TimeInForce::GTC);
+
+        // FOK buy for strictly more than is available at or below `price`.
+        let want = resting_qty + extra;
+        let result = exchange.submit_limit(Side::Buy, price, want, TimeInForce::FOK);
+
+        prop_assert_eq!(result.status, OrderStatus::Cancelled);
+        prop_assert_eq!(result.filled_quantity, 0);
+        prop_assert_eq!(result.resting_quantity, 0);
+        prop_assert!(result.trades.is_empty());
+        prop_assert!(
+            exchange.get_order(result.order_id).is_none(),
+            "FOK-rejected id retrievable via get_order"
+        );
+    }
+
     // ========================================================================
     // DETERMINISM INVARIANTS
     // ========================================================================