diff --git a/prod/docs/UV_EXEC_PRIORITY_LADDER_20260713.md b/prod/docs/UV_EXEC_PRIORITY_LADDER_20260713.md new file mode 100644 index 0000000..1d244a4 --- /dev/null +++ b/prod/docs/UV_EXEC_PRIORITY_LADDER_20260713.md @@ -0,0 +1,124 @@ +# UV execution priority ladder — HJ's A–G adapted to our subsystems + +**Status:** doctrine. Supersedes the ad-hoc P0–P4 mapping in +`asex_kernel_executor.py:_intent_priority`. +**Origin:** HJ's generalized ladder (2026-07-13), adapted to DOLPHIN/UV subsystems. +**Occasion:** the 2026-07-13 orphan incident, which is a textbook violation of it. + +--- + +## The law + +Work is ranked by **what is irrecoverable if it is late**. Truth outranks action; +safety outranks profit; profit outranks permission; research outranks nothing. + +A tier may never be starved by a lower tier. A lower tier may never *destroy* a +higher tier's work — which is precisely what happened on 2026-07-13, when tier-G +telemetry annihilated a tier-B fill. + +--- + +## The ladder, mapped to our subsystems + +### A — Exchange / session safety *(nothing is true if the pipe is lying)* +| HJ's item | Our subsystem | State | +|---|---|---| +| heartbeat | MHS (market-health sensors), HZ client death detector | **not ranked work** — lives outside the queue | +| disconnect | `LiveEFeed` WS lifecycle, HZ client isolation doctrine | **not ranked** | +| sequence gap | `EEvent.venue_seq`, scanner dedup ratchet | **not ranked** (ratchet bug bit us 2026-06-22) | +| trading halted | — | **MISSING** | +| stale price / book | `E-TRIPWIRE` (e_feed), staleness labels | logs only, **not ranked** | +| kill switch | `rm /root/uv-wt/prime-live/UV_PROMOTED.arm` (two-man arm) | **P0 ✓** | + +**Gap:** only the kill switch is ranked. Every other A-item is a log line or a +startup gate (`VenueReadiness`, M4), not pre-emptive ranked work. A feed that has +silently died outranks every trade decision — today it outranks nothing. + +### B — Execution truth *(you cannot manage what you do not know you hold)* +| HJ's item | Our subsystem | State | +|---|---|---| +| fills / partial fills | `EEvent.FILL` → `EKBridge` → kernel | **P4 — LAST** | +| cancels / rejects | venue events → FSM | P4 | +| open order state | `bingx_venue.reconcile()` | kernel-out only (cannot discover) | +| true position | `/user/positions`, `AccountProjection` | **no adopt path at all** | + +**THE INVERSION — the single most important finding.** +`asex_kernel_executor.py:319` enqueues account events at **priority=4**, the lowest +tier — *below ENTER (P3)*. Under queue pressure UV will open a new position **before** +applying the fill that tells it what it already owns. + +Tonight is the proof, and it is exact: the venue filled 6 orders (tier-B truth), and a +tier-G telemetry exception erased the record of every one of them. UV then believed it +was flat while holding 6 live SHORTs. **No SL, TP, or ADVSL can save a position the +kernel does not know exists** — which is why B ranks above C and D, not below them. + +**Required:** account/fill events re-rank to **tier B (immediately below A)**, with a +bounded drain batch so B cannot starve C. + +### C — Price-triggered capital preservation +| HJ's item | Our subsystem | State | +|---|---|---| +| hard SL | catastrophic floor 0.0120, scan tighten-only | **P1 ✓** | +| max adverse excursion | ADVSL (5 gates, `ASL_PRESSURE_CONT_STRESS`) | **P1 ✓** | +| liquidation distance | — | **MISSING** | +| daily / session loss | — | **MISSING** | +| symbol loss | — | **MISSING** | +| account leverage | leverage read for `tp_curve` only | **not a trigger** | +| reduce-only emergency exit | P0 catastrophic EXIT | ✓ (used tonight to flatten) | + +### D — Profit preservation +| HJ's item | Our subsystem | State | +|---|---|---| +| TP | `tp_curve` (0.0020 base + cubic), OB ×1.40/×0.60/×0.75, TP_FLOOR ratchet | **P2 ✓** | +| trailing stop | — | **MISSING** | +| giveback stop | TP_FLOOR ratchet is a partial analogue | partial | +| time stop | MAX_HOLD (250 base × regime) | **P2 ✓** | +| reprice / cancel stale resting exit | PINK `ExecutionRouter` maker/taker | **not ranked** | + +### E — Existing-order maintenance +| HJ's item | Our subsystem | State | +|---|---|---| +| prevent duplicate orders | `TpSlHandler.submit_decision()` reservation boundary | ✓ (not ranked) | +| cancel bad quotes / amend exits | `ExecutionRouter` | **not ranked** | +| prevent self-cross | — | **MISSING** | + +### F — Entry permission *(the only tier allowed to be slow)* +| HJ's item | Our subsystem | State | +|---|---|---| +| DOLPHIN regime | regime/posture feed | ✓ upstream of queue | +| SHEKHINAH / HD prediction | EFSM overlay, HD/TSF | ✓ | +| OBF imbalance | OBF mid-injection | **double-dead** (hook-10 orphaned; runner steps pre-hook prices) | +| spread / depth / slippage | — | **MISSING as a gate** | +| funding / external | `FUNDING_FEE` events | accounted, not gated | +| time-slot weighting | — | MISSING | +| risk budget | capital/leverage | partial | + +`ENTER` sits at **P3 ✓** — correctly below every exit. The *gates* themselves run in +decision code upstream of the queue, which is fine: permission may be slow. + +### G — Persistence / research *(outranks nothing; may never block anything)* +| HJ's item | Our subsystem | State | +|---|---|---| +| replay log / CH spool | M6 journal lane (durable spool + batcher) | ✓ off-path | +| dashboards / telemetry | `bingx_venue` telemetry lane | ✓ **off-path as of today** | +| LMDB | — | n/a | +| model updates | MALKHUT / research | off-path | + +**2026-07-13:** telemetry was inline on the exec path and able to raise. It is now a +bounded non-blocking ring (`deque(maxlen=4096)`, drop-oldest, drops counted) drained by +a daemon lane. Measured: 3.65 µs/call on the exec path against a plane that blocks for +2 s per publish; inline that was a 2000 s stall. + +--- + +## Standing rules that fall out of the ladder + +1. **Truth before action.** Tier B is applied before any tier C/D/F work is + *decided*. A decision taken on a stale book is not a decision, it is a guess. +2. **Nothing below tier B may ever mutate or veto tier B.** Telemetry, journals and + dashboards observe; they do not get a vote on whether a fill happened. +3. **Non-blocking below tier C.** Anything at D or lower that touches I/O does it via + a bounded ring with drop-oldest. Loss of research data beats backpressure on capital. +4. **Every tier is either ranked work or an explicit, documented exemption.** "It's + handled somewhere upstream" is how heartbeat, halt, and stale-book ended up + ranking below a dashboard write.