Taker flatten

crates/vike-mm/src/taker_flatten.rs's taker_flatten is the market-order side of Guilbaud and Pham, Optimal High-Frequency Trading with Limit and Market Orders (Quantitative Finance 13(1):79–94, 2013; arXiv:1106.5040), reduced to one pure function. The header states the idea it cherry-picks: a passive maker earns the spread by resting limit orders, but pure limit quoting cannot bound inventory — an adverse run fills one side repeatedly and the position drifts unboundedly. Guilbaud–Pham add an impulse-control leg on top of the continuous quoting: at discrete moments the agent may cross the book with a market order to instantaneously cut inventory it cannot skew its way out of.

Vike Trader's maker already has two passive answers to the same problem — the inventory skew leans quote sizes toward flat, and near a binary resolution the settlement schedule force-flattens through a reservation shift. What lives here is the missing active leg.

The decision

taker_flatten(inventory, band) returns Some((side_sign, qty)) naming the market order that cuts the band-excess inventory, or None when nothing should be taken. inventory is the current signed position, band the tolerated inventory half-width the passive skew manages. It fires only when inventory.abs() > band, strictly over — sitting exactly at the band is not over, so it holds. When it fires, side_sign = −inventory.signum() (long sells to reduce, short buys) and qty = inventory.abs() − band, so qty is strictly positive whenever the result is Some. A negative band is clamped to zero rather than allowed to widen the trigger, and zero inventory is None under any band.

The header is explicit that this is a practitioner heuristic. The Guilbaud–Pham optimal impulse region is the solution of a quasi-variational HJB inequality with no closed form; the fixed band is the standard practitioner reduction of that region to one tunable — the simplest defensible shape and the pinned, testable baseline. A convex or asymmetric band is a caller composition on top.

The inert-when-off invariant follows from the strict inequality: a maker whose inventory stays within its band never takes, the impulse leg is dormant, and the maker is byte-identical to the passive skew-only path. The in-file tests pin each edge — within the band, at the band, long and short over it, a zero band, a negative band.

Who calls it

The crate root once parked this module under #[allow(dead_code)] as a deferred pure core; the allow is gone because the cross-exchange maker calls it as its hard-naked-band impulse. XemmMaker::drive_flatten in crates/vike-mm/src/xemm/mod.rs is that site, and its doc sets the terms:

• it fires at most once per halt — the flatten_fired latch is cleared on resume, so a halted maker being ticked does not send a flatten market every tick;
• it fires only while the hedge ledger owes nothing — an in-flight hedge is already closing the exposure, and a second market on top of it would over-hedge;
• it runs only once guards::over_hard_band holds on the ledger's naked exposure, and it cuts back to the soft band: the call is taker_flatten(naked, naked_band), sent through Broker::submit_market on the hedge symbol.

The same doc states when the leg can be reached at all. In the fully-hedged configuration (hedge_ratio == 1.0) the ledger's residual and the naked exposure are the same quantity, so this leg is unreachable by construction; it exists for the deliberately partial case (hedge_ratio < 1.0) and for an exposure that arrived some way the ledger's own retry cannot close. The two bands are XemmParams::naked_band (soft — while |unhedged| exceeds it, the side that would grow the exposure is suppressed) and XemmParams::naked_hard_band (halt, pull both sides, fire the impulse for the excess over the soft band); XemmMaker::new defaults them to qty and 3·qty, and XemmMaker::with_naked_bands tunes both. The whole guard vocabulary is on guards.