docs: V7_RISK_DOMINANT preemption reference (r7 live tape; corrected from prior mis-attribution)

prod/docs/V7_RISK_DOMINANT_PREEMPTION_REFERENCE.md

@@ -0,0 +1,269 @@
+# V7_RISK_DOMINANT — Preemption Reference & Economic-Policy Note
+
+**Status:** verified against the live r7 tape (`f13_v21_terminal_max_hold_r7_overnight_20260828`).
+**Scope:** which subsystem preempts a correctly‑resting TP, **why**, and what the
+realized economics were — plus the one policy lever that is *actually* in play.
+**Constraint:** the kernel worktree `/root/uv-wt/f13-hl` is READ‑ONLY here. This doc
+cites LoCs for review; it does **not** tune live r7 (see ·Tuning caveat).
+
+> **TL;DR (corrected):** `V7_RISK_DOMINANT` is **not** a bug and is **not**
+> `ADVSL`/`TP_FLOOR`. It is the `RETRACT` reason emitted by BLUE's
+> `AlphaExitEngineV7` when its `exit_pressure` metric exceeds
+> `retract_pressure_threshold` (default **1.7**). In r7 it fired on two ETH SHORTS
+> and **cancelled their correctly‑rested ×1.40 TPs** (never hit), closing the legs
+> at **−0.0060%** then **−0.0201%** (residual market close) — net‑zero, slot
+> recycled. The TP was placed correctly (tp_exit_modulation ×1.40); the move simply
+> never reached it. The right question is an **economic‑policy review of the
+> `retract_pressure_threshold` (1.7)**, not a change to TP/ADVSL/MAX_HOLD.
+
+---
+
+## 1. What V7_RISK_DOMINANT is
+
+A **reason string** produced by BLUE's vol‑normalised exit engine, **not** a kernel
+LoC. It is returned as the `reason` field of the engine's decision dict and surfaced
+by r7 as `v7_reason=V7_RISK_DOMINANT` in the RETRACT‑edge log line.
+
+| Artifact | File (READ‑ONLY) | LoC | Role |
+|---|---|---|---|
+| `AlphaExitEngineV7` (the engine) | `/mnt/dolphinng5_predict/nautilus_dolphin/nautilus_dolphin/nautilus/alpha_exit_v7_engine.py` | `:364` class; `:447` `evaluate`; `:753‑754` **the `V7_RISK_DOMINANT` RETRACT branch** | emits `{"action":"RETRACT","reason":"V7_RISK_DOMINANT",...}` |
+| `AlphaExitV7Config` thresholds | `…/alpha_exit_v7_engine.py` | `:163‑170` | `exit_pressure_threshold=3.0`, `retract_pressure_threshold=1.7`, `extend_pressure_threshold=-0.5` |
+| V7 calibration notes | `…/alpha_exit_v7_engine.py` | `:721‑741` | 13,000+ RETRACT events → 1.0→1.7; ≥1.7 == "correct retractions" (avg PnL negative) |
+| `VioletExitV7Adapter` (VIOLET boundary) | `/root/uv-wt/f13-hl/prod/clean_arch/violet/exit_v7_wrapper.py` | `:68` class; `:71‑84` init (default config); `:111` `evaluate`; `:132‑138` **priority=2, reason passthrough** | wraps the engine; returns `ExitDecision(reason=…, priority=2)` |
+| Wiring into r7 | `/root/uv-wt/f13-hl/prod/clean_arch/violet/uv/tpsl_ticker.py` | `:732‑766` `_evaluate_v7`; `:496‑523` V7 EXIT path; `:596‑632` **V7 RETRACT edge** | where the RETRACT decision turns into a cancel + `v7_retract` close |
+
+### 1.1 The engine's decision tiering (verbatim, `alpha_exit_v7_engine.py:742‑759`)
+
+```python
+if exit_pressure > cfg.exit_pressure_threshold:        # 742  (3.0 default)
+    if mae_risk > mfe_risk and mae_risk > 0:
+        _reason = "V7_MAE_SL_VOL_NORM"
+        return {"action": "EXIT",   "reason": _reason,              **base_out}   # 745 full
+    # V7_COMPOSITE_PRESSURE — only downgrade to RETRACT if MAE
+    # exceeds the floor.  Negligible adverse movement (< 2 bps)
+    # is likely microstructure noise, not a real exit signal.
+    if mae >= cfg.composite_pressure_mae_floor:        # 749  (0.0002)
+        return {"action": "RETRACT", "reason": "V7_RISK_DOMINANT",   **base_out}   # 750 <-- primary RETRACT
+if exit_pressure > cfg.retract_pressure_threshold:     # 753  (1.7 default)
+    return {"action": "RETRACT", "reason": "V7_RISK_DOMINANT",      **base_out}    # 754 <-- primary RETRACT
+
+if exit_pressure < cfg.extend_pressure_threshold and pnl_pct > 0:                 # 756 (-0.5)
+    return {"action": "EXTEND",  "reason": "V7_DIRECTIONAL_EDGE",   **base_out}    # 757
+return {"action": "HOLD",        "reason": None,                  **base_out}    # 759
+```
+
+**`V7_RISK_DOMINANT` fires on two paths** — both `RETRACT`:
+1. `:750` — *COMPOSITE_PRESSURE* downgrade: `exit_pressure > 3.0` AND `mae ≥ composite_pressure_mae_floor (0.0002)`.
+2. `:754` (PRIMARY for r7) — `exit_pressure > retract_pressure_threshold (1.7)`.
+
+`RETRACT` is a **half / de‑risk** action (see §3), **not** a full `EXIT`.
+
+### 1.2 Calibration evidence (verbatim, `:721‑741`)
+
+```
+# EXIT pressure threshold: 3.0 (raised from 2.69, 2026-05-12)
+#   79 COMPOSITE_PRESSURE EXIT events: total -$963 across 78 trades.
+#   9 trades had MAE < 0.0002 (2 bps) at exit — avg PnL +17% (V7 units),
+#   meaning they were IN PROFIT when cut … false positives from micronoise.
+#   MAE guard (composite_pressure_mae_floor = 0.0002) prevents these 9.
+#   remaining 70 exits at MAE >= 2bps avg PnL -$12.35 — genuine adverse
+#   movements where the cut saves against MAX_HOLD loss.
+#
+#   RETRACT threshold raised from 1.0 to 1.7 based on 13,000+ RETRACT events:
+#   ep=1.0-1.6 avg PnL was POSITIVE (+0.07 to +0.12 V7 units) →
+#   "false retractions on profitable trades".  ep=1.7+ avg PnL turns
+#   negative, indicating correct retractions.
+```
+
+So the engine asserts **≥1.7 pressure == a "correct" cut** (it is saving against a bigger MAX_HOLD loss *on average*). The r7 question is whether that aggregate holds for r7's regime (see §5).
+
+---
+
+## 2. Where it fires in r7 — the dispatch ordering (READ‑ONLY)
+
+`alpha_exit_v7_engine.py` is wrapped by `VioletExitV7Adapter`
+(`exit_v7_wrapper.py:71‑84` — constructed by r7 with **no config arg**, so the engine
+uses the **1.7 default**; the `2.0` seen at `alpha_exit_v7_engine.py:416` is only a
+docstring example for a per‑asset override that has **no callers** —
+`get_effective_config` `:410` / `set_asset_config` `:421` are stubs).
+
+r7 evaluates it once per bar in `tpsl_ticker.py:_evaluate_v7` (`:732‑766`):
+
+```
+tpsl_ticker.py:482   # V7 (BLUE parity, both roles) — one evaluation per bar
+tpsl_ticker.py:492   if has_market_price and self._v7_authority_enabled:
+tpsl_ticker.py:493       v7_raw = self._evaluate_v7(pos, bars, price, ingress)
+tpsl_ticker.py:494       v7_action = str(v7_raw.get("action","")).upper()
+```
+
+The `exit_authority` dispatch this bar (inside the `if not _expired` / bars<max_hold
+branch) is strictly ordered (comments are in `tpsl_ticker.py`):
+
+1. **V7 EXIT (full)** — `tpsl_ticker.py:496‑523` (`if v7_action == "EXIT"`).
+   *"BLUE accepts ONLY the provider's EXIT (HOLD/RETRACT fall through); it
+   outranks ADVSL and MAX_HOLD on this bar."* → `exit_fraction=1.0`,
+   `trigger_type="v7_exit"`, `reason=_normalize_v7_exit_reason(raw.reason)`.
+2. **ADVSL** — `tpsl_ticker.py:524‑595`. Shadow‑only by default; live actuation
+   behind `UV_ADVSL_LIVE=1` opt‑in (`tpsl_ticker.py:543‑544`). **For r7 this was
+   OFF** (the boot arm `EXIT PRE-EMPTION armed (ADVSL/TP_FLOOR…)` is a generic
+   notice and did **not** actuate on these trades — see §6).
+3. **V7 RETRACT (half)** — `tpsl_ticker.py:596‑632`:
+   ```python
+   # 596  # DE-RISK HALF on the HOLD->RETRACT transition only —
+   # 597  # fraction 0.50, never repeated while RETRACT is sustained
+   # 603  if v7_action == "RETRACT" and v7_prev_action != "RETRACT":
+   # 604      self._v7_retract_fires += 1
+   # 612      exit_fraction=0.5, exit_leg_ratios=(0.5,)
+   # 616      LOGGER.warning("V7 RETRACT (half): %s %s state=%s v7_reason=%s",
+   # 620      # ANTI-GHOST (2026-08-13): a RETRACT whose exit is REJECTED while
+   # 622      # venue truth is FLAT is a ghost → confirm_closed + forget.
+   # 625      if state == "rejected" and self._venue_flat(pos.asset):
+   ```
+   This is the **V7_RISK_DOMINANT** path: it submits an `EXIT PRE-EMPT CANCEL`
+   that **cancels the resting TP** (so the TP never fills), then routes the
+   de‑risk half through `trigger_type="v7_retract"`.
+4. **MAX_HOLD terminal** — `tpsl_ticker.py:633‑660` (`Add.15 TERMINAL MAX_HOLD`),
+   gated by `_max_hold_expired` (`tpsl_ticker.py:567`). Not reached for these legs
+   (closed via V7 RETRACT first).
+
+Config knobs / telemetry (`tpsl_ticker.py:299‑313`, `:1092`):
+`'_v7_authority_enabled = os.environ.get("UV_V7_EXIT_AUTHORITY","1")'` (307‑08);
+counters `'_v7_evaluations'`, `'_v7_exit_fires'`, `'_v7_retract_fires'`,
+`'_v7_last_action'` (311‑13) emitted at `:1092`.
+
+---
+
+## 3. The two r7 preempted legs — full tape (READ‑ONLY spool)
+
+Spool: `/root/dolphin_logs/uv_journal_runs/f13_v21_terminal_max_hold_r7_overnight_20260828/runner.log`
+
+### force‑fd9731b2 (ETH SHORT) — entry 2491.50, TP rested at 2484.5238 (0.28% OTM, ×1.40)
+| t (2026‑08‑28) | line | log |
+|---|---|---|
+| 13:58:27 | 513 | `TP REST-ON-ENTRY SUBMITTED: force-fd9731b2f9 ETHUSDT qty=0.008400 @ …` (TP + entry placed) |
+| 13:59:07.458 | 558 | `V7 RETRACT (half): ETHUSDT force-fd9731b2f9 state=preempt_requested v7_reason=V7_RISK_DOMINANT` |
+| 13:59:07.458 | — | `EXIT PRE-EMPT CANCEL submitted: force-fd9731b2f9 ETHUSDT — v7_retract out…` |
+| 13:59:08.931 | 560 | `EXIT PRE-EMPT CANCEL OUTCOME: trade_id=force-fd9731b2f9 verdict=confirmed` (TP **cancelled**, slot released) |
+| 13:59:08.933 | 563 | `TPSL EXIT: v7_retract ETHUSDT force-fd9731b2f9 at 2491.65 (-0.0060%)` ← half close |
+| 14:02:14.783 | 669 | `V7 RETRACT (half): … state=dispatched v7_reason=V7_RISK_DOMINANT` |
+| 14:02:14.789 | 673 | `TPSL EXIT: v7_retract force-fd9731b2f9 at 2492.00 (-0.0201%)` ← residual close |
+| 14:02:26.449 | 679 | `POSITION CLOSED (net-zero) + exit disarmed: ETHUSDT (trade force-fd9731b2f9)` |
+
+- TP **2484.5238 never filled** — live‑tape low ≈ 2491.35 (only ~0.0006% favourable; TP sat 0.28% away).
+- Realised: **−0.0060%** then **−0.0201%** (residual) → net ≈ **−0.020%**, slot recycled. ✔ matches the Dev‑agent live review ("preempted at ~−0.006%, closed remaining partial at about −0.020%").
+
+### force‑475d4ed5 (ETH SHORT) — entry 2492.0, TP rested ≈ 0.28% OTM
+| t | line | log |
+|---|---|---|
+| 14:03:15 | 709 | `FORCE_ENGAGE: SYNTHETIC ENTER ETHUSDT SHORT @ 2504.48 u=0.8` |
+| 14:03:16 / :17 | 716/717 | `TP REST-ON-ENTRY SUBMITTED` → `ACKED` (reduce‑only TP on book) |
+| 14:06:04.213 | 806 | `V7 RETRACT (half): force-475d4ed5ce state=preempt_requested v7_reason=V7_RISK_DOMINANT` |
+| 14:06:05.464 | 808 | `EXIT PRE-EMPT CANCEL OUTCOME: verdict=confirmed` |
+| 14:06:05.469 | 811 | `TPSL EXIT: v7_retract force-475d4ed5ce at 2491.15 (0.0060%)` |
+| 14:07:04.661 | 848 | `V7 RETRACT (half): state=dispatched v7_reason=V7_RISK_DOMINANT` |
+| 14:07:04.665 | 851 | `TPSL EXIT: v7_retract force-475d4ed5ce at 2493.15 (-0.0743%)` |
+| 14:07:19.304 | 865 | `POSITION CLOSED (net-zero) + exit disarmed: ETHUSDT (trade force-475d4ed5ce)` |
+
+Same shape: V7_RISK_DOMINANT cancels the resting TP, closes half then residual at
+near‑entry → net‑zero, slot recycled, FORCE re‑engages. A third leg
+(`force-e3d6af52`, DOGE) cycled the same way (`:1733` `POSITION CLOSED net-zero`
+14:31:28).
+
+---
+
+## 4. The TP was placed correctly (×1.40) — and was never hit
+
+The SHORT entry‑TP level is the soft‑TP curve widened in the CASCADE branch:
+
+```python
+# tp_exit_modulation.py:92-102
+curve  = compute_soft_tp_pct(base, our_leverage)     # 92
+dynamic = curve                                        # 93  branch = "NEUTRAL"
+if ingress.cascade_count > 0:                          # 100
+    dynamic *= 1.40                                    # 101  branch = "CASCADE"
+```
+
+For the r7 SHORTs `base ≈ 0.20%` × 1.40 (CASCADE) = **0.28% TP** ⇒ 2484.5238 from a
+2491.50 entry — exactly the "correctly rested TP" the live review cites. The TP
+order is reduce‑only on the book (`:513`/`717` `TP REST-ON-ENTRY SUBMITTED …
+reduce-once` ACKed at the venue). It was **not** hit because tape low (2491.35)
+never approached 2484.52; it was **cancelled** by the V7 RETRACT edge
+(`EXIT PRE-EMPT CANCEL OUTCOME verdict=confirmed`).
+
+---
+
+## 5. Economic‑policy question (the lever)
+
+`V7_RISK_DOMINANT` fires when `exit_pressure > retract_pressure_threshold` (1.7,
+default). "Pressure" is the engine's composite risk score
+(`alpha_exit_v7_engine.py:694‑719` `base_out` keys: `exit_pressure`, `rv_comp`,
+`mae_thresh1`, `bounce_score`, `bounce_risk`, … — built from MAE tiers §5.2,
+velocity/acceleration, Bollinger squeeze, fractal/Hurst, OB microstruct, EXF
+macros). The calibration at `:721‑741` treats **≥1.7 as a "correct" cut** — but
+that is an **aggregate** claim (13,000+ retractions).
+
+The r7 tape shows the cuts landing at **−0.006% / −0.020%** while a correctly
+rested **×1.40 TP 0.28% away sat untouched** (tape moved <0.001% favourable). So:
+
+> **Policy review (do NOT change while r7 is running):** should
+> `retract_pressure_threshold` (1.7 → 2.0?) let the correctly‑rested ×1.40 TP
+> survive small adverse excursions, or is the ≥1.7 cut still right for this
+> regime? Raising it = fewer preempts, more TP‑hits‑attempted (also more
+> MAX_HOLD exposure if pressure is real). Lowering it = more near‑breakeven cuts.
+
+The engine already records the signal for the review: every RETRACT bar emits
+`exit_pressure` via `last_raw_decision` → `v7_raw` (see `tpsl_ticker.py:761‑762`
+`raw["ob_imbalance"]`, and `v7_raw.get("exit_pressure")` logged at `:513`), plus
+the counters `_v7_retract_fires` / `_v7_exit_fires` (`:313`, `:1092`). A sample of
+`(exit_pressure, pct_move, max_fav, realised)` at each RETRACT edge is enough to
+decide without touching r7.
+
+---
+
+## 6. Definitely NOT this (corrections from the live tape)
+
+- **ADVSL did not actuate.** `UV_ADVSL_LIVE` defaults off (`tpsl_ticker.py:544`);
+  ADVSL ran shadow‑only. The `EXIT PRE-EMPTION armed (ADVSL/TP_FLOOR…)` boot line
+  is a generic pre‑emption notice; for these trades the **specific cause was
+  `v7_reason=V7_RISK_DOMINANT`**, logged at the same millisecond as the CANCEL
+  submit (`:558`). Do **not** chase `tp_exit_modulation.py` / ADVSL knobs for this.
+- **TP_FLOOR never fired.** (It is a `tpsl_ticker.py` MAX_HOLD floor, unrelated.)
+- **My earlier 6.02% `max_favorable_pct` reading was stale/mis‑associated** — the
+  live tape shows tape low ≈ 2491.35 vs TP 2484.52; there was **no 6% favourable
+  move on fd9731b2**. Retract that claim.
+
+---
+
+## 7. Observation / tuning cheat‑sheet (read‑only until policy decided)
+
+- **See the V7 authority fire:** `grep -nE "V7 RETRACT \(half\)|TPSL EXIT: v7_retract|EXIT PRE-EMPT CANCEL OUTCOME" runner.log`
+- **Toggle V7 on/off (coarse; affects V7 EXIT, RETRACT, EXTEND):** env `UV_V7_EXIT_AUTHORITY`
+  (`tpsl_ticker.py:307‑08`, default `"1"`).
+- **Fine‑tune the threshold:** `AlphaExitV7Config.retract_pressure_threshold`
+  (`alpha_exit_v7_engine.py:165`, default `1.7`; per‑asset `set_asset_config` is a stub
+  `:421` with no callers; r7 constructs the adapter with **no config** →
+  `exit_v7_wrapper.py:84` → engine default 1.7).
+- **Counter telemetry:** `v7_evaluations` / `v7_exit_fires` / `v7_retract_fires`
+  (`tpsl_ticker.py:311‑13`, emitted to heartbeat at `:1092`).
+
+---
+
+## LoC index (exact)
+
+- Reason producer (engine decision tiers):
+  `nautilus_dolphin/nautilus/nautilus/alpha_exit_v7_engine.py` — `:742‑759` (tiering), `:750` & `:754` (V7_RISK_DOMINANT RETRACT), `:163‑170` (thresholds), `:721‑741` (calibration), `:447` (`evaluate`), `:364` (class).
+- Boundary (priority=2, reason passthrough, default config):
+  `prod/clean_arch/violet/exit_v7_wrapper.py` — `:71‑84` (init), `:110‑138` (`evaluate`), `:132‑138` (priority=2 / RETRACT-not-promoted), `:125‑128` (raw decision capture).
+- Dispatch into r7 (the preemptor path):
+  `prod/clean_arch/violet/uv/tpsl_ticker.py` — `:482‑495` (V7 eval/arm), `:496‑523` (V7 EXIT full, outranks ADVSL/MAX_HOLD), `:524‑595` (ADVSL shadow + `UV_ADVSL_LIVE`), `:596‑632` (**V7 RETRACT half** + ANTI‑GHOST guard), `:633‑660` (MAX_HOLD terminal), `:299‑313` (V7 knobs/counters), `:307‑308` (`UV_V7_EXIT_AUTHORITY`), `:732‑766` (`_evaluate_v7`), `:756` (engine `.evaluate`), `:761` (`last_raw_decision`), `:1092` (counter telemetry).
+- TP placement (correctly rested ×1.40, untouched):
+  `prod/clean_arch/violet/uv/tp_exit_modulation.py` — `:92` (`compute_soft_tp_pct(base, leverage)`), `:100‑102` (`CASCADE` ×1.40). TP submit at entry: journal `TP REST-ON-ENTRY SUBMITTED` (e.g. `runner.log:513`, `:717`).
+- Tape evidence (READ‑ONLY spool):
+  `/root/dolphin_logs/uv_journal_runs/f13_v21_terminal_max_hold_r7_overnight_20260828/runner.log` — `:558/:560/:563` (fd9731b2 preempt), `:669/:673/:679` (fd9731b2 close), `:806/:808/:811` (475d4ed5 preempt), `:848/:851/:865` (475d4ed5 close), `:1733` (DOGE cycle close).
+
+### ·Tuning caveat (hard)
+r7 is live. **No config/env edits, no code edits, no restart** until policy is
+decided. Collect a RETRACT sample (exit_pressure, pct_move, max_favorable,
+realised) from the counters above; decide threshold offline; then relaunch r7
+against the patched tree. The author of this doc is read‑only on the kernel
+worktree and will not mutate it.