siloqy/prod/docs/VIOLET_SUB_SPEC__L3_EXCHANGE_LEVERAGE.md

# VIOLET Sub-Spec — L3 Exchange-Leverage Wrapper (parallel-developable unit)

**Status:** READY TO BUILD, independently. Self-contained brief for an autonomous agent
running **on this host** (`/mnt/dolphinng5_predict`, no git remote). Python
`/home/dolphin/siloqy_env/bin/python3`. Branch `exp/pink-ditav2-sprint0-20260530`.
This is **V3.5** of `VIOLET_DEV_SPEC_AND_PLAN.md`. Develop in parallel with V3.4
(DecisionEngine↔Sizing integration, owned by the lead) — **zero file overlap.**

## 1. Objective

Wrap BLUE's conviction→exchange-leverage mapping into a V-TYPES-bounded VIOLET L3
component, **bit-identical** to the real mapping in `prod/bingx/leverage.py`. This is the
"tradeability" side of the dual-leverage: the bet-sizer's internal **conviction leverage**
[0.5, 9.0] sizes the QUANTITY; the **exchange leverage** [1, 3] (BingX integer, conservatively
capped) is derived from it at the venue boundary. VIOLET needs a typed, observable wrapper
for this so V4 (execution) can set venue leverage faithfully.

## 2. Non-negotiable constraints

- **WRAP, DON'T REIMPLEMENT.** Call the real `prod/bingx/leverage.py` functions; do not
  re-derive the linear map / rounding. Bit-identity is the gate.
- **ZERO edits to shared files** (`prod/bingx/leverage.py`, `prod/nautilus_event_trader.py`,
  `prod/clean_arch/dita_v2/*`, `nautilus_dolphin/**`, `blue_parity.py`). Per-commit:
  `git diff --cached --name-only` must not contain them.
- **V-TYPES** (`prod/clean_arch/violet/domain.py`): refined types at boundaries, `@typed`
  (beartype) on public methods, `StrictModel` value objects. Only poison guards
  (finite + in-domain); **NO arbitrary magnitude caps BLUE/leverage.py lacks** (a prior
  reviewer flagged exactly this liberty in the sizing layer — do not repeat it).
- **Exchange-agnostic naming preserved**: this is the L3 boundary; keep the internal
  (conviction) vs exchange distinction explicit in types and field names.

## 3. The wrap target (authoritative — `prod/bingx/leverage.py`, 83 lines, no callers)

Constants: `CONVICTION_MIN=0.5`, `CONVICTION_MAX=9.0`, `EXCHANGE_LEV_MIN=1`,
`EXCHANGE_LEV_MAX=3`, `LEVERAGE_MAPPING_RULE="round_half_even_linear_0.5_to_9.0_to_1_to_exchange_cap"`.

Functions to wrap (exact signatures):
```
def normalize_bingx_leverage_value(leverage, *, exchange_min=EXCHANGE_LEV_MIN,
                                   exchange_max=EXCHANGE_LEV_MAX) -> int
    # ROUND_HALF_EVEN(leverage) clamped to [exchange_min, exchange_max] (BingX int-only)
def map_internal_conviction_to_exchange_leverage_target(internal, *, exchange_min=..,
                                   exchange_max=..) -> float
    # clamp internal to [0.5,9.0]; linear: exch_min + (internal-0.5)/(9.0-0.5) * (exch_max-exch_min)
def map_internal_conviction_to_exchange_leverage(internal, *, exchange_min=.., exchange_max=..) -> int
    # = normalize_bingx_leverage_value(map_..._target(internal), ...)  -> final integer exchange leverage
```
**Behaviours that MUST round-trip bit-identically:** the [0.5,9.0] clamp of out-of-range
conviction; the linear interpolation; **ROUND_HALF_EVEN** (banker's rounding — x.5 cases
round to even, e.g. 1.5→2, 2.5→2); the integer clamp to [exchange_min, exchange_max];
non-default `exchange_min/max` args.

## 4. Deliverable — files to CREATE

### 4.1 `prod/clean_arch/violet/exchange_leverage.py`

- **Refined types** (V-TYPES, in this file or import from domain): reuse
  `ConvictionLeverage` from `alpha_wrappers.py` (Annotated float gt/ge 0). New:
  `ExchangeLeverage = Annotated[int, Field(ge=1)]` (BingX integer; NO upper-cap liberty —
  the function clamps to exchange_max itself).
- **`ExchangeLeverageDecision(StrictModel)`**: `internal_conviction: ConvictionLeverage`,
  `target_exchange_leverage: float` (the pre-round target, allow_inf_nan=False),
  `exchange_leverage: ExchangeLeverage` (final int), `exchange_min: int`, `exchange_max: int`.
  Frozen + extra=forbid.
- **`VioletExchangeLeverage`** class:
  - `_import_leverage()`: import `prod.bingx.leverage` (it's an in-repo module; plain
    `from prod.bingx import leverage` should work since cwd is the root — verify; no
    nautilus_dolphin root-injection needed).
  - `__init__(self, *, exchange_min=1, exchange_max=3)`: store caps (defaults = gold/BingX).
  - `@typed map_target(self, internal_conviction: float) -> float`: wraps
    `map_internal_conviction_to_exchange_leverage_target`.
  - `@typed normalize(self, leverage: float) -> int`: wraps `normalize_bingx_leverage_value`.
  - `@typed to_exchange(self, internal_conviction: float) -> ExchangeLeverageDecision`:
    wraps `map_internal_conviction_to_exchange_leverage`, returns the full decision
    (target + final + caps) for traceability.
- Module docstring: the dual-leverage doctrine (conviction sizes quantity; exchange leverage
  derived at venue boundary), cite `FRACTIONAL_LEVERAGE_TO_BINGX_FIX.md` and
  `VIOLET_V3_FINDINGS.md §2`.

### 4.2 `prod/clean_arch/violet/test_violet_exchange_leverage.py`

Mirror the test patterns in `test_violet_sizing.py` / `test_violet_modulation.py`
(hypothesis + drift-guards + `@pytest.mark.gate`). Required tests:

**Unit:**
- defaults: `exchange_min=1`, `exchange_max=3`; constants match leverage.py (drift-guard:
  import leverage.py and assert `CONVICTION_MIN/MAX/EXCHANGE_LEV_MIN/MAX` equal the wrapper's).
- conviction 0.5 → target 1.0; conviction 9.0 → target 3.0 (endpoints).
- **ROUND_HALF_EVEN boundary cases**: craft convictions whose target lands on x.5 and assert
  the final int matches banker's rounding (e.g. target 1.5 → 2, 2.5 → 2). Compute the exact
  conviction that yields target=1.5/2.5 from the linear map and verify.
- out-of-range conviction (`<0.5`, `>9.0`, and the sizing extremes up to 9) clamps like BLUE.
- non-default `exchange_max` (e.g. 5, 9) flows through.
- `ExchangeLeverageDecision` frozen (pydantic raises on mutate).

**Property (hypothesis):**
- `@given` conviction ∈ floats[-5, 64] (incl. out-of-range), exchange_max ∈ ints[1,9]:
  wrapper output `==` leverage.py output **exactly** (this is unit-level bit-identity);
  final exchange_leverage ∈ [exchange_min, exchange_max] and is an int.

**Gate (`@pytest.mark.gate`):**
- `test_gate_exchange_leverage_bit_identity`: **N≥1e6** Monte-Carlo over the joint space
  (conviction ∈ uniform[-1, 64] to hammer clamping + the full sizing range; exchange_min ∈
  {1}, exchange_max ∈ {1,2,3,5,9}). Assert VIOLET `to_exchange(...).exchange_leverage` and
  `.target_exchange_leverage` are **float/int-for-float `==`** to the real leverage.py
  functions across every sample. `np.count_nonzero(blue != violet) == 0`. Write a gate
  report to `prod/VIOLET_dev/reports/violet_v3_exchange_leverage_<ts>.json` (mirror
  `_write_gate_report` in `test_violet_sizing.py`).

## 5. Validation gate (BINDING)

1. **MC bit-identity** (§4.2 gate) at N≥1e6, exact `==`, joint conviction×exchange-cap space
   incl. out-of-domain conviction (clamp coverage) and x.5 rounding boundaries.
2. Full non-gate suite green; **shared-files-clean**; the import of `prod.bingx.leverage`
   resolves on-host.

## 6. Acceptance criteria

- `exchange_leverage.py` + `test_violet_exchange_leverage.py` created (no other files touched).
- MC bit-identity gate: 0/1e6 mismatches.
- Unit + property tests green; ROUND_HALF_EVEN boundary explicitly tested.
- `git diff --cached --name-only` ∌ any shared file.
- Commit message documents: wrap target, bit-identity result, V-TYPES boundary.

## 7. Watch-outs (learned from the sizing review)

- **No arbitrary magnitude caps** in the V-TYPES aliases (no `le=64`-style ceilings) — only
  what leverage.py itself enforces. The function clamps; the type must not double-guard with
  a value BLUE/leverage.py would accept.
- **ROUND_HALF_EVEN ≠ round-half-up.** `2.5 → 2`, not 3. Test the even-rounding explicitly.
- Bit-identity here is "trivial" by design (you call the real function) — that's the point:
  the gate proves the V-TYPES boundary + arg passing perturb nothing. Do NOT use `approx`.
- `target` (float, pre-round) and `exchange_leverage` (int, post-round) are BOTH part of the
  contract — journal/return both.

## 8. Integration (lead will wire; agent need not)

The lead integrates `VioletExchangeLeverage` at the L3/exec boundary in V4 (venue
leverage-set), consuming `VioletSizer`'s conviction output. The agent's deliverable is the
standalone, gated component + tests. Hand back: the two files + the gate report path.

## 9. References

`prod/bingx/leverage.py` (target) · `prod/docs/FRACTIONAL_LEVERAGE_TO_BINGX_FIX.md`
(dual-leverage origin) · `VIOLET_DEV_SPEC_AND_PLAN.md` (V3.5) · `VIOLET_V3_FINDINGS.md §2`
(dual-leverage) · pattern refs: `prod/clean_arch/violet/modulation.py`,
`test_violet_sizing.py` (gate + `_write_gate_report` style), `domain.py` (V-TYPES).