sentiment-engine/prod/docs/SPEC_UNIFIED_EXEC_LAYER_20260714.md

# 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). **WHY T1 exists (operator, verbatim): usable RIGHT NOW, WITHOUT WEIRD BUGS.** Its simplicity is a SAFETY property, not a convenience: every weird bug in Appendix D came from complexity at this seam (races, rollbacks, phantom state). T1 adds exactly ONE new state (resting GTX with TTL) and ONE new transition (TTL→cross) — both de-bugged in PINK production for a month — and inherits every truth/idempotency guarantee unchanged. No chase ⇒ no requote races. No advice ⇒ no clamp bugs. No book model ⇒ no misread books. The only new wire op is cancel-at-TTL, and cancel-INDETERMINATE is already law (§8). The bug surface is, by construction, the smallest nonzero one available. | 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.2 The size axis — S-grades (operator bonus doctrine, 2026-07-14)

Size that moves the book is a SECOND dimension, orthogonal to smartness. Every
`ExecutionRequest` gets an S-grade at intake, computed from Appendix E's power-law
model (`D(d)=A·d^(1-α)`, per-asset, stress-adjusted by fragility factor):

| Grade | Definition | Today's reality | Handling |
|---|---|---|---|
| **S0** | size ≪ top-of-book depth (walk < 1 tick) | BLUE's ~$60K avg vs ~$212K BTC best bid — mostly S0 on majors, NOT on alts | any tier executes directly |
| **S1** | walks visible levels (expected walk ≥ spread) | alts at current sizing already here (enter-slip −24 bps says so) | T2+ prices the walk into give-up/cross decisions |
| **S2** | exceeds book capacity in the urgency window | future capital | must be SLICED — refused whole, loudly, below T14 |
| **S3** | size IS the market (footprint changes MM behavior) | the 1MM-era problem | MALKHUT/VIBRASS game-theoretic territory |

**The composability ruling** (the operator asked; the contract answers):

- **COMPOSABLE (sub-rung style, `T*.s`, available at any tier ≥ T1):** slicing/
  scheduling — TWAP/VWAP/participation-rate slicers are CALLERS: they decompose one
  parent request into N child `ExecutionRequest`s over time, each child inheriting
  urgency and S0/S1 grade. The agnostic contract makes this free — the layer cannot
  tell a slicer from a brain, by design. Ships as a separate `sizer` module ABOVE
  the contract; the layer itself gains only a `parent_request_id` journal field so
  friction telemetry can aggregate families. (VIBRASS's "TWAP/VWAP at size" future,
  per the dual-clock north star, lands exactly here.)
- **NOT composable (wholesale tiers, T14+):** size-aware tactics INSIDE a working
  order — venue-native iceberg (dialect where supported), live-depth-adaptive child
  sizing, queue-position games, stealth/anti-detection placement, cross-venue
  liquidity seeking. These change the working-order state machine itself and each
  carries its own weird-bug class (the very thing T1 exists to avoid), so they may
  not ride in as sub-rungs. **T14 = size mechanics; T15+ = adversarial size games**
  (MALKHUT-adjacent; distinct from T10's placement authority).

**Pre-qualification gate (the pain-fence):** below T14, the layer REFUSES S2+
requests whole — loudly, with the computed expected-walk in the refusal — forcing
the caller through a slicer or the operator through a tier decision. Nobody
discovers the large-size pain class by accident in production.

## 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.*