docs(spec): SMART-EXEC — non-naive MM/trade executor at the venue-adapter seam
Urgency ladder mapped to A-G doctrine, Router+SmartPlacer adjudication first, inherits indeterminate triage, venue-side catastrophic backstop, parity-invisible. Build is POST_FINISH-sequenced. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Codex
125
prod/docs/SPEC_UV_SMART_EXEC_MM.md
Normal file
125
prod/docs/SPEC_UV_SMART_EXEC_MM.md
Normal file
@@ -0,0 +1,125 @@
|
||||
# SPEC — UV Non-Naive Execution Layer ("SMART-EXEC")
|
||||
**Status:** SPEC ONLY — build is POST_FINISH-SEQUENCED (first task upon parity cert).
|
||||
**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?
|
||||
Reference in New Issue
Block a user