/**
 * SET 28a — one honest log line per LLM call: stage + purpose + candidate
 * position + attempt, with tokens ON the same line. Built once at the call
 * site that knows the real token counts (the client), so nothing downstream
 * needs to guess which event a usage record belongs to.
 *
 * Format: `llm call — <stage>: <purpose> [candidate n/K, t=<temp>, attempt m] (in→ / out← tok)`
 * The bracket and token suffix are each omitted when their inputs are absent
 * (e.g. the bracket is empty for a single, non-candidate, first-attempt draw).
 */
export interface LlmCallLogInput {
  stage: string;
  purpose: string;
  candidate?: { n: number; k: number };
  temp?: number;
  attempt?: number;
  attemptLabel?: 'attempt' | 'pass';
  inputTokens?: number;
  outputTokens?: number;
}

function fmtTok(n: number): string {
  return n.toLocaleString('en-US');
}

export function formatLlmCallEvent(rec: LlmCallLogInput): string {
  const bracket: string[] = [];
  if (rec.candidate) bracket.push(`candidate ${rec.candidate.n}/${rec.candidate.k}`);
  if (rec.temp != null) bracket.push(`t=${rec.temp}`);
  if (rec.attempt != null) bracket.push(`${rec.attemptLabel ?? 'attempt'} ${rec.attempt}`);
  const bracketStr = bracket.length ? ` [${bracket.join(', ')}]` : '';
  const tokStr = rec.inputTokens != null && rec.outputTokens != null
    ? ` (${fmtTok(rec.inputTokens)}→ / ${fmtTok(rec.outputTokens)}← tok)`
    : '';
  return `llm call — ${rec.stage}: ${rec.purpose}${bracketStr}${tokStr}`;
}
