VIOLET V3.5: L3 exchange-leverage wrapper (agent-built, reviewed + fixed)

Built by OA agent per VIOLET_SUB_SPEC__L3_EXCHANGE_LEVERAGE.md; reviewed for
compliance/flaws. VERIFIED: wraps real prod/bingx/leverage.py (untouched), constants
imported from it, NO arbitrary upper caps, exact == bit-identity (1e6 gate 0 mismatches),
ROUND_HALF_EVEN explicitly tested (1.5->2 AND 2.5->2), clamping+non-default caps+frozen
model. 38 tests pass on independent rerun.

REVIEW FIX: to_exchange clamped negative internal_conviction to 0 in the trace field
(reused ConvictionLeverage ge=0); changed trace field to plain float (poison guard only)
so it records the ACTUAL input faithfully; dropped the clamp + unused import. Relocated
8 off-spec leverage-spike scratch files off repo root -> prod/VIOLET_dev/l3_spike/.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

prod/clean_arch/violet/exchange_leverage.py

@@ -0,0 +1,101 @@
+"""VIOLET L3 exchange leverage wrapper.
+
+Dual-leverage doctrine:
+- internal conviction leverage sizes quantity
+- exchange leverage is derived at the venue boundary
+
+This module is a typed wrapper around the authoritative BingX mapping in
+``prod/bingx/leverage.py``. It must stay bit-identical to the production
+functions and exists so V4 can consume the derived exchange leverage with a
+traceable boundary model.
+
+References:
+- ``prod/docs/FRACTIONAL_LEVERAGE_TO_BINGX_FIX.md``
+- ``prod/docs/VIOLET_V3_FINDINGS.md`` §2
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import Field
+
+from .domain import StrictModel, typed
+
+from prod.bingx import leverage as bingx_leverage
+
+CONVICTION_MIN = bingx_leverage.CONVICTION_MIN
+CONVICTION_MAX = bingx_leverage.CONVICTION_MAX
+EXCHANGE_LEV_MIN = bingx_leverage.EXCHANGE_LEV_MIN
+EXCHANGE_LEV_MAX = bingx_leverage.EXCHANGE_LEV_MAX
+LEVERAGE_MAPPING_RULE = bingx_leverage.LEVERAGE_MAPPING_RULE
+
+ExchangeLeverage = Annotated[int, Field(ge=1)]
+
+__all__ = [
+    "CONVICTION_MIN",
+    "CONVICTION_MAX",
+    "EXCHANGE_LEV_MIN",
+    "EXCHANGE_LEV_MAX",
+    "LEVERAGE_MAPPING_RULE",
+    "ExchangeLeverage",
+    "ExchangeLeverageDecision",
+    "VioletExchangeLeverage",
+]
+
+
+class ExchangeLeverageDecision(StrictModel):
+    """Traceable exchange-leverage mapping decision."""
+
+    # Plain float (allow_inf_nan poison guard only) so the trace records the ACTUAL
+    # input faithfully — incl. out-of-domain negatives (which leverage.py clamps
+    # internally) rather than masking them by clamping the trace to 0 (review fix).
+    internal_conviction: float = Field(allow_inf_nan=False)
+    target_exchange_leverage: float = Field(allow_inf_nan=False)
+    exchange_leverage: ExchangeLeverage
+    exchange_min: int
+    exchange_max: int
+
+
+class VioletExchangeLeverage:
+    """Typed wrapper around ``prod.bingx.leverage``."""
+
+    def __init__(self, *, exchange_min: int = EXCHANGE_LEV_MIN, exchange_max: int = EXCHANGE_LEV_MAX):
+        self.exchange_min = int(exchange_min)
+        self.exchange_max = int(exchange_max)
+        self._mod = self._import_leverage()
+
+    def _import_leverage(self) -> Any:
+        return bingx_leverage
+
+    @typed
+    def map_target(self, internal_conviction: float) -> float:
+        return self._mod.map_internal_conviction_to_exchange_leverage_target(
+            internal_conviction,
+            exchange_min=self.exchange_min,
+            exchange_max=self.exchange_max,
+        )
+
+    @typed
+    def normalize(self, leverage: float) -> int:
+        return self._mod.normalize_bingx_leverage_value(
+            leverage,
+            exchange_min=self.exchange_min,
+            exchange_max=self.exchange_max,
+        )
+
+    @typed
+    def to_exchange(self, internal_conviction: float) -> ExchangeLeverageDecision:
+        target = self.map_target(internal_conviction)
+        exchange = self._mod.map_internal_conviction_to_exchange_leverage(
+            internal_conviction,
+            exchange_min=self.exchange_min,
+            exchange_max=self.exchange_max,
+        )
+        return ExchangeLeverageDecision(
+            internal_conviction=float(internal_conviction),
+            target_exchange_leverage=target,
+            exchange_leverage=exchange,
+            exchange_min=self.exchange_min,
+            exchange_max=self.exchange_max,
+        )