# Paper book: risk-overlay re-tune (vol budget + dormant kill + drop gate) — Design (Phase 2F-A3g)

**Date:** 2026-06-22
**Status:** Design (approved)
**Repo:** fxhnt
**Follows:** A3f (compounding equity fix) + the overlay A/B sweep on the corrected curve.

## Motivation

With the equity accounting fixed (A3f), the overlay A/B sweep on the corrected curve showed the live overlay
(12% vol-target, ½-Kelly, +killswitch, +marginal-gate) was strangling the edges to +10.5% / Sharpe 1.20.
The data identified the right overlay for these Sharpe-2 crypto edges:
- **vol-target is good** but the **12% / ½-Kelly level was far too timid** (~0.1 leverage). Full-Kelly at a
  25–40% vol budget gives **Sharpe 3.2–3.3, +138%–298%, DD −11%–18%** and *dominates* raw inverse-vol
  (higher Sharpe AND lower DD).
- **marginal-gate HURTS** on this 2-sleeve book (Sharpe 1.78→1.33; benches contributors). Drop it.
- **killswitch at −15/−7 whipsaws** (worse return AND worse DD). BUT a **wider kill (−25/−12) is dormant** at
  the chosen vol budget (vol-target caps DD below the threshold) → zero cost, retained as tail insurance.

## Decisions (from the sweep + user)

- **vol budget: 30% full-Kelly** (`_TARGET_VOL=0.30`, `_KELLY_FRACTION=1.0`) — the balanced middle
  (+183%, Sharpe 3.24, −13.6% DD). A single constant, trivially re-dialable to 25/35/40.
- **killswitch: keep, widened to −25/−12** (`_KILL_DD=0.25`, `_REENTER_DD=0.12`) — dormant at this vol budget
  (the A/B showed identical results with/without it at 25–40% vol), so it's free tail-insurance for a
  worse-than-−25% crash. (User: "drop gate, keep a wider killswitch.")
- **marginal-gate: OFF** — remove the `marginal_gate_active` call from both `paper_risk_overlay` and
  `paper_book_returns`. Keep the `marginal_gate_active` function + its tests in place (validated tool, may be
  re-enabled when the book grows past ~3 sleeves) but document it as intentionally disabled.

## Components

1. **Constants in `application/paper_book.py`:** `_TARGET_VOL = 0.30`, `_KELLY_FRACTION = 1.0`,
   `_KILL_DD = 0.25`, `_REENTER_DD = 0.12`. (Were `0.12 / 0.5 / 0.15 / 0.07`.)
2. **`paper_risk_overlay`:** remove the `active = marginal_gate_active(returns_by_sleeve, active_sleeves)`
   line — weight directly over `active_sleeves`. Leverage + killswitch paths unchanged (they read the new
   constants).
3. **`paper_book_returns`:** remove the `active = marginal_gate_active(before_d, active)` line in the per-date
   loop — weight over the has-history `active` directly. (Keeps the shadow replay consistent with the overlay
   so live == replay.)
4. Docstring note on `marginal_gate_active` (+ the overlay): the gate is intentionally OFF for the current
   small book; the wider killswitch is a dormant backstop at the 30% vol budget.

## Data flow

Unchanged shape — only the overlay parameters + the (removed) gate step change. `paper_risk_overlay` and
`paper_book_returns` both weight over the same `active` set (no gate) and apply the new vol-target/kill
constants → live `/paper` == `/paper/replay` preserved.

## Risks / safety

- **Read-only/additive w.r.t. accounting + strategy mechanics:** only overlay *parameters* + the gate toggle
  change. No change to `book_allocator`, sleeve `run()`/`advance()`, the equity accounting (A3f), the shadow
  signal, or any broker path.
- **Higher leverage (full-Kelly 30% vs ½-Kelly 12%):** deploys more exposure (the point). Still capped at
  `_MAX_LEVERAGE=3.0`; the vol-target de-risks as realized vol rises; the −25/−12 kill backstops a true crash.
- **Consistency:** identical overlay in both paths (gate removed from both).
- **Honest caveats (documented, not in scope):** gross/frictionless (no fee/slippage model); a single
  ~1yr crypto window (2025-06→2026-06) — the 30% choice is a risk-appetite dial, not an optimization claim;
  xsfunding (3rd edge) still excluded from replay.

## Out of scope

Fee/slippage model; removing the now-uncalled `marginal_gate_active` + tests (kept as a re-enablable tool);
adding xsfunding to replay; per-sleeve vol-target; walk-forward parameter validation.

## Acceptance criteria

- Constants updated to `0.30 / 1.0 / 0.25 / 0.12`; the existing overlay unit tests still pass (they assert
  shape/behaviour, not the specific constant values — update any that hard-coded 0.12/0.5/0.15/0.07, preserving
  intent).
- `marginal_gate_active` no longer called by `paper_risk_overlay` or `paper_book_returns`; the
  `test_overlay_drops_dead_sleeve_from_weights` test (which asserted the gate dropped a dead sleeve via the
  overlay) is updated/removed to reflect the gate being off (the gate fn keeps its own direct unit tests).
- Full suite green.
- Re-run backfill in-cluster → `/paper/replay` curve reflects the re-tuned overlay (~+150–200% gross, Sharpe
  ~3, DD ~−14% — directionally matching the C-grid 30% row); `/paper` live agrees; verified post-deploy.
- Read-only/additive (accounting/strategy mechanics); no `*.dbn` staged.
