# Hyperliquid v76 paper-runtime learning harness

Use when Testnet execution gates are technically proven but live-preview is still blocked and the user wants fast v76 strategy learnings without weakening live safety.

## Safety boundary

- Keep **no live-go / no micro-live / no Mainnet signed action** explicit in every tool and report.
- Use Mainnet only for read-only market data and local paper fills.
- `CTB_PAPER_TRADING=true` and `CTB_DRY_RUN=false` is acceptable only when the runtime uses a local `PaperExecutor`; document that `dry_run=false` means simulated paper fills, not exchange orders.
- Refuse/abort paper runtimes if `CTB_LIVE_TRADING_ALLOWED=true` is present unless the task is explicitly live-approved and all live gates pass.
- Strategy modules must remain pure: no `Exchange`, `Info`, `market_open`, `order`, `cancel`, `market_close`, CCXT `create_order`, or signed SDK calls in `src/strategies/`.
- Verify with an AST/static scan plus tests before reporting safety.

## Runtime shape

Create dedicated experiment dirs under the repo runtime tree unless the project has a canonical runtime root:

```text
runtime/experiments/candidate_v76_hl_confirmed_squeeze_hybrid/
runtime/experiments/candidate_v76_strict_live_candidate/
runtime/experiments/candidate_v76_research_probe/
```

Each dir should contain:

- `trade_journal.jsonl` — scorecard-compatible paper exits/fills with net costs.
- `signal_journal.jsonl` — shadow signal decisions, including blocked signals.
- `bot.pid` — supervisor/monitor identity.
- `state.json` — lightweight paper runtime state such as previous mids and recent coin distribution.

Supervisor status should validate both PID liveness and `/proc/<pid>/environ` identity:

- `CTB_STRATEGY_ID=<expected>`
- `CTB_PAPER_TRADING=true`
- `CTB_DRY_RUN=false`

## Shadow signal journal schema

Log every relevant signal event, not just executed paper trades:

- `timestamp`, `coin`, `strategy_id`
- `setup_type`: `squeeze_breakout`, `survival_reclaim`, or `blocked`
- `signal_score`
- `would_enter`
- `block_reason`
- `spread_pct`, `depth_ok`
- `expected_roundtrip_cost_pct`
- `expected_move_pct`
- `expected_move_vs_cost`
- `funding`
- `data_quality_allowed`
- `breadth_state`, `trend_state`
- `leakage_state` including top-coin/WLD throttling status
- `risk_gate_result`
- `final_decision`

This distinguishes whether v76 is too quiet because of market regime, signal filters, cost model, WLD/top-coin leakage, data quality, or a bug.

## Strict vs research-probe pattern

Run at least two paper-only variants in parallel:

### `candidate_v76_strict_live_candidate`

- Conservative final logic.
- `expected_move >= 3x roundtrip_cost`.
- WLD/top-coin leakage throttled or blocked.
- `top_coin_share_last_30 <= 50%` remains a live-readiness gate.
- Strict spread/depth/data-quality filters.

### `candidate_v76_research_probe`

- Paper-only, explicitly not live-capable.
- `expected_move >= 2x roundtrip_cost`.
- Slightly looser breadth/reclaim checks.
- Survival-rebound after reclaim may be allowed.
- Mark every trade/report as `RESEARCH` or `research=true`.
- Never automatically promote this variant to live readiness; use it only for learning which filters matter.

## Replay / ablation from historical journals

Add a read-only replay tool when prior paper strategies have useful journals, e.g.:

```bash
.venv/bin/python -m src.tools.v76_replay_from_journals \
  --source-strategies candidate_v66_squeeze_breakout_sampler,candidate_v69_squeeze_breakout_confirmed,candidate_v75_hybrid_survival_squeeze \
  --target-strategy candidate_v76_hl_confirmed_squeeze_hybrid \
  --json
```

Report:

- Which old winners v76 would have taken.
- Which old losers v76 would have blocked.
- Most common blocking filters.
- `pnl_total_net`, `pnl_ex_wld`, `pnl_ex_top_coin`, per-coin PnL.
- `top_coin_share`.
- Counts for cost, breadth, data-quality, leakage, trend, and no-reclaim blocks.

If v76 blocks nearly all historical winners because of WLD/top-coin leakage, do not weaken live gates. Instead, keep strict unchanged and experiment only in the research-probe.

## Scorecard learning block

Extend the fast scorecard with a v76 section that reads the local v76 runtime dirs and surfaces:

- strict/base/research trades
- signals seen/blocked
- top block reasons
- net PnL, `pnl_ex_wld`, `pnl_ex_top_coin`
- top coin share last 20/30
- per-coin stats
- cost drag and spread/depth rejects
- data-quality rejects
- average `expected_move_vs_cost`
- recommendation: keep strict / loosen specific research filter / block coin / continue paper
- `eligible_for_manual_live_proposal: yes/no`

Keep eligibility `no` until the user's live-preview scorecard gates are met.

## Telegram alert smoke

Before marking Telegram green, check only presence/absence of env values, never secret contents:

- `CTB_TELEGRAM_ALERTS`
- `CTB_TELEGRAM_BOT_TOKEN`
- `CTB_TELEGRAM_CHAT_ID`
- optional `CTB_TELEGRAM_THREAD_ID`

If values are missing, run the smoke tool anyway and report `skipped` with a journal path. Do not claim alerts were tested unless actual Telegram sends succeeded for all required alert types.

## Reporting checklist

- Commit SHA.
- Focused/full/compileall results.
- PaperRuntime started yes/no.
- Supervisor process status and env identity.
- Strict vs research-probe learning summary.
- Shadow signal top block reasons.
- Replay/ablation result.
- Telegram smoke result and missing env presence flags.
- Updated scorecard learning block.
- Preflight status.
- Explicit: no Mainnet order, no Mainnet signed action, no micro-live.