# SPEC — UV Non-Naive Execution Layer ("SMART-EXEC")
**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
Everything above the venue adapter decides WHAT (side, size, asset, exit trigger).
SMART-EXEC decides HOW: maker-vs-taker, where-in-book, when to chase, when to give
up and cross. It slots BELOW the DITAv2 kernel at the venue-adapter seam, so the
kernel, FSM, journals, and the parity ledger see identical semantics — SMART-EXEC
is **parity-invisible by construction**. Economics: taker RT ~0.10% → maker-both
~0.04%; day-1 smoke flips breakeven → +0.9% equal-weight. Research: 90%+ of orders
fill as maker when price "moves to us".

## 1. Assets unified (adjudication = sub-task 1, DO FIRST)
| asset | what it is | keep |
|---|---|---|
| PINK `ExecutionRouter` | maker/taker POLICY + hooks; 265 tests; `maker_both` ran production since 2026-06-11 | the policy state machine + test corpus |
| BLUE `alpha_engine/execution/` SmartPlacer | OB-aware PLACEMENT: `fill_simulator` (30s bookDepth), `signal_confidence_adapter` (conviction→placement), `ob_reader`, `smartplacer_constants` | the where-in-book model |
| `BingX_FILL_CHARACTERIZATION_AND_ADVANTAGES.md` | measured venue friction, incl. VST conditional-order sampling (`prod/bingx/characterization.py`) | ground truth to adjudicate BOTH against |
Likely complementary (Router = whether-maker; SmartPlacer = where-maker). The
adjudication verdict decides: Router ∪ SmartPlacer ∪ union — nothing built before
that memo exists.

## 2. Contract
**Input** (from kernel via venue adapter): `KernelIntent` + `guideline_price`
(decision layer's reference — e.g. tick price that triggered the exit) +
`urgency_class` (below). Decision layers NEVER place orders; they hand a
guideline and an urgency. (Resolves the ADVSL-stale-price concern: scan-clock
exits pass their price as guideline; SMART-EXEC executes against live book.)
**Output**: same `VenueEvent`/receipt stream the naive adapter emits today —
plus friction telemetry (§8). The kernel cannot tell SMART-EXEC from naive
MARKET; only the fills get cheaper.

## 3. Urgency ladder (maps to exec-priority doctrine A–G)
| class | source | policy |
|---|---|---|
| `CATASTROPHIC` | SL / kill switch (C-tier) | taker MARKET immediately. No cleverness. Ever. |
| `PROTECT` | TP_FLOOR give-back, ADVSL full-retract (C/D) | maker at touch, **one** reprice, ≤2s total, then cross |
| `HARVEST` | FIXED_TP (D) | maker-first at target±placement offset; chase ≤N repricings; give-up trigger: if regression eats X% of unrealized, cross |
| `ROTATE` | MAX_HOLD, admin exits (E) | patient maker; TTL minutes; cross at TTL |
| `ACQUIRE` | ENTER (F) | patient maker inside spread per SmartPlacer; abandon (don't chase) if price runs — a missed entry is free, a chased entry is not |
Urgency is assigned by the CALLER (it knows why), never inferred by SMART-EXEC.

## 4. Order-management loop
- Runs on the steel clock (1s now; L2/L3 ladder later — design for cadence
  injection, no hardcoded 1s).
- Per working order: state = {placed_px, queue_age, book_state, chases_left, ttl}.
- Reprice rule: only toward urgency (never widen an exit). Max chases per class
  (constants from characterization data, not vibes).
- Every transition journaled (§8). Single-writer discipline: one owned dispatch
  lane (ASEx pattern, as `uv-exit-dispatch` today); the price/tick lane never
  blocks on wire time.

## 5. Execution truth (inherits bdc54fb doctrine wholesale)
- Failure triage on every wire op: NOT_ATTEMPTED / REFUSED → rollback sound;
  INDETERMINATE → point-lookup own clientOrderID (bounded, read-only, NOT a
  reconcile); unresolved → UNKNOWN, no synthetic REJECT, E-feed FILL settles.
- Cancel is a wire op too: cancel-INDETERMINATE means the order MAY still be
  live → do not re-place until truth established (double-fill guard).
- Idempotency: every order carries our clientOrderID; replace = cancel-confirm
  → place, never blind amend.
- Partial fills are normal in maker land: FSM already speaks PARTIAL_FILL;
  SMART-EXEC must never hold a partial hostage to policy — remainder follows
  the same urgency ladder, fills stream up immediately.

## 6. Venue-side catastrophic backstop (rides along, parity-invisible)
On ENTER, attach `stopLoss` (STOP_MARKET, workingType=MARK_PRICE) at ~2× the
software SL on the SAME placeOrder request. It acts only if the client is dead
or blind (HZ silent-death history) — hence parity-invisible: it fires only when
the system parity measures has already failed. **VST-verify before live:
attached stop auto-cancels when position closes** (orphan-order risk = proto-
PINK hell). Serializer support for attach params must be added to prod/bingx
(execution.py has standalone conditionals only).

## 7. What SMART-EXEC is NOT (negative constraints — encode in tests)
- NOT a reconciler. It never scans open orders it didn't place. Never grows
  the point-lookup into one.
- NOT a decision layer. It never overrides side/size/asset, never vetoes an
  exit, never delays CATASTROPHIC by even one loop tick.
- NOT multi-venue (yet). BingX only; the seam (venue adapter) is where
  multi-venue lands later, not inside policy.
- NOT dependent on IMPETUS. Guideline price comes from caller; live book from
  ob_reader/REST today. IMPETUS (wire-atomic shm tick) plugs into the SAME
  price seam later and only makes it faster.
- Telemetry NEVER on the exec path (b46ebd2 lesson): lossless side-lane spool,
  0-drop, own thread.

## 8. Observability (before-and-after or it didn't happen)
Per order: intended px (guideline) / placed px / fill px / maker-vs-taker flag /
queue_age / chases / fees. Aggregates: effective friction bps per urgency class
vs the naive-MARKET baseline measured 2026-07-10 (venue-friction-half audit).
Table: `dolphin_uv.exec_smart_journal` (DDL ships WITH the code + applier
verify-set entry — lesson of 2026-07-13: tables that don't exist journal
nothing).

## 9. Testing doctrine (non-negotiable subset)
- Mutation litmus on: urgency mapping (flip CATASTROPHIC→maker must go RED),
  give-up triggers, chase bounds, indeterminate triage, backstop attach.
- fill_simulator replay: policy vs recorded 30s bookDepth — deterministic,
  seed-pinned.
- VST live E2E per class (Router corpus pattern — it has 265 to crib from).
- Poison: partial fill mid-chase, cancel-INDETERMINATE, venue reject storms,
  clock stall, spread inversion, zero-liquidity book.
- No green-by-pollution; env-gate live tests.

## 10. Rollout ladder
shadow (log-only intents) → `maker_entry_only` → `maker_both` → live capital.
Env kill switch `UV_SMART_EXEC=0` reverts to naive MARKET instantly (deployment
knob, not code path removal). Each rung: friction delta vs baseline published
before the next rung.

## 11. NFRs (standing hardening doctrine applies)
Graal-ready, ASEx single-writer, jemalloc, no hardcoded paths/ports, V-TYPES
at boundaries, self-test-to-death on boot, DeadNode reaper hygiene, cadence
injectable (no literal 1s), constants in one `_constants.py` with provenance
comments citing characterization data.

## 12. Open questions (answer during adjudication, not during build)
1. Router's maker_both stats on PINK vs BingX *perp* book microstructure now.
2. SmartPlacer signal_confidence_adapter: is Alpha-conviction available in UV's
   PRIME path, or does UV need a conviction proxy (vel_div magnitude)?
3. Attached-TP alongside attached-SL: worth it, or software TP_FLOOR only?
   (TP_FLOOR ratchet is inexpressible venue-side — likely software-only.)
4. Does BingX queue-priority survive price-unchanged replaces? (characterize)
5. Backstop width: 2× software SL, or ATR-scaled?