# Paper-book foundation audit (Phase 2F — pause & audit)

**Date:** 2026-06-22
**Status:** Audit (no code) — decide the architecture before resuming
**Trigger:** "going in circles" — A3c→A4→A5 each layered a fix that revealed the next gap. Stop, audit.

## Layers (current architecture, as built)

1. **Data (warehouse, DuckDB feature store)** — `feature='close'` (perp, 2020-09→2026, 217 sym),
   `'spot_close'` (2017→2026, 162 sym), `'funding'` (2020-06→2026, 217 sym). Daily granularity.
   **Survivorship-biased** (only currently-listed symbols have history; delisted coins absent).
2. **Per-sleeve return signal (`paper_sleeve_ret`)** — per (date, sleeve) daily return, from a **unit shadow
   book** (`paper_shadow_positions`, never throttled). Directional sleeves: `sleeve_daily_return` = price MTM
   (`Σ qty·Δclose / gross`). Carry (xsfunding): `sleeve_daily_carry` = delta-neutral `Σ w·((spot_ret−perp_ret)
   +funding)/gross`. **Per-sleeve return MODE** (price vs carry) via `getattr(sleeve,'return_mode')`.
3. **Sizing overlay (`paper_risk_overlay`)** — ISV-adaptive inverse-vol weights (`isv_adaptive_weights`) +
   vol-target leverage (`vol_target_leverage`, adaptive budget [25,35]% A3h, cap 3.0) + drawdown killswitch
   (`DrawdownKillSwitch`, −25/−12). Computed from the strictly-prior `paper_sleeve_ret` window.
4. **Equity accounting (`paper_nav`, `persist_paper_book`)** — compounding MTM (A3f): `equity_d = equity_{d-1}
   + Σ positions_before.qty·(close − entry)`; book sized off running equity.
5. **Verification** — offline sweeps over `paper_sleeve_ret`; the real in-cluster backfill is ground truth.

## CONFIRMED issues (with evidence)

### F1 — ⛔ Equity ignores the per-sleeve return mode (carry P&L is dropped). [LOAD-BEARING]
`persist_paper_book` computes `gain = Σ p.qty·(price − entry)` over ALL positions — **price MTM only, no carry
branch.** The carry sleeve's positions are market-neutral perp longs/shorts → marked to perp close they net to
~0 (basis only). **So xsfunding's +1.8-Sharpe funding P&L NEVER reaches `paper_nav`.** The signal layer (F2)
uses carry; the equity layer uses price. **Basis mismatch between sizing and equity.** Evidence: all-xsfunding
dates (2020-10) where equity barely moves; `persist_paper_book:30` is price-only.
→ The "3-edge" equity is really the 2 directional edges; carry only crowds *weights*, contributes ~0 *return*.

### F2 — ⛔ Leverage caps the vol-target MULTIPLIER, not actual GROSS exposure.
`vol_target_leverage` caps `lev ≤ 3.0`. But effective gross = `lev × Σ w_sleeve·gross_sleeve`; the
market-neutral carry has `gross_sleeve=2` → **observed effective gross 6.0×** (cluster: 2020 mean 5.82, max
6.00). The cap is on the wrong quantity.

### F3 — ⛔ No warmup: max leverage on cold-start thin history.
2020 (series start, thin history) ran mean 5.8× leverage → the multi-year book's **−98.9% maxDD trough was
2021-02-28** ($100k→$175k→$1,986). The vol-target levers maximally before it has a stable vol estimate.

### F4 — ⚠️ Multi-year OOS: the overlay was overfit to a 1-yr bull.
1-yr (2025-26) showed +147%/Sharpe 2.74; the SAME overlay over 2020-2026 = **−98.9% maxDD**. The A3g/A3h
re-tune (30% full-Kelly) was calibrated on a benign window.

### F5 — ⚠️ Offline sweep under-models risk → unreliable for tuning.
The cycle sweep reported −3% to −23% maxDD; the real deployed backfill was −98.9% (it ignores the gross-2
stacking + uses a has-history active-set proxy). **Tune/verify on the real backfill, never the sweep.**

### F6 — ⚠️ Carry deep-tail unmodellable from this data.
Carry maxDD only −3.4% even through 2022, because the catastrophic carry losses (FTX counterparty, LUNA
delist, ADL, intraday squeezes) are absent from **daily + survivorship-biased + Binance-surviving** data. The
*normal* carry risk is realistic (Sharpe 1.80 multi-year); the *tail* is structurally invisible here.

## What is SOUND (keep)
- The edges are real (multi-year standalone Sharpe: ts-trend 2.39, unlock 1.73, **xsfunding 1.80**).
- A3f compounding accounting is correct **for price-MTM (directional) sleeves**; live==replay holds for them.
- The shadow-signal design (kill-proof, causal) is sound for directional sleeves.
- Data ingestion (funding/spot/perp, multi-year) is correct + reusable.

## Architectural decisions needed
- **D1 (carry):** carry has TWO independent blockers (F1 equity-gap + F6 unmodellable tail). Decide:
  (a) **carry live-only** (revert from replay; keep `xsfunding_nav` forward-track + the data) — converges; OR
  (b) wire carry P&L into equity (fix F1) AND accept the tail stays optimistic (F6) + cap its weight.
  **Audit recommendation: (a)** — the daily-survivor replay cannot faithfully carry a delta-neutral funding
  edge; its truth is a live forward record.
- **D2 (leverage):** cap **actual gross exposure** (e.g. ≤3× gross incl. market-neutral legs), not the
  vol-target multiplier (fixes F2). Apply post-sizing in `persist_paper_book`/`derive_and_persist`.
- **D3 (warmup):** no leverage > 1.0 until ≥ `vol_lookback` (60) real book-return obs (fixes F3).
- **D4 (validation):** re-derive/verify the overlay on the **full 6-yr cycle via the real backfill** (not the
  sweep); the target is a *survivable* maxDD across the bear, accepting lower bull-year return (fixes F4/F5).
- **D5 (scope discipline):** one coherent change implementing the chosen D1+D2+D3, then verify — no more
  incremental layering.

## Recommended target architecture (if D1=a)
A **2-edge directional paper book** (ts-trend + unlock), price-MTM compounding (sound today), with a
**gross-capped, warmed-up** overlay re-derived on the full cycle. **xsfunding stays live-only** (`xsfunding_nav`
+ the ingested funding/spot data retained). This is internally consistent (signal==equity basis), structurally
safe (gross cap + warmup), and validated cross-cycle — and it stops the layering. The carry edge is real and
tracked where its risk is real (live), not faked in a daily replay.

## Immediate state
Cockpit currently shows the 6-yr multi-year backfill (+4320% / −98.9% — the directional book at 6× gross). It
should be restored to a trustworthy view once D1–D4 are decided + implemented.
