kalshi-trading-bot-cli 2.1.3 → 2.1.4

package/src/commands/series.ts

@@ -0,0 +1,386 @@
+/**
+ * Series-level rollup over Octagon's /kalshi/markets endpoint.
+ *
+ * "Series" is the Kalshi grouping above markets — KXBTCD is a series, while
+ * KXBTCD-26DEC31-T100000 is a market inside it. Octagon doesn't expose a
+ * dedicated series endpoint, so we paginate /kalshi/markets and reduce by
+ * series_ticker client-side. The open universe is ~few thousand markets so
+ * this is cheap (2-3 paginated calls).
+ */
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import {
+  searchKalshiMarkets,
+  getBasketCandles,
+  listKalshiSeries,
+  getSeriesEvents,
+  type KalshiMarketRow,
+  type BasketCandlesResponse,
+  type SeriesRollupRow,
+  type SeriesEventRow,
+} from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+const UNIVERSE_PAGE_LIMIT = 200;
+const MAX_PAGES = 25; // safety cap; universe is small
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+function fmtMoney(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  return `$${v.toFixed(2)}`;
+}
+
+// ─── Rollup logic ───────────────────────────────────────────────────────────
+
+export interface SeriesRollup {
+  series_ticker: string;
+  market_count: number;
+  active_count: number;
+  total_volume_24h: number;
+  total_open_interest: number;
+  dominant_category: string | null;
+  sample_titles: string[];
+  earliest_close: string | null;
+  latest_close: string | null;
+}
+
+function rollupBySeries(markets: KalshiMarketRow[]): SeriesRollup[] {
+  const map = new Map<string, {
+    market_count: number;
+    active_count: number;
+    total_volume_24h: number;
+    total_open_interest: number;
+    category_counts: Map<string, number>;
+    sample_titles: string[];
+    earliest_close: string | null;
+    latest_close: string | null;
+  }>();
+
+  for (const m of markets) {
+    // Use series_ticker if present, else derive from market_ticker prefix
+    // (Kalshi convention: SERIES-EVENT-OUTCOME)
+    const series = m.series_ticker ?? m.market_ticker.split('-')[0];
+    if (!series) continue;
+
+    let entry = map.get(series);
+    if (!entry) {
+      entry = {
+        market_count: 0,
+        active_count: 0,
+        total_volume_24h: 0,
+        total_open_interest: 0,
+        category_counts: new Map(),
+        sample_titles: [],
+        earliest_close: null,
+        latest_close: null,
+      };
+      map.set(series, entry);
+    }
+
+    entry.market_count += 1;
+    if (m.status === 'active' || m.status === 'open') entry.active_count += 1;
+    entry.total_volume_24h += m.volume_24h ?? 0;
+    entry.total_open_interest += m.open_interest ?? 0;
+
+    const cat = m.category ?? '';
+    if (cat) entry.category_counts.set(cat, (entry.category_counts.get(cat) ?? 0) + 1);
+
+    if (entry.sample_titles.length < 3 && m.title) entry.sample_titles.push(m.title);
+
+    if (m.close_time) {
+      if (!entry.earliest_close || m.close_time < entry.earliest_close) entry.earliest_close = m.close_time;
+      if (!entry.latest_close || m.close_time > entry.latest_close) entry.latest_close = m.close_time;
+    }
+  }
+
+  return Array.from(map.entries()).map(([series_ticker, agg]) => {
+    let dominant_category: string | null = null;
+    let dominantCount = 0;
+    for (const [cat, count] of agg.category_counts.entries()) {
+      if (count > dominantCount) {
+        dominant_category = cat;
+        dominantCount = count;
+      }
+    }
+    return {
+      series_ticker,
+      market_count: agg.market_count,
+      active_count: agg.active_count,
+      total_volume_24h: agg.total_volume_24h,
+      total_open_interest: agg.total_open_interest,
+      dominant_category,
+      sample_titles: agg.sample_titles,
+      earliest_close: agg.earliest_close,
+      latest_close: agg.latest_close,
+    };
+  });
+}
+
+async function fetchUniverse(opts: {
+  q?: string;
+  category?: string;
+  series_ticker?: string;
+  min_volume_24h?: number;
+  close_before?: string;
+  maxMarkets?: number;
+}): Promise<KalshiMarketRow[]> {
+  const all: KalshiMarketRow[] = [];
+  let cursor: string | undefined;
+  const cap = opts.maxMarkets ?? 5000;
+  for (let i = 0; i < MAX_PAGES; i++) {
+    const page = await searchKalshiMarkets({
+      q: opts.q,
+      category: opts.category,
+      series_ticker: opts.series_ticker,
+      min_volume_24h: opts.min_volume_24h,
+      close_before: opts.close_before,
+      limit: UNIVERSE_PAGE_LIMIT,
+      cursor,
+    });
+    all.push(...page.data);
+    if (all.length >= cap || !page.has_more || !page.next_cursor) break;
+    cursor = page.next_cursor;
+  }
+  return all;
+}
+
+// ─── Handlers ───────────────────────────────────────────────────────────────
+
+export type SeriesResult =
+  | { kind: 'list'; data: SeriesRollup[]; total_markets: number }
+  | { kind: 'server-list'; data: SeriesRollupRow[]; has_more: boolean }
+  | { kind: 'detail'; series_ticker: string; rollup: SeriesRollup; markets: KalshiMarketRow[] }
+  | { kind: 'candles'; series_ticker: string; tickers_used: string[]; data: BasketCandlesResponse }
+  | { kind: 'events'; series_ticker: string; data: SeriesEventRow[]; has_more: boolean };
+
+export async function handleSeries(args: ParsedArgs): Promise<CLIResponse<SeriesResult>> {
+  try {
+    const positional = args.positionalArgs[0]?.toLowerCase();
+
+    // series candles <ticker> [--timeframe]
+    if (positional === 'candles') {
+      const seriesTicker = (args.positionalArgs[1] ?? args.seriesTicker)?.toUpperCase();
+      if (!seriesTicker) {
+        return wrapError('series', 'MISSING_SERIES', 'Usage: series candles <series_ticker> [--timeframe 1y]');
+      }
+      // Server-side prefix match — replaces the old paginate-then-filter dance.
+      const topN = args.topK ?? 20;
+      const page = await searchKalshiMarkets({
+        series_prefix: seriesTicker,
+        sort_by: 'volume_24h',
+        limit: topN,
+      });
+      if (page.data.length === 0) {
+        return wrapError('series', 'EMPTY_SERIES', `No markets found for series ${seriesTicker}`);
+      }
+      const tickers = page.data.map((m) => m.market_ticker);
+      const data = await getBasketCandles({ market_tickers: tickers, timeframe: args.timeframe });
+      return wrapSuccess('series', { kind: 'candles', series_ticker: seriesTicker, tickers_used: tickers, data });
+    }
+
+    // series events <ticker> — list events in a series (new endpoint)
+    if (positional === 'events') {
+      const seriesTicker = (args.positionalArgs[1] ?? args.seriesTicker)?.toUpperCase();
+      if (!seriesTicker) {
+        return wrapError('series', 'MISSING_SERIES', 'Usage: series events <series_ticker> [--limit N] [-q "filter"]');
+      }
+      const resp = await getSeriesEvents(seriesTicker, { limit: args.limit, q: args.query });
+      return wrapSuccess('series', {
+        kind: 'events', series_ticker: seriesTicker, data: resp.data, has_more: !!resp.has_more,
+      });
+    }
+
+    // series search <query> [--min-volume N] — keyword search rolled up by series
+    if (positional === 'search') {
+      const q = args.positionalArgs.slice(1).join(' ');
+      if (!q) {
+        return wrapError('series', 'MISSING_QUERY', 'Usage: series search <query>');
+      }
+      const markets = await fetchUniverse({ q, min_volume_24h: args.minVolume });
+      const rollups = rollupBySeries(markets).sort((a, b) => b.total_volume_24h - a.total_volume_24h);
+      const limited = rollups.slice(0, args.limit ?? 30);
+      return wrapSuccess('series', { kind: 'list', data: limited, total_markets: markets.length });
+    }
+
+    // series <SERIES_TICKER> — drill into one series (server-side prefix match)
+    if (args.positionalArgs[0] && args.positionalArgs[0].toUpperCase().startsWith('KX')) {
+      const seriesTicker = args.positionalArgs[0].toUpperCase();
+      const limit = args.limit ?? 30;
+      const page = await searchKalshiMarkets({
+        series_prefix: seriesTicker,
+        sort_by: 'volume_24h',
+        limit,
+      });
+      if (page.data.length === 0) {
+        return wrapError('series', 'EMPTY_SERIES', `No markets found for series ${seriesTicker}`);
+      }
+      const rollup = rollupBySeries(page.data)[0];
+      return wrapSuccess('series', {
+        kind: 'detail', series_ticker: seriesTicker, rollup, markets: page.data,
+      });
+    }
+
+    // series list [--category C] [--min-volume N] [--limit N] [--series-prefix KX]
+    // Uses the new server-side /kalshi/series rollup endpoint — 1 call vs paginated reduce.
+    const serverPage = await listKalshiSeries({
+      series_prefix: args.seriesTicker,
+      category: args.category,
+      min_volume_24h: args.minVolume,
+      sort_by: 'total_volume_24h',
+      limit: args.limit ?? 50,
+    });
+    return wrapSuccess('series', {
+      kind: 'server-list', data: serverPage.data, has_more: !!serverPage.has_more,
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('series', 'OCTAGON_ERROR', message);
+  }
+}
+
+// ─── Formatters ─────────────────────────────────────────────────────────────
+
+export function formatSeriesHuman(result: SeriesResult): string {
+  if (result.kind === 'list') return formatSeriesList(result.data, result.total_markets);
+  if (result.kind === 'server-list') return formatServerSeriesList(result.data, result.has_more);
+  if (result.kind === 'detail') return formatSeriesDetail(result.series_ticker, result.rollup, result.markets);
+  if (result.kind === 'events') return formatSeriesEvents(result.series_ticker, result.data, result.has_more);
+  return formatSeriesCandles(result.series_ticker, result.tickers_used, result.data);
+}
+
+function formatServerSeriesList(rows: SeriesRollupRow[], hasMore: boolean): string {
+  const lines: string[] = [];
+  const more = hasMore ? ' (more available)' : '';
+  lines.push(`Series rollup — ${rows.length} series${more}, sorted by 24h volume (server-side)`);
+  lines.push('');
+  if (rows.length === 0) {
+    lines.push('No series match.');
+    return lines.join('\n');
+  }
+  const tableRows: string[][] = rows.map((r) => [
+    r.series_ticker,
+    truncate(r.series_title ?? r.dominant_category ?? '-', 30),
+    String(r.active_count),
+    String(r.market_count),
+    fmtVol(r.total_volume_24h),
+    r.dominant_category ?? '-',
+    (r.last_seen_at ?? '').slice(0, 10),
+  ]);
+  lines.push(formatTable(
+    ['Series', 'Title / Category', 'Active', 'Total', '24h Vol', 'Dom Cat', 'Last seen'],
+    tableRows,
+  ));
+  lines.push('');
+  lines.push('Use "series <SERIES>" to drill in, "series events <SERIES>" to see events, "series candles <SERIES>" for NAV.');
+  return lines.join('\n');
+}
+
+function formatSeriesEvents(seriesTicker: string, events: SeriesEventRow[], hasMore: boolean): string {
+  const lines: string[] = [];
+  const more = hasMore ? ' (more available)' : '';
+  lines.push(`Events in series ${seriesTicker} — ${events.length} shown${more}`);
+  lines.push('');
+  if (events.length === 0) {
+    lines.push('No events in this series.');
+    return lines.join('\n');
+  }
+  const rows: string[][] = events.map((e) => [
+    e.event_ticker,
+    truncate(e.title ?? '', 45),
+    e.category ?? '-',
+    (e.close_time ?? '').slice(0, 10) || '-',
+    e.has_report ? '✓' : '-',
+  ]);
+  lines.push(formatTable(['Event', 'Title', 'Category', 'Closes', 'Report'], rows));
+  return lines.join('\n');
+}
+
+function formatSeriesList(rollups: SeriesRollup[], totalMarkets: number): string {
+  const lines: string[] = [];
+  lines.push(`Series rollup — ${rollups.length} series across ${totalMarkets} markets, sorted by 24h volume`);
+  lines.push('');
+  if (rollups.length === 0) {
+    lines.push('No series match.');
+    return lines.join('\n');
+  }
+  const rows: string[][] = rollups.map((r) => [
+    r.series_ticker,
+    truncate(r.sample_titles[0] ?? '-', 40),
+    String(r.active_count),
+    String(r.market_count),
+    fmtVol(r.total_volume_24h),
+    fmtVol(r.total_open_interest),
+    r.dominant_category ?? '-',
+    (r.earliest_close ?? '').slice(0, 10),
+  ]);
+  lines.push(formatTable(
+    ['Series', 'Sample title', 'Active', 'Total', '24h Vol', 'OI', 'Category', 'Earliest close'],
+    rows,
+  ));
+  lines.push('');
+  lines.push('Use "series <SERIES>" to drill in, "series candles <SERIES>" for theme NAV.');
+  return lines.join('\n');
+}
+
+function formatSeriesDetail(seriesTicker: string, rollup: SeriesRollup, markets: KalshiMarketRow[]): string {
+  const lines: string[] = [];
+  lines.push(`Series ${seriesTicker} — ${rollup.active_count}/${rollup.market_count} active, $${rollup.total_volume_24h.toFixed(0)} 24h vol`);
+  lines.push(`  Category    ${rollup.dominant_category ?? '-'}`);
+  lines.push(`  Close range ${(rollup.earliest_close ?? '-').slice(0, 10)}  →  ${(rollup.latest_close ?? '-').slice(0, 10)}`);
+  lines.push('');
+  if (markets.length === 0) {
+    lines.push('No sub-markets.');
+    return lines.join('\n');
+  }
+  const rows: string[][] = markets.map((m) => [
+    m.market_ticker,
+    truncate(m.title, 38),
+    m.status,
+    fmtMoney(m.last_price ?? m.yes_ask),
+    fmtVol(m.volume_24h),
+    (m.close_time ?? '').slice(0, 10),
+  ]);
+  lines.push(formatTable(['Market', 'Title', 'Status', 'Last', '24h Vol', 'Closes'], rows));
+  return lines.join('\n');
+}
+
+function formatSeriesCandles(seriesTicker: string, tickers: string[], data: BasketCandlesResponse): string {
+  const lines: string[] = [];
+  lines.push(`Series ${seriesTicker} NAV — ${data.timeframe} window, ${data.candles.length} bins, basket of top ${tickers.length} sub-markets`);
+  if (data.missing.length > 0) {
+    lines.push(`  Excluded (no candle history): ${data.missing.length}`);
+  }
+  lines.push('');
+  if (data.candles.length === 0) {
+    lines.push('No candles available.');
+    return lines.join('\n');
+  }
+  const recent = data.candles.slice(-10);
+  const rows: string[][] = recent.map((c) => [
+    new Date(c.time * 1000).toISOString().slice(0, 16).replace('T', ' '),
+    c.open.toFixed(3),
+    c.high.toFixed(3),
+    c.low.toFixed(3),
+    c.close.toFixed(3),
+  ]);
+  lines.push(formatTable(['Time (UTC)', 'Open', 'High', 'Low', 'Close'], rows));
+  if (data.candles.length > recent.length) {
+    lines.push('');
+    lines.push(`(showing last ${recent.length} of ${data.candles.length} bins — use --json for all)`);
+  }
+  return lines.join('\n');
+}
+
+// Exposed so theme commands can reuse the rollup + universe fetcher
+export { fetchUniverse, rollupBySeries };

package/src/commands/similar.ts

@@ -0,0 +1,97 @@
+import { wrapSuccess, wrapError } from './json.js';
+import type { CLIResponse } from './json.js';
+import type { ParsedArgs } from './parse-args.js';
+import { findSimilarMarkets, type SimilarResponse, type SimilarMarketRow } from '../scan/octagon-kalshi-api.js';
+import { formatTable } from './scan-formatters.js';
+
+function truncate(s: string, max: number): string {
+  return s.length > max ? s.slice(0, max - 1) + '…' : s;
+}
+
+function fmtMoney(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  return `$${v.toFixed(2)}`;
+}
+
+function fmtVol(v: number | null | undefined): string {
+  if (v === null || v === undefined) return '-';
+  if (v >= 1_000_000) return `${(v / 1_000_000).toFixed(1)}M`;
+  if (v >= 1_000) return `${(v / 1_000).toFixed(1)}k`;
+  return v.toFixed(0);
+}
+
+function looksLikeTicker(s: string): boolean {
+  // Kalshi tickers are uppercase with hyphens, digits, no spaces. Anything with
+  // a space or lowercase letter is treated as a free-text query.
+  return /^[A-Z0-9._-]+$/i.test(s) && /[A-Z]/i.test(s) && s.includes('-');
+}
+
+export async function handleSimilar(args: ParsedArgs): Promise<CLIResponse<SimilarResponse>> {
+  const positional = args.positionalArgs.join(' ').trim();
+  let anchorTicker = args.ticker;
+  let q = args.query;
+
+  if (!anchorTicker && !q && positional) {
+    // Single-token uppercase-ish string with a hyphen → treat as ticker, else as query.
+    if (looksLikeTicker(positional)) {
+      anchorTicker = positional.toUpperCase();
+    } else {
+      q = positional;
+    }
+  }
+
+  if (!anchorTicker && !q) {
+    return wrapError('similar', 'MISSING_ANCHOR', 'Usage: similar <ticker> | similar -q "query text" [--top-k N] [--category C] [--min-volume N] [--close-before ISO]');
+  }
+  if (anchorTicker && q) {
+    return wrapError('similar', 'AMBIGUOUS_ANCHOR', 'Pass either a ticker or -q "query", not both.');
+  }
+
+  try {
+    const data = await findSimilarMarkets({
+      anchor_ticker: anchorTicker,
+      q,
+      top_k: args.topK,
+      category: args.category,
+      min_volume_24h: args.minVolume,
+      close_before: args.closeBefore,
+    });
+    return wrapSuccess('similar', data);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return wrapError('similar', 'OCTAGON_ERROR', message);
+  }
+}
+
+export function formatSimilarHuman(data: SimilarResponse): string {
+  const lines: string[] = [];
+  const anchor = data.anchor_ticker
+    ? `ticker ${data.anchor_ticker}`
+    : data.anchor_query
+      ? `query "${data.anchor_query}"`
+      : 'unknown anchor';
+  lines.push(`Markets similar to ${anchor} — ${data.data.length} result(s)`);
+  lines.push('');
+
+  if (data.data.length === 0) {
+    lines.push('No similar markets found.');
+    return lines.join('\n');
+  }
+
+  const rows: string[][] = data.data.map((m: SimilarMarketRow) => [
+    m.market_ticker,
+    truncate(m.title, 40),
+    m.distance.toFixed(3),
+    fmtMoney(m.last_price ?? m.yes_ask),
+    fmtVol(m.volume_24h),
+    m.category ?? '-',
+  ]);
+
+  lines.push(formatTable(
+    ['Ticker', 'Title', 'Distance', 'Last', '24h Vol', 'Category'],
+    rows,
+  ));
+  lines.push('');
+  lines.push('Lower distance = closer cosine similarity.');
+  return lines.join('\n');
+}

package/src/components/intro.ts

@@ -68,6 +68,15 @@ export class IntroComponent extends Container {
     this.addChild(new Spacer(1));
     const cmd = (label: string) => theme.muted(label.padEnd(11));
     this.addChild(new Text(cmd('/search') + 'Search events by theme, ticker, or free-text; /search edge for edge scan', 0, 0));
+    this.addChild(new Text(cmd('/similar') + '<ticker|"text">  Semantic neighbors (Octagon embeddings)', 0, 0));
+    this.addChild(new Text(cmd('/clusters') + '[--ranked|--behavioral]  Browse thematic & behavioral clusters', 0, 0));
+    this.addChild(new Text(cmd('/peers') + '<ticker>  Markets in the same cluster', 0, 0));
+    this.addChild(new Text(cmd('/events') + '[ticker]  Octagon events + outcome ladder', 0, 0));
+    this.addChild(new Text(cmd('/series') + '[ticker]  Series rollup; /series candles <SERIES> for NAV', 0, 0));
+    this.addChild(new Text(cmd('/themes') + 'list|show|report|audit|overlap  Editorial narrative registry', 0, 0));
+    this.addChild(new Text(cmd('/catalysts') + 'upcoming --days N  Markets closing soon, grouped by week', 0, 0));
+    this.addChild(new Text(cmd('/correlate') + '<t1> <t2> [...]  Pairwise correlation matrix', 0, 0));
+    this.addChild(new Text(cmd('/basket') + 'build|backtest|size|candles|validate  Diversified basket tools', 0, 0));
     this.addChild(new Text(cmd('/portfolio') + 'Overview, positions, orders, balance, status', 0, 0));
     this.addChild(new Text(cmd('/analyze') + '<ticker>  Full analysis: edge, research, Kelly sizing', 0, 0));
     this.addChild(new Text(cmd('/watch') + '<ticker>  Live price/orderbook feed', 0, 0));

package/src/db/editorial-themes.ts

@@ -0,0 +1,111 @@
+/**
+ * Editorial themes registry — user-curated narrative buckets (e.g. "AI Race
+ * Milestones", "Iran Escalation") that map to lists of Kalshi series. Distinct
+ * from the existing `themes` table (which holds Kalshi-API watch lists) and
+ * from Octagon's nightly k-means clusters (which are embedding-derived).
+ */
+import type { Database } from 'bun:sqlite';
+
+export interface EditorialThemeRow {
+  name: string;
+  description: string | null;
+  search_volume: number | null;
+  created_at: number;
+  updated_at: number;
+}
+
+export interface EditorialThemeWithSeries extends EditorialThemeRow {
+  series: string[];
+}
+
+export function listEditorialThemes(db: Database): EditorialThemeRow[] {
+  return db.query(
+    'SELECT name, description, search_volume, created_at, updated_at FROM editorial_themes ORDER BY name',
+  ).all() as EditorialThemeRow[];
+}
+
+export function getEditorialTheme(db: Database, name: string): EditorialThemeWithSeries | null {
+  const row = db.query(
+    'SELECT name, description, search_volume, created_at, updated_at FROM editorial_themes WHERE name = $name',
+  ).get({ $name: name }) as EditorialThemeRow | undefined;
+  if (!row) return null;
+  const series = db.query(
+    'SELECT series_ticker FROM editorial_theme_series WHERE theme_name = $name ORDER BY series_ticker',
+  ).all({ $name: name }) as Array<{ series_ticker: string }>;
+  return { ...row, series: series.map((s) => s.series_ticker) };
+}
+
+export function upsertEditorialTheme(
+  db: Database,
+  args: { name: string; description?: string | null; search_volume?: number | null },
+): void {
+  const now = Date.now();
+  db.query(
+    `INSERT INTO editorial_themes (name, description, search_volume, created_at, updated_at)
+     VALUES ($name, $description, $search_volume, $now, $now)
+     ON CONFLICT(name) DO UPDATE SET
+       description = COALESCE($description, description),
+       search_volume = COALESCE($search_volume, search_volume),
+       updated_at = $now`,
+  ).run({
+    $name: args.name,
+    $description: args.description ?? null,
+    $search_volume: args.search_volume ?? null,
+    $now: now,
+  });
+}
+
+export function deleteEditorialTheme(db: Database, name: string): boolean {
+  const before = (db.query('SELECT COUNT(*) as n FROM editorial_themes WHERE name = $name').get({ $name: name }) as { n: number }).n;
+  db.query('DELETE FROM editorial_themes WHERE name = $name').run({ $name: name });
+  return before > 0;
+}
+
+export function addSeriesToTheme(db: Database, themeName: string, seriesTickers: string[]): number {
+  const stmt = db.query(
+    `INSERT OR IGNORE INTO editorial_theme_series (theme_name, series_ticker) VALUES ($name, $series)`,
+  );
+  let added = 0;
+  for (const s of seriesTickers) {
+    const upper = s.trim().toUpperCase();
+    if (!upper) continue;
+    const changes = stmt.run({ $name: themeName, $series: upper });
+    if (changes.changes > 0) added += 1;
+  }
+  return added;
+}
+
+export function removeSeriesFromTheme(db: Database, themeName: string, seriesTickers: string[]): number {
+  const stmt = db.query(
+    `DELETE FROM editorial_theme_series WHERE theme_name = $name AND series_ticker = $series`,
+  );
+  let removed = 0;
+  for (const s of seriesTickers) {
+    const upper = s.trim().toUpperCase();
+    const changes = stmt.run({ $name: themeName, $series: upper });
+    removed += changes.changes;
+  }
+  return removed;
+}
+
+export function setSearchVolume(db: Database, themeName: string, volume: number): boolean {
+  const result = db.query(
+    `UPDATE editorial_themes SET search_volume = $vol, updated_at = $now WHERE name = $name`,
+  ).run({ $name: themeName, $vol: volume, $now: Date.now() });
+  return result.changes > 0;
+}
+
+/**
+ * Returns series tickers that appear in more than one theme. Useful for
+ * cross-theme dedupe audits.
+ */
+export function findSeriesOverlaps(db: Database): Array<{ series_ticker: string; themes: string[] }> {
+  const rows = db.query(
+    `SELECT series_ticker, GROUP_CONCAT(theme_name, '|') as themes_csv
+     FROM editorial_theme_series
+     GROUP BY series_ticker
+     HAVING COUNT(*) > 1
+     ORDER BY series_ticker`,
+  ).all() as Array<{ series_ticker: string; themes_csv: string }>;
+  return rows.map((r) => ({ series_ticker: r.series_ticker, themes: r.themes_csv.split('|') }));
+}