kalshi-trading-bot-cli 2.1.0

package/src/gateway/sessions/store.ts

@@ -0,0 +1,65 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { appPath } from '../../utils/paths.js';
+
+export type SessionEntry = {
+  sessionKey: string;
+  createdAt: number;
+  updatedAt: number;
+  lastChannel?: string;
+  lastTo?: string;
+  lastAccountId?: string;
+  lastAgentId?: string;
+};
+
+export type SessionStore = Record<string, SessionEntry>;
+
+export function resolveSessionStorePath(agentId: string): string {
+  const base = process.env.APP_SESSIONS_DIR ?? appPath('sessions');
+  return join(base, agentId, 'sessions.json');
+}
+
+export function loadSessionStore(path: string): SessionStore {
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as SessionStore;
+  } catch {
+    return {};
+  }
+}
+
+export function saveSessionStore(path: string, store: SessionStore): void {
+  const dir = dirname(path);
+  if (!existsSync(dir)) {
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(path, JSON.stringify(store, null, 2), 'utf8');
+}
+
+export function upsertSessionMeta(params: {
+  storePath: string;
+  sessionKey: string;
+  channel: string;
+  to: string;
+  accountId: string;
+  agentId: string;
+}): SessionEntry {
+  const store = loadSessionStore(params.storePath);
+  const existing = store[params.sessionKey];
+  const now = Date.now();
+  const next: SessionEntry = {
+    sessionKey: params.sessionKey,
+    createdAt: existing?.createdAt ?? now,
+    updatedAt: now,
+    lastChannel: params.channel,
+    lastTo: params.to,
+    lastAccountId: params.accountId,
+    lastAgentId: params.agentId,
+  };
+  store[params.sessionKey] = next;
+  saveSessionStore(params.storePath, store);
+  return next;
+}
+

package/src/gateway/types.ts

@@ -0,0 +1,11 @@
+export type InboundContext = {
+  channel: 'whatsapp';
+  accountId: string;
+  from: string;
+  to: string;
+  chatType: 'direct' | 'group';
+  body: string;
+  senderName?: string;
+  messageId?: string;
+};
+

package/src/gateway/utils.ts

@@ -0,0 +1,82 @@
+export function normalizeE164(number: string): string {
+  const withoutPrefix = number.replace(/^whatsapp:/, '').trim();
+  // Strip everything except digits; we deliberately ignore any number of leading '+'.
+  const digitsOnly = withoutPrefix.replace(/[^\d]/g, '');
+  if (!digitsOnly) {
+    return '+';
+  }
+  return `+${digitsOnly}`;
+}
+
+export function isSelfChatMode(
+  selfE164: string | null | undefined,
+  allowFrom?: Array<string | number> | null,
+): boolean {
+  if (!selfE164) {
+    return false;
+  }
+  if (!Array.isArray(allowFrom) || allowFrom.length === 0) {
+    return false;
+  }
+  const normalizedSelf = normalizeE164(selfE164);
+  return allowFrom.some((value) => {
+    if (value === '*') {
+      return false;
+    }
+    try {
+      return normalizeE164(String(value)) === normalizedSelf;
+    } catch {
+      return false;
+    }
+  });
+}
+
+/**
+ * Convert a phone number or JID to a WhatsApp JID suitable for sending messages.
+ * 
+ * - Strips 'whatsapp:' prefix if present
+ * - For JIDs with @s.whatsapp.net, strips device suffix (e.g., :0)
+ * - For group JIDs (@g.us), returns as-is
+ * - Otherwise, normalizes as E.164 and converts to @s.whatsapp.net format
+ */
+/**
+ * Clean up markdown for WhatsApp compatibility.
+ * - Converts `**text**` (markdown bold) to `*text*` (WhatsApp bold)
+ * - Merges adjacent bold sections to prevent literal asterisks showing
+ */
+export function cleanMarkdownForWhatsApp(text: string): string {
+  let result = text;
+  // Convert markdown bold (**text**) to WhatsApp bold (*text*)
+  result = result.replace(/\*\*([^*]+)\*\*/g, '*$1*');
+  // Merge adjacent bold sections: `*foo* *bar*` -> `*foo bar*`
+  result = result.replace(/\*([^*]+)\*\s+\*([^*]+)\*/g, '*$1 $2*');
+  return result;
+}
+
+export function toWhatsappJid(input: string): string {
+  const clean = input.replace(/^whatsapp:/, '').trim();
+  
+  // Handle group JIDs - return as-is
+  if (clean.endsWith('@g.us')) {
+    return clean;
+  }
+  
+  // Handle user JIDs with @s.whatsapp.net - strip device suffix if present
+  if (clean.includes('@s.whatsapp.net')) {
+    // Extract phone number, stripping device suffix like ":0"
+    const atIndex = clean.indexOf('@');
+    const localPart = clean.slice(0, atIndex);
+    // Strip device suffix (e.g., "15551234567:0" -> "15551234567")
+    const phone = localPart.includes(':') ? localPart.split(':')[0] : localPart;
+    return `${phone}@s.whatsapp.net`;
+  }
+  
+  // Handle other JIDs (like @lid) - return as-is
+  if (clean.includes('@')) {
+    return clean;
+  }
+  
+  // Phone number - normalize and convert
+  const digits = normalizeE164(clean).replace(/\D/g, '');
+  return `${digits}@s.whatsapp.net`;
+}

package/src/index.tsx

@@ -0,0 +1,30 @@
+#!/usr/bin/env bun
+// Side-effect import: env.ts performs the dotenv load against the canonical
+// ENV_PATH (~/.kalshi-bot/.env or CWD .env). Must run before any other module
+// reads process.env.
+import './utils/env.js';
+import { runCli } from './cli.js';
+import { parseArgs } from './commands/parse-args.js';
+import { dispatch } from './commands/dispatch.js';
+import { initTelemetry, trackEvent, shutdownTelemetry } from './utils/telemetry.js';
+import packageJson from '../package.json';
+
+const parsed = parseArgs();
+
+await initTelemetry();
+trackEvent('app_start', {
+  mode: parsed.subcommand === 'chat' || parsed.subcommand === 'init' ? 'tui' : 'cli',
+  command: parsed.subcommand,
+  version: packageJson.version,
+});
+
+if (parsed.subcommand === 'chat') {
+  await runCli();
+  await shutdownTelemetry();
+} else if (parsed.subcommand === 'init') {
+  await runCli({ forceSetup: true });
+  await shutdownTelemetry();
+} else {
+  await dispatch(parsed);
+  await shutdownTelemetry();
+}

package/src/model/llm.ts

@@ -0,0 +1,247 @@
+import { AIMessage } from '@langchain/core/messages';
+import { ChatOpenAI } from '@langchain/openai';
+import { ChatAnthropic } from '@langchain/anthropic';
+import { ChatGoogleGenerativeAI } from '@langchain/google-genai';
+import { ChatOllama } from '@langchain/ollama';
+import { ChatPromptTemplate } from '@langchain/core/prompts';
+import { SystemMessage, HumanMessage } from '@langchain/core/messages';
+import { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import { StructuredToolInterface } from '@langchain/core/tools';
+import { Runnable } from '@langchain/core/runnables';
+import { z } from 'zod';
+import { DEFAULT_SYSTEM_PROMPT } from '@/agent/prompts';
+import type { TokenUsage } from '@/agent/types';
+import { logger } from '@/utils';
+import { classifyError, isNonRetryableError } from '@/utils/errors';
+import { resolveProvider, getProviderById } from '@/providers';
+
+export const DEFAULT_PROVIDER = 'openai';
+export const DEFAULT_MODEL = process.env.DEFAULT_MODEL ?? 'gpt-5.4';
+
+/**
+ * Gets the fast model variant for the given provider.
+ * Falls back to the provided model if no fast variant is configured (e.g., Ollama).
+ */
+export function getFastModel(modelProvider: string, fallbackModel: string): string {
+  return getProviderById(modelProvider)?.fastModel ?? fallbackModel;
+}
+
+// Generic retry helper with exponential backoff
+async function withRetry<T>(fn: () => Promise<T>, provider: string, maxAttempts = 3): Promise<T> {
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (e) {
+      const message = e instanceof Error ? e.message : String(e);
+      const errorType = classifyError(message);
+      logger.error(`[${provider} API] ${errorType} error (attempt ${attempt + 1}/${maxAttempts}): ${message}`);
+
+      if (isNonRetryableError(message)) {
+        throw new Error(`[${provider} API] ${message}`);
+      }
+
+      if (attempt === maxAttempts - 1) {
+        throw new Error(`[${provider} API] ${message}`);
+      }
+      await new Promise((r) => setTimeout(r, 500 * 2 ** attempt));
+    }
+  }
+  throw new Error('Unreachable');
+}
+
+// Model provider configuration
+interface ModelOpts {
+  streaming: boolean;
+}
+
+type ModelFactory = (name: string, opts: ModelOpts) => BaseChatModel;
+
+function getApiKey(envVar: string): string {
+  const apiKey = process.env[envVar];
+  if (!apiKey) {
+    throw new Error(`[LLM] ${envVar} not found in environment variables`);
+  }
+  return apiKey;
+}
+
+// Factories keyed by provider id — prefix routing is handled by resolveProvider()
+const MODEL_FACTORIES: Record<string, ModelFactory> = {
+  anthropic: (name, opts) =>
+    new ChatAnthropic({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('ANTHROPIC_API_KEY'),
+    }),
+  google: (name, opts) =>
+    new ChatGoogleGenerativeAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('GOOGLE_API_KEY'),
+    }),
+  xai: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('XAI_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.x.ai/v1',
+      },
+    }),
+  openrouter: (name, opts) =>
+    new ChatOpenAI({
+      model: name.replace(/^openrouter:/, ''),
+      ...opts,
+      apiKey: getApiKey('OPENROUTER_API_KEY'),
+      configuration: {
+        baseURL: 'https://openrouter.ai/api/v1',
+      },
+    }),
+  moonshot: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('MOONSHOT_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.moonshot.cn/v1',
+      },
+    }),
+  deepseek: (name, opts) =>
+    new ChatOpenAI({
+      model: name,
+      ...opts,
+      apiKey: getApiKey('DEEPSEEK_API_KEY'),
+      configuration: {
+        baseURL: 'https://api.deepseek.com',
+      },
+    }),
+  ollama: (name, opts) =>
+    new ChatOllama({
+      model: name.replace(/^ollama:/, ''),
+      ...opts,
+      ...(process.env.OLLAMA_BASE_URL ? { baseUrl: process.env.OLLAMA_BASE_URL } : {}),
+    }),
+};
+
+const DEFAULT_FACTORY: ModelFactory = (name, opts) =>
+  new ChatOpenAI({
+    model: name,
+    ...opts,
+    apiKey: getApiKey('OPENAI_API_KEY'),
+  });
+
+export function getChatModel(
+  modelName: string = DEFAULT_MODEL,
+  streaming: boolean = false
+): BaseChatModel {
+  const opts: ModelOpts = { streaming };
+  const provider = resolveProvider(modelName);
+  const factory = MODEL_FACTORIES[provider.id] ?? DEFAULT_FACTORY;
+  return factory(modelName, opts);
+}
+
+interface CallLlmOptions {
+  model?: string;
+  systemPrompt?: string;
+  outputSchema?: z.ZodType<unknown>;
+  tools?: StructuredToolInterface[];
+  toolChoice?: 'required' | 'auto' | 'none';
+  signal?: AbortSignal;
+}
+
+export interface LlmResult {
+  response: AIMessage | string;
+  usage?: TokenUsage;
+}
+
+function extractUsage(result: unknown): TokenUsage | undefined {
+  if (!result || typeof result !== 'object') return undefined;
+  const msg = result as Record<string, unknown>;
+
+  const usageMetadata = msg.usage_metadata;
+  if (usageMetadata && typeof usageMetadata === 'object') {
+    const u = usageMetadata as Record<string, unknown>;
+    const input = typeof u.input_tokens === 'number' ? u.input_tokens : 0;
+    const output = typeof u.output_tokens === 'number' ? u.output_tokens : 0;
+    const total = typeof u.total_tokens === 'number' ? u.total_tokens : input + output;
+    return { inputTokens: input, outputTokens: output, totalTokens: total };
+  }
+
+  const responseMetadata = msg.response_metadata;
+  if (responseMetadata && typeof responseMetadata === 'object') {
+    const rm = responseMetadata as Record<string, unknown>;
+    if (rm.usage && typeof rm.usage === 'object') {
+      const u = rm.usage as Record<string, unknown>;
+      const input = typeof u.prompt_tokens === 'number' ? u.prompt_tokens : 0;
+      const output = typeof u.completion_tokens === 'number' ? u.completion_tokens : 0;
+      const total = typeof u.total_tokens === 'number' ? u.total_tokens : input + output;
+      return { inputTokens: input, outputTokens: output, totalTokens: total };
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Build messages with Anthropic cache_control on the system prompt.
+ * Marks the system prompt as ephemeral so Anthropic caches the prefix,
+ * reducing input token costs by ~90% on subsequent calls.
+ */
+function buildAnthropicMessages(systemPrompt: string, userPrompt: string) {
+  return [
+    new SystemMessage({
+      content: [
+        {
+          type: 'text' as const,
+          text: systemPrompt,
+          cache_control: { type: 'ephemeral' },
+        },
+      ],
+    }),
+    new HumanMessage(userPrompt),
+  ];
+}
+
+export async function callLlm(prompt: string, options: CallLlmOptions = {}): Promise<LlmResult> {
+  const { model = DEFAULT_MODEL, systemPrompt, outputSchema, tools, toolChoice, signal } = options;
+  const finalSystemPrompt = systemPrompt || DEFAULT_SYSTEM_PROMPT;
+
+  const llm = getChatModel(model, false);
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let runnable: Runnable<any, any> = llm;
+
+  if (outputSchema) {
+    runnable = llm.withStructuredOutput(outputSchema, { strict: false });
+  } else if (tools && tools.length > 0 && llm.bindTools) {
+    const provider = resolveProvider(model);
+    // Anthropic uses 'any' instead of 'required' for forced tool calling
+    const resolvedChoice = toolChoice === 'required' && provider.id === 'anthropic' ? 'any' : toolChoice;
+    runnable = resolvedChoice ? llm.bindTools(tools, { tool_choice: resolvedChoice }) : llm.bindTools(tools);
+  }
+
+  const invokeOpts = signal ? { signal } : undefined;
+  const provider = resolveProvider(model);
+  let result;
+
+  if (provider.id === 'anthropic') {
+    // Anthropic: use explicit messages with cache_control for prompt caching (~90% savings)
+    const messages = buildAnthropicMessages(finalSystemPrompt, prompt);
+    result = await withRetry(() => runnable.invoke(messages, invokeOpts), provider.displayName);
+  } else {
+    // Other providers: use ChatPromptTemplate (OpenAI/Gemini have automatic caching)
+    const promptTemplate = ChatPromptTemplate.fromMessages([
+      ['system', finalSystemPrompt],
+      ['user', '{prompt}'],
+    ]);
+    const chain = promptTemplate.pipe(runnable);
+    result = await withRetry(() => chain.invoke({ prompt }, invokeOpts), provider.displayName);
+  }
+  const usage = extractUsage(result);
+
+  // If no outputSchema and no tools, extract content from AIMessage
+  // When tools are provided, return the full AIMessage to preserve tool_calls
+  if (!outputSchema && !tools && result && typeof result === 'object' && 'content' in result) {
+    return { response: (result as { content: string }).content, usage };
+  }
+  return { response: result as AIMessage, usage };
+}

package/src/providers.ts

@@ -0,0 +1,94 @@
+/**
+ * Canonical provider registry — single source of truth for all provider metadata.
+ * When adding a new provider, add a single entry here; all other modules derive from this.
+ */
+
+export interface ProviderDef {
+  /** Slug used in config/settings (e.g., 'anthropic') */
+  id: string;
+  /** Human-readable name (e.g., 'Anthropic') */
+  displayName: string;
+  /** Model name prefix used for routing (e.g., 'claude-'). Empty string for default (OpenAI). */
+  modelPrefix: string;
+  /** Environment variable name for API key. Omit for local providers (e.g., Ollama). */
+  apiKeyEnvVar?: string;
+  /** Fast model variant for lightweight tasks like summarization. */
+  fastModel?: string;
+}
+
+export const PROVIDERS: ProviderDef[] = [
+  {
+    id: 'openai',
+    displayName: 'OpenAI',
+    modelPrefix: '',
+    apiKeyEnvVar: 'OPENAI_API_KEY',
+    fastModel: 'gpt-4.1',
+  },
+  {
+    id: 'anthropic',
+    displayName: 'Anthropic',
+    modelPrefix: 'claude-',
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+    fastModel: 'claude-haiku-4-5',
+  },
+  {
+    id: 'google',
+    displayName: 'Google',
+    modelPrefix: 'gemini-',
+    apiKeyEnvVar: 'GOOGLE_API_KEY',
+    fastModel: 'gemini-3-flash-preview',
+  },
+  {
+    id: 'xai',
+    displayName: 'xAI',
+    modelPrefix: 'grok-',
+    apiKeyEnvVar: 'XAI_API_KEY',
+    fastModel: 'grok-4-1-fast-reasoning',
+  },
+  {
+    id: 'moonshot',
+    displayName: 'Moonshot',
+    modelPrefix: 'kimi-',
+    apiKeyEnvVar: 'MOONSHOT_API_KEY',
+    fastModel: 'kimi-k2-5',
+  },
+  {
+    id: 'deepseek',
+    displayName: 'DeepSeek',
+    modelPrefix: 'deepseek-',
+    apiKeyEnvVar: 'DEEPSEEK_API_KEY',
+    fastModel: 'deepseek-chat',
+  },
+  {
+    id: 'openrouter',
+    displayName: 'OpenRouter',
+    modelPrefix: 'openrouter:',
+    apiKeyEnvVar: 'OPENROUTER_API_KEY',
+    fastModel: 'openrouter:openai/gpt-4o-mini',
+  },
+  {
+    id: 'ollama',
+    displayName: 'Ollama',
+    modelPrefix: 'ollama:',
+  },
+];
+
+const defaultProvider = PROVIDERS.find((p) => p.id === 'openai')!;
+
+/**
+ * Resolve the provider for a given model name based on its prefix.
+ * Falls back to OpenAI when no prefix matches.
+ */
+export function resolveProvider(modelName: string): ProviderDef {
+  return (
+    PROVIDERS.find((p) => p.modelPrefix && modelName.startsWith(p.modelPrefix)) ??
+    defaultProvider
+  );
+}
+
+/**
+ * Look up a provider by its slug (e.g., 'anthropic', 'google').
+ */
+export function getProviderById(id: string): ProviderDef | undefined {
+  return PROVIDERS.find((p) => p.id === id);
+}

package/src/risk/circuit-breaker.ts

@@ -0,0 +1,113 @@
+import type { Database } from 'bun:sqlite';
+import { fetchLiveBankroll } from './kelly.js';
+import { insertRiskSnapshot, getLatestSnapshot, getDrawdownHistory } from '../db/risk.js';
+import type { RiskSnapshot } from '../db/risk.js';
+
+export interface CircuitBreakerConfig {
+  dailyLossLimit?: number;  // cents, default 5000 ($50)
+  maxDrawdown?: number;     // fraction, default 0.20
+}
+
+export interface CircuitBreakerStatus {
+  active: boolean;
+  reason?: string;
+}
+
+export class CircuitBreaker {
+  private config: Required<CircuitBreakerConfig>;
+
+  constructor(config?: CircuitBreakerConfig) {
+    this.config = {
+      dailyLossLimit: config?.dailyLossLimit ?? 5000,
+      maxDrawdown: config?.maxDrawdown ?? 0.20,
+    };
+  }
+
+  /**
+   * Check if circuit breaker should be active.
+   * Reads latest risk snapshot — does not call external APIs.
+   */
+  check(db: Database): CircuitBreakerStatus {
+    const snapshot = getLatestSnapshot(db);
+    if (!snapshot) return { active: false };
+
+    // Check daily P&L loss limit
+    if (snapshot.daily_pnl != null && snapshot.daily_pnl < -this.config.dailyLossLimit) {
+      return {
+        active: true,
+        reason: `Daily P&L ${snapshot.daily_pnl} cents exceeds loss limit of -${this.config.dailyLossLimit} cents`,
+      };
+    }
+
+    // Check drawdown
+    if (snapshot.drawdown_current != null && snapshot.drawdown_current >= this.config.maxDrawdown) {
+      return {
+        active: true,
+        reason: `Drawdown ${(snapshot.drawdown_current * 100).toFixed(1)}% >= max ${this.config.maxDrawdown * 100}%`,
+      };
+    }
+
+    return { active: false };
+  }
+
+  /**
+   * Take a fresh snapshot: fetch live bankroll, compute drawdown vs
+   * portfolio high-water mark from risk_snapshots history, insert new snapshot.
+   */
+  async snapshot(db: Database): Promise<RiskSnapshot> {
+    const bankroll = await fetchLiveBankroll();
+
+    // Compute high-water mark from history
+    const dayAgo = Math.floor(Date.now() / 1000) - 86400;
+    const history = getDrawdownHistory(db, dayAgo);
+
+    let highWaterMark = bankroll.portfolioValue;
+    let dailyPnl = 0;
+
+    if (history.length > 0) {
+      // High-water mark is max portfolio_value across all snapshots
+      for (const h of history) {
+        if (h.portfolio_value != null && h.portfolio_value > highWaterMark) {
+          highWaterMark = h.portfolio_value;
+        }
+      }
+
+      // Daily P&L = current portfolio value - earliest snapshot's portfolio value in the window
+      const earliest = history[0];
+      if (earliest.portfolio_value != null) {
+        dailyPnl = bankroll.portfolioValue - earliest.portfolio_value;
+      }
+    }
+
+    // Drawdown = (high_water - current) / high_water
+    const drawdownCurrent = highWaterMark > 0
+      ? (highWaterMark - bankroll.portfolioValue) / highWaterMark
+      : 0;
+
+    // Max drawdown is the worst we've seen
+    const latestSnapshot = getLatestSnapshot(db);
+    const drawdownMax = Math.max(
+      drawdownCurrent,
+      latestSnapshot?.drawdown_max ?? 0
+    );
+
+    const now = Math.floor(Date.now() / 1000);
+    const cbStatus = this.check(db);
+
+    const snapshot: RiskSnapshot = {
+      timestamp: now,
+      cash_balance: bankroll.cashBalance,
+      portfolio_value: bankroll.portfolioValue,
+      open_exposure: bankroll.openExposure,
+      available_bankroll: bankroll.availableBankroll,
+      daily_pnl: dailyPnl,
+      drawdown_current: drawdownCurrent,
+      drawdown_max: drawdownMax,
+      positions_count: null, // caller can set if needed
+      circuit_breaker_on: cbStatus.active ? 1 : 0,
+    };
+
+    insertRiskSnapshot(db, snapshot);
+    return snapshot;
+  }
+}

package/src/risk/correlation.ts

@@ -0,0 +1,40 @@
+import type { Database } from 'bun:sqlite';
+
+/**
+ * Count open positions per event category by joining positions (status='open')
+ * with events on event_ticker.
+ */
+export function getCorrelationByCategory(db: Database): Map<string, number> {
+  const rows = db.query(`
+    SELECT e.category, COUNT(*) as cnt
+    FROM positions p
+    JOIN events e ON p.event_ticker = e.ticker
+    WHERE p.status = 'open' AND e.category IS NOT NULL
+    GROUP BY e.category
+  `).all() as Array<{ category: string; cnt: number }>;
+
+  const map = new Map<string, number>();
+  for (const row of rows) {
+    map.set(row.category, row.cnt);
+  }
+  return map;
+}
+
+/**
+ * Check if adding a position to the given event's category would exceed the limit.
+ */
+export function isCorrelated(
+  eventTicker: string,
+  db: Database,
+  maxPerCategory = 3
+): boolean {
+  const event = db.query('SELECT category FROM events WHERE ticker = $ticker').get({
+    $ticker: eventTicker,
+  }) as { category: string | null } | null;
+
+  if (!event?.category) return false;
+
+  const counts = getCorrelationByCategory(db);
+  const current = counts.get(event.category) ?? 0;
+  return current >= maxPerCategory;
+}