kalshi-trading-bot-cli 2.1.0

package/src/backtest/fetcher.ts

@@ -0,0 +1,247 @@
+import type { Database } from 'bun:sqlite';
+
+/** Thrown when the history API requires a paid subscription. */
+export class SubscriptionRequiredError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SubscriptionRequiredError';
+  }
+}
+
+/** Narrow snapshot type representing what we actually store and use from history. */
+export interface OutcomeProbability {
+  market_ticker: string;
+  outcome_name?: string;
+  model_probability: number;   // percentage 0-100
+  market_probability: number;  // percentage 0-100
+  /** Per-contract cumulative volume at snapshot time (nullable for older snapshots). */
+  volume?: number | null;
+  /** Per-contract trailing 24h volume at snapshot time (nullable for older snapshots). */
+  volume_24h?: number | null;
+}
+
+export interface HistorySnapshot {
+  history_id: number;
+  event_ticker: string;
+  captured_at: string;
+  name: string | null;
+  series_category: string | null;
+  confidence_score: number | null;
+  model_probability: number;   // percentage 0-100
+  market_probability: number;  // percentage 0-100
+  edge_pp: number | null;
+  close_time: string | null;
+  outcome_probabilities?: OutcomeProbability[] | null;
+  outcome_probabilities_json?: string | null; // raw JSON from DB cache
+}
+
+interface HistoryPage {
+  event_ticker: string;
+  data: HistorySnapshot[];
+  next_cursor: string | null;
+  has_more: boolean;
+}
+
+const EVENTS_API_BASE = 'https://api.octagonai.co/v1';
+const PAGE_LIMIT = 200;
+const TIMEOUT_MS = 60_000;
+
+/**
+ * Fetch all history snapshots for an event from the Octagon API.
+ * Supports optional time window filtering via captured_from/captured_to.
+ */
+export async function fetchEventHistory(
+  eventTicker: string,
+  opts?: { capturedFrom?: string; capturedTo?: string; days?: number },
+): Promise<HistorySnapshot[]> {
+  const apiKey = process.env.OCTAGON_API_KEY;
+  if (!apiKey) throw new Error('OCTAGON_API_KEY not set');
+
+  const all: HistorySnapshot[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const params = new URLSearchParams({ limit: String(PAGE_LIMIT) });
+    params.set('exclude_empty_model', 'true');
+    if (cursor) params.set('cursor', cursor);
+    if (opts?.capturedFrom) params.set('captured_from', opts.capturedFrom);
+    if (opts?.capturedTo) params.set('captured_to', opts.capturedTo);
+    if (opts?.days) params.set('days', String(opts.days));
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    let resp: Response;
+    try {
+      resp = await fetch(
+        `${EVENTS_API_BASE}/prediction-markets/events/${encodeURIComponent(eventTicker)}/history?${params}`,
+        { headers: { Authorization: `Bearer ${apiKey}` }, signal: controller.signal },
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+
+    if (!resp.ok) {
+      const body = await resp.text().catch(() => '');
+      if (resp.status === 403 || resp.status === 402) {
+        throw new SubscriptionRequiredError(
+          'The Octagon history API requires a paid subscription. ' +
+          'The unresolved edge scanner (--unresolved) uses the free events API. ' +
+          'Upgrade at https://app.octagonai.co to unlock resolved market backtesting.',
+        );
+      }
+      throw new Error(`Octagon history API ${resp.status} for ${eventTicker}: ${body.slice(0, 200)}`);
+    }
+
+    const raw = (await resp.json()) as unknown;
+    if (!raw || typeof raw !== 'object') {
+      throw new Error(`Octagon history API returned invalid response for ${eventTicker}`);
+    }
+    const page = raw as Record<string, unknown>;
+    if (!Array.isArray(page.data)) {
+      throw new Error(`Octagon history API response missing data array for ${eventTicker}`);
+    }
+    const hasMore = typeof page.has_more === 'boolean' ? page.has_more : false;
+    if (hasMore && !page.next_cursor) {
+      throw new Error(`Octagon history API has_more=true but next_cursor missing for ${eventTicker}`);
+    }
+    all.push(...(page.data as HistorySnapshot[]));
+    cursor = hasMore ? (page.next_cursor as string) : null;
+  } while (cursor);
+
+  return all;
+}
+
+/**
+ * Fetch event history and cache it in the local octagon_history table.
+ * Only uses the cache for full-history requests (no time window).
+ * When capturedFrom/capturedTo are provided, always fetches fresh from the API.
+ *
+ * If `maxAgeDays` is supplied, the cache is considered stale when the newest
+ * cached snapshot is older than that window, and we refetch from the API so
+ * new snapshots show up. `INSERT OR IGNORE` keeps old rows intact.
+ */
+export async function fetchAndCacheHistory(
+  db: Database,
+  eventTicker: string,
+  opts?: { capturedFrom?: string; capturedTo?: string; days?: number; maxAgeDays?: number },
+): Promise<HistorySnapshot[]> {
+  const hasWindow = !!(opts?.capturedFrom || opts?.capturedTo);
+
+  // Only use cache for full-history requests (no time window filter)
+  if (!hasWindow) {
+    const cached = db.query(
+      'SELECT COUNT(*) as cnt, MAX(captured_at) as newest FROM octagon_history WHERE event_ticker = $et',
+    ).get({ $et: eventTicker }) as { cnt: number; newest: string | null };
+
+    let cacheFresh = cached.cnt > 0;
+    if (cacheFresh && opts?.maxAgeDays && cached.newest) {
+      const newestEpoch = new Date(cached.newest).getTime();
+      const cutoffEpoch = Date.now() - opts.maxAgeDays * 24 * 60 * 60 * 1000;
+      if (Number.isFinite(newestEpoch) && newestEpoch < cutoffEpoch) {
+        cacheFresh = false; // newest snapshot is older than the lookback window
+      }
+    }
+
+    if (cacheFresh) {
+      const rows = db.query(
+        `SELECT history_id, event_ticker, captured_at, name, series_category,
+                confidence_score, model_probability, market_probability, edge_pp, close_time,
+                outcome_probabilities_json
+         FROM octagon_history WHERE event_ticker = $et ORDER BY captured_at ASC`,
+      ).all({ $et: eventTicker }) as HistorySnapshot[];
+      // Parse outcome_probabilities from cached JSON
+      for (const r of rows) {
+        if (r.outcome_probabilities_json) {
+          try { r.outcome_probabilities = JSON.parse(r.outcome_probabilities_json); } catch { /* skip */ }
+        }
+      }
+      return rows;
+    }
+  }
+
+  // Fetch from API
+  const snapshots = await fetchEventHistory(eventTicker, opts);
+
+  // Cache in DB (only for full-history requests to avoid partial cache)
+  if (!hasWindow) {
+    const insert = db.prepare(`
+      INSERT OR IGNORE INTO octagon_history
+        (history_id, event_ticker, captured_at, model_probability, market_probability,
+         edge_pp, confidence_score, series_category, close_time, name, outcome_probabilities_json)
+      VALUES ($history_id, $event_ticker, $captured_at, $model_probability, $market_probability,
+              $edge_pp, $confidence_score, $series_category, $close_time, $name, $opj)
+    `);
+
+    db.transaction(() => {
+      for (const s of snapshots) {
+        insert.run({
+          $history_id: s.history_id,
+          $event_ticker: s.event_ticker,
+          $captured_at: s.captured_at,
+          $model_probability: s.model_probability,
+          $market_probability: s.market_probability,
+          $edge_pp: s.edge_pp,
+          $confidence_score: s.confidence_score,
+          $series_category: s.series_category ?? null,
+          $close_time: s.close_time ?? null,
+          $name: s.name ?? null,
+          $opj: s.outcome_probabilities ? JSON.stringify(s.outcome_probabilities) : null,
+        });
+      }
+    })();
+
+    // Re-read merged cache so callers see old snapshots that may have been
+    // stored on a previous fetch but omitted from this API response.
+    const merged = db.query(
+      `SELECT history_id, event_ticker, captured_at, name, series_category,
+              confidence_score, model_probability, market_probability, edge_pp, close_time,
+              outcome_probabilities_json
+       FROM octagon_history WHERE event_ticker = $et ORDER BY captured_at ASC`,
+    ).all({ $et: eventTicker }) as HistorySnapshot[];
+    for (const r of merged) {
+      if (r.outcome_probabilities_json) {
+        try { r.outcome_probabilities = JSON.parse(r.outcome_probabilities_json); } catch { /* skip */ }
+      }
+    }
+    return merged;
+  }
+
+  return snapshots;
+}
+
+/**
+ * Select the snapshot closest to a target date (N days ago).
+ * Returns the last snapshot captured on or before the target date.
+ * If `minDate` is provided, snapshots older than that are rejected — this
+ * prevents a 15-day lookback from silently using a 30-day-old prediction
+ * when the event has no fresh snapshot within the window.
+ *
+ * Additionally requires each candidate snapshot to carry a finite
+ * `market_probability` and a non-empty `outcome_probabilities` array
+ * (mirrors the Supabase-methodology guard
+ * `market_probability IS NOT NULL AND LENGTH(outcome_probabilities_json) > 2`).
+ *
+ * Probabilities in the returned snapshot are percentages (0-100).
+ */
+export function selectSnapshotByDate(
+  snapshots: HistorySnapshot[],
+  targetDate: Date,
+  minDate?: Date,
+): HistorySnapshot | null {
+  const targetEpoch = targetDate.getTime();
+  const minEpoch = minDate ? minDate.getTime() : -Infinity;
+
+  let best: HistorySnapshot | null = null;
+  let bestEpoch = -Infinity;
+  for (const s of snapshots) {
+    if (!Number.isFinite(s.market_probability)) continue;
+    if (!Array.isArray(s.outcome_probabilities) || s.outcome_probabilities.length === 0) continue;
+    const capturedEpoch = new Date(s.captured_at).getTime();
+    if (capturedEpoch <= targetEpoch && capturedEpoch >= minEpoch && capturedEpoch > bestEpoch) {
+      best = s;
+      bestEpoch = capturedEpoch;
+    }
+  }
+  return best;
+}

package/src/backtest/metrics.ts

@@ -0,0 +1,165 @@
+import type { ScoredSignal, BacktestResult } from './types.js';
+
+/**
+ * Skill score: how much better Octagon is vs the market as a forecaster.
+ * Positive = model beats market. Negative = market is better.
+ */
+export function computeSkillScore(brierOctagon: number, brierMarket: number): number {
+  if (brierMarket === 0) return 0;
+  return 1 - (brierOctagon / brierMarket);
+}
+
+/**
+ * Bootstrap confidence interval for a statistic.
+ * Resamples `data` with replacement `iterations` times, computes `statFn` on each sample.
+ * Returns [lower, upper] at the given confidence level (default 95%).
+ */
+export function bootstrapCI(
+  data: number[],
+  statFn: (sample: number[]) => number,
+  iterations = 10_000,
+  alpha = 0.05,
+): [number, number] {
+  if (data.length === 0) return [0, 0];
+  if (!Number.isFinite(iterations) || !Number.isInteger(iterations) || iterations <= 0) {
+    throw new Error(`bootstrapCI: iterations must be a finite integer > 0, got ${iterations}`);
+  }
+  if (!Number.isFinite(alpha) || alpha <= 0 || alpha >= 1) {
+    throw new Error(`bootstrapCI: alpha must be a finite number in (0, 1), got ${alpha}`);
+  }
+
+  const stats: number[] = [];
+  for (let i = 0; i < iterations; i++) {
+    const sample: number[] = [];
+    for (let j = 0; j < data.length; j++) {
+      sample.push(data[Math.floor(Math.random() * data.length)]);
+    }
+    stats.push(statFn(sample));
+  }
+  stats.sort((a, b) => a - b);
+
+  if (stats.length === 0) return [0, 0];
+  const lo = Math.min(Math.max(0, Math.floor((alpha / 2) * stats.length)), stats.length - 1);
+  const hi = Math.min(Math.max(0, Math.floor((1 - alpha / 2) * stats.length)), stats.length - 1);
+  return [stats[lo], stats[hi]];
+}
+
+/**
+ * Compute Brier score: ((forecast/100) - (outcome/100))²
+ * Both forecast and outcome are on 0-100 scale.
+ */
+function brier(forecast: number, outcome: number): number {
+  return ((forecast / 100) - (outcome / 100)) ** 2;
+}
+
+/**
+ * Compute all backtest metrics from a unified list of scored signals.
+ */
+export function computeMetrics(signals: ScoredSignal[], minEdgePp = 0.5): Omit<BacktestResult, 'subscription_notice'> {
+  const n = signals.length;
+  if (n === 0) {
+    return {
+      verdict: { summary: 'No markets with Octagon coverage found.', significant: false, profitable: false },
+      days: 0,
+      events_scored: 0,
+      markets_resolved: 0,
+      markets_unresolved: 0,
+      brier_octagon: 0,
+      brier_market: 0,
+      skill_score: 0,
+      skill_ci: [0, 0],
+      edge_signals: 0,
+      edge_hit_rate: 0,
+      hit_rate_ci: [0, 0],
+      flat_bet_pnl: 0,
+      flat_bet_roi: 0,
+      total_capital: 0,
+      signals: [],
+    };
+  }
+
+  // Brier scores — model vs market, both compared to outcome (market_now)
+  const brierOctagonScores = signals.map(s => brier(s.model_prob, s.market_now));
+  const brierMarketScores = signals.map(s => brier(s.market_then, s.market_now));
+  const brierOctagon = brierOctagonScores.reduce((a, b) => a + b, 0) / n;
+  const brierMarket = brierMarketScores.reduce((a, b) => a + b, 0) / n;
+
+  // Skill score with bootstrap CI — resample both
+  const skillScore = computeSkillScore(brierOctagon, brierMarket);
+  const indices = signals.map((_, i) => i);
+  const skillCI = bootstrapCI(indices, (sample) => {
+    let sumOctagon = 0;
+    let sumMarket = 0;
+    for (const idx of sample) {
+      sumOctagon += brierOctagonScores[idx];
+      sumMarket += brierMarketScores[idx];
+    }
+    const avgOctagon = sumOctagon / sample.length;
+    const avgMarket = sumMarket / sample.length;
+    return avgMarket === 0 ? 0 : 1 - (avgOctagon / avgMarket);
+  });
+
+  // Edge signals: where |edge| >= minEdgePp AND edge is non-zero
+  const edgeSignals = signals.filter(s => s.edge_pp !== 0 && Math.abs(s.edge_pp) >= minEdgePp);
+  const edgeCount = edgeSignals.length;
+
+  // Hit rate: did the market move in the direction the model predicted?
+  const hits = edgeSignals.filter(s => {
+    // Model said YES (edge > 0): hit if market_now > market_then
+    // Model said NO (edge < 0): hit if market_now < market_then
+    if (s.edge_pp > 0) return s.market_now > s.market_then;
+    return s.market_now < s.market_then;
+  });
+  const hitRate = edgeCount > 0 ? hits.length / edgeCount : 0;
+
+  // Bootstrap hit rate CI
+  const hitRateData = edgeSignals.map(s => {
+    if (s.edge_pp > 0) return s.market_now > s.market_then ? 1 : 0;
+    return s.market_now < s.market_then ? 1 : 0;
+  });
+  const hitRateCI = bootstrapCI(hitRateData, (sample) => {
+    return sample.reduce((a, b) => a + b, 0) / sample.length;
+  });
+
+  // P&L and capital-weighted ROI (matches Supabase methodology):
+  //   ROI = sum(pnl) / sum(capital) across edge signals.
+  const pnl = edgeSignals.reduce((sum, s) => sum + s.pnl, 0);
+  const totalCapital = edgeSignals.reduce((sum, s) => sum + s.capital, 0);
+  const roi = totalCapital > 0 ? pnl / totalCapital : 0;
+
+  // Counts
+  const uniqueEvents = new Set(signals.map(s => s.event_ticker));
+  const resolved = signals.filter(s => s.resolved).length;
+  const unresolved = signals.filter(s => !s.resolved).length;
+
+  // Verdict
+  const significant = skillCI[0] > 0;
+  const profitable = pnl > 0;
+  let summary: string;
+  if (skillScore > 0.05 && significant && profitable) {
+    summary = `Model has edge (Skill +${(skillScore * 100).toFixed(1)}% [CI: +${(skillCI[0] * 100).toFixed(1)}%, +${(skillCI[1] * 100).toFixed(1)}%]; ROI +${(roi * 100).toFixed(1)}%)`;
+  } else if (skillScore > 0 && !significant) {
+    summary = `Inconclusive — need more data (Skill +${(skillScore * 100).toFixed(1)}%, CI includes zero)`;
+  } else {
+    summary = `No edge detected (Skill ${(skillScore * 100).toFixed(1)}%)`;
+  }
+
+  return {
+    verdict: { summary, significant, profitable },
+    days: 0, // filled by caller
+    events_scored: uniqueEvents.size,
+    markets_resolved: resolved,
+    markets_unresolved: unresolved,
+    brier_octagon: brierOctagon,
+    brier_market: brierMarket,
+    skill_score: skillScore,
+    skill_ci: skillCI,
+    edge_signals: edgeCount,
+    edge_hit_rate: hitRate,
+    hit_rate_ci: hitRateCI,
+    flat_bet_pnl: pnl,
+    flat_bet_roi: roi,
+    total_capital: totalCapital,
+    signals,
+  };
+}

package/src/backtest/renderer.ts

@@ -0,0 +1,196 @@
+import type { BacktestResult, ScoredSignal } from './types.js';
+import { writeFileSync } from 'fs';
+
+export interface FormatOpts {
+  minEdge?: number;          // 0-1 scale, default 0.005 (0.5pp)
+}
+
+/**
+ * Format complete backtest result for terminal display.
+ */
+export function formatBacktestHuman(result: BacktestResult, opts?: FormatOpts): string {
+  const minEdgePp = ((opts?.minEdge ?? 0.005) * 100).toFixed(1);
+  const now = new Date();
+  const from = new Date(now.getTime() - result.days * 24 * 60 * 60 * 1000);
+  const fromStr = from.toISOString().slice(5, 10).replace('-', '/');
+  const toStr = now.toISOString().slice(5, 10).replace('-', '/');
+
+  const lines: string[] = [];
+  lines.push(`Octagon Backtest — ${result.days}-day lookback (${fromStr} – ${toStr})`);
+  lines.push('══════════════════════════════════════════════════════════');
+  lines.push('');
+
+  if (result.subscription_notice) {
+    lines.push(`  ${result.subscription_notice}`);
+    lines.push('');
+    // Still show unresolved signals if any
+    const unresolvedSignals = result.signals.filter(s => !s.resolved);
+    if (unresolvedSignals.length > 0) {
+      lines.push(formatUnresolvedTable(unresolvedSignals, minEdgePp));
+    }
+    return lines.join('\n');
+  }
+
+  if (result.signals.length === 0) {
+    lines.push('No data available. Try a longer lookback (--days 60) or broader filter.');
+    return lines.join('\n');
+  }
+
+  // Unified scorecard
+  lines.push(`VERDICT: ${result.verdict.summary}`);
+  lines.push('');
+  lines.push(`  Events         ${result.events_scored}`);
+  lines.push(`  Markets        ${result.markets_resolved + result.markets_unresolved}   (${result.markets_resolved} resolved, ${result.markets_unresolved} unresolved)`);
+  lines.push('');
+  // Brier scores and Skill Score are hidden for now (keep values in result for JSON/CSV consumers).
+  // lines.push(`  Brier (Octagon)   ${result.brier_octagon.toFixed(3)}`);
+  // lines.push(`  Brier (Market)    ${result.brier_market.toFixed(3)}`);
+  // lines.push(`  Skill Score       ${result.skill_score >= 0 ? '+' : ''}${(result.skill_score * 100).toFixed(1)}%  [95% CI: ${(result.skill_ci[0] * 100).toFixed(1)}% to ${(result.skill_ci[1] * 100).toFixed(1)}%]`);
+  // lines.push('');
+  lines.push(`  Edge signals      ${result.edge_signals}   (min edge: ${minEdgePp}pp)`);
+  if (result.edge_signals > 0) {
+    lines.push(`  Hit rate          ${(result.edge_hit_rate * 100).toFixed(1)}%  [95% CI: ${(result.hit_rate_ci[0] * 100).toFixed(1)}% to ${(result.hit_rate_ci[1] * 100).toFixed(1)}%]`);
+    lines.push(`  Flat-bet P&L      ${result.flat_bet_pnl >= 0 ? '+' : ''}$${result.flat_bet_pnl.toFixed(2)} (ROI: ${result.flat_bet_roi >= 0 ? '+' : ''}${(result.flat_bet_roi * 100).toFixed(1)}%)`);
+    lines.push(`  Capital deployed  $${result.total_capital.toFixed(2)}   (capital-weighted ROI)`);
+  }
+
+  // Resolved detail table
+  const resolved = result.signals.filter(s => s.resolved);
+  if (resolved.length > 0) {
+    lines.push('');
+    lines.push(formatResolvedTable(resolved));
+  }
+
+  // Unresolved detail table
+  const unresolved = result.signals.filter(s => !s.resolved);
+  if (unresolved.length > 0) {
+    lines.push('');
+    lines.push(formatUnresolvedTable(unresolved, minEdgePp));
+  }
+
+  return lines.join('\n');
+}
+
+function formatResolvedTable(signals: ScoredSignal[]): string {
+  const lines: string[] = [];
+  lines.push(`RESOLVED (${signals.length} markets — scored against Kalshi settlement)`);
+  lines.push('─────────────────────────────────────────────────────────');
+
+  const header = '  ' + [
+    'Ticker'.padEnd(30),
+    'Model'.padStart(6),
+    'Mkt Then'.padStart(9),
+    'Outcome'.padStart(10),
+    'Edge'.padStart(7),
+    'Bkt'.padStart(7),
+    'P&L'.padStart(8),
+    'ROI'.padStart(8),
+  ].join('  ');
+  lines.push(header);
+
+  // Sort by |P&L| descending
+  const sorted = [...signals].sort((a, b) => Math.abs(b.pnl) - Math.abs(a.pnl));
+  for (const s of sorted.slice(0, 20)) {
+    const outcome = s.market_now === 100 ? 'YES 100%' : 'NO  0%';
+    const roi = s.capital > 0 ? (s.pnl / s.capital) * 100 : 0;
+    const roiStr = s.capital > 0
+      ? `${roi >= 0 ? '+' : ''}${roi.toFixed(1)}%`
+      : '—';
+    const row = '  ' + [
+      s.market_ticker.padEnd(30),
+      `${s.model_prob.toFixed(0)}%`.padStart(6),
+      `${s.market_then.toFixed(0)}%`.padStart(9),
+      outcome.padStart(10),
+      `${s.edge_pp >= 0 ? '+' : ''}${s.edge_pp.toFixed(0)}pp`.padStart(7),
+      s.edge_bucket.padStart(7),
+      `${s.pnl >= 0 ? '+' : ''}$${s.pnl.toFixed(2)}`.padStart(8),
+      roiStr.padStart(8),
+    ].join('  ');
+    lines.push(row);
+  }
+  if (sorted.length > 20) {
+    lines.push(`  ... and ${sorted.length - 20} more`);
+  }
+
+  return lines.join('\n');
+}
+
+function formatUnresolvedTable(signals: ScoredSignal[], minEdgePp: string): string {
+  const lines: string[] = [];
+  lines.push(`UNRESOLVED (${signals.length} markets — mark-to-market vs Kalshi trading price)`);
+  lines.push('────────────────────────────────────────────────────────────────');
+
+  const header = '  ' + [
+    'Ticker'.padEnd(30),
+    'Model'.padStart(6),
+    'Mkt Then'.padStart(9),
+    'Now'.padStart(6),
+    'Edge'.padStart(7),
+    'Bkt'.padStart(7),
+    'M2M'.padStart(8),
+    'ROI'.padStart(8),
+  ].join('  ');
+  lines.push(header);
+
+  // Sort by |edge| descending
+  const sorted = [...signals].sort((a, b) => Math.abs(b.edge_pp) - Math.abs(a.edge_pp));
+  for (const s of sorted.slice(0, 20)) {
+    const roi = s.capital > 0 ? (s.pnl / s.capital) * 100 : 0;
+    const roiStr = s.capital > 0
+      ? `${roi >= 0 ? '+' : ''}${roi.toFixed(1)}%`
+      : '—';
+    const row = '  ' + [
+      s.market_ticker.padEnd(30),
+      `${s.model_prob.toFixed(0)}%`.padStart(6),
+      `${s.market_then.toFixed(0)}%`.padStart(9),
+      `${s.market_now.toFixed(0)}%`.padStart(6),
+      `${s.edge_pp >= 0 ? '+' : ''}${s.edge_pp.toFixed(0)}pp`.padStart(7),
+      s.edge_bucket.padStart(7),
+      `${s.pnl >= 0 ? '+' : ''}$${s.pnl.toFixed(2)}`.padStart(8),
+      roiStr.padStart(8),
+    ].join('  ');
+    lines.push(row);
+  }
+  if (sorted.length > 20) {
+    lines.push(`  ... and ${sorted.length - 20} more`);
+  }
+
+  return lines.join('\n');
+}
+
+/** Escape a CSV cell: wrap in quotes if it contains comma, quote, or newline. */
+function csvEscape(val: string | number): string {
+  const s = String(val);
+  if (s.includes(',') || s.includes('"') || s.includes('\n') || s.includes('\r')) {
+    return '"' + s.replace(/"/g, '""') + '"';
+  }
+  return s;
+}
+
+/**
+ * Export per-market detail to CSV.
+ */
+export function exportCSV(result: BacktestResult, path: string): void {
+  const rows: string[] = [];
+  rows.push('type,ticker,event_ticker,series_category,edge_bucket,model_prob,market_then,market_now,edge_pp,pnl,capital,resolved,close_time');
+
+  for (const s of result.signals) {
+    rows.push([
+      s.resolved ? 'resolved' : 'unresolved',
+      csvEscape(s.market_ticker),
+      csvEscape(s.event_ticker),
+      csvEscape(s.series_category),
+      csvEscape(s.edge_bucket),
+      s.model_prob.toFixed(1),
+      s.market_then.toFixed(1),
+      s.market_now.toFixed(1),
+      s.edge_pp.toFixed(1),
+      s.pnl.toFixed(4),
+      s.capital.toFixed(4),
+      s.resolved ? '1' : '0',
+      csvEscape(s.close_time),
+    ].join(','));
+  }
+
+  writeFileSync(path, rows.join('\n') + '\n');
+}

package/src/backtest/types.ts

@@ -0,0 +1,45 @@
+export interface BacktestOpts {
+  days: number;               // lookback period in days (default 30)
+  resolvedOnly: boolean;
+  unresolvedOnly: boolean;
+  category?: string;
+  minEdge: number;            // fractional (0-1 scale), converted to pp by caller (e.g., 0.005 → 0.5pp)
+  exportPath?: string;
+}
+
+/** A single scored market signal — unified type for both resolved and unresolved. */
+export interface ScoredSignal {
+  event_ticker: string;
+  market_ticker: string;
+  series_category: string;
+  model_prob: number;         // 0-100 (Octagon model % from N days ago)
+  market_then: number;        // 0-100 (Kalshi trading price N days ago, from Octagon snapshot)
+  market_now: number;         // 0-100 (settlement for resolved, current price for unresolved)
+  resolved: boolean;
+  edge_pp: number;            // model_prob - market_then
+  pnl: number;               // computed P&L for this signal ($ per $1 face value)
+  capital: number;           // $ capital deployed per $1 face value: kp/100 for YES edges, (100-kp)/100 for NO edges
+  edge_bucket: string;        // absolute-edge bucket label e.g. "0-5%", "5-10%", ..., "90%+"
+  confidence_score: number;
+  close_time: string;
+}
+
+export interface BacktestResult {
+  verdict: { summary: string; significant: boolean; profitable: boolean };
+  days: number;
+  events_scored: number;
+  markets_resolved: number;
+  markets_unresolved: number;
+  brier_octagon: number;
+  brier_market: number;
+  skill_score: number;
+  skill_ci: [number, number];
+  edge_signals: number;
+  edge_hit_rate: number;
+  hit_rate_ci: [number, number];
+  flat_bet_pnl: number;
+  flat_bet_roi: number;       // capital-weighted: sum(pnl) / sum(capital) across edge signals
+  total_capital: number;      // sum of capital across edge signals (ROI denominator)
+  signals: ScoredSignal[];
+  subscription_notice?: string;
+}