# v76 Market Confluence Light Gating

Use when a Hyperliquid/v76 paper strategy has realistic lifecycle evidence but poor timing/negative net PnL, and the next roadmap step is market snapshot/confluence rather than loosening entries.

## Pattern

1. Keep the layer read-only first:
   - `live_order_allowed=false`
   - `mainnet_signed_action=false`
   - output to `runtime/reports/market_confluence_latest.json`
   - daily report line only; no execution authority yet.
2. Build pure scoring functions over collected market context:
   - trend: price vs SMA fast/slow, trend stack
   - momentum: RSI constructive zone, overheated penalty
   - volatility: ATR% edge zone, too-high volatility blocker
   - liquidity: prefer Hyperliquid day-notional volume (`dayNtlVlm`) over base candle volume when available; still include spread and L2 availability blockers
   - derivatives context: funding, premium, open interest, mark/oracle/prev-day values from Hyperliquid `metaAndAssetCtxs`
   - derivatives score: conservative crowding filter over funding, premium, open interest, and mark/oracle basis; explicit blockers include `open_interest_unknown`, `crowded_positive_funding`, `stressed_negative_funding`, `premium_too_high`, `premium_dislocated_negative`, and `mark_oracle_basis_wide`
   - regime: BTC trend and data reliability/staleness
3. In parallel with the score, emit a normalized read-only market snapshot (e.g. `market_snapshot.v1`) with stable per-coin sections:
   - `price`, `ohlcv`, `trend`, `momentum`, `volatility`, `liquidity`, `derivatives`, `fundamentals`, `sentiment`, `regime`, `risk`, `confluence`
   - Preserve `live_order_allowed=false` and `mainnet_signed_action=false` at both top level and coin level.
   - Include the computed `derivatives_score` inside each coin's `derivatives` section so reports and gates can explain crowding blocks without recomputing.
   - For not-yet-integrated external sources such as CoinGecko fundamentals or news/social sentiment, use explicit `status=not_loaded` placeholders; do not guess values.
4. Return a per-coin `final_score`, `recommendation`, and explicit blockers. Recommended labels:
   - `paper_candidate`
   - `block_new_entry`
4. Integrate into the report before gating live/paper entries:
   - `Market Confluence Light: regime=..., eligible=..., top=..., live=nein`
5. Do not treat high score alone as permission to trade. A coin can have a high numeric score and still be blocked by hard blockers such as weak liquidity or wide spread.
6. Only after report/test stability should it become a paper-only v76 entry gate:
   - lifecycle gate green enough for data collection
   - anti-chase/retest gate passes
   - confluence score >= threshold
   - no liquidity/regime/data-quality blockers
7. Implement the paper-only gate with two evidence paths:
   - Prefer persisted `runtime/reports/market_confluence_latest.json` so runtime decisions match the report the user sees.
   - If no persisted snapshot exists, fall back to a local tick-level score from the current `CoinMarketContext` so tests and emergency paper runs still fail deterministically.
   - The local fallback must populate neutral/safe derivatives fields (`open_interest>0`, `premium=0`, `mark_px=oracle_px=mid`, day-notional volume present) unless real data is available; otherwise `open_interest_unknown` can accidentally block legacy runtime tests and paper scans that do not load the persisted snapshot.
8. Journal the full confluence decision into each signal row:
   - `source` (`market_confluence_latest` or `local_tick_context`)
   - `score`
   - `recommendation`
   - `allowed`
   - `blockers`
   - `reasons`
   - `live_order_allowed=false`
   - `mainnet_signed_action=false`
9. Convert blockers into explicit signal block reasons (`confluence_block_new_entry`, `confluence_weak_liquidity`, `confluence_spread_too_wide`, etc.) and de-duplicate reasons before final decision construction.
10. After wiring the gate, restart only paper-only supervisors and verify recent signals show confluence blockers when the market snapshot says `eligible=0`/`risk_off`.

## Tests to add

- Clean context returns `paper_candidate`, no live flags.
- Overheated/illiquid/wide-spread context returns `block_new_entry` with explicit blockers.
- Crowded derivatives context returns `block_new_entry` with `derivatives_score` below neutral and explicit funding/premium/basis blockers.
- Collector maps Hyperliquid `metaAndAssetCtxs` rows to coins by universe index and stores funding, premium, open interest, mark/oracle/prev-day/day-notional fields.
- Liquidity scoring uses `dayNtlVlm` when present, falling back to candle/base volume only when notional volume is unavailable.
- Normalized `market_snapshot.v1` serialization includes all target sections and explicit `not_loaded` placeholders for fundamentals/sentiment rather than invented values.
- Report serialization preserves `live_order_allowed=false` and `mainnet_signed_action=false`.
- Daily report renders a compact confluence line without raw JSON dumps.
- v76 strict runtime blocks an otherwise valid paper lifecycle entry when `market_confluence_latest.json` marks the coin `block_new_entry`.
- The signal journal for that block contains `confluence_gate.source=market_confluence_latest`, no live flags, and block reasons derived from the confluence blockers.
- Full test suite remains green before restarting paper supervisors.

## Reporting lesson

For this user, include phase progress and explicit live posture. Keep report compact enough not to be clipped:

```text
✅ Gebaut: Market Confluence Light
🧪 Tests: 308 passed
🚫 Live: nein, read-only snapshot
➡️ Weiter: wire as paper-only v76 entry gate
```