sentiment-engine/prod/docs/SPEC_UV_SMART_EXEC_MM.md

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?