# Converge to a trustworthy 2-edge book — Design (Phase 2F-A6)

**Date:** 2026-06-22
**Status:** Design (approved — implements the foundation audit's decisions)
**Repo:** fxhnt
**Follows:** the foundation audit (`2026-06-22-paper-book-foundation-audit.md`). User chose D1=a (carry live-only).

## Motivation

The audit confirmed: (F1) carry P&L isn't in equity, (F6) carry tail is unmodellable from daily/survivor data,
(F2) leverage caps the vol-target multiplier not gross (→6× via carry gross-2), (F3) no warmup (cold-start
over-levers), (F4) overlay overfit to a 1-yr bull (6-yr maxDD −98.9%), (F5) offline sweep under-models risk.
**Converge** to one trustworthy book per the audit's recommendation: **2 directional edges (ts-trend +
unlock), price-MTM (signal==equity basis), gross-capped + warmed-up overlay, re-derived/validated on the real
6-yr cycle.** xsfunding → **live-only** (kept on the `xsfunding_nav` forward-track; funding/spot data + carry
helpers retained, just not in the replay).

## Decisions (from the audit)

- **D1 — carry live-only:** remove `xsfunding` from the replay sleeve set (`_REPLAYABLE_SLEEVES`). Keep the
  ingested funding/spot data, the `xsfunding_nav` live asset, and the carry helpers (`XsFundingReplay`,
  `sleeve_daily_carry`, `delta_neutral_return_panel`) in the tree (tested; documented as not-in-replay by
  design). Removing carry also resolves F2's gross-2 stacking (directional sleeves are ~gross-1).
- **D3 — warmup:** `vol_target_leverage` returns `1.0` (unlevered) until ≥ `vol_lookback` (60) book-return
  observations — no maximal leverage on cold-start thin history.
- **D2 — gross cap (belt-and-suspenders):** cap realized **gross exposure** ≤ `max_gross` (3.0) × equity in
  `derive_and_persist` (scale all positions down if exceeded). Mostly moot once carry is gone, but makes the
  invariant explicit and safe if a market-neutral sleeve is ever re-added.
- **D4 — validate on the REAL backfill, not the sweep:** after the above, re-backfill the full 6-yr cycle
  in-cluster and MEASURE the real maxDD. If still too hot (the 30% full-Kelly adaptive budget likely is for 3×
  directional through 2022), **re-derive the vol budget by running a few REAL backfills** at lower budgets
  (e.g. 10/15/20% , ½ vs full Kelly) and pick the one with a survivable maxDD at acceptable return. The
  offline sweep is unreliable (F5) — decide on real-backfill numbers.
- **D5 — one coherent change, then verify.** No new layering beyond D1–D3 + the D4 budget pick.

## Components

1. **`vol_target_leverage` warmup** (`paper_book.py`): add `warmup_obs: int = _VOL_LOOKBACK`; if the usable
   return window has `< warmup_obs` points, return `1.0`. (Currently returns 1.0 only for `<2` obs / `pv≤1e-12`.)
2. **Gross cap** (`PaperBookService.derive_and_persist` + `persist_paper_book`): add `max_gross: float = 3.0`;
   after building `target`, `gross = Σ|p.qty·p.entry_price|`; if `gross > max_gross·capital_base`, scale every
   `qty` by `max_gross·capital_base / gross`. Threaded from `persist_paper_book(..., max_gross=3.0)`.
3. **Revert carry from replay** (`cli.py`): drop `"xsfunding"` from `_REPLAYABLE_SLEEVES` (so
   `_paper_backfill_sleeves` no longer builds it). The `dn_by_date` construction may stay (inert without a
   carry sleeve) or be removed for cleanliness — implementer's call, keep tests green. Update the command echo
   ("xsfunding excluded — live-only" again, now for the audited reason). Snapshot path unaffected (carry was
   never wired into the live snapshot).
4. **D4 re-derivation (operational, in T-deploy):** real 6-yr backfills at candidate budgets → pick survivable.

## Data flow (after)

2 directional sleeves → `current_weights` → unit shadow → `sleeve_daily_return` (price MTM) →
`paper_sleeve_ret`. Overlay: ISV weights + warmed-up vol-target (adaptive budget, to be re-derived) + kill →
gross-capped sizing. Equity: compounding price-MTM (A3f) — **signal basis == equity basis** (both price MTM)
→ internally consistent, every displayed number trustworthy.

## Risks / safety

- **Read-only/additive to mechanics:** warmup + gross-cap are guards (only ever REDUCE leverage/exposure);
  default `max_gross=3.0` + `warmup_obs=60`. Removing a sleeve from the set is subtractive. A3f accounting,
  shadow signal, ISV weights, killswitch, live `xsfunding_nav` untouched.
- **Existing tests:** the `*_equal_weights_*`/leverage tests use ≤1-date or explicit params; the warmup
  (≥60 obs) won't fire on tiny test books unless they exceed 60 days — check + update any that do. The carry
  unit tests (sleeve_daily_carry, XsFundingReplay, delta_neutral_return_panel) stay (helpers retained).
- **D4 honesty:** the 2-edge directional risk IS captured by daily price-MTM (the −98.9% was real), so the
  re-derived budget reflects real cross-cycle risk. Pick for *survivability*, accept lower bull-year return.
- **Convergence:** this is the LAST structural change (D5); subsequent work is parameter choice on real data.

## Out of scope

Wiring carry P&L into equity (carry is live-only); the carry deep-tail data project (F6, unmodellable here);
the live-snapshot xsfunding wiring (carry not in replay or snapshot now).

## Acceptance criteria

- `vol_target_leverage` returns 1.0 until ≥`warmup_obs` obs; unit-tested (thin window → 1.0; ≥60 → levers).
- gross cap: a book whose raw gross > `max_gross·equity` is scaled to exactly `max_gross·equity`; equity base
  unchanged; default 3.0 leaves normal directional books (gross≈leverage≤3) untouched; tested.
- `xsfunding` not in the replay sleeve set; backfill builds only directional (+ stablecoin) sleeves; tested.
- full suite green.
- in-cluster: re-backfill 6-yr → **real maxDD measured**; vol budget re-derived on real backfills to a
  survivable level; final 2-edge curve reported (return / Sharpe / **maxDD across the 2022 bear**) +
  H1/H2-style cross-regime check; `/paper` + `/paper/replay` render the trustworthy curve; verified.
- read-only/additive (guards only); carry data + live track retained; no `*.dbn` staged.
