# Crypto paper-research hardening

Use this checklist when adding data sources, strategy families, runtimes, supervisors, or promotion reports to an automated crypto research stack.

## Completion gate

Before declaring the work complete, perform an independent read-only review of three surfaces:

1. data provenance, freshness, mappings, and outcome attribution;
2. strategy semantics and lifecycle realism;
3. runtime isolation, supervision, and promotion-report integrity.

Treat a screen, signal, or advisor as distinct from a persistent paper strategy. Do not describe it as fully implemented unless entries, positions, exits, costs, state, and reports are exercised end to end.

## Safety boundary

Every paper runtime must fail closed unless all flags are explicit:

- `CTB_PAPER_TRADING=true`
- `CTB_LIVE_TRADING_ALLOWED=false`
- `CTB_LIVE_ORDER_ALLOWED=false`
- `HL_MAINNET_SIGNED_ACTION=false`

Reject missing, malformed, or non-false execution flags. Apply `PaperExecutor.blocked_by_cost`; creating a fill object does not imply the trade is admissible. Research/advisor paths must never instantiate a live executor or signed client.

## External data contract

Each source envelope should carry:

- versioned `source_id` and endpoint/schema version;
- immutable `snapshot_id` over canonical source data;
- provider observation time and local collection time;
- age, source-specific TTL, status (`ok|partial|missing|stale|error`);
- numeric reliability plus reasons/blockers;
- explicit requested-versus-returned coverage;
- `research_only=true`, `live_order_allowed=false`.

Persist the exact source snapshot IDs and gate decisions from signal → position → entry → final exit. Attribution supports grouped outcomes; it does not prove causality.

Use explicit semantic mappings. Never map a token to a chain metric merely because it is deployed on that chain (for example, LINK is not Ethereum TVL). Slow DeFi/TVL context is research/regime context, not an intraday direction trigger.

Do not encode missing liquidation coverage as zero. Zero is valid only when a fresh, healthy stream observed no events during the defined rolling window. Public REST crowding ratios are not equivalent to a liquidation stream.

## Strategy-family semantics

Confluence must be family- and direction-aware:

- long-biased trend scores must not automatically block valid shorts;
- choppy/range can block trend strategies while enabling range strategies;
- universal risk, liquidity, freshness, and data-quality blockers still apply to all families.

Minimum realism by family:

- **Breakout–retest:** persistent `armed → retested → confirmed` state; a same-bar breakout/retest shortcut is not equivalent.
- **Relative value:** rolling spread history, stable beta/correlation, synchronized timestamps, beta/dollar-neutral sizing, atomic two-leg paper fill, pair-level stop/PnL. Cross-sectional strongest-long/weakest-short is only a screen and must fail closed.
- **Liquidation reversal:** fresh 1m/5m liquidation/OI evidence, sweep/reclaim, volume and trend-continuation guard; stale/missing stream blocks.
- **Funding/basis carry:** real or conservatively simulated spot leg, perp leg, both fees/spreads/slippage, borrow availability/cost, basis and margin risk. A perp-only short is not market-neutral carry.
- **Portfolio sleeve:** dedicated cash/lots/NAV/turnover/rebalance simulator and benchmarks. Static advisor weights are not a portfolio backtest.

## Evidence versioning

A material change to filters, mappings, cost handling, lifecycle, or parameters requires a new strategy version/config fingerprint. Do not mix pre-change journals with post-change promotion evidence.

If a process has old-version open paper positions, stop it safely and archive the complete runtime directory before starting the new version. Never relabel an old position or its exit as evidence for the new version.

## Supervisor and journals

- Use an atomic supervisor lock to prevent overlapping cron runs.
- Validate PID, command, strategy ID, environment, and process start identity.
- If process identity is ambiguous, warn and fail closed rather than blindly starting a second writer.
- Keep one isolated runtime directory per candidate.
- Prefer atomic state writes; guard JSONL/PID writers when parallelism is possible.
- Heartbeat freshness is part of process health, not merely `/proc/<pid>` existence.

## Promotion-report integrity

Promotion reports must validate candidate ID, strategy version, and config fingerprint. Count only unique, fully paired entry → final-exit lifecycles. Partial exits are not independent completed trades. Treat duplicate exits, malformed JSONL, foreign rows, corrupted/missing state, stale health, unknown process state, proxy inputs, and open positions as explicit blockers—not as empty/clean evidence.

Keep promotion as a manual proposal only. It never grants execution authority.

## Verification checklist

- focused safety/data/strategy tests;
- full test suite and syntax/diff checks;
- one live read-only source smoke with redacted structural output;
- one paper scan per candidate;
- process environment and heartbeat verification;
- clean versioned runtime state;
- explicit list of implemented lifecycles versus screens/advisors/deferred paths;
- no live orders, signed actions, or implicit promotion.