Z-Score Reversion

const zscoreBot: BotDef = {
  id: "zscore",
  name: "Z-Score Reversion",
  category: "stats",
  glyph: "ζ",
  tagline: "Bet on snap-back when the price wanders too far.",
  formula: "z = (price − μ) / σ over n bars",
  params: [
    { key: "period", label: "Window", kind: "number", default: 30, min: 10, max: 120, step: 1 },
    { key: "threshold", label: "|z| threshold", kind: "number", default: 2, min: 1, max: 3, step: 0.1 },
  ],
  run: (ctx, p): BotResult => {
    const period = Math.round(num(p, "period", 30));
    const th = num(p, "threshold", 2);
    const px = closes(ctx.candles);
    const z = zscore(px, period);
    const signals: Signal[] = [];
    const sigArr: (1 | -1 | 0)[] = px.map(() => 0);
    for (let i = 1; i < z.length; i++) {
      const a = z[i - 1], b = z[i];
      if (a == null || b == null) continue;
      if (a < -th && b >= -th) {
        signals.push({ i, kind: "buy", price: px[i], label: "reverting up" });
        sigArr[i] = 1;
      } else if (a > th && b <= th) {
        signals.push({ i, kind: "sell", price: px[i], label: "reverting down" });
        sigArr[i] = -1;
      }
    }
    const bt = backtestLongOnly(px, sigArr);
    const last = z[z.length - 1] ?? 0;
    return {
      signals,
      metrics: [
        { key: "z", label: "Z", value: fmtNum(last, 2), tone: last > th ? "bear" : last < -th ? "bull" : "neutral" },
        { key: "thr", label: "Threshold", value: `±${th}`, tone: "neutral" },
        { key: "trades", label: "Trades", value: String(bt.trades) },
        { key: "win", label: "Win rate", value: `${(bt.winRate * 100).toFixed(0)}%`, tone: bt.winRate > 0.5 ? "bull" : "warn" },
      ],
      pane: {
        kind: "line",
        series: [{ values: z, color: "var(--plasma)", label: "z" }],
        refLines: [
          { value: th, color: "var(--bear)", label: "+" + th },
          { value: -th, color: "var(--bull)", label: "−" + th },
          { value: 0, color: "var(--fg-faint)" },
        ],
        height: 80,
      },
      summary: `Z = ${last.toFixed(2)} (threshold ±${th}). ${signals.length} reversion entries.`,
      beginner:
        "Z-score asks: how unusual is today's price compared to recent days? A z of -2 means 'cheaper than 97% of recent prices'. Most things drift back to average — that's the trade.",
      verdict: {
        side: last < -th ? "buy" : last > th ? "sell" : "hold",
        text: last < -th
          ? `${last.toFixed(2)}σ below mean — historical bounce zone.`
          : last > th
          ? `${last.toFixed(2)}σ above mean — historical fade zone.`
          : "Within the noise band — no signal.",
        confidence: Math.min(1, Math.abs(last) / 3),
      },
      equity: bt.equity,
    };
  },
};