A routing-time maximum-spread gate — refuse entries when the live book is too wide

[eaitbrahim]

Proposed by the operator during the Phase 10 expansion review (2026-08-17): a routing-time maximum-spread gate — an entry (BUY) is refused when the venue's live spread at routing exceeds a configurable threshold, so thin books cannot be entered at any moment their spread makes the fill economics materially worse than the cost model assumes.

Why it is now cheap: #332's entry-override warning already reads best_bid/best_ask from the preview_order call _run_order makes — the book data and the routing-time hook both exist. The gate is a threshold check beside that warning ((ask − bid) / mid > max_entry_spread_pct → veto), the same fail-closed family as rails 12/13/17.

Design questions for the PR (this issue is the agreement CONTRIBUTING requires for rail work):

• Threshold source: config (execution.max_entry_spread_pct?) with a docstring'd conservative default; or scaled per-product from slippage is one global 5bp constant applied from BTC to TON #259's liquidity-scaled slippage (spread cap as a multiple of assumed slippage).
• Scope: BUYs only (entries), like rail 17; SELLs must never be trapped by a spread gate (exits must execute).
• Live path only — paper fills are synthetic and never see a book; document that the paper-hourly profile therefore accrues no evidence about this rail (a reason it ships before any live resumption, not before paper expansion).
• Interaction with fix(executor): warn loudly when a conditional entry price is overridden by market routing (#260) #332's warning: the same preview read feeds both; one helper, two consumers.

[eaitbrahim]

Shipped in PR #360 (merged e2e2189; adversarially reviewed — approved with two money-path hardening tests applied before merge: the extreme-exponent fail-closed arm and gate-before-confirm ordering, both mutation-verified).

Design as agreed in this issue, all four questions answered:

• Threshold source: config execution.max_entry_spread_pct, Decimal, default 0.005 (50bp) — anchored to feat(backtest): per-product slippage scaled from liquidity — assumed, capped, and reported (#259) #334's SLIPPAGE_CAP_PCT: if the spread ALONE exceeds the worst per-leg cost the backtest ever assumes, the economics are materially worse than modeled. Bounds (0, 0.10], ConfigError names the key; knob documented in the dev and live config templates and pinned in the goldens.
• Scope: BUY entries only — execute() is the only BUY constructor (plain and DCA entries); brackets, scale-outs and stop-rolls are SELLs and return before any book read. Exits can never be trapped by this gate.
• Paper: never runs it (synthetic fills see no book), pinned by test; the runbook and README state that the paper profiles accrue no evidence about this gate — the reason it ships before any live resumption.
• fix(executor): warn loudly when a conditional entry price is overridden by market routing (#260) #332 interaction: one _preview_book helper (NaN/missing/extreme-safe, reads both the live dict and the port Preview.detail shape), two consumers — the existing routing-override warning (behavior unchanged, its tests untouched) and the new gate. Boundary is >= (fail-closed); an unreadable book refuses with the distinct book_unreadable reason; refusal reports vetoed_by and a structured executor.entry_spread_refused / executor.entry_book_unreadable event with spread, threshold, product and rule.

Not deployed yet — lands with the next release cut. Remaining known limit, documented in the gate's docstring: it keys on side and does not inspect order_configuration; if #260's remediation ever introduces resting BUY orders, revisit the scope (no such caller exists today).