Starter Coach

{
  "name": "starter-coach",
  "description": "Starter Coach V2 — conversational 6-step skill that guides users to build their own automated DEX spot-trading bot on OKX DEX. Onboard → Profile → Build Strategy → Paper Trade → Go Live. Uses OnchainOS CLI for all on-chain data and execution.",
  "version": "1.0.0",
  "author": {
    "name": "VibeCodeDaddy",
    "github": "VibeCodeDaddy69"
  },
  "license": "MIT",
  "keywords": [
    "trading-bot",
    "strategy-builder",
    "coaching",
    "paper-trade",
    "backtesting",
    "dex",
    "onchainos",
    "solana",
    "ethereum"
  ],
  "repository": "https://github.com/okx/plugin-store"
}

"""
Backtest engine — replay a validated spec against historical OHLCV data.

Hard-rejects any spec where live_only == true (must go through paper_gate instead).
"""
from __future__ import annotations

import json
from dataclasses import dataclass, field
from typing import Any

from harness import validate_spec, LIVE_ONLY_TYPES
from primitives.entry import MarketContext, Bar, evaluate_entry
from primitives.exit import Position, ExitSignal, evaluate_all_exits
from primitives.filter import evaluate_filters
from primitives.sizing import compute_size
from primitives.risk import PortfolioState, check_all_overlays


@dataclass
class Trade:
    token: str
    entry_price: float
    exit_price: float
    entry_bar: int
    exit_bar: int
    size_usd: float
    pnl_usd: float
    pnl_pct: float
    exit_reason: str


@dataclass
class BacktestResult:
    ok: bool = False
    error: str = ""
    trades: list[Trade] = field(default_factory=list)
    total_pnl_usd: float = 0.0
    total_pnl_pct: float = 0.0
    win_rate: float = 0.0
    max_drawdown_pct: float = 0.0
    sharpe: float = 0.0
    trade_count: int = 0


def _compute_indicators(bars: list[Bar], spec: dict) -> dict[str, Any]:
    """Pre-compute indicators needed by the spec's entry/exit/filters."""
    closes = [b.close for b in bars]
    indicators: dict[str, Any] = {"ema": {}, "sma": {}, "rsi": {}, "macd": {}, "bbands": {}}

    # Collect periods needed
    entry = spec.get("entry", {})
    etype = entry.get("type", "")

    # SMA/EMA
    for period in _extract_ma_periods(spec):
        if len(closes) >= period:
            indicators["sma"][period] = _sma(closes, period)
            indicators["ema"][period] = _ema(closes, period)

    # RSI
    if etype == "rsi_threshold":
        p = entry.get("period", 14)
        indicators["rsi"][p] = _rsi(closes, p)

    # MACD
    if etype == "macd_cross":
        fast = entry.get("fast_period", 12)
        slow = entry.get("slow_period", 26)
        sig = entry.get("signal_period", 9)
        macd_l, signal_l, hist_l = _macd(closes, fast, slow, sig)
        indicators["macd"] = {"macd": macd_l, "signal": signal_l, "hist": hist_l}

    # Bollinger Bands
    if etype == "bollinger_touch":
        p = entry.get("period", 20)
        std = entry.get("std_dev", 2.0)
        upper, middle, lower = _bbands(closes, p, std)
        indicators["bbands"] = {"upper": upper, "middle": middle, "lower": lower}

    return indicators


def _extract_ma_periods(spec: dict) -> set[int]:
    periods: set[int] = set()
    entry = spec.get("entry", {})
    if entry.get("type") == "ma_cross":
        periods.add(entry.get("fast_period", 10))
        periods.add(entry.get("slow_period", 50))
    for filt in spec.get("filters", []):
        if filt.get("type") == "market_regime":
            periods.add(filt.get("ma_period", 200))
    return periods


def _sma(values: list[float], period: int) -> list[float]:
    result: list[float] = []
    for i in range(len(values)):
        if i < period - 1:
            result.append(0.0)
        else:
            result.append(sum(values[i - period + 1:i + 1]) / period)
    return result


def _ema(values: list[float], period: int) -> list[float]:
    result: list[float] = []
    k = 2 / (period + 1)
    for i, v in enumerate(values):
        if i == 0:
            result.append(v)
        else:
            result.append(v * k + result[-1] * (1 - k))
    return result


def _rsi(values: list[float], period: int) -> list[float]:
    result: list[float] = [50.0]  # default for first value
    gains: list[float] = []
    losses: list[float] = []
    for i in range(1, len(values)):
        delta = values[i] - values[i - 1]
        gains.append(max(delta, 0))
        losses.append(max(-delta, 0))
        if i < period:
            result.append(50.0)
            continue
        if i == period:
            avg_gain = sum(gains[-period:]) / period
            avg_loss = sum(losses[-period:]) / period
        else:
            avg_gain = (avg_gain * (period - 1) + gains[-1]) / period
            avg_loss = (avg_loss * (period - 1) + losses[-1]) / period
        if avg_loss == 0:
            result.append(100.0)
        else:
            rs = avg_gain / avg_loss
            result.append(100 - 100 / (1 + rs))
    return result


def _macd(values: list[float], fast: int, slow: int, signal: int):
    fast_ema = _ema(values, fast)
    slow_ema = _ema(values, slow)
    macd_line = [f - s for f, s in zip(fast_ema, slow_ema)]
    signal_line = _ema(macd_line, signal)
    hist = [m - s for m, s in zip(macd_line, signal_line)]
    return macd_line, signal_line, hist


def _bbands(values: list[float], period: int, std_dev: float):
    sma_vals = _sma(values, period)
    upper, lower = [], []
    for i in range(len(values)):
        if i < period - 1:
            upper.append(0.0)
            lower.append(0.0)
        else:
            window = values[i - period + 1:i + 1]
            mean = sma_vals[i]
            variance = sum((x - mean) ** 2 for x in window) / period
            std = variance ** 0.5
            upper.append(mean + std_dev * std)
            lower.append(mean - std_dev * std)
    return upper, sma_vals, lower


def run_backtest(
    spec: dict,
    bars: list[dict],
    initial_equity: float = 10000.0,
) -> BacktestResult:
    """
    Run a backtest on historical data.

    Args:
        spec: validated strategy spec dict
        bars: list of {ts, open, high, low, close, volume} dicts
        initial_equity: starting capital in USD

    Returns:
        BacktestResult
    """
    # 1. Validate
    ok, errors, meta = validate_spec(spec)
    if not ok:
        return BacktestResult(ok=False, error=f"Spec validation failed: {'; '.join(errors)}")

    if meta["live_only"]:
        return BacktestResult(
            ok=False,
            error="live_only spec cannot be backtested. Use paper_gate for graduation."
        )

    # 2. Parse bars
    parsed_bars = [
        Bar(ts=b["ts"], open=b["open"], high=b["high"],
            low=b["low"], close=b["close"], volume=b["volume"])
        for b in bars
    ]
    if len(parsed_bars) < 50:
        return BacktestResult(ok=False, error="Insufficient bars (need >= 50)")

    # 3. Pre-compute indicators
    indicators = _compute_indicators(parsed_bars, spec)

    # 4. Simulate
    equity = initial_equity
    peak_equity = equity
    max_dd = 0.0
    trades: list[Trade] = []
    position: Position | None = None
    portfolio = PortfolioState(
        equity_usd=equity, peak_equity_usd=equity, session_start_ts=parsed_bars[0].ts
    )
    returns: list[float] = []

    entry_spec = spec["entry"]
    exit_spec = spec["exit"]
    sizing_spec = spec["sizing"]
    filters = spec.get("filters", [])
    overlays = spec.get("risk_overlays", [])

    for i in range(50, len(parsed_bars)):
        ctx = MarketContext(
            bars=parsed_bars[:i + 1],
            current_price=parsed_bars[i].close,
            timeframe=spec.get("instrument", {}).get("timeframe", "5m"),
            token=spec.get("instrument", {}).get("symbol", ""),
        )
        ctx.ema = indicators.get("ema", {})
        ctx.sma = indicators.get("sma", {})
        ctx.rsi = indicators.get("rsi", {})
        ctx.macd = indicators.get("macd", {})
        ctx.bbands = indicators.get("bbands", {})

        # Check exits first
        if position is not None:
            sig = evaluate_all_exits(ctx, position, exit_spec)
            if sig:
                pnl_pct = (ctx.current_price - position.entry_price) / position.entry_price * 100
                sell_frac = sig.sell_pct / 100
                pnl_usd = position.size_usd * sell_frac * pnl_pct / 100
                trades.append(Trade(
                    token=position.token, entry_price=position.entry_price,
                    exit_price=ctx.current_price, entry_bar=position.entry_bar_idx,
                    exit_bar=i, size_usd=position.size_usd * sell_frac,
                    pnl_usd=pnl_usd, pnl_pct=pnl_pct, exit_reason=sig.reason,
                ))
                equity += pnl_usd
                returns.append(pnl_pct)
                if pnl_usd < 0:
                    portfolio.consecutive_losses += 1
                else:
                    portfolio.consecutive_losses = 0
                if sig.sell_pct >= 100:
                    position = None
                    portfolio.open_positions -= 1
                else:
                    position.size_usd *= (1 - sell_frac)
                portfolio.equity_usd = equity
                if equity > peak_equity:
                    peak_equity = equity
                    portfolio.peak_equity_usd = peak_equity
                dd = (peak_equity - equity) / peak_equity * 100 if peak_equity > 0 else 0
                max_dd = max(max_dd, dd)

        # Try entry if no position
        if position is None:
            # Check risk overlays
            portfolio.equity_usd = equity
            overlay_ok, _ = check_all_overlays(portfolio, overlays)
            if not overlay_ok:
                continue
            # Check filters
            filter_ok, _ = evaluate_filters(ctx, filters)
            if not filter_ok:
                continue
            # Check entry
            if evaluate_entry(ctx, entry_spec):
                size = compute_size(equity, ctx, sizing_spec)
                if size > 0:
                    position = Position(
                        token=ctx.token, entry_price=ctx.current_price,
                        entry_ts=parsed_bars[i].ts, entry_bar_idx=i,
                        size_usd=size, peak_price=ctx.current_price,
                    )
                    portfolio.open_positions += 1
                    portfolio.trades_today += 1

    # 5. Close any remaining position at last bar
    if position is not None:
        final_price = parsed_bars[-1].close
        pnl_pct = (final_price - position.entry_price) / position.entry_price * 100
        pnl_usd = position.size_usd * pnl_pct / 100
        trades.append(Trade(
            token=position.token, entry_price=position.entry_price,
            exit_price=final_price, entry_bar=position.entry_bar_idx,
            exit_bar=len(parsed_bars) - 1, size_usd=position.size_usd,
            pnl_usd=pnl_usd, pnl_pct=pnl_pct, exit_reason="end_of_data",
        ))
        equity += pnl_usd
        returns.append(pnl_pct)

    # 6. Compute stats
    total_pnl = equity - initial_equity
    total_pnl_pct = total_pnl / initial_equity * 100 if initial_equity > 0 else 0
    wins = sum(1 for t in trades if t.pnl_usd > 0)
    win_rate = wins / len(trades) * 100 if trades else 0
    sharpe = 0.0
    if returns:
        avg_ret = sum(returns) / len(returns)
        if len(returns) > 1:
            variance = sum((r - avg_ret) ** 2 for r in returns) / (len(returns) - 1)
            std_ret = variance ** 0.5
            sharpe = (avg_ret / std_ret) * (252 ** 0.5) if std_ret > 0 else 0

    return BacktestResult(
        ok=True,
        trades=trades,
        total_pnl_usd=round(total_pnl, 2),
        total_pnl_pct=round(total_pnl_pct, 2),
        win_rate=round(win_rate, 1),
        max_drawdown_pct=round(max_dd, 2),
        sharpe=round(sharpe, 2),
        trade_count=len(trades),
    )

"""
Harness — validate strategy specs against schema.json + forbidden-pattern checks.

Usage:
    from harness import validate_spec
    ok, errors = validate_spec(spec_dict)
"""
from __future__ import annotations

import json
from pathlib import Path
from typing import Any

try:
    import jsonschema
    from jsonschema import Draft202012Validator
except ImportError:
    jsonschema = None  # type: ignore
    Draft202012Validator = None  # type: ignore

SCHEMA_PATH = Path(__file__).parent / "schema.json"

# Primitives with x-live-only: true in schema.json
LIVE_ONLY_TYPES: set[str] = {
    # entries
    "smart_money_buy", "dev_buy", "ranking_entry", "wallet_copy_buy",
    # exits
    "smart_money_sell", "dev_dump", "wallet_mirror_sell", "fast_dump_exit",
    # filters
    "mcap_range", "launch_age",
    "honeypot_check", "lp_locked", "buy_tax_max", "sell_tax_max",
    "liquidity_min", "top_holders_max", "bundler_ratio_max",
    "dev_holding_max", "insider_holding_max", "fresh_wallet_ratio_max",
    "smart_money_present_min", "phishing_exclude", "whale_concentration_max",
}


def _load_schema() -> dict:
    with open(SCHEMA_PATH) as f:
        return json.load(f)


def _collect_types(spec: dict) -> set[str]:
    """Walk the spec and collect every primitive type used."""
    types: set[str] = set()
    entry = spec.get("entry", {})
    if isinstance(entry, dict) and "type" in entry:
        types.add(entry["type"])
    exit_block = spec.get("exit", {})
    for inner_key in ("stop_loss", "take_profit", "trailing_stop", "tiered_take_profit"):
        if inner_key in exit_block:
            types.add(inner_key)
    for other in exit_block.get("other", []):
        if isinstance(other, dict) and "type" in other:
            types.add(other["type"])
    for filt in spec.get("filters", []):
        if isinstance(filt, dict) and "type" in filt:
            types.add(filt["type"])
    sizing = spec.get("sizing", {})
    if isinstance(sizing, dict) and "type" in sizing:
        types.add(sizing["type"])
    for overlay in spec.get("risk_overlays", []):
        if isinstance(overlay, dict) and "type" in overlay:
            types.add(overlay["type"])
    return types


def _check_live_only(spec: dict) -> bool:
    """Return True if any primitive in the spec is live_only."""
    return bool(_collect_types(spec) & LIVE_ONLY_TYPES)


def _check_h01(spec: dict, errors: list[str]) -> None:
    """H-01: stop_loss is required."""
    exit_block = spec.get("exit", {})
    if "stop_loss" not in exit_block:
        errors.append("H-01: exit.stop_loss is required. A strategy without a stop is gambling.")
    elif not isinstance(exit_block["stop_loss"], dict) or "pct" not in exit_block["stop_loss"]:
        errors.append("H-01: exit.stop_loss must have a 'pct' field.")


def _check_h02(spec: dict, errors: list[str]) -> None:
    """H-02: No martingale / averaging down."""
    meta = spec.get("meta", {})
    for field in ("description", "author_intent", "name"):
        text = str(meta.get(field, "")).lower()
        for keyword in ("martingale", "double down", "average down", "averaging down"):
            if keyword in text:
                errors.append(f"H-02: Martingale / averaging down detected in meta.{field}. Rejected.")
                return


def _check_h03(spec: dict, errors: list[str]) -> None:
    """H-03: stop_loss.pct must be < take_profit.pct (when take_profit is used)."""
    exit_block = spec.get("exit", {})
    sl = exit_block.get("stop_loss", {})
    tp = exit_block.get("take_profit", {})
    if not sl or not tp:
        return
    sl_pct = sl.get("pct", 0)
    tp_pct = tp.get("pct", 0)
    if sl_pct and tp_pct and sl_pct >= tp_pct:
        errors.append(
            f"H-03: stop_loss ({sl_pct}%) must be tighter than take_profit ({tp_pct}%). "
            "Negative asymmetry rejected."
        )


def _check_h05(spec: dict, errors: list[str]) -> None:
    """H-05: sizing.pct * max_daily_trades.n <= 20% daily risk cap."""
    sizing = spec.get("sizing", {})
    if sizing.get("type") != "fixed_pct":
        return
    pct = sizing.get("pct", 0)
    for overlay in spec.get("risk_overlays", []):
        if overlay.get("type") == "max_daily_trades":
            n = overlay.get("n", 1)
            daily_risk = pct * n
            if daily_risk > 20:
                errors.append(
                    f"H-05: fixed_pct ({pct}%) x max_daily_trades ({n}) = {daily_risk}% "
                    "exceeds 20% daily risk cap."
                )
            return


def _check_h06(spec: dict, errors: list[str]) -> None:
    """H-06: No unknown primitive types."""
    known_types = {
        "price_drop", "price_breakout", "ma_cross", "rsi_threshold",
        "volume_spike", "time_schedule", "smart_money_buy", "dev_buy",
        "macd_cross", "bollinger_touch", "ranking_entry", "wallet_copy_buy",
        "time_exit", "indicator_reversal", "smart_money_sell", "dev_dump",
        "wallet_mirror_sell", "fast_dump_exit",
        "time_window", "volatility_range", "volume_minimum", "cooldown",
        "market_regime", "price_range", "btc_overlay", "top_zone_guard",
        "mcap_range", "launch_age",
        "honeypot_check", "lp_locked", "buy_tax_max", "sell_tax_max",
        "liquidity_min", "top_holders_max", "bundler_ratio_max",
        "dev_holding_max", "insider_holding_max", "fresh_wallet_ratio_max",
        "smart_money_present_min", "phishing_exclude", "whale_concentration_max",
        "fixed_pct", "fixed_usd", "volatility_scaled",
        "max_daily_trades", "max_concurrent_positions", "drawdown_pause",
        "correlation_cap", "session_loss_pause",
    }
    for t in _collect_types(spec):
        if t in ("stop_loss", "take_profit", "trailing_stop", "tiered_take_profit"):
            continue
        if t not in known_types:
            errors.append(f"H-06: Unknown primitive type '{t}'. No freeform code allowed.")


def validate_spec(spec: dict[str, Any]) -> tuple[bool, list[str], dict[str, Any]]:
    """
    Validate a strategy spec.

    Returns:
        (ok, errors, meta)
        - ok: True if spec is valid
        - errors: list of human-readable error strings
        - meta: {"live_only": bool, "primitive_count": int, "types_used": list[str]}
    """
    errors: list[str] = []

    # 1. JSON Schema validation (H-04 param bounds + structural)
    if Draft202012Validator is not None:
        schema = _load_schema()
        validator = Draft202012Validator(schema)
        for error in sorted(validator.iter_errors(spec), key=lambda e: list(e.path)):
            path = ".".join(str(p) for p in error.absolute_path) or "(root)"
            errors.append(f"Schema: {path} — {error.message}")
    else:
        errors.append("Warning: jsonschema not installed. Run: pip install jsonschema")

    # 2. Forbidden-pattern checks
    _check_h01(spec, errors)
    _check_h02(spec, errors)
    _check_h03(spec, errors)
    _check_h05(spec, errors)
    _check_h06(spec, errors)

    # 3. Derive metadata
    types_used = sorted(_collect_types(spec))
    live_only = _check_live_only(spec)

    meta = {
        "live_only": live_only,
        "primitive_count": len(types_used),
        "types_used": types_used,
    }

    return len(errors) == 0, errors, meta


if __name__ == "__main__":
    import sys
    if len(sys.argv) < 2:
        print("Usage: python harness.py <spec.json>")
        sys.exit(1)
    with open(sys.argv[1]) as f:
        spec = json.load(f)
    ok, errors, meta = validate_spec(spec)
    if ok:
        print(f"PASS  live_only={meta['live_only']}  primitives={meta['primitive_count']}")
        print(f"  types: {', '.join(meta['types_used'])}")
    else:
        print(f"FAIL  ({len(errors)} errors)")
        for e in errors:
            print(f"  - {e}")
        sys.exit(1)

MIT License

Copyright (c) 2026 VibeCodeDaddy

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

"""
Live execution engine — real-time position monitoring + trade execution.

Ties together:
  - onchainos.py (data + swap execution + wallet monitoring)
  - primitives/* (entry/exit/filter/sizing/risk evaluators)
  - paper_gate.py (graduation-gated sizing)
  - harness.py (spec validation)

Usage:
    from live_engine import LiveEngine
    engine = LiveEngine(spec, wallet_address="...")
    engine.start()  # blocking loop
"""
from __future__ import annotations

import json
import time
import logging
from dataclasses import dataclass, field, asdict
from pathlib import Path
from typing import Any

from harness import validate_spec
from onchainos import OnchainOS, SwapResult
from primitives.entry import MarketContext, Bar, evaluate_entry
from primitives.exit import Position, ExitSignal, evaluate_all_exits
from primitives.filter import evaluate_filters
from primitives.sizing import compute_size
from primitives.risk import PortfolioState, check_all_overlays
from paper_gate import get_allowed_size_multiplier, record_paper_trade

log = logging.getLogger("live_engine")

# ── Config ────────────────────────────────────────────────────────

TICK_INTERVAL_SEC = 30       # Poll interval for price/candle checks
BALANCE_POLL_SEC = 60        # Poll interval for wallet balance sync
POSITION_STATE_DIR = Path(__file__).parent / ".live_state"

# Common stablecoin addresses per chain (quote tokens for swaps)
QUOTE_TOKENS: dict[str, str] = {
    "solana": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",   # USDC on Solana
    "ethereum": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",   # USDC on Ethereum
    "base": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",       # USDC on Base
    "bsc": "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d",        # USDC on BSC
    "arbitrum": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",    # USDC on Arbitrum
}


# ── Position Tracking ─────────────────────────────────────────────

@dataclass
class LivePosition:
    """A tracked open position."""
    token_address: str = ""
    token_symbol: str = ""
    entry_price: float = 0.0
    entry_ts: float = 0.0
    entry_tx_hash: str = ""
    size_usd: float = 0.0
    token_amount: float = 0.0     # actual tokens held
    peak_price: float = 0.0       # for trailing stop
    current_price: float = 0.0
    unrealized_pnl_usd: float = 0.0
    unrealized_pnl_pct: float = 0.0
    bars_held: int = 0
    status: str = "open"          # open | closing | closed


@dataclass
class EngineState:
    """Persisted engine state across restarts."""
    strategy_name: str = ""
    wallet_address: str = ""
    chain: str = "solana"
    positions: list[dict[str, Any]] = field(default_factory=list)
    closed_trades: list[dict[str, Any]] = field(default_factory=list)
    equity_usd: float = 0.0
    peak_equity_usd: float = 0.0
    trades_today: int = 0
    consecutive_losses: int = 0
    last_trade_day: str = ""
    total_trades: int = 0
    total_pnl_usd: float = 0.0
    started_ts: float = 0.0
    last_tick_ts: float = 0.0


def _state_path(strategy_name: str) -> Path:
    POSITION_STATE_DIR.mkdir(parents=True, exist_ok=True)
    return POSITION_STATE_DIR / f"{strategy_name}.json"


def _load_engine_state(strategy_name: str) -> EngineState:
    path = _state_path(strategy_name)
    if not path.exists():
        return EngineState(strategy_name=strategy_name, started_ts=time.time())
    with open(path) as f:
        data = json.load(f)
    return EngineState(**data)


def _save_engine_state(state: EngineState) -> None:
    state.last_tick_ts = time.time()
    path = _state_path(state.strategy_name)
    with open(path, "w") as f:
        json.dump(asdict(state), f, indent=2)


# ── Live Engine ───────────────────────────────────────────────────

class LiveEngine:
    """
    Real-time execution engine for a validated strategy spec.

    Lifecycle:
      1. validate spec
      2. resolve wallet address
      3. sync initial balances
      4. enter tick loop:
         a. fetch latest candles + price
         b. update position prices + P&L
         c. evaluate exits → fire sells
         d. evaluate entries → fire buys
         e. persist state
    """

    def __init__(
        self,
        spec: dict[str, Any],
        wallet_address: str | None = None,
        initial_equity: float = 0.0,
        paper_mode: bool = False,
    ):
        # Validate spec
        ok, errors, meta = validate_spec(spec)
        if not ok:
            raise ValueError(f"Invalid spec: {'; '.join(errors)}")

        self.spec = spec
        self.meta = meta
        self.paper_mode = paper_mode

        # Extract spec components
        self.strategy_name = spec["meta"]["name"]
        self.chain = spec.get("universe", {}).get("chain", "solana")
        self.symbol = spec["instrument"]["symbol"]
        self.timeframe = spec["instrument"]["timeframe"]
        self.entry_spec = spec["entry"]
        self.exit_spec = spec["exit"]
        self.sizing_spec = spec["sizing"]
        self.filters = spec.get("filters", [])
        self.overlays = spec.get("risk_overlays", [])

        # OnchainOS client
        self.os = OnchainOS(chain=self.chain)

        # Resolve wallet
        self.wallet = wallet_address or self.os.get_wallet_address() or ""
        if not self.wallet and not paper_mode:
            raise ValueError("No wallet address. Log in via `onchainos wallet login`.")

        # Quote token for swaps
        self.quote_token = QUOTE_TOKENS.get(self.chain, "")

        # Graduation multiplier (0.0 = paper, 0.1 = micro, 1.0 = full)
        self.size_multiplier = get_allowed_size_multiplier(self.strategy_name)

        # Load or create engine state
        self.state = _load_engine_state(self.strategy_name)
        self.state.wallet_address = self.wallet
        self.state.chain = self.chain
        if initial_equity > 0:
            self.state.equity_usd = initial_equity
            self.state.peak_equity_usd = initial_equity

        # Rebuild open positions from state
        self.positions: list[LivePosition] = []
        for p_data in self.state.positions:
            self.positions.append(LivePosition(**p_data))

        # Portfolio state for risk overlays
        self.portfolio = PortfolioState(
            trades_today=self.state.trades_today,
            open_positions=len(self.positions),
            open_tokens=[p.token_symbol for p in self.positions],
            equity_usd=self.state.equity_usd,
            peak_equity_usd=self.state.peak_equity_usd,
            consecutive_losses=self.state.consecutive_losses,
            session_start_ts=self.state.started_ts,
        )

        log.info(
            f"LiveEngine initialized: {self.strategy_name} "
            f"chain={self.chain} wallet={self.wallet[:8]}... "
            f"positions={len(self.positions)} equity=${self.state.equity_usd:.2f} "
            f"multiplier={self.size_multiplier}"
        )

    # ── Main Loop ─────────────────────────────────────────────────

    def start(self) -> None:
        """Blocking tick loop. Ctrl-C to stop."""
        log.info(f"Starting live engine for {self.strategy_name}")
        self._sync_balances()

        try:
            while True:
                self._tick()
                time.sleep(TICK_INTERVAL_SEC)
        except KeyboardInterrupt:
            log.info("Engine stopped by user")
        finally:
            self._persist()

    def run_once(self) -> dict[str, Any]:
        """Run a single tick (for testing or cron-based execution)."""
        return self._tick()

    # ── Tick ──────────────────────────────────────────────────────

    def _tick(self) -> dict[str, Any]:
        """Single evaluation cycle."""
        tick_result: dict[str, Any] = {
            "ts": time.time(),
            "exits": [],
            "entries": [],
            "errors": [],
        }

        # Reset daily counters if new day
        today = time.strftime("%Y-%m-%d")
        if self.state.last_trade_day != today:
            self.state.trades_today = 0
            self.state.last_trade_day = today
            self.portfolio.trades_today = 0

        try:
            # Resolve target token(s)
            tokens = self._resolve_tokens()
            if not tokens:
                return tick_result

            for token_addr, token_symbol in tokens:
                # Build market context
                ctx = self._build_context(token_addr, token_symbol)
                if ctx is None:
                    continue

                # 1. Check exits for open positions on this token
                for pos in self.positions:
                    if pos.token_address != token_addr or pos.status != "open":
                        continue
                    pos.current_price = ctx.current_price
                    pos.unrealized_pnl_pct = (
                        (ctx.current_price - pos.entry_price) / pos.entry_price * 100
                        if pos.entry_price > 0 else 0
                    )
                    pos.unrealized_pnl_usd = pos.size_usd * pos.unrealized_pnl_pct / 100
                    if ctx.current_price > pos.peak_price:
                        pos.peak_price = ctx.current_price
                    pos.bars_held += 1

                    position_obj = Position(
                        token=token_symbol,
                        entry_price=pos.entry_price,
                        entry_ts=pos.entry_ts,
                        entry_bar_idx=0,
                        size_usd=pos.size_usd,
                        peak_price=pos.peak_price,
                    )
                    sig = evaluate_all_exits(ctx, position_obj, self.exit_spec)
                    if sig:
                        exit_result = self._execute_exit(pos, sig, ctx)
                        tick_result["exits"].append(exit_result)

                # 2. Check entries if no position on this token
                has_position = any(
                    p.token_address == token_addr and p.status == "open"
                    for p in self.positions
                )
                if not has_position:
                    entry_result = self._try_entry(ctx, token_addr, token_symbol)
                    if entry_result:
                        tick_result["entries"].append(entry_result)

        except Exception as e:
            log.error(f"Tick error: {e}")
            tick_result["errors"].append(str(e))

        self._persist()
        return tick_result

    # ── Token Resolution ──────────────────────────────────────────

    def _resolve_tokens(self) -> list[tuple[str, str]]:
        """
        Resolve which tokens to evaluate this tick.
        Fixed symbol: [(token_address, symbol)]
        Dynamic universe (*): fetch from rankings/wallets.
        """
        if self.symbol != "*":
            # Fixed token — symbol is like "SOL-USDC", extract base
            base = self.symbol.split("-")[0]
            # We need the token address — get from price-info or basic-info
            # For now, use the symbol as-is; the engine caller should provide addresses
            return [(self.symbol, base)]

        # Dynamic universe — fetch from rankings or wallet tracker
        entry_type = self.entry_spec.get("type", "")
        if entry_type == "ranking_entry":
            list_name = self.entry_spec.get("list_name", "trending")
            top_n = self.entry_spec.get("top_n", 20)
            items = self.os.subscribe_ranking(list_name, top_n)
            return [(item.token, item.symbol) for item in items if item.token]
        elif entry_type == "wallet_copy_buy":
            wallets = self.entry_spec.get("target_wallet", [])
            if isinstance(wallets, str):
                wallets = [wallets]
            events = self.os.track_wallets(wallets, trade_type=1)  # buys only
            return list({(e.token, e.token[:8]) for e in events if e.token})
        elif entry_type == "smart_money_buy":
            events = self.os.track_smart_money(trade_type=1)
            return list({(e.token, e.token[:8]) for e in events if e.token})

        return []

    # ── Market Context ────────────────────────────────────────────

    def _build_context(self, token_addr: str, token_symbol: str) -> MarketContext | None:
        """Fetch candles + price and build a MarketContext."""
        candles = self.os.get_candles(token_addr, bar=self.timeframe, limit=100)
        if len(candles) < 10:
            return None

        bars = [
            Bar(
                ts=c["ts"], open=c["open"], high=c["high"],
                low=c["low"], close=c["close"], volume=c["volume"],
            )
            for c in candles
        ]
        current_price = bars[-1].close if bars else 0

        # If current price is 0, try price-info
        if current_price == 0:
            price_data = self.os.get_price_info(token_addr)
            if "error" not in price_data:
                current_price = float(
                    price_data.get("price", price_data.get("lastPrice", 0)) or 0
                )

        if current_price == 0:
            return None

        ctx = MarketContext(
            bars=bars,
            current_price=current_price,
            timeframe=self.timeframe,
            token=token_symbol,
        )

        # Attach on-chain safety data for live_only filters
        # ctx.onchainos is read by primitives/filter.py for safety tag checks
        if self.meta.get("live_only"):
            ctx.onchainos = self.os
            ctx.onchainos_tags = self.os.get_safety_tags(token_addr)

        return ctx

    # ── Entry Execution ───────────────────────────────────────────

    def _try_entry(
        self, ctx: MarketContext, token_addr: str, token_symbol: str
    ) -> dict[str, Any] | None:
        """Evaluate entry conditions and execute buy if triggered."""
        # Check risk overlays
        self.portfolio.equity_usd = self.state.equity_usd
        overlay_ok, blockers = check_all_overlays(self.portfolio, self.overlays)
        if not overlay_ok:
            return None

        # Check filters
        filter_ok, failing = evaluate_filters(ctx, self.filters)
        if not filter_ok:
            return None

        # Check entry trigger
        if not evaluate_entry(ctx, self.entry_spec):
            return None

        # Compute size (with graduation multiplier)
        raw_size = compute_size(self.state.equity_usd, ctx, self.sizing_spec)
        size_usd = raw_size * self.size_multiplier
        if size_usd <= 0:
            return None

        log.info(
            f"ENTRY signal: {token_symbol} @ ${ctx.current_price:.6f} "
            f"size=${size_usd:.2f} (x{self.size_multiplier})"
        )

        # Execute swap
        if self.paper_mode:
            tx_hash = f"paper_{int(time.time())}"
            token_amount = size_usd / ctx.current_price if ctx.current_price > 0 else 0
        else:
            result = self.os.swap_execute(
                from_token=self.quote_token,
                to_token=token_addr,
                readable_amount=str(round(size_usd, 2)),
                wallet=self.wallet,
            )
            if not result.ok:
                log.error(f"Swap failed: {result.error}")
                return {"action": "entry_failed", "error": result.error}
            tx_hash = result.tx_hash
            token_amount = size_usd / ctx.current_price if ctx.current_price > 0 else 0

        # Track position
        pos = LivePosition(
            token_address=token_addr,
            token_symbol=token_symbol,
            entry_price=ctx.current_price,
            entry_ts=time.time(),
            entry_tx_hash=tx_hash,
            size_usd=size_usd,
            token_amount=token_amount,
            peak_price=ctx.current_price,
            current_price=ctx.current_price,
        )
        self.positions.append(pos)
        self.portfolio.open_positions += 1
        self.portfolio.open_tokens.append(token_symbol)
        self.state.trades_today += 1
        self.portfolio.trades_today += 1
        self.state.total_trades += 1

        # Record for paper gate
        if self.paper_mode:
            record_paper_trade(self.strategy_name)

        return {
            "action": "entry",
            "token": token_symbol,
            "price": ctx.current_price,
            "size_usd": size_usd,
            "tx_hash": tx_hash,
            "paper": self.paper_mode,
        }

    # ── Exit Execution ────────────────────────────────────────────

    def _execute_exit(
        self, pos: LivePosition, sig: ExitSignal, ctx: MarketContext
    ) -> dict[str, Any]:
        """Execute a sell based on exit signal."""
        sell_frac = sig.sell_pct / 100
        sell_usd = pos.size_usd * sell_frac
        pnl_pct = (ctx.current_price - pos.entry_price) / pos.entry_price * 100
        pnl_usd = sell_usd * pnl_pct / 100

        log.info(
            f"EXIT signal: {pos.token_symbol} reason={sig.reason} "
            f"sell={sig.sell_pct}% pnl={pnl_pct:+.1f}% (${pnl_usd:+.2f})"
        )

        # Execute sell swap
        tx_hash = ""
        if self.paper_mode:
            tx_hash = f"paper_exit_{int(time.time())}"
        else:
            # Sell the token amount proportional to sell_pct
            sell_amount = pos.token_amount * sell_frac
            if sell_amount > 0:
                result = self.os.swap_execute(
                    from_token=pos.token_address,
                    to_token=self.quote_token,
                    readable_amount=str(sell_amount),
                    wallet=self.wallet,
                )
                if not result.ok:
                    log.error(f"Exit swap failed: {result.error}")
                    return {"action": "exit_failed", "error": result.error}
                tx_hash = result.tx_hash

        # Update state
        self.state.equity_usd += pnl_usd
        self.state.total_pnl_usd += pnl_usd
        if self.state.equity_usd > self.state.peak_equity_usd:
            self.state.peak_equity_usd = self.state.equity_usd
        self.portfolio.equity_usd = self.state.equity_usd
        self.portfolio.peak_equity_usd = self.state.peak_equity_usd

        if pnl_usd < 0:
            self.state.consecutive_losses += 1
            self.portfolio.consecutive_losses += 1
        else:
            self.state.consecutive_losses = 0
            self.portfolio.consecutive_losses = 0

        trade_record = {
            "token": pos.token_symbol,
            "token_address": pos.token_address,
            "entry_price": pos.entry_price,
            "exit_price": ctx.current_price,
            "size_usd": sell_usd,
            "pnl_usd": round(pnl_usd, 4),
            "pnl_pct": round(pnl_pct, 2),
            "reason": sig.reason,
            "entry_ts": pos.entry_ts,
            "exit_ts": time.time(),
            "tx_hash": tx_hash,
            "paper": self.paper_mode,
        }

        if sig.sell_pct >= 100:
            pos.status = "closed"
            self.portfolio.open_positions -= 1
            if pos.token_symbol in self.portfolio.open_tokens:
                self.portfolio.open_tokens.remove(pos.token_symbol)
            self.state.closed_trades.append(trade_record)
        else:
            pos.size_usd *= (1 - sell_frac)
            pos.token_amount *= (1 - sell_frac)

        return {"action": "exit", **trade_record}

    # ── Balance Sync ──────────────────────────────────────────────

    def _sync_balances(self) -> None:
        """Sync wallet balances with on-chain state."""
        if self.paper_mode:
            return

        balances = self.os.get_all_balances(force=True)
        if not balances:
            log.warning("Could not fetch wallet balances")
            return

        # Calculate total equity from balances
        total_usd = 0.0
        for bal in balances:
            if isinstance(bal, dict):
                usd_val = float(bal.get("balanceUsd", bal.get("usd_value", 0)) or 0)
                total_usd += usd_val

        if total_usd > 0:
            self.state.equity_usd = total_usd
            if total_usd > self.state.peak_equity_usd:
                self.state.peak_equity_usd = total_usd
            log.info(f"Wallet equity synced: ${total_usd:.2f}")

    # ── Position Queries ──────────────────────────────────────────

    def get_open_positions(self) -> list[dict[str, Any]]:
        """Return all open positions with current P&L."""
        result = []
        for pos in self.positions:
            if pos.status != "open":
                continue
            result.append({
                "token": pos.token_symbol,
                "token_address": pos.token_address,
                "entry_price": pos.entry_price,
                "current_price": pos.current_price,
                "size_usd": pos.size_usd,
                "unrealized_pnl_usd": pos.unrealized_pnl_usd,
                "unrealized_pnl_pct": pos.unrealized_pnl_pct,
                "bars_held": pos.bars_held,
                "entry_ts": pos.entry_ts,
            })
        return result

    def get_portfolio_summary(self) -> dict[str, Any]:
        """Return portfolio summary for display."""
        open_pos = self.get_open_positions()
        total_unrealized = sum(p["unrealized_pnl_usd"] for p in open_pos)
        return {
            "strategy": self.strategy_name,
            "chain": self.chain,
            "wallet": self.wallet,
            "equity_usd": round(self.state.equity_usd, 2),
            "peak_equity_usd": round(self.state.peak_equity_usd, 2),
            "total_pnl_usd": round(self.state.total_pnl_usd, 2),
            "unrealized_pnl_usd": round(total_unrealized, 2),
            "open_positions": len(open_pos),
            "total_trades": self.state.total_trades,
            "trades_today": self.state.trades_today,
            "consecutive_losses": self.state.consecutive_losses,
            "size_multiplier": self.size_multiplier,
            "paper_mode": self.paper_mode,
            "positions": open_pos,
        }

    def get_trade_history(self) -> list[dict[str, Any]]:
        """Return closed trade history."""
        return list(self.state.closed_trades)

    # ── Persistence ───────────────────────────────────────────────

    def _persist(self) -> None:
        """Save engine state to disk."""
        # Serialize open positions
        self.state.positions = [
            asdict(p) for p in self.positions if p.status == "open"
        ]
        _save_engine_state(self.state)

"""
LLM-driven strategy generation.

Takes a user profile + full primitive catalog → unique spec + theme + tagline.
Falls back gracefully if LLM is unavailable.
"""
from __future__ import annotations

import json
import os
import re
from typing import Any

# ── Primitive catalog (concise form for LLM prompt) ──────────────────────────

PRIMITIVE_CATALOG = """
ENTRY PRIMITIVES (pick exactly one):
- price_drop: {pct, lookback_bars} — buy when price drops X% in window
- price_breakout: {direction, lookback_bars, confirm_pct} — buy on breakout
- ma_cross: {fast_period, slow_period, ma_type} — buy when fast MA crosses slow MA
- rsi_threshold: {period, level, direction} — buy when RSI crosses level (cross_up at 30 = oversold)
- volume_spike: {multiplier, avg_bars} — buy on unusual volume surge
- time_schedule: {interval, anchor_utc} — DCA on fixed schedule (interval: 1D/1W/1M)
- smart_money_buy: {min_wallets, window_min} — buy when N smart wallets buy same token within window
- dev_buy: {min_usd, window_min} — buy when developer wallet buys their own token
- macd_cross: {fast_period, slow_period, signal_period, direction} — buy on MACD crossover
- bollinger_touch: {period, std_dev, band} — buy when price touches band (band: lower/upper)
- ranking_entry: {list_name, top_n} — snipe from list (list_name: trending/gainers/new)
- wallet_copy_buy: {target_wallet[], min_usd, mirror_mode} — mirror wallet buys (mirror_mode: instant/mcap_target)

EXIT PRIMITIVES:
Required field: stop_loss: {pct}
Optional extras in "other" array:
- {type: take_profit, pct} — fixed take profit %
- {type: trailing_stop, pct} — trailing stop %
- {type: tiered_take_profit, tiers:[{pct_gain, pct_sell},...]} — sell in layers (pct_sell values must sum to 100)
- {type: time_exit, max_bars} — exit after N bars
- {type: indicator_reversal, mirror_entry: true} — exit when entry signal reverses
- {type: smart_money_sell, min_wallets, window_min} — exit when smart money sells
- {type: dev_dump, min_usd} — exit on developer dump
- {type: wallet_mirror_sell, target_wallet[], min_pct_sold} — mirror wallet sells
- {type: fast_dump_exit, drop_pct, window_sec} — emergency rug/dump exit

FILTER PRIMITIVES (optional array):
General filters: time_window, volatility_range, volume_minimum, cooldown, market_regime, price_range, btc_overlay, top_zone_guard
Token safety (use for meme/new tokens): mcap_range, launch_age, honeypot_check, lp_locked, buy_tax_max, sell_tax_max, liquidity_min, top_holders_max, bundler_ratio_max, dev_holding_max, insider_holding_max, fresh_wallet_ratio_max, smart_money_present_min, phishing_exclude, whale_concentration_max

SIZING PRIMITIVES (pick one):
- {type: fixed_usd, usd} — fixed dollar amount per trade
- {type: fixed_pct, pct} — fixed % of portfolio per trade
- {type: volatility_scaled, target_risk_pct, atr_period} — scale size by volatility

RISK OVERLAY PRIMITIVES (array):
- {type: max_daily_trades, n}
- {type: max_concurrent_positions, n}
- {type: drawdown_pause, pause_pct}
- {type: session_loss_pause, max_consecutive_losses}
- {type: correlation_cap, mode, max_correlated}
"""

_SYSTEM = """You are a trading strategy architect. Design unique, personalized trading strategies by snapping primitives together like building blocks.

Rules:
- Pick exactly ONE entry primitive, configure its params thoughtfully for the user's situation
- stop_loss is always required; add creative exit combos in "other"
- Use token safety filters for meme/new token strategies (honeypot, lp_locked, etc.)
- theme = 2-3 word punchy identity (like "Momentum Engine", "Shadow Whale", "Dip Assassin")
- tagline = one sentence: the core trading philosophy of this strategy
- Make it genuinely unique — tune params to the user's specific profile, not generic defaults
- Be creative with primitive combinations — the same goal with different risk/budget should feel different
"""

_PROMPT = """\
Design a trading strategy for this user.

USER PROFILE:
{profile_json}
{extra}

PRIMITIVE CATALOG:
{catalog}

Return ONLY valid JSON (no markdown, no explanation):
{{
  "theme": "2-3 word name",
  "tagline": "one sentence philosophy",
  "spec": {{
    "meta": {{
      "name": "snake_case_64chars_max",
      "version": "1.0",
      "risk_tier": "conservative|moderate|aggressive",
      "description": "one line description",
      "author_intent": "{goal}"
    }},
    "instrument": {{
      "symbol": "TOKEN-USDC or * for dynamic",
      "timeframe": "5m|15m|1H|4H|1D"
    }},
    "entry": {{"type": "...", ...params}},
    "exit": {{
      "stop_loss": {{"pct": N}},
      "other": [...]
    }},
    "sizing": {{"type": "fixed_usd", "usd": {budget}}},
    "filters": [...],
    "risk_overlays": [...]
  }}
}}

For dynamic/wallet/meme strategies add at top level: "universe": {{"selector": "entry_type_value", "chain": "solana"}}
"""


def _get_api_key() -> str:
    """Get API key from env or Claude OAuth credentials."""
    key = os.environ.get("ANTHROPIC_API_KEY", "").strip()
    if key:
        return key
    creds_path = os.path.expanduser("~/.claude/.credentials.json")
    if not os.path.isfile(creds_path):
        return ""
    try:
        import time
        with open(creds_path) as f:
            creds = json.load(f)
        oauth = creds.get("claudeAiOauth", {})
        token = oauth.get("accessToken", "")
        if token and oauth.get("expiresAt", 0) > time.time() * 1000:
            return token
    except Exception:
        pass
    return ""


def _extract_json(text: str) -> dict[str, Any]:
    # Strip any leading non-JSON characters (org prefixes, markdown fences, etc.)
    text = text.strip()
    # Find first { or [ — start of JSON
    start = min(
        (text.find(c) for c in "{[" if text.find(c) != -1),
        default=0,
    )
    text = text[start:]
    # Strip trailing markdown fences
    text = re.sub(r"\s*```\s*$", "", text).strip()
    return json.loads(text)


# "Other" exit types that must live in exit.other[], not directly on exit
_OTHER_EXIT_TYPES = {
    "time_exit", "indicator_reversal", "smart_money_sell",
    "dev_dump", "wallet_mirror_sell", "fast_dump_exit",
}
# Inner exit types that must be direct keys on exit, not in exit.other[]
_INNER_EXIT_KEYS = {"stop_loss", "take_profit", "trailing_stop", "tiered_take_profit"}


def _normalize_spec(spec: dict[str, Any]) -> dict[str, Any]:
    """
    Auto-repair common LLM structural hallucinations before harness validation.

    Fixes applied (all silent — no errors raised here):
    1. Other-exit types placed directly on exit → moved to exit.other[]
    2. Inner-exit types placed in exit.other[] → promoted to direct exit keys
    3. Missing universe block when symbol == "*"
    4. tiered_take_profit tiers pct_sell doesn't sum to 100 → rescale last tier
    5. meta.live_only flag auto-set (harness also does this, but set it early)
    """
    import copy
    spec = copy.deepcopy(spec)

    exit_block = spec.get("exit", {})

    # Fix 1: other-exit types sitting directly on exit → move to exit.other[]
    other = exit_block.get("other", [])
    for key in list(exit_block.keys()):
        if key in _OTHER_EXIT_TYPES:
            item = exit_block.pop(key)
            if isinstance(item, dict):
                item.setdefault("type", key)
            else:
                item = {"type": key}
            other.append(item)
    if other:
        exit_block["other"] = other

    # Fix 2: inner-exit types sitting inside exit.other[] → promote to direct keys
    remaining_other = []
    for item in exit_block.get("other", []):
        if isinstance(item, dict) and item.get("type") in _INNER_EXIT_KEYS:
            key = item["type"]
            promoted = {k: v for k, v in item.items() if k != "type"}
            exit_block.setdefault(key, promoted)
        else:
            remaining_other.append(item)
    if remaining_other:
        exit_block["other"] = remaining_other
    elif "other" in exit_block:
        del exit_block["other"]

    spec["exit"] = exit_block

    # Fix 3: missing universe when symbol == "*"
    instr = spec.get("instrument", {})
    if instr.get("symbol") == "*" and "universe" not in spec:
        entry_type = spec.get("entry", {}).get("type", "ranking_entry")
        chain = spec.get("meta", {}).get("chain", "solana")
        spec["universe"] = {"selector": entry_type, "chain": chain}

    # Fix 4: tiered_take_profit pct_sell rescaling
    ttp = exit_block.get("tiered_take_profit", {})
    tiers = ttp.get("tiers", [])
    if tiers:
        total = sum(t.get("pct_sell", 0) for t in tiers)
        if total != 100 and total > 0:
            # Rescale all tiers proportionally, assign remainder to last
            scaled = [round(t.get("pct_sell", 0) * 100 / total) for t in tiers]
            diff = 100 - sum(scaled)
            scaled[-1] += diff
            for t, s in zip(tiers, scaled):
                t["pct_sell"] = s

    return spec


def generate_strategy_spec(
    profile: dict[str, Any],
    api_key: str = "",
) -> tuple[dict[str, Any], str, str, list[str]]:
    """
    LLM-generate a unique strategy spec.

    Returns (spec, theme, tagline, errors).
    Empty spec + errors list means failure — caller should fall back to template.
    """
    if not api_key:
        api_key = _get_api_key()
    if not api_key:
        return {}, "", "", ["No API key — LLM generation unavailable"]

    goal   = profile.get("goal", "unknown")
    budget = profile.get("total_budget") or profile.get("budget_per_trade") or 100
    wallets = profile.get("target_wallets", [])

    extra = f"\nWallets to track/mirror: {wallets}" if wallets else ""

    prompt = _PROMPT.format(
        profile_json=json.dumps(profile, indent=2),
        catalog=PRIMITIVE_CATALOG,
        goal=goal,
        budget=budget,
        extra=extra,
    )

    try:
        import anthropic
        from harness import validate_spec
        client = anthropic.Anthropic(api_key=api_key)

        messages: list[dict] = [{"role": "user", "content": prompt}]
        theme = tagline = ""
        spec: dict[str, Any] = {}
        last_errors: list[str] = []

        # Retry loop — up to 3 attempts, each feeds harness errors back to LLM
        for attempt in range(3):
            resp = client.messages.create(
                model="claude-haiku-4-5-20251001",
                max_tokens=2000,
                system=_SYSTEM,
                messages=messages,
            )
            raw = resp.content[0].text.strip()

            try:
                data = _extract_json(raw)
            except json.JSONDecodeError as e:
                last_errors = [f"Invalid JSON on attempt {attempt + 1}: {e}"]
                messages.append({"role": "assistant", "content": raw})
                messages.append({"role": "user", "content": (
                    f"Your response was not valid JSON. Error: {e}\n"
                    "Return ONLY a valid JSON object — no markdown, no explanation."
                )})
                continue

            theme   = data.get("theme", "")
            tagline = data.get("tagline", "")
            spec    = data.get("spec", {})

            if not spec or "entry" not in spec:
                last_errors = ["Incomplete spec: missing 'entry' block"]
                messages.append({"role": "assistant", "content": raw})
                messages.append({"role": "user", "content": (
                    "The spec is missing the required 'entry' block. "
                    "Return the complete JSON spec including entry, exit, sizing, filters, risk_overlays."
                )})
                continue

            # Normalize before validation (fix common structural errors)
            spec = _normalize_spec(spec)
            spec.setdefault("meta", {}).update({"theme": theme, "tagline": tagline})

            ok, errors, _ = validate_spec(spec)
            if ok:
                return spec, theme, tagline, []

            # Feed errors back for next attempt
            last_errors = errors
            messages.append({"role": "assistant", "content": raw})
            messages.append({"role": "user", "content": (
                f"The spec failed harness validation on attempt {attempt + 1}. "
                f"Fix ALL of these errors and return the corrected JSON:\n"
                + "\n".join(f"- {e}" for e in errors)
            )})

        # All retries exhausted — return best attempt + errors
        return spec, theme, tagline, last_errors

    except Exception as e:
        return {}, "", "", [f"LLM generation failed: {e}"]


# ── Deterministic theme fallback (when LLM unavailable) ──────────────────────

_FALLBACK_THEMES: dict[str, tuple[str, str]] = {
    "meme_sniper":  ("Momentum Sniper",  "Catch the spike, bank in layers, flee the rug"),
    "smart_money":  ("Shadow Whale",     "Follow alpha moves, exit when they exit"),
    "copy_trade":   ("Mirror Strike",    "Instant mirror execution, ride their edge"),
    "dca":          ("Steady Stacker",   "Time-based accumulation with trailing protection"),
    "dip_buy":      ("Dip Assassin",     "Buy the fear, sell the recovery"),
    "trend_follow": ("Trend Rider",      "Never fight the trend, let winners run"),
    "mean_revert":  ("Rubber Band",      "Oversold is just a discount waiting to expire"),
    "grid":         ("Grid Maker",       "Be the market maker, collect both sides"),
}


def get_fallback_theme(goal_key: str) -> tuple[str, str]:
    """Return (theme, tagline) for when LLM is unavailable."""
    return _FALLBACK_THEMES.get(goal_key, ("Custom Strategy", "Built from your unique profile"))