hjnormey/sentiment-engine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5e052503c4920ffd82d2664980cf93cd6bd27e64
sentiment-engine/prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md

39 KiB
Raw Blame History

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. Operating tiers — the smartness ladder (operator doctrine, 2026-07-14)

Orthogonal to the deployment rungs (§15.1): tiers are what the executor IS; rungs are how each tier goes live. Every tier kill-switches to the tier below; a tier ships only after the tier below has published its friction delta. Higher tiers may only get cheaper or safer — never change WHAT (the §2.3 promises hold at every tier).

Tier Name Content Standing
T0 Naive MARKET everything (today's flights) LIVE — the eternal fallback, never deleted
T1 Better orders The operator's point, verbatim intent: "fire trades better than costly MARKET, try and MM, cut fees in half by simply using better order types — usable RIGHT NOW." Concretely: GTX/post-only-first with bounded quote lifetime → cross at TTL; CATASTROPHIC passes through as MARKET untouched; nothing else. No SmartPlacer, no advice, no chase logic. This is a PORT, not an invention: PINK's maker_both ran production since 2026-06-11 (L2, 265 tests), and short-lived GTX is the ONLY L8-certified fill-improvement technique (§4-16). Entry gate: Q1 (measure the maker fee — one VST GTX fill). Prize at 50-75% maker conversion: ~$43-64K on BLUE's historical volume (§4-20). FIRST SHIPPABLE INCREMENT — buildable immediately on unpark, pre-adjudication
T2 Characterization-informed L8 sweep findings become tactics: symbol-aware quantization/notional banding (§4-15), partial-remainder re-quote per urgency (§4-11), venue idiom law (§4-17), SNAPSHOT barrier (§4-19), latency decomposition telemetry (§4-18) after T1 delta published
T3 OB-aware placement SmartPlacer adoption (L3): where-in-book offsets, ob_confirms_signal, conviction→patience (Q2 proxy), Appendix-E depth priors (validated) gated on A1 adjudication
T4 Full drive loop PINK port complete (§7): chase budgets, requote gate, fill-vs-cancel races, exit escalation the v1-spec vision
T5 Fast plane WS/shm price seam (L9) in the loop; C1 location-independence exercised (colo-ready); session-aware constants (App. E)
T6 Multi-leg exit_leg_ratios proven end-to-end (Q6); ADVSL partial retraction legs ride the layer
T7 Advised MALKHUT advice plane live (§5) — she suggests, layer clamps, telemetry closes her training loop
T8 Self-tuning constants auto-updated from own friction telemetry (provenance-logged, operator-gated)
T9 Multi-venue second dialect module (§11); Binance pre-staged by L7 tables + App. E
T10 MALKHUT game-theoretic placement she doesn't advise placement — she IS placement (fulfilment policy executes through the same contract, same promises) the north star
T11–T12 Unassigned headroom — the ladder expects rungs we can't name yet
T13 Reserved ASI. (If the market is still imperfect enough to need an executor, §0 still applies.) reserved by operator

15.1 Deployment rungs (per tier; each publishes 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.