From 2ce96987a1202d588436c16fad850e3978338cb8 Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 14 Jul 2026 19:28:51 +0200 Subject: [PATCH] docs(exec): THE UNIFIED EXECUTION LAYER master spec (DITA-T / SMART-EXEC v2) Operator-commissioned master: agnostic contract ('an asset, a size, and a prayer'), 11-source lineage table with per-asset standing, five contract promises, MALKHUT advice plane (three laws, bounded authority, training-loop closure), urgency ladder, PINK drive-loop port doctrine, execution truth + priority integration as law, venue dialect seam, 20-point how-we-trade distillation (incl. original BingX characterization sweep specifics + the $91-231K measured prize), Appendix D = Flight-series at-exchange inventory (14 lessons, previously uninventoried), Appendix E = mm_'s microstructure priors (MEASURED adopted / CALIBRATED gated on A1 validation). Supersedes SPEC_UV_SMART_EXEC_MM (marked in-place); governs SMART_EXEC_BACKLOG. Co-Authored-By: Claude Opus 4.8 (1M context) --- prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md | 473 ++++++++++++++++++ prod/docs/SPEC_UV_SMART_EXEC_MM.md | 2 +- 2 files changed, 474 insertions(+), 1 deletion(-) create mode 100644 prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md diff --git a/prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md b/prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md new file mode 100644 index 0000000..3f158a5 --- /dev/null +++ b/prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md @@ -0,0 +1,473 @@ +# SPEC — THE UNIFIED EXECUTION LAYER ("DITA-T / SMART-EXEC v2") + +**Status**: MASTER SPEC — supersedes `SPEC_UV_SMART_EXEC_MM.md` (2026-07-13, subsumed +whole) and governs `SMART_EXEC_BACKLOG.md` items S1–S9 + L-lane. Build remains +POST_FINISH-SEQUENCED unless the operator unparks it. +**Author**: Fable, 2026-07-14, operator-commissioned ("the most complete, exhaustive, +correct, clear, effective spec ever written by man or agent — putting together all we +know about how we would want to best trade"). +**Home**: the DITAv2 lineage's venue-talking half — the "T" of the system. Everything +above it thinks; this layer *transacts*. + +--- + +## 0. Charter — one paragraph + +Every layer above this one decides **WHAT**: side, size, asset, and why-now. This layer +decides **HOW**: maker or taker, where in the book, when to chase, when to requote, when +to give up and cross, what protective orders ride along, and what the truth is when the +wire goes quiet mid-order. Its calling contract is deliberately impoverished — **"an +asset, a size, and a prayer"** (operator's words, now doctrine §2) — so that every brain +this factory ever produces (BLUE, UV/BLUE-PRIME flights, VIOLET, VIBRASS children, +MALKHUT, things not yet named) executes through the *same* battle-tested body. The +economics that justify its existence are measured, not hoped: taker round-trip ≈ 10 bps +(5.016 bps/side over 1,455 live fills) vs maker-both ≈ 4 bps *if* the assumed 1 bp maker +fee survives measurement (§17-Q1 — still the cheapest high-stakes experiment we have); +UV's own audit showed the identical brain losing −758 USDT on friction alone while BLUE +netted +2.5%/day — **execution is where the parity gap is made of money.** + +## 1. Lineage — what this spec unifies, and the standing on each part + +| # | Asset | What it contributes | Status / evidence | +|---|---|---|---| +| L1 | **PINK drive loop** (`prod/clean_arch/runtime/pink_direct.py:931-1210`) | THE starting point (operator ruling). ~280 lines of scar tissue: TTL sweep, fill-vs-cancel race reclassification, venue-truth requote gate, exit escalation. Every branch is a real incident. | Production-run since 2026-06-11; `maker_both` ACTIVE. **Port behavior warts-and-all — do NOT rewrite** (transcribe-the-mess doctrine, same ruling as the ADVSL port). | +| L2 | **PINK `ExecutionRouter`** | Pure maker/taker POLICY: stdlib-only, zero I/O, 265 tests incl. live VST E2E. The whether-maker machine + `pre_submit` hook (may return a replacement plan). | Genuinely portable, a day's work. Test corpus comes with it. | +| L3 | **SmartPlacer** (`alpha_engine/execution/smart_placer.py`) | The where-in-book model: `decide_placement`, `compute_limit_price`, `check_adverse_move`, `ob_confirms_signal` (`ExecutionMethod`/`FallbackAction`/`PlacementDecision`); siblings `fill_simulator` (30 s bookDepth replay), `ob_reader`, `signal_confidence_adapter` (conviction→patience). | **Zero importers anywhere** — adopting it breaks nothing. Adjudication vs Router required (§17-A1): likely complementary (Router=whether, Placer=where). | +| L4 | **DITAv2 kernel + venue seam** | The FSM, intent idempotency, identity-collision detection, ns-timed receipts, `u-`/`m-` clientOrderId discipline, multi-leg capability (`exit_leg_ratios` — built, unproven), sync+async submit paths, M2 ExecIoLoop (one owned venue-I/O lane), M4 VenueReadiness fail-DARK. | The chassis this layer bolts into. Async path is the only sanctioned one (D5 ruling: no sync sign-off). | +| L5 | **Execution-truth doctrine** (bdc54fb + BUGCLASS_INDETERMINATE_OUTCOME) | NOT_ATTEMPTED / REFUSED / **INDETERMINATE** triage; *unknown is never flat*; post-ack failures may never veto an accepted order; `VenuePostAckError` fence. | Codified after the 6-orphan incident; fault-injection matrix exists. Inherited wholesale (§8). | +| L6 | **Priority doctrine A–G → P0–P4** (`UV_EXEC_PRIORITY_LADDER_20260713.md`, fix `b34eb4c`) | Session safety > execution truth > capital preservation > profit/maintenance > entry. Bounded P1 burst (16) so truth can't starve a hard SL. Mutation-verified 2026-07-14. | LIVE in the flight series. This layer's dispatch inherits it (§9). | +| L7 | **mm_'s order-type normalization** (`MALKHUT/malkhut/training/order_types.py`) | FIX-annotated order SEMANTICS (BaseType/TimeInForce/Conditional/Instruction/Compound) + per-venue dialect tables + `normalize_to_exchange`/`is_type_available`. The interlock plane between MALKHUT and this layer. | Adopt as the order-vocabulary (S9) **after the two corrections**: (a) POST_ONLY/IOC/FOK are BingX `timeInForce`, not `type` — the map must split namespaces; (b) `trailing_stop→TRIGGER_MARKET` silently un-trails — BingX has native `TRAILING_STOP_MARKET` + `TRAILING_TP_SL`. | +| L8 | **Venue characterization** (BingX) — PRIMARY SOURCE: `BingX_FILL_CHARACTERIZATION_AND_ADVANTAGES.md` (2026-04-24 live sweep, 10 symbols × 4 order families, + cmd-PASS8 savings addendum) | RTT anatomy: ~40 ms to CF edge, ~195 ms edge→origin, warm-TLS saves 20–85 ms; REST-only order entry (no WS trade, no FIX — CCXT-verified); 10 req/s order endpoint; GOAWAY recycle ≈ every 8.5 k requests (benign); `.pro` backup trust anchor fixed (`7155de2`); offline symbols ack `code==0` with empty data (fabricated-fill fence landed); dashed wire symbols; VST `allOrders` time-filter broken (filter client-side). | Measured 2026-07-10→14. Constants in this spec cite this row, not vibes. | +| L9 | **WS price lane** (P0–P3, LIVE in Flight 6, `e35ac0b`) | Push mark prices ~0.8 s fresh (vs ≤1 s poll + RTT), `PriceStore` wait-free reads, frame journal for deterministic replay, REST fallback age-gated. Mark = risk-geometry truth; OB top = execution truth; last/close = brain-parity truth — **three price truths, never conflated**. | This layer reads OB for placement and mark for protective geometry; it never touches the brain's price. | +| L10 | **mm_'s OB microstructure study** — PERSISTED: `MALKHUT/docs/OB_MICROSTRUCTURE_STUDY.md` (12 sections, 13 assets, live Binance/BingX + Bouchaud/Cont-Stoikov/Cartea-Jaimungal calibrations) | Majors' spread = 1 tick (0.0016 bps — maker capture ≈ 0 on Binance majors, material on BingX); 100-level book spans ~13 bps (deep-depth metrics need the 5000-level feed); best-bid depth BTC ≈ $212 K. Parameterizes SmartPlacer offsets + fill_simulator per venue. | Persistence requested; numbers feed `_constants.py` provenance. | +| L11 | **MALKHUT** (future, "advise-bearing") | Game-theoretic fulfilment: `FulfilmentAction` (kind, qty_fraction, order_type, post_only, reduce_only, cancel/replace) + `RiskDecision` approval envelope + adversarial self-play training. | NOT an authority over this layer — an **advisor** (§5). Compatibility is BY CONSTRUCTION, not retrofit. | + +## 2. The Contract — "an asset, a size, and a prayer" (agnosticism doctrine) + +The operator's ruling, made precise: **the execution layer knows NOTHING about the +caller's world.** Not leverage math, not dual-leverage flight machinery, not postures, +not commit-chains, not capital, not why. Compatibility with the Flight series (or +anything else) is therefore not a feature — it is the *absence* of coupling. + +### 2.1 Input — `ExecutionRequest` (the whole surface; nothing else may leak in) + +``` +ExecutionRequest: + request_id str # caller-minted, idempotency key end-to-end + asset str # canonical undashed ("BTCUSDT"); dialects dash it + side BUY|SELL + size Decimal # base quantity. Sizing is the CALLER's problem, solved. + reduce_only bool # position-decreasing intent (exits set True) + urgency UrgencyClass # §6 — assigned by CALLER, never inferred + guideline_price Decimal | None # decision-time reference, NOT a limit + protective ProtectiveSpec | None # §10 — attach-SL geometry (mark-based) + advice ExecutionAdvice | None# §5 — MALKHUT/other advisor hints, ignorable + deadline_ms int | None # caller's patience budget (ROTATE/ACQUIRE) +``` + +Leverage note (the operator suspected this point was dumb, and he was right): venue +leverage set-calls are **venue-account plumbing**, not execution policy. The dialect +layer (§11) exposes `ensure_symbol_mode(asset, leverage, margin_mode)` as an idempotent +pre-trade primitive the caller invokes if IT cares; the drive loop never reads it. + +### 2.2 Output — the receipt stream (identical shape to the naive adapter, plus truth) + +Callers receive the same `VenueEvent`/receipt stream the naive MARKET adapter emits +today — `ACKED → PARTIAL_FILL* → FULL_FILL | REJECTED | UNKNOWN` — with ns timestamps, +fees when the venue reports them, and the friction telemetry of §12 flowing on a side +lane. **The kernel cannot tell SMART-EXEC from naive MARKET; only the fills get +cheaper.** (Parity-invisibility, inherited from v1 §0 — the golden-vector cert is what +makes executor changes safe: brain unchanged, body improved.) + +### 2.3 The five promises (the contract's soul — each gets a mutation-RED test) + +1. **I will act on your urgency immediately** — CATASTROPHIC is never delayed one tick. +2. **I will never change WHAT you asked** — side/size/asset/reduce_only are sacred. +3. **I will never lie about outcomes** — fills stream as they happen; unknown is + reported UNKNOWN, never guessed flat, never synthetically rejected. +4. **I will never lose an order** — every order carries `request_id`-derived + clientOrderId; every state transition is journaled before it is acted on. +5. **I will always be revertible** — `UV_SMART_EXEC=0` restores naive MARKET at next + boot; no code path is removed to make the smart path work. + +## 3. Placement in the system — the "T" seam + +``` + BRAINS (any epoch, any species) ADVISORS (bounded authority) + BLUE · UV/BLUE-PRIME flights · MALKHUT fulfilment policy · + VIOLET · VIBRASS children future RL/VIBRASS tacticians + │ ExecutionRequest │ ExecutionAdvice + ▼ ▼ + ┌──────────────────────────────────────────────────────────────┐ + │ UNIFIED EXECUTION LAYER (this spec) │ + │ urgency policy → placement decision → DRIVE LOOP │ + │ (Router ∪ SmartPlacer adjudicated) (PINK port, §7) │ + ├──────────────────────────────────────────────────────────────┤ + │ DITAv2 kernel seam: FSM, idempotency, receipts, multi-leg │ + ├──────────────────────────────────────────────────────────────┤ + │ VENUE DIALECT (§11): BingX today; the ONLY multi-venue seam │ + └──────────────────────────────────────────────────────────────┘ + │ REST (orders) ▲ WS (account/E-feed, prices) + ▼ │ + BingX (VST → mainnet) +``` + +It lives in the DITAv2 lineage between the kernel FSM and the venue dialect — +`prod/clean_arch/dita_v2/exec/` (new package; vendored per VENDOR.lock law: canonical +upstream first, `vendor_sync.sh`, never edit the vendored copy). The kernel keeps +owning intents/receipts/idempotency; this layer owns *working-order tactics*. + +## 4. What every epoch taught us (the distilled how-we-want-to-trade) + +The operator asked for "all we know." Enumerated, with provenance: + +1. **Missed entries are free; chased entries are not** (Alpha-epoch). ACQUIRE abandons, + never chases. +2. **Exits are not entries** (BLUE TP-masking + ADVSL history). Exit tactics may only + tighten toward urgency; never reprice an exit away from execution. +3. **The venue's truth outranks ours** (PINK requote gate; E-feed doctrine). Requote + decisions read venue state (order status, book), not our intent memory. +4. **Unknown is never flat** (6-orphan incident). A timeout is INDETERMINATE; only a + proven refusal rolls back. Point-lookup by clientOrderId; else UNKNOWN and let the + E-feed FILL settle it. +5. **Observability never rides the exec path** (b46ebd2 telemetry stall; 2000 s → 3.65 µs). + Lossless side-lane spool, own thread, zero drops. +6. **Truth before action** (tier-B inversion, `b34eb4c`). Apply the fill you already + own before dispatching the next entry. +7. **Fees are measured, not assumed** (5.016 bps taker measured; 1 bp maker STILL an + assumption — §17-Q1 blocks economics claims until measured with one VST GTX fill). +8. **Slippage is the bigger half** (UV audit: enter-slip −24 bps systematically adverse + vs fees +10 bps). Placement quality > fee tier. +9. **Multi-round-trip loops are where latency pays** (RTT anatomy). One-shot orders + don't benefit from colo; drive loops do (~180 ms/leg) — hence **C1: the loop takes + venue-I/O and market state through injected seams only** (no ambient state, no + hardcoded paths), so it can run venue-side someday without a rewrite. +10. **Attach the dead-man's stop at the venue** (HZ silent-death lineage). Software is + the strategy; the venue-attached STOP_MARKET at ~2× software SL is the will. +11. **Partials are normal in maker land** (Router production experience). Stream them + up instantly; the remainder inherits the same urgency; never hold a partial hostage. +12. **Book truth requires the right feed** (mm_'s study). Spread/depth gates must be + parameterized per venue: Binance-major numbers ≠ BingX numbers; the dead + `_spread_allows_maker` (never fed `spread_bps`) gets wired to live top-of-book. +13. **Silent failure is the house specialty** (silent subs, silent sends, silent + deaths — all live-caught 2026-07-14). Every lane gets a liveness deadline and a + cross-check tripwire; "no error" is never evidence of success. +14. **Order semantics once, venues as dialects** (mm_'s layer). Policy speaks + normalized order language; `normalize_to_exchange` translates at the boundary. +15. **Quantize to venue tick AND step before submit; size by notional band** (L8 sweep: + partials cluster on low-price/high-qty symbols — XRP 31.446→31, DOGE 459.793→459, + SHIB 7.29M→7.288M, ADA 180.577→180; AAVE's 0.1 step is coarse). The tick/step + matrix for 10 symbol families is in L8 §Precision — dialect layer owns it. +16. **GTX/post-only is the ONLY certified fill-improvement technique** (L8 verdict, + verbatim): "disciplined short-lived GTX/post-only maker quoting near the market" — + evidence: BTC/ETH/SOL/AAVE/YFI/XRP GTX fills, some at better-than-market levels; + bounded quote lifetime + cancel/replace discipline; only where non-fill is + acceptable. Everything else is either normal mechanics or unproven. +17. **Venue idioms are law** (L8): trailing `callbackRate` is PERCENT, range `(0,10]`; + one-way flattening needs `positionSide=BOTH`; MARKET with a stray `price` is + accepted and the price ignored; non-integer leverage rejected; IOC resolves + PARTIALLY_FILLED|CANCELLED (never UNKNOWN post-fix); nested `{"order":{...}}` acks + must be normalized or the true orderId is lost (defect fixed 2026-04-24). +18. **Never mistake observation latency for venue latency** (L8): the ~4.7 s + "market fill detection" was harness composite, not the venue. The production + measurement is the four-way split t_submit/t_ack/t_ws/t_pos — §12 telemetry + MUST emit exactly that decomposition (it separates venue matching, user-stream + propagation, account propagation, and our classifier). +19. **Absorb the SNAPSHOT burst before trusting the stream** (L8 deferred TODO): + private WS emits a large SNAPSHOT flood on connect before deltas; adapter needs a + `snapshot_absorbed` readiness barrier, cache-warming from it (leverage/margin + state), and suppressed drift alarms during the flood. SNAPSHOT is never a + substitute for ORDER_TRADE_UPDATE. +20. **The prize is measured** (L8 addendum, BLUE production data, 2,681 trades, + $214 M notional): all-taker fees ≈ $107 K; 50–75% maker → saves ~$43–64 K; spread + capture → ~$45–160 K; partial-recovery → ~$3–6 K. Total $91–231 K vs realized + +$48.8 K capital gain over the same period — the executor's headroom is 1.9–4.7× + the strategy's own PnL. Assumptions (fill probability, no alpha decay from queue + risk) are exactly what §15's rung-by-rung friction deltas verify. + +## 5. The Advice Plane — MALKHUT compatibility BY CONSTRUCTION + +MALKHUT is being built as an **advise-bearing layer** (operator's framing). The +execution layer therefore exposes one advisory socket, with strictly bounded authority: + +``` +ExecutionAdvice: # ALL fields optional; None = layer defaults + order_type NormalizedType |None # mm_'s vocabulary (L7), e.g. "post_only" + placement_offset ticks | None # where-in-book refinement + patience_ms int | None # within the caller's deadline, never beyond + chase_budget int | None # ≤ class maximum, never above + compound TP_SL | OCO | None # attach suggestions (validated §10) + advisor_id str # provenance, journaled with every use +``` + +**The three laws of advice** (each mutation-RED tested): +1. Advice may **refine tactics, never risk**: it cannot raise urgency's aggression cap, + cannot exceed the caller's deadline, cannot touch side/size/asset/reduce_only, + cannot downgrade CATASTROPHIC handling. Violating advice is clamped and counted + (`advice_clamped` telemetry), not obeyed. +2. Advice is **ignorable**: the layer must produce a valid execution with `advice=None` + forever. MALKHUT absent ⇒ today's behavior. +3. Advice is **accountable**: every applied/clamped/ignored advice is journaled with + `advisor_id`, so MALKHUT's self-play training can learn from realized outcomes + (the fill telemetry of §12 is exactly her reward signal — the loop closes). + +Mapping (Appendix B): MALKHUT `FulfilmentAction(kind, qty_fraction, order_type, +post_only, reduce_only, cancel/replace…)` decomposes into caller-side sizing +(qty_fraction × equity → `size`) + `ExecutionAdvice` (order_type/post_only) + verbs the +layer already owns (cancel/replace = drive-loop operations exposed as +`amend(request_id, …)` / `cancel(request_id)`). Her `RiskDecision` approval stays +ABOVE the contract, in her runtime — this layer sees only approved requests. + +## 6. Urgency ladder (v1 §3, ratified with today's amendments) + +| class | source (A–G tier) | policy | +|---|---|---| +| `CATASTROPHIC` | SL/kill/liquidation (A/C) | taker MARKET immediately. No cleverness. Ever. Advice ignored by law. | +| `PROTECT` | TP_FLOOR give-back, ADVSL retract (C/D) | maker at touch, **one** reprice, ≤2 s total, then cross. | +| `HARVEST` | FIXED_TP (D) | maker at target ± SmartPlacer offset; chase ≤ N; give-up: regression eats X% of unrealized → cross. | +| `ROTATE` | MAX_HOLD, admin (E) | patient maker; TTL from `deadline_ms`; cross at TTL. | +| `ACQUIRE` | ENTER (F) | patient maker inside spread; **abandon, never chase** (§4-1). | + +Urgency is the caller's declaration of *why*; it is the only "why" this layer ever +learns. N/X/TTL constants live in `_constants.py` with provenance comments citing L8/L10 +characterization rows — **constants from data, never vibes** (and never hardcoded 1 s: +cadence is injected, L2/L3 clock ladders plug in later). + +## 7. The Drive Loop (PINK port — the beating heart) + +Port `pink_direct.py:931-1210` behavior-faithfully onto the DITAv2 async seam +(M2 ExecIoLoop lane, ASEx single-writer): + +- **Working-order state** per order: `{placed_px, queue_age, book_state, chases_left, + ttl, urgency, advice_applied}` — self-contained, serializable (C1: the whole loop + state must survive relocation). +- **TTL sweep** each cadence tick: expired working orders escalate per class table. +- **Fill-vs-cancel race reclassification**: a cancel raced by a fill is a FILL — + venue truth wins, the loop reclassifies rather than double-places (L1 scar). +- **Requote gate**: reprice only when venue state says the order is still live AND + the book moved beyond the class's requote threshold AND `chases_left > 0` AND the + move is toward urgency. Queue-priority question §17-Q4 gates price-unchanged replaces. +- **Exit escalation**: PROTECT/HARVEST exits that exhaust tactics cross unconditionally — + an exit may end cheap or end market, but it always ends. +- **Cancel is a wire op** (v1 §5): cancel-INDETERMINATE ⇒ the order MAY live ⇒ no + re-place until truth (double-fill guard); replace = cancel-CONFIRM → place, never + blind amend. +- **Dispatch integration** (§9): loop-emitted operations enter the kernel through the + P0–P4 priority queue like everything else; a CATASTROPHIC cross rides P0/P1, entries + P4 — the loop cannot invert the ladder. + +## 8. Execution truth (L5, inherited wholesale — restated as law) + +Every wire operation triages into: **NOT_ATTEMPTED** (provably never sent — rollback +sound) / **REFUSED** (venue proved refusal — rollback sound) / **INDETERMINATE** +(sent, outcome unknown — **rollback FORBIDDEN**; bounded point-lookup of own +clientOrderId; unresolved ⇒ UNKNOWN; the E-feed FILL settles it eventually). Post-ack +bookkeeping failure raises `VenuePostAckError` and may never veto the accepted order +(the effect exists; only the record hiccupped). The invariant, and it is the whole +ballgame: **kernel_believes_flat ⇒ venue_is_flat**, under every interleaving the +fault-injection matrix can produce. + +## 9. Priority integration (L6) + +This layer emits work; it never owns the ladder. All kernel mutations flow the +P0 session-safety > P1 execution-truth > P2 capital-preservation > P3 profit/maintenance +> P4 entry queue with the bounded P1 burst (16→P2 yield). The drive loop maps: +CATASTROPHIC ops → P0/P1-adjacent (per trigger), PROTECT → P2, HARVEST/ROTATE → P3, +ACQUIRE → P4. Mutation test: a flood of ACQUIRE placements must never delay one +PROTECT cross (RED by removing the class→priority map). + +## 10. Protective attach — the venue-side will (v1 §6, ratified + mm_ L7) + +On ENTER, the same placeOrder carries `stopLoss` (STOP_MARKET, `workingType=MARK_PRICE`) +at ~2× software SL (width question §17-Q5: fixed 2× vs ATR-scaled). It exists for the +day the client is dead or blind — parity-invisible because it only fires when parity +already failed. mm_'s `TRAILING_TP_SL`/compound mapping (corrected L7) is the vocabulary +for attach params. **VST-verify before live: attached orders auto-cancel on position +close** (orphan-order risk = proto-PINK hell). Serializer support lands in +`prod/bingx/execution.py` (has standalone conditionals only today). + +## 11. Venue dialect layer — the only multi-venue seam + +One module per venue implements: symbol dialect (dash/undash), order-type dialect +(mm_'s corrected tables — `type` vs `timeInForce` namespaces SPLIT), attach-param +serialization, rate budgets (BingX: 10 req/s orders), transport quirks (GOAWAY recycle, +keep-alive heartbeat L1, `.pro` trust anchor, offline-symbol `code==0` fence, dashed WS +symbols, silent subscriptions), and `ensure_symbol_mode` (leverage/margin plumbing, +§2.1). BingX is the only implementation now; Binance's row in mm_'s table plus her OB +numbers (L10) pre-stage the second. **Multi-venue happens HERE and only here** — policy +and loop never learn venue names. + +## 12. Observability — before-and-after or it didn't happen + +Per order: guideline px / placed px / fill px / maker-taker flag / queue_age / chases / +advice_applied+advisor_id / fees / triage outcomes. Aggregates: effective friction bps +per urgency class vs the naive-MARKET baseline (2026-07-10 audit = the frozen baseline). +Tables: `dolphin_uv.exec_smart_journal` + `…advice_journal` — **DDL ships WITH the code +and registers in the applier verify-set** (the 404-storm lesson: tables that don't exist +journal nothing, loudly spool-only at best). Telemetry is lossless-side-lane by law +(§4-5). The friction telemetry is simultaneously MALKHUT's training reward (§5-3) — +one instrument, two consumers. + +## 13. What this layer is NOT (negative constraints — each encoded in a test) + +- NOT a reconciler: never scans orders it didn't place; point-lookup never grows into one. +- NOT a decision layer: never overrides WHAT, never vetoes/delays an exit, never + infers urgency. +- NOT a risk manager: MALKHUT/kernels own approval; this layer executes approved asks. +- NOT venue-aware above §11: policy code containing a venue name is a review reject. +- NOT flight-aware: any import from `blue_prime`/flight runners into this package is a + review reject (agnosticism is enforced by import-linting, not intention). +- NOT dependent on IMPETUS/WS lane: guideline from caller, book via ob_reader/REST + today; the WS/shm price seam (L9) plugs in and only makes it faster. +- NOT allowed to write telemetry on the exec path. Ever. (b46ebd2.) + +## 14. Testing doctrine (the campaign, condensed — full matrix at commissioning) + +- **Mutation litmus per mechanism** (the house law): urgency map (CATASTROPHIC→maker + must RED), give-up triggers, chase bounds, TTL escalation, triage branches, advice + clamps (all three laws), class→priority map, attach serialization. A mechanism + without a RED-capable test does not merge. +- **fill_simulator replay**: policy vs recorded 30 s bookDepth, deterministic, + seed-pinned; extended with mm_'s venue-parameterized books (L10). +- **Fault-injection matrix** (L5): exception at EVERY statement after each side effect; + kernel may never conclude absence it cannot prove. Property/fuzz over interleavings + of {ack, no-ack, timeout, post-ack raise, partial, duplicate}: kernel_flat ⇒ venue_flat. +- **Poison**: partial mid-chase, cancel-INDETERMINATE, reject storms, clock stall, + spread inversion, zero-liquidity book, offline symbol, GOAWAY mid-loop, advice with + every field poisoned (NaN offsets, negative patience, urgency-escalating advice). +- **VST live E2E per urgency class** (Router's 265-test corpus as the crib) + the + maker-fee measurement (§17-Q1) as the FIRST live test ever run. +- **Differential**: golden-vector cert green across executor swap (brain unchanged — + the parity machinery is what makes all of this safe to ship). +- No green-by-pollution; env-gate live tests; NO SOAKS (operator, 2026-07-14) — bounded + scenario tests over open-ended clock runs. + +## 15. Rollout ladder (each rung publishes its friction delta before the next) + +`shadow` (log-only intents beside naive) → `maker_entry_only` → `maker_both` → +live capital. Kill switch `UV_SMART_EXEC=0` = naive MARKET at next boot (deployment +knob; the naive path is never deleted). Flights adopt via the same env-seam pattern +the WS lane proved today (`UV_PRICE_SOURCE`): default inert, G3-style proof that +default-off is bit-identical, operator owns each rung. + +## 16. NFRs (standing hardening doctrine, applies in full) + +Graal-ready (6 NFR-G rules), ASEx single-writer, jemalloc, no hardcoded paths/ports/ +cadences, V-TYPES at boundaries, self-test-to-death on boot, DeadNode reaper hygiene, +location-independent loop state (C1), vendored via VENDOR.lock law, one `_constants.py` +with provenance-cited constants. + +## 17. Open questions & pre-build tasks (answered during adjudication, not build) + +- **Q1 (FIRST, cheapest, blocks the economics)**: measure the real BingX maker fee — + one VST GTX fill. The $91K–$231K savings case rests on an assumed 1 bp. +- **A1**: Router ∪ SmartPlacer adjudication memo (v1 §1 ruling stands: nothing built + before it exists). Include mm_'s L10 data in the fill-model calibration, AND + validate Appendix E's CALIBRATED priors against our own tapes (P0 captures + F5/F6 + journals + L8 sweep artifacts) — priors that fail validation are dropped, loudly. +- **Q2**: conviction source in UV's PRIME path — Alpha conviction absent; vel_div + magnitude as proxy? (SmartPlacer's signal_confidence_adapter input.) +- **Q3**: attached-TP alongside attached-SL, or software-TP only? (TP_FLOOR ratchet is + inexpressible venue-side — likely software-only; TRAILING_TP_SL may change this.) +- **Q4**: does BingX queue priority survive price-unchanged replaces? (Characterize; + gates the requote rule.) +- **Q5**: backstop width — 2× software SL vs ATR-scaled. +- **Q6**: multi-leg round-trip proof (kernel→venue→accounting) on VST before ADVSL + partial-retraction legs ride this layer (DITAv2 built it; UV never proved it). +- **Q7**: MALKHUT advice-journal schema review with mm_ (her training loop consumes it — + co-design, not impose). + +## Appendix A — Flight/dual-leverage compatibility (why there is nothing to do) + +The Flight series' dual-leverage machinery lives entirely in sizing and venue-account +setup — both ABOVE the contract (§2.1). A flight calls `ensure_symbol_mode` when its +leverage policy says so, computes `size` however it likes, and hands this layer the +result. The layer's ignorance IS the compatibility. (Operator called this point dumb; +the spec agrees and enshrines the dumbness as law.) + +## Appendix B — MALKHUT mapping table + +| MALKHUT concept | Lands as | +|---|---| +| `FulfilmentAction.kind = PLACE/CROSS_SPREAD/REDUCE/FULL_EXIT` | `ExecutionRequest` (+urgency: CROSS_SPREAD→PROTECT-like aggression via advice, never via urgency escalation) | +| `qty_fraction × balance` | caller-side sizing → `size` | +| `order_type` (normalized) | `ExecutionAdvice.order_type` through corrected L7 tables | +| `post_only` | `ExecutionAdvice.order_type = post_only` | +| `reduce_only` | `ExecutionRequest.reduce_only` (contract, not advice — it changes WHAT) | +| `CANCEL` / `CANCEL_REPLACE` | `cancel(request_id)` / `amend(request_id, …)` verbs | +| `RiskDecision` | stays in MALKHUT's runtime, above the contract | +| her `m_` clientOrderId prefix | honored: prefix namespace is caller-supplied via `request_id` convention (`u-`, `m-`, `p-` coexist) | + +## Appendix D — Flight-series at-exchange inventory (VST, Flights 1–6, 2026-07-10→14) + +The operator flagged that no inventory existed of what the Flight series taught us by +*actually executing* at-exchange. This is it — every lesson has a scar-commit: + +| # | Lesson | Evidence / fix | +|---|---|---| +| F-1 | Register protective watches from the FILL, never the intent (qty-0 ghost watches: 10 entries, 0 exits, day 1) | `da4163b` — bridge.last_intent registration | +| F-2 | Post-ack failure may never veto an accepted order (telemetry signature skew synthetically REJECTED every 200-OK ENTER → 6 orphan SHORTs) | `b46ebd2` + `VenuePostAckError` fence; class-fix, not instance-fix | +| F-3 | Exits must not ride the scan clock (scan-synchronous drain = 12 s exit delivery) | M6 steel lane; measured F5: decision→dispatch median 4 ms, max 58 ms | +| F-4 | VST acks offline symbols with `code==0` + EMPTY data → fabricated fills | no-orderId ack ⇒ REJECTED; promotion universe gate (EXITs always pass) | +| F-5 | Kernel slot state must advance on venue-fill-confirm, not submit-accept (desyncs both ways: SLOT_BUSY refusals + phantom exits) | dirty-25 root-cause, `d0ae6a1`+`bcd3798` | +| F-6 | clientOrderId must propagate caller→venue end-to-end (kernel-minted p-e/p-x ids broke venue joins; time+qty joins are the fallback, never the design) | promo_client_id metadata propagation | +| F-7 | VST `allOrders` startTime/endTime filters are BROKEN (return empty) — filter client-side | flight recorder + sentinel both hit it | +| F-8 | Measured venue round-trip through the full stack: bridge→receipt median 0.36 s, p90 0.66 s, max 1.21 s (n=95) | F5 timing sweep 2026-07-14 | +| F-9 | Wire values are quantized (wallet 4 dp) — compare at wire precision, exactly at decision level | E-TRIPWIRE fix `d70eb68` (121 false CRITICALs) | +| F-10 | Trigger→fill costs ≤4 bps at 1 s detection (TP prints +0.28/+0.28/+0.32 vs 0.28% effective trigger) — detection granularity, not tactics, was the binding constraint; WS lane (L9) attacks exactly this | F5 exit anatomy + tp_exit_ingress evaluations | +| F-11 | Runners die silently (F4 03:11, F5 16:47 SIGKILL mass-event) — the exec layer's host needs supervision + log-stall watchdog; a dead client is why the venue-attached backstop (§10) exists | F6 watchdog; FL7 wants supervisord | +| F-12 | Arm gates must be fresh-per-call env+file, and kill-switch drills find alias traps (`rm -i` silently no-ops on EOF) | kill-switch drill 2026-07-13, passed 2nd attempt | +| F-13 | Per-order venue leverage set-calls work and are cheap (`leverage SET symbol=LTC-USDT 2→1` inline pre-order) — confirms §2.1: `ensure_symbol_mode` as idempotent pre-trade plumbing | F5/F6 logs | +| F-14 | Journal-lane degradation must be spool-and-loud, never blocking, never silent (404 storm: 933 rows spooled, zero lost, flushed later) | M6 journal clock + 2026-07-14 replay | + +## Appendix E — Microstructure priors (mm_'s study; SPECIFIC beats general) + +From `MALKHUT/docs/OB_MICROSTRUCTURE_STUDY.md`. Two provenance grades — MEASURED +(live API, congruent with our own numbers: adopt) and CALIBRATED (literature-fit +models: adopt as priors, validate against our tapes in A1 before constants ship). + +**MEASURED — BingX vs Binance (the dialect-layer economics table):** perp spreads +1.7–12.6× wider on BingX; BTC depth ~20× thinner; taker 1.25× higher (0.05% vs +0.04% — corroborates our 5.016 bps independently); API latency 2–3× (matches L8 RTT +anatomy); funding follows Binance with R²≈0.90 at 0–8 h lag (Binance = leading +indicator); spot spreads 18–389× wider (**never** BingX spot). Net: **BingX maker +capture is REAL money** (wide spreads = harvestable edge) where Binance majors offer +~none (1-tick spreads) — the maker-first economics of this spec are venue-specific, +and BingX is the favorable venue for them. Wider quotes, lower aggression. + +**CALIBRATED — power-law depth/slippage model (SmartPlacer + fill_simulator +parameterization):** `D(d) = A·d^(1-α)` per asset (BTC A=$750 K α=0.70 … DOGE +A=$22 K α=1.00); expected market-order slippage from walking it (BTC: $100 K ≈ +0.5 bps, $1 M ≈ 3.5 bps; DOGE: $10 K ≈ 5 bps, $100 K ≈ 50 bps). Implication the +callers inherit: **book capacity bounds size** — but for THIS layer it means the +give-up/cross decision must price the walk, not assume it free. + +**CALIBRATED — stress fragility (CATASTROPHIC context):** MMs pull quotes 1–5 ms +into a cascade; depth collapses to 10–30% of normal (BTC ×0.10, DOGE ×0.30); +recovery is minutes. Consequence: a CATASTROPHIC cross during a cascade pays the +vacuum price — doctrine unchanged (cross anyway; §6), but Q5's backstop width and +PROTECT's ≤2 s window should be sized knowing the book they'll meet is the stressed +one, not the quoted one. + +**CALIBRATED — MM pull-speed per class (requote thresholds):** institutional books +(BTC 3 ms) punish stale quotes; retail books (DOGE 25 ms) tolerate them. Requote +cadence constants should be class-aware, not global. + +**CALIBRATED — session structure:** depth/spread swing 4–7× intraday (US-open peak +15:00 UTC, Asia trough); weekend spreads +10–30%. Patience/TTL constants get a +session multiplier knob (future; constants file reserves it). + +## Appendix C — Supersession map + +| Prior doc | Disposition | +|---|---| +| `SPEC_UV_SMART_EXEC_MM.md` (07-13) | SUBSUMED — §§2/3/5/6/7/8/9/10/12 of v1 map to §§6/4/8/2.2/7/13/12/10/14 here; v1 marked superseded in-place. | +| `SMART_EXEC_BACKLOG.md` S1–S9, L1–L4 | GOVERNED — backlog becomes the work queue of this spec (S1=Q1, S2=L2 port, S3=§7, S4=L3 adoption, S5=§4-12, S6=§12, S7=§10, S8=§6, S9=L7). | +| `UV_EXEC_PRIORITY_LADDER_20260713.md` | REFERENCED as law (§9). | +| `BUGCLASS_INDETERMINATE_OUTCOME_20260713.md` | REFERENCED as law (§8). | +| `UV_WS_PRICE_LANE_MIGRATION_SPEC_20260714.md` | SIBLING — price plane; this spec consumes its store, never duplicates it. | + +--- + +*The one-sentence soul: every brain gets the same body, the body takes an asset, a +size, and a prayer — and answers with fills, truth, and a bill smaller than yesterday's.* diff --git a/prod/docs/SPEC_UV_SMART_EXEC_MM.md b/prod/docs/SPEC_UV_SMART_EXEC_MM.md index 17ce1a1..cee83eb 100644 --- a/prod/docs/SPEC_UV_SMART_EXEC_MM.md +++ b/prod/docs/SPEC_UV_SMART_EXEC_MM.md @@ -1,5 +1,5 @@ # SPEC — UV Non-Naive Execution Layer ("SMART-EXEC") -**Status:** SPEC ONLY — build is POST_FINISH-SEQUENCED (first task upon parity cert). +**Status:** ⚠ SUPERSEDED 2026-07-14 by `SPEC_UNIFIED_EXEC_LAYER_20260714.md` (subsumed whole — see its Appendix C for the section map). Kept for provenance; do not build from this document. **Author:** Fable, 2026-07-13. **Owner seam:** DITAv2 venue-adapter boundary. ## 0. One paragraph