@relayburn/sdk 1.8.0 → 1.10.0

package/CHANGELOG.md

@@ -4,12 +4,41 @@ All notable changes to `@relayburn/sdk`.
 
 ## [Unreleased]
 
+## [1.10.0] - 2026-05-03
+
+### Breaking Changes
+
+- `hotspots()` now returns a discriminated union (`{ kind: 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent' | 'findings' }`) instead of either an attribution blob or a raw findings array. Callers must branch on `kind`. The default (no `groupBy`, no `patterns`) returns the `attribution` shape that mirrors `burn hotspots --json`. Pass `patterns` to get `findings`. Pass `groupBy` to narrow attribution to one axis (`bash` / `bash-verb` / `file` / `subagent`). Warrants the SDK major bump.
+
+### Added
+
+- `hotspots({ groupBy })` narrows attribution to one aggregation axis: `bash`, `bash-verb`, `file`, or `subagent`. Useful for MCP tools and embedders that only want a single per-axis cut.
+- `hotspots({ project, since })` accept the same forwarded options the other SDK queries do (project filter + ISO/relative `since` window normalization).
+- `hotspots()` reads through the SQLite archive by default with transparent fallback to the JSONL ledger walk on archive failure. Pass `onLog` to capture the fallback reason.
+- `hotspots()` surfaces a coverage-refusal shape (`refused: true` + `refusalReason`) when every matched turn lacks the tool-call/tool-result coverage `attributeHotspots` needs, so presenters can map it to the user-facing exit-2 + stderr message.
+
+## [1.9.0] - 2026-05-03
+
+### Added
+
+- `compare({ models, … })` returns the per-(model, activity) `CompareResult` shape (`analyzedTurns`, `models`, `categories`, `totals`, flat `cells[]`, `fidelity { minimum, excluded, summary }`) — the JSON object `burn compare --json` now emits. Mirrors the CLI's archive-vs-ledger branching: archive when `minFidelity === 'partial'` and no provider filter, ledger walk otherwise. Falls back transparently to the ledger walk when the archive read fails.
+- `sessionCost({ session })` returns the compact per-session cost shape (`totalUSD`, `totalTokens`, `turnCount`, `models`) the MCP `burn__sessionCost` tool now wraps directly.
+- `summary()` result now includes `turnCount`.
+- `summary()` and `sessionCost()` read through the SQLite archive by default with transparent fallback to the JSONL ledger walk on archive failure. Pass `onLog` to capture the fallback reason.
+- `overhead({ project, since?, kind? })` returns per-file + per-section overhead cost attribution (the JSON shape `burn overhead --json` now consumes).
+- `overheadTrim({ project, since?, kind?, top?, includeDiff? })` returns trim recommendations with projected savings and (by default) embedded unified diffs (the JSON shape `burn overhead trim --json` now consumes). Pass `includeDiff: false` to skip the per-file disk reads.
+- `summary({ since })` and `overhead({ since })` / `overheadTrim({ since })` now accept either an ISO timestamp or a relative range (`24h`, `7d`, `4w`, `2m`); the SDK normalizes both forms before querying the ledger so direct SDK callers get the same forgiving input shape CLI users have. Previously a raw relative string would silently filter out every turn.
+
 ## [1.7.0] - 2026-05-02
 
 ### Added
 
 - `hotspots({ patterns })` now also surfaces `tool-output-bloat`, `ghost-surface`, and `tool-call-pattern` findings (previously only the core `detectPatterns` set). Each side-channel detector loads its own inputs (Claude settings, tool-result events, on-disk surface) lazily based on the requested patterns.
 
+### Changed
+
+- SDK no longer depends on `@relayburn/cli`. `ingest()` now imports from the new `@relayburn/ingest` package, and `buildGhostSurfaceInputs` lives in `@relayburn/analyze`. The SDK's public surface is unchanged.
+
 ## [1.5.0] - 2026-05-01
 
 ### Added

package/README.md

@@ -1,12 +1,50 @@
 # @relayburn/sdk
 
-Embeddable Relayburn SDK for in-process ingestion and analysis.
+Embeddable Relayburn SDK for in-process ingestion and analysis. This package is the **source of truth** for the in-process query/compute surface — `@relayburn/mcp` and `@relayburn/cli` consume the SDK rather than duplicating its logic.
 
 ```ts
-import { Ledger, ingest, summary, hotspots } from '@relayburn/sdk';
+import {
+  Ledger,
+  ingest,
+  summary,
+  sessionCost,
+  compare,
+  overhead,
+  overheadTrim,
+  hotspots,
+} from '@relayburn/sdk';
 
 await Ledger.open({ home: '/tmp/relayburn-home' });
 await ingest({ ledgerHome: '/tmp/relayburn-home' });
+
+// Slice-wide rollup: turnCount + per-model + per-tool aggregates.
 const stats = await summary({ session: 'session-id', ledgerHome: '/tmp/relayburn-home' });
+
+// Compact session-scoped cost shape (totalUSD/totalTokens/turnCount/models).
+// Powers the MCP `burn__sessionCost` tool.
+const cost = await sessionCost({ session: 'session-id' });
+
+// Per-(model, activity) comparison shape — the JSON object `burn compare --json` emits.
+const cmp = await compare({
+  models: ['claude-sonnet-4-6', 'claude-haiku-4-5'],
+  since: '30d',
+  minFidelity: 'usage-only',
+});
+
+// Overhead-file (CLAUDE.md / AGENTS.md / .claude/CLAUDE.md) cost attribution.
+const oh = await overhead({ project: '/path/to/repo', since: '30d' });
+const trim = await overheadTrim({ project: '/path/to/repo', top: 3 });
+
+// Per-axis hotspot attribution + pattern findings. Returns a discriminated
+// union — branch on `kind`:
+//   { kind: 'attribution', files, bashVerbs, bash, subagents, sessions, … }
+//   { kind: 'bash' | 'bash-verb' | 'file' | 'subagent', rows: [...] }
+//   { kind: 'findings', findings: WasteFinding[], summary }
+const attribution = await hotspots({ session: 'session-id' });
+const fileRows = await hotspots({ session: 'session-id', groupBy: 'file' });
 const findings = await hotspots({ session: 'session-id', patterns: ['retry-loop'] });
 ```
+
+`summary`, `sessionCost`, `compare`, `overhead`, `overheadTrim`, and `hotspots` read through the SQLite archive when available, transparently falling back to the JSONL ledger walk if the archive can't be opened. Pass `onLog` to surface fallback messages in your host's log channel.
+
+`overheadTrim` includes a unified-diff string per recommendation by default (matches `burn overhead trim --json`); pass `includeDiff: false` to skip the per-file disk reads when you only need the recommendation rows.

package/index.d.ts

@@ -4,11 +4,155 @@ export declare class Ledger { static open(opts?: LedgerOpenOptions): Promise<Led
 export interface IngestOptions { sessionId?: string; harness?: 'claude-code'|'codex'|'opencode'; ledgerHome?: string }
 export declare function ingest(opts?: IngestOptions): Promise<unknown>
 
-export interface SummaryOptions { session?: string; project?: string; since?: string; ledgerHome?: string }
-export declare function summary(opts?: SummaryOptions): Promise<{ totalTokens: number; totalCost: number; byTool: Array<{tool:string;tokens:number;cost:number;count:number}>; byModel: Array<{model:string;tokens:number;cost:number}> }>
+export interface SummaryOptions {
+  session?: string;
+  project?: string;
+  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
+  since?: string;
+  ledgerHome?: string;
+  /** Optional logger invoked when the SQLite archive read fails and the SDK falls back to a full ledger walk. */
+  onLog?: (msg: string) => void;
+}
+export declare function summary(opts?: SummaryOptions): Promise<{
+  totalTokens: number;
+  totalCost: number;
+  turnCount: number;
+  byTool: Array<{ tool: string; tokens: number; cost: number; count: number }>;
+  byModel: Array<{ model: string; tokens: number; cost: number }>;
+}>
+
+export interface SessionCostOptions {
+  /** Session id to total. Omit for `{ note: 'no session id provided' }`. */
+  session?: string;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+export interface SessionCostResult {
+  sessionId: string | null;
+  totalUSD: number;
+  totalTokens: number;
+  turnCount: number;
+  models: string[];
+  note?: string;
+}
+/** Compact session-scoped cost shape; powers the MCP `burn__sessionCost` tool. */
+export declare function sessionCost(opts?: SessionCostOptions): Promise<SessionCostResult>
+
+export type OverheadFileKind = 'claude-md' | 'agents-md';
+export type OverheadHarness = 'claude-code' | 'codex' | 'opencode';
+
+export interface OverheadOptions {
+  /** Project path to inspect; defaults to process.cwd(). */
+  project?: string;
+  /** ISO timestamp or relative range (`24h`, `7d`, `4w`, `2m`); the SDK normalizes both forms before querying. */
+  since?: string;
+  /** Narrow to a single overhead file kind. */
+  kind?: OverheadFileKind;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+
+export interface OverheadSection {
+  heading: string;
+  startLine: number;
+  endLine: number;
+  tokens: number;
+}
+
+export interface OverheadSectionCost {
+  filePath: string;
+  section: OverheadSection;
+  tokenShare: number;
+  costPerSession: number;
+  totalCost: number;
+}
+
+export interface OverheadAttributionDetail {
+  sessionCount: number;
+  perSessionAvg: number;
+  perSessionP95: number;
+  totalCost: number;
+  sectionCosts: OverheadSectionCost[];
+}
+
+export interface OverheadFileSummary {
+  kind: OverheadFileKind;
+  path: string;
+  appliesTo: OverheadHarness[];
+  totalLines: number;
+  bytes: number;
+  tokens: number;
+  sections: OverheadSection[];
+  groupingLevel: number;
+}
+
+export interface OverheadPerFileEntry {
+  path: string;
+  kind: OverheadFileKind;
+  appliesTo: OverheadHarness[];
+  attribution: OverheadAttributionDetail;
+}
+
+export interface OverheadResult {
+  project: string;
+  files: OverheadFileSummary[];
+  perFile: OverheadPerFileEntry[];
+  grandTotal: number;
+}
+
+/** Per-file + per-section overhead cost attribution. Powers `burn overhead`. */
+export declare function overhead(opts?: OverheadOptions): Promise<OverheadResult>
+
+export interface OverheadTrimOptions extends OverheadOptions {
+  /** Recommendations per file. Default 3. */
+  top?: number;
+  /** Include the unified-diff text per recommendation (requires a file read per recommended file). Default true; pass false to skip. */
+  includeDiff?: boolean;
+}
+
+export interface OverheadTrimRecommendation {
+  file: string;
+  kind: OverheadFileKind;
+  appliesTo: OverheadHarness[];
+  section: { heading: string; startLine: number; endLine: number; tokens: number };
+  projectedSavings: {
+    perSessionUsd: number;
+    acrossWindowUsd: number;
+    tokens: number;
+    tokenShare: number;
+  };
+  diff?: string;
+}
+
+export interface OverheadTrimResult {
+  project: string;
+  since: string;
+  recommendations: OverheadTrimRecommendation[];
+  summary: {
+    filesAnalyzed: number;
+    filesWithRecommendations: number;
+    totalRecommendations: number;
+    totalProjectedSavingsPerSession: number;
+    totalProjectedSavingsAcrossWindow: number;
+  };
+}
+
+/** Trim recommendations for high-cost overhead-file sections. Powers `burn overhead trim`. */
+export declare function overheadTrim(opts?: OverheadTrimOptions): Promise<OverheadTrimResult>
+
+export type HotspotsGroupBy = 'attribution' | 'bash' | 'bash-verb' | 'file' | 'subagent';
 
 export interface HotspotsOptions {
   session?: string;
+  project?: string;
+  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
+  since?: string;
+  /**
+   * Narrow the attribution result to a single aggregation axis. When omitted
+   * (or `'attribution'`), the full attribution shape is returned. Ignored
+   * when `patterns` is set — patterns always returns the `findings` shape.
+   */
+  groupBy?: HotspotsGroupBy;
   /**
    * Pattern kinds to detect. Supported kinds:
    *   - core (via `detectPatterns`): `retry-loop`, `failure-run`,
@@ -16,10 +160,199 @@ export interface HotspotsOptions {
    *     `skill-recall-dup`, `skill-pruning-protection`, `system-prompt-tax`
    *   - side-channel: `tool-output-bloat`, `ghost-surface`, `tool-call-pattern`
    *
-   * When omitted or empty, returns the attribution result instead of a
-   * findings array.
+   * When omitted or empty, returns the attribution result instead of the
+   * findings shape.
    */
   patterns?: string[];
   ledgerHome?: string;
+  /** Optional logger invoked when the SQLite archive read fails and the SDK falls back to a full ledger walk. */
+  onLog?: (msg: string) => void;
 }
-export declare function hotspots(opts?: HotspotsOptions): Promise<unknown>
+
+/** Per-axis aggregation row (file). */
+export interface HotspotsFileRow {
+  path: string;
+  firstEmitTurnIndex: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  ridingTurns: number;
+  totalCost: number;
+}
+
+/** Per-axis aggregation row (bash, exact command). */
+export interface HotspotsBashRow {
+  command: string | undefined;
+  argsHash: string;
+  callCount: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  totalCost: number;
+}
+
+/** Per-axis aggregation row (bash, by leading verb). */
+export interface HotspotsBashVerbRow {
+  verb: string;
+  callCount: number;
+  distinctCommands: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  avgPersistenceTurns: number;
+  totalCost: number;
+  topExamples: string[];
+}
+
+/** Per-axis aggregation row (subagent / Agent / Task). */
+export interface HotspotsSubagentRow {
+  subagentType: string;
+  callCount: number;
+  initialTokens: number;
+  persistenceTokens: number;
+  totalCost: number;
+}
+
+export interface HotspotsSessionTotal {
+  sessionId: string;
+  grandCost: number;
+  attributedCost: number;
+  unattributedCost: number;
+  attributionMethod: 'sized' | 'even-split';
+}
+
+export interface HotspotsFidelityBlock {
+  analyzed: number;
+  excluded: number;
+  /** Aggregate fidelity summary for the matched-window turns (analyzed + excluded). */
+  summary: unknown;
+  refused: boolean;
+}
+
+/** Full attribution shape — mirrors the CLI's `burn hotspots --json`. */
+export interface HotspotsAttributionResult {
+  kind: 'attribution';
+  turnsAnalyzed: number;
+  grandTotal: number;
+  attributedTotal: number;
+  unattributedTotal: number;
+  attributionDegraded: boolean;
+  sessions: HotspotsSessionTotal[];
+  files: HotspotsFileRow[];
+  bashVerbs: HotspotsBashVerbRow[];
+  bash: HotspotsBashRow[];
+  subagents: HotspotsSubagentRow[];
+  fidelity: HotspotsFidelityBlock;
+  /** Set when every matched turn lacked the coverage attribution needs. */
+  refused?: boolean;
+  refusalReason?: string;
+}
+
+/** Narrowed shapes — one aggregation axis only. */
+export interface HotspotsBashResult { kind: 'bash'; rows: HotspotsBashRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsBashVerbResult { kind: 'bash-verb'; rows: HotspotsBashVerbRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsFileResult { kind: 'file'; rows: HotspotsFileRow[]; refused?: boolean; refusalReason?: string }
+export interface HotspotsSubagentResult { kind: 'subagent'; rows: HotspotsSubagentRow[]; refused?: boolean; refusalReason?: string }
+
+export interface HotspotsFinding {
+  kind: string;
+  severity: string;
+  sessionId: string;
+  title: string;
+  estimatedSavings: { usdPerSession?: number; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+export interface HotspotsFindingsResult {
+  kind: 'findings';
+  findings: HotspotsFinding[];
+  /** Aggregate fidelity summary for the matched-window turns. */
+  summary: unknown;
+}
+
+export type HotspotsResult =
+  | HotspotsAttributionResult
+  | HotspotsBashResult
+  | HotspotsBashVerbResult
+  | HotspotsFileResult
+  | HotspotsSubagentResult
+  | HotspotsFindingsResult;
+
+/**
+ * Per-axis hotspot attribution + pattern-finding queries. Returns a
+ * discriminated union — see `HotspotsResult`.
+ */
+export declare function hotspots(opts?: HotspotsOptions): Promise<HotspotsResult>
+
+export type FidelityClass = 'full' | 'usage-only' | 'aggregate-only' | 'cost-only' | 'partial';
+
+export interface FidelitySummaryShape {
+  total: number;
+  byClass: Record<FidelityClass, number>;
+  unknown: number;
+  missingCoverage: Record<string, number>;
+}
+
+export interface CompareExcludedBreakdown {
+  total: number;
+  aggregateOnly: number;
+  costOnly: number;
+  partial: number;
+  usageOnly: number;
+}
+
+export interface CompareCellResult {
+  model: string;
+  category: string;
+  turns: number;
+  editTurns: number;
+  oneShotTurns: number;
+  pricedTurns: number;
+  totalCost: number;
+  costPerTurn: number | null;
+  oneShotRate: number | null;
+  cacheHitRate: number | null;
+  medianRetries: number | null;
+  noData: boolean;
+  insufficientSample: boolean;
+}
+
+export interface CompareOptions {
+  /** Required: ≥2 model names to compare. */
+  models: string[];
+  session?: string;
+  project?: string;
+  /** ISO timestamp (e.g. `2026-04-01T00:00:00Z`) or relative range (`24h`, `7d`, `4w`, `2m`). */
+  since?: string;
+  workflow?: string;
+  agent?: string;
+  /** Resolved provider filter (e.g. `['anthropic', 'synthetic']`). */
+  provider?: string[];
+  /** Insufficient-sample threshold; cells below this get flagged. Default 5. */
+  minSample?: number;
+  /** Minimum fidelity class to include in the aggregate. Default `'usage-only'`. */
+  minFidelity?: FidelityClass;
+  ledgerHome?: string;
+  onLog?: (msg: string) => void;
+}
+
+export interface CompareResult {
+  analyzedTurns: number;
+  minSample: number;
+  models: string[];
+  categories: string[];
+  totals: Record<string, { turns: number; totalCost: number }>;
+  cells: CompareCellResult[];
+  fidelity: {
+    minimum: FidelityClass;
+    excluded: CompareExcludedBreakdown;
+    summary: FidelitySummaryShape;
+  };
+}
+
+/**
+ * Per-(model, activity) comparison shape. Powers `burn compare` and the
+ * future `burn__compare` MCP tool. Reads through the SQLite archive when
+ * `minFidelity === 'partial'` and no provider filter is set; otherwise
+ * walks the ledger so the fidelity gate / provider filter can be applied
+ * per-turn. Falls back transparently to the ledger walk when the archive
+ * read fails.
+ */
+export declare function compare(opts: CompareOptions): Promise<CompareResult>

package/index.js

@@ -1,21 +1,48 @@
-import { queryAll, queryUserTurns, queryToolResultEvents } from '@relayburn/ledger';
 import {
-  loadPricing,
+  buildArchive,
+  queryAll,
+  queryAllFromArchive,
+  queryTurnsFromArchive,
+  queryUserTurns,
+  queryToolResultEvents,
+} from '@relayburn/ledger';
+import {
+  aggregateByBash,
+  aggregateByBashVerb,
+  aggregateByFile,
+  aggregateBySubagent,
+  attributeOverhead,
+  buildCompareTable,
+  buildGhostSurfaceInputs,
+  buildTrimRecommendations,
+  compareFromArchive,
   costForTurn,
-  attributeHotspots,
+  DEFAULT_MIN_SAMPLE,
+  detectGhostSurface,
   detectPatterns,
-  findingsFromPatterns,
+  detectToolCallPatterns,
   detectToolOutputBloat,
-  toolOutputBloatToFinding,
-  detectGhostSurface,
+  filterTurnsByProvider,
+  findingsFromPatterns,
+  findOverheadFiles,
   ghostSurfaceToFinding,
-  detectToolCallPatterns,
-  toolCallPatternToFinding,
+  hasMinimumFidelity,
   loadClaudeSettings,
-  userClaudeSettingsPath,
+  loadOverheadFile,
+  loadPricing,
   projectClaudeSettingsPath,
+  renderUnifiedDiffForRecommendation,
+  summarizeFidelity,
+  sumCosts,
+  attributeHotspots,
+  toolCallPatternToFinding,
+  toolOutputBloatToFinding,
+  userClaudeSettingsPath,
 } from '@relayburn/analyze';
-import { ingestAll, buildGhostSurfaceInputs } from '@relayburn/cli';
+import { ingestAll } from '@relayburn/ingest';
+import { parseBashCommand, resolveProject } from '@relayburn/reader';
+import { readFile } from 'node:fs/promises';
+import * as path from 'node:path';
 
 function withHome(home, fn) {
   const prev = process.env.RELAYBURN_HOME;
@@ -28,6 +55,65 @@ function withHome(home, fn) {
   });
 }
 
+// Bring the SQLite archive current and query against it, falling back to a
+// full ledger walk if the archive can't be built or read. Mirrors the strategy
+// the CLI's loadTurns() uses so SDK consumers (and the MCP server, which now
+// calls through here) get the same hot-path performance without re-implementing
+// the fallback logic in every caller. `onLog` lets callers surface the
+// fallback reason; defaults to a no-op so library use stays quiet.
+async function loadTurnsViaArchive(q, onLog) {
+  try {
+    await buildArchive();
+    return await queryAllFromArchive(q);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    onLog?.(`archive query failed, falling back to ledger walk: ${msg}`);
+    return queryAll(q);
+  }
+}
+
+async function loadSessionTurnsViaArchive(sessionId, onLog) {
+  try {
+    await buildArchive();
+    return await queryTurnsFromArchive({ sessionId });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    onLog?.(`archive query failed, falling back to ledger walk: ${msg}`);
+    return queryAll({ sessionId });
+  }
+}
+
+// Accept either a CLI-style relative range (`24h`, `7d`, `4w`, `2m`) or an
+// ISO timestamp and return an ISO string the ledger query can compare. The
+// ledger filter does lexical string comparison on `turn.ts`, so passing a raw
+// `7d` would silently filter every turn out (since `'7'` > `'2'` lexically).
+// Lifted from `packages/cli/src/format.ts` so direct SDK callers (and future
+// MCP tools) get the same forgiving input shape the CLI users see, without
+// the silent-drop trap.
+function normalizeSince(since) {
+  if (since === undefined) return undefined;
+  if (typeof since !== 'string' || since.length === 0) return undefined;
+  const m = /^(\d+)([hdwm])$/.exec(since);
+  if (!m) {
+    const d = new Date(since);
+    if (Number.isNaN(d.getTime())) {
+      throw new Error(`invalid since: ${since} (expected ISO timestamp or relative range like 7d)`);
+    }
+    return d.toISOString();
+  }
+  const n = parseInt(m[1], 10);
+  const unit = m[2];
+  const ms =
+    unit === 'h'
+      ? n * 3600_000
+      : unit === 'd'
+        ? n * 86400_000
+        : unit === 'w'
+          ? n * 7 * 86400_000
+          : /* m */ n * 30 * 86400_000;
+  return new Date(Date.now() - ms).toISOString();
+}
+
 export class Ledger {
   static async open(opts = {}) {
     return new Ledger(opts.home);
@@ -44,8 +130,8 @@ export async function ingest(opts = {}) {
 
 export async function summary(opts = {}) {
   return withHome(opts.ledgerHome, async () => {
-    const q = { sessionId: opts.session, project: opts.project, since: opts.since };
-    const turns = await queryAll(q);
+    const q = { sessionId: opts.session, project: opts.project, since: normalizeSince(opts.since) };
+    const turns = await loadTurnsViaArchive(q, opts.onLog);
     const pricing = await loadPricing();
     const byTool = new Map();
     const byModel = new Map();
@@ -78,65 +164,331 @@ export async function summary(opts = {}) {
       }
     }
 
-    return { totalTokens, totalCost, byTool: [...byTool.values()], byModel: [...byModel.values()] };
+    return {
+      totalTokens,
+      totalCost,
+      turnCount: turns.length,
+      byTool: [...byTool.values()],
+      byModel: [...byModel.values()],
+    };
   });
 }
 
-export async function hotspots(opts = {}) {
+// Compact session-scoped cost summary. Same numbers as `summary({ session })`
+// but shaped for callers that just want the headline: totalUSD, totalTokens,
+// turnCount, distinct models. The MCP `burn__sessionCost` tool wraps this
+// directly so the cost shape lives in one place. `note` is set when the
+// session is empty or when no session id was provided so MCP clients can
+// surface a human-readable reason without re-deriving it.
+export async function sessionCost(opts = {}) {
   return withHome(opts.ledgerHome, async () => {
-    const turns = await queryAll({ sessionId: opts.session });
-    const userTurns = await queryUserTurns({ sessionId: opts.session });
+    const sessionId = opts.session;
+    if (!sessionId) {
+      return {
+        sessionId: null,
+        totalUSD: 0,
+        totalTokens: 0,
+        turnCount: 0,
+        models: [],
+        note: 'no session id provided',
+      };
+    }
+    const turns = await loadSessionTurnsViaArchive(sessionId, opts.onLog);
+    if (turns.length === 0) {
+      return {
+        sessionId,
+        totalUSD: 0,
+        totalTokens: 0,
+        turnCount: 0,
+        models: [],
+        note: 'no turns recorded for this session yet',
+      };
+    }
     const pricing = await loadPricing();
-    const userTurnsBySession = bucketBySession(userTurns);
-    const attribution = attributeHotspots(turns, { pricing, userTurnsBySession });
+    const models = new Set();
+    let totalTokens = 0;
+    const costs = [];
+    for (const t of turns) {
+      models.add(t.model);
+      const u = t.usage;
+      totalTokens +=
+        (u.input ?? 0) +
+        (u.output ?? 0) +
+        (u.reasoning ?? 0) +
+        (u.cacheRead ?? 0) +
+        (u.cacheCreate5m ?? 0) +
+        (u.cacheCreate1h ?? 0);
+      const c = costForTurn(t, pricing);
+      if (c) costs.push(c);
+    }
+    const total = sumCosts(costs);
+    return {
+      sessionId,
+      totalUSD: Math.round(total.total * 1_000_000) / 1_000_000,
+      totalTokens,
+      turnCount: turns.length,
+      models: [...models].sort(),
+    };
+  });
+}
+
+// Coverage flags `attributeHotspots` and the matching aggregators need.
+// Records without `fidelity` (older ledger writers, foreign sources) are
+// treated as best-effort full and pass the gate. Mirrors
+// `ATTRIBUTION_REQUIRED` + `turnPassesCoverage` in the CLI.
+const HOTSPOTS_ATTRIBUTION_REQUIRED = ['hasToolCalls', 'hasToolResultEvents'];
 
-    if (!opts.patterns || opts.patterns.length === 0) return attribution;
+function turnPassesCoverage(turn, required) {
+  const f = turn.fidelity;
+  if (!f) return true;
+  for (const key of required) {
+    if (!f.coverage[key]) return false;
+  }
+  return true;
+}
 
-    const wanted = new Set(opts.patterns);
-    const findings = [];
+const VALID_HOTSPOTS_GROUP_BY = ['attribution', 'bash', 'bash-verb', 'file', 'subagent'];
 
-    // Core patterns (retries, failures, edit-heavy, etc.) flow through
-    // detectPatterns + findingsFromPatterns; non-matching kinds are filtered.
-    const detected = detectPatterns(turns, { pricing, userTurnsBySession });
-    for (const f of findingsFromPatterns(detected)) {
-      if (wanted.has(f.kind)) findings.push(f);
-    }
+// Expanded hotspots(): returns a discriminated union covering every shape the
+// CLI's `burn hotspots --json` (and a few narrower programmatic cuts) need.
+//
+//   { kind: 'attribution' }                       — full per-axis aggregations
+//   { kind: 'bash' | 'bash-verb' | 'file' |
+//          'subagent' }                           — narrow to one aggregation
+//   { kind: 'findings' }                          — pattern findings (when
+//                                                   `patterns` is set)
+//
+// `groupBy` and `patterns` are mutually exclusive: passing `patterns` always
+// returns the findings shape and `groupBy` is ignored.
+//
+// Pattern detectors that need extra data (Claude settings, tool-result events,
+// on-disk ghost surface) are loaded lazily based on the requested patterns,
+// the same way the CLI does — so passing only `['retry-loop']` won't pay for
+// a settings.json read.
+export async function hotspots(opts = {}) {
+  return withHome(opts.ledgerHome, async () => {
+    const usingPatterns = opts.patterns && opts.patterns.length > 0;
 
-    // Side-channel detectors live outside detectPatterns. Each one reads its
-    // own slice of state, so we run them lazily based on `wanted`.
-
-    if (wanted.has('tool-output-bloat')) {
-      const settings = [];
-      const userLoaded = await loadClaudeSettings(userClaudeSettingsPath());
-      if (userLoaded) settings.push(userLoaded);
-      const projectLoaded = await loadClaudeSettings(projectClaudeSettingsPath());
-      if (projectLoaded) settings.push(projectLoaded);
-      const toolResultEvents = await queryToolResultEvents({ sessionId: opts.session });
-      const bloats = detectToolOutputBloat({
-        settings,
-        toolResultEvents,
-        userTurns,
-        turns,
-        pricing,
-      });
-      for (const b of bloats) findings.push(toolOutputBloatToFinding(b));
+    // Only validate `groupBy` when it actually steers the result. Per the
+    // documented mutual-exclusivity, passing `patterns` always returns
+    // findings and `groupBy` is ignored — including when its value is
+    // unknown — so callers that pass through a stale `groupBy` alongside
+    // `patterns` keep working.
+    if (
+      !usingPatterns &&
+      opts.groupBy !== undefined &&
+      !VALID_HOTSPOTS_GROUP_BY.includes(opts.groupBy)
+    ) {
+      throw new Error(
+        `invalid hotspots groupBy: ${JSON.stringify(opts.groupBy)} ` +
+          `(expected one of: ${VALID_HOTSPOTS_GROUP_BY.join(', ')})`,
+      );
     }
 
-    if (wanted.has('ghost-surface')) {
-      const ghostInputs = await buildGhostSurfaceInputs(turns, pricing);
-      const ghosts = await detectGhostSurface(ghostInputs);
-      for (const g of ghosts) findings.push(ghostSurfaceToFinding(g));
-    }
+    const q = q_(opts);
+    const turns = await loadTurnsViaArchive(q, opts.onLog);
+    const pricing = await loadPricing();
 
-    if (wanted.has('tool-call-pattern')) {
-      const patterns = detectToolCallPatterns(turns, { pricing });
-      for (const p of patterns) findings.push(toolCallPatternToFinding(p));
+    if (usingPatterns) {
+      return runHotspotsFindings(turns, pricing, opts, q);
     }
 
-    return findings;
+    return runHotspotsAttribution(turns, pricing, opts, q);
   });
 }
 
+async function runHotspotsAttribution(turns, pricing, opts, q = {}) {
+  const eligible = [];
+  const excluded = [];
+  for (const t of turns) {
+    if (turnPassesCoverage(t, HOTSPOTS_ATTRIBUTION_REQUIRED)) eligible.push(t);
+    else excluded.push(t);
+  }
+
+  const fidelitySummary = summarizeFidelity(turns);
+
+  // Refusal: nothing to attribute. Mirror the CLI's refused-shape so callers
+  // can branch on `refused` without re-deriving the reason.
+  if (turns.length > 0 && eligible.length === 0) {
+    const refusalReason =
+      `${turns.length}/${turns.length} turns lack tool-call/tool-result coverage required for hotspots attribution`;
+    const groupBy = opts.groupBy ?? 'attribution';
+    if (groupBy !== 'attribution') {
+      return { kind: groupBy, rows: [], refused: true, refusalReason };
+    }
+    return {
+      kind: 'attribution',
+      turnsAnalyzed: 0,
+      grandTotal: 0,
+      attributedTotal: 0,
+      unattributedTotal: 0,
+      attributionDegraded: false,
+      sessions: [],
+      files: [],
+      bashVerbs: [],
+      bash: [],
+      subagents: [],
+      fidelity: {
+        analyzed: 0,
+        excluded: turns.length,
+        summary: fidelitySummary,
+        refused: true,
+      },
+      refused: true,
+      refusalReason,
+    };
+  }
+
+  const sessionIds = new Set(eligible.map((t) => t.sessionId));
+  // Reuse the precomputed `q` from the caller — `normalizeSince()` calls
+  // `Date.now()` for relative ranges, so re-deriving here would cut the
+  // user-turn window at a slightly later boundary than the turn slice and
+  // drop borderline records.
+  const userTurnsBySession = await bulkUserTurnsBySession(sessionIds, q);
+  const result = attributeHotspots(eligible, { pricing, userTurnsBySession });
+
+  const groupBy = opts.groupBy ?? 'attribution';
+  if (groupBy === 'bash') {
+    return { kind: 'bash', rows: aggregateByBash(result.attributions) };
+  }
+  if (groupBy === 'bash-verb') {
+    return {
+      kind: 'bash-verb',
+      rows: aggregateByBashVerb(result.attributions, parseBashCommand),
+    };
+  }
+  if (groupBy === 'file') {
+    return { kind: 'file', rows: aggregateByFile(result.attributions) };
+  }
+  if (groupBy === 'subagent') {
+    return { kind: 'subagent', rows: aggregateBySubagent(result.attributions) };
+  }
+
+  const files = aggregateByFile(result.attributions);
+  const bashVerbs = aggregateByBashVerb(result.attributions, parseBashCommand);
+  const bash = aggregateByBash(result.attributions);
+  const subagents = aggregateBySubagent(result.attributions);
+  const evenSplit = result.sessionTotals.filter(
+    (s) => s.attributionMethod === 'even-split',
+  ).length;
+  const attributionDegraded =
+    result.sessionTotals.length > 0 &&
+    evenSplit / result.sessionTotals.length >= 0.5;
+
+  return {
+    kind: 'attribution',
+    turnsAnalyzed: eligible.length,
+    grandTotal: result.grandTotal,
+    attributedTotal: result.attributedTotal,
+    unattributedTotal: result.unattributedTotal,
+    attributionDegraded,
+    sessions: result.sessionTotals,
+    files,
+    bashVerbs,
+    bash,
+    subagents,
+    fidelity: {
+      analyzed: eligible.length,
+      excluded: excluded.length,
+      summary: fidelitySummary,
+      refused: false,
+    },
+  };
+}
+
+async function runHotspotsFindings(turns, pricing, opts, q = {}) {
+  const wanted = new Set(opts.patterns);
+  const findings = [];
+  // Forward `since` (and `sessionId`) so the user-turn + tool-result-event
+  // streams stay inside the same matched window the turn slice uses.
+  // Without this, detectors that read user-turn or tool-result-event state
+  // (system-prompt-tax, tool-output-bloat, retry/failure/cancellation graph
+  // walks) would mix older pre-window events into windowed analysis and
+  // surface false findings on long-lived sessions.
+  const sideQuery = {};
+  if (q.sessionId !== undefined) sideQuery.sessionId = q.sessionId;
+  if (q.since !== undefined) sideQuery.since = q.since;
+  const userTurns = await queryUserTurns(sideQuery);
+  const userTurnsBySession = bucketBySession(userTurns);
+
+  // Core patterns (retries, failures, edit-heavy, etc.) flow through
+  // detectPatterns + findingsFromPatterns; non-matching kinds are filtered.
+  const detected = detectPatterns(turns, { pricing, userTurnsBySession });
+  for (const f of findingsFromPatterns(detected)) {
+    if (wanted.has(f.kind)) findings.push(f);
+  }
+
+  // Side-channel detectors live outside detectPatterns. Each one reads its
+  // own slice of state, so we run them lazily based on `wanted`.
+
+  if (wanted.has('tool-output-bloat')) {
+    const settings = [];
+    const userLoaded = await loadClaudeSettings(userClaudeSettingsPath());
+    if (userLoaded) settings.push(userLoaded);
+    const projectLoaded = await loadClaudeSettings(projectClaudeSettingsPath());
+    if (projectLoaded) settings.push(projectLoaded);
+    const toolResultEvents = await queryToolResultEvents(sideQuery);
+    const bloats = detectToolOutputBloat({
+      settings,
+      toolResultEvents,
+      userTurns,
+      turns,
+      pricing,
+    });
+    for (const b of bloats) findings.push(toolOutputBloatToFinding(b));
+  }
+
+  if (wanted.has('ghost-surface')) {
+    const ghostInputs = await buildGhostSurfaceInputs(turns, pricing);
+    const ghosts = await detectGhostSurface(ghostInputs);
+    for (const g of ghosts) findings.push(ghostSurfaceToFinding(g));
+  }
+
+  if (wanted.has('tool-call-pattern')) {
+    const patterns = detectToolCallPatterns(turns, { pricing });
+    for (const p of patterns) findings.push(toolCallPatternToFinding(p));
+  }
+
+  return {
+    kind: 'findings',
+    findings,
+    summary: summarizeFidelity(turns),
+  };
+}
+
+// Build the ledger Query from SDK opts. Used by the bulk user-turn loader so
+// it narrows by `since`/`source` during streaming rather than buffering the
+// entire historical ledger. Mirrors the CLI's same trick.
+function q_(opts) {
+  const q = {};
+  if (opts.session) q.sessionId = opts.session;
+  if (opts.project) q.project = opts.project;
+  const since = normalizeSince(opts.since);
+  if (since) q.since = since;
+  return q;
+}
+
+// One ledger pass + in-memory bucket. Mirrors the CLI's `bulkUserTurnsBySession`:
+// the per-session form `queryUserTurns({sessionId})` re-streams the entire
+// ledger.jsonl on every call, so we issue a single bulk pass here and bucket
+// by sessionId. `since`/`source` are forwarded so the streaming filter narrows
+// the in-memory buffer to the same window the eligible turns live in.
+async function bulkUserTurnsBySession(sessionIds, q = {}) {
+  const out = new Map();
+  if (sessionIds.size === 0) return out;
+  const filter = {};
+  if (q.since !== undefined) filter.since = q.since;
+  if (q.source !== undefined) filter.source = q.source;
+  const all = await queryUserTurns(filter);
+  for (const ut of all) {
+    if (!sessionIds.has(ut.sessionId)) continue;
+    const list = out.get(ut.sessionId);
+    if (list) list.push(ut);
+    else out.set(ut.sessionId, [ut]);
+  }
+  return out;
+}
+
 function bucketBySession(userTurns) {
   const out = new Map();
   for (const ut of userTurns) {
@@ -146,3 +498,339 @@ function bucketBySession(userTurns) {
   }
   return out;
 }
+
+const VALID_OVERHEAD_KINDS = ['claude-md', 'agents-md'];
+
+// Discover and parse overhead files for a project, returning the parsed files
+// alongside the cost attribution (per-file and per-section). Shared by
+// `overhead()` (report mode) and `overheadTrim()` (recommendations mode) so the
+// discovery + ingest + query + attribution pipeline lives in one place.
+async function gatherOverhead(opts = {}) {
+  const projectPath = opts.project ? path.resolve(opts.project) : process.cwd();
+  const kind = opts.kind;
+  if (kind !== undefined && !VALID_OVERHEAD_KINDS.includes(kind)) {
+    throw new Error(
+      `invalid overhead kind: ${JSON.stringify(kind)} (expected one of: ${VALID_OVERHEAD_KINDS.join(', ')})`,
+    );
+  }
+
+  let found = await findOverheadFiles(projectPath);
+  if (kind) found = found.filter((f) => f.kind === kind);
+  if (found.length === 0) {
+    return { projectPath, files: [], attribution: null };
+  }
+
+  const files = [];
+  for (const f of found) files.push(await loadOverheadFile(f));
+
+  const resolved = resolveProject(projectPath);
+  const q = { project: resolved.projectKey ?? projectPath };
+  const normalizedSince = normalizeSince(opts.since);
+  if (normalizedSince) q.since = normalizedSince;
+
+  const turns = await loadTurnsViaArchive(q, opts.onLog);
+  const pricing = await loadPricing();
+  const attribution = attributeOverhead({ files, turns, pricing });
+  return { projectPath, files, attribution };
+}
+
+export async function overhead(opts = {}) {
+  return withHome(opts.ledgerHome, async () => {
+    const data = await gatherOverhead(opts);
+    if (!data.attribution) {
+      return { project: data.projectPath, files: [], perFile: [], grandTotal: 0 };
+    }
+    return {
+      project: data.projectPath,
+      files: data.files.map(({ file, parsed }) => ({
+        kind: file.kind,
+        path: file.path,
+        appliesTo: file.appliesTo,
+        totalLines: parsed.totalLines,
+        bytes: parsed.bytes,
+        tokens: parsed.tokens,
+        sections: parsed.sections,
+        groupingLevel: parsed.groupingLevel,
+      })),
+      perFile: data.attribution.perFile.map((p) => ({
+        path: p.file.path,
+        kind: p.file.kind,
+        appliesTo: p.file.appliesTo,
+        attribution: p.attribution,
+      })),
+      grandTotal: data.attribution.grandTotal,
+    };
+  });
+}
+
+export async function overheadTrim(opts = {}) {
+  return withHome(opts.ledgerHome, async () => {
+    const data = await gatherOverhead(opts);
+    const topPerFile = parseTopN(opts.top);
+    const sinceLabel = opts.since ?? 'all time';
+    if (!data.attribution) {
+      return {
+        project: data.projectPath,
+        since: sinceLabel,
+        recommendations: [],
+        summary: {
+          filesAnalyzed: 0,
+          filesWithRecommendations: 0,
+          totalRecommendations: 0,
+          totalProjectedSavingsPerSession: 0,
+          totalProjectedSavingsAcrossWindow: 0,
+        },
+      };
+    }
+
+    // The diff field is the unified-diff text the trim recommendation would
+    // produce — heavy enough to opt out of but useful enough that the CLI's
+    // --json mode always emits it. Keep that default; allow opts.includeDiff
+    // === false to skip the file reads when a caller (e.g. a future MCP tool)
+    // only wants the recommendation rows.
+    const includeDiff = opts.includeDiff !== false;
+    const textCache = new Map();
+    const recommendations = [];
+    let filesWithRecommendations = 0;
+
+    for (const fileAttr of data.attribution.perFile) {
+      const recs = buildTrimRecommendations(fileAttr.attribution, topPerFile);
+      if (recs.length === 0) continue;
+      filesWithRecommendations++;
+      let text;
+      if (includeDiff) {
+        text = textCache.get(fileAttr.file.path);
+        if (text === undefined) {
+          text = await readFile(fileAttr.file.path, 'utf8');
+          textCache.set(fileAttr.file.path, text);
+        }
+      }
+      for (const rec of recs) {
+        const entry = {
+          file: toProjectRelativePath(fileAttr.file.path, data.projectPath),
+          kind: fileAttr.file.kind,
+          appliesTo: fileAttr.file.appliesTo,
+          section: {
+            heading: rec.section.heading,
+            startLine: rec.section.startLine,
+            endLine: rec.section.endLine,
+            tokens: rec.section.tokens,
+          },
+          projectedSavings: {
+            perSessionUsd: rec.projectedSavingsPerSession,
+            acrossWindowUsd: rec.projectedSavingsAcrossWindow,
+            tokens: rec.section.tokens,
+            tokenShare: rec.tokenShare,
+          },
+        };
+        if (includeDiff) {
+          entry.diff = renderUnifiedDiffForRecommendation(
+            fileAttr.file.path,
+            text,
+            rec,
+            data.projectPath,
+          );
+        }
+        recommendations.push(entry);
+      }
+    }
+
+    return {
+      project: data.projectPath,
+      since: sinceLabel,
+      recommendations,
+      summary: {
+        filesAnalyzed: data.files.length,
+        filesWithRecommendations,
+        totalRecommendations: recommendations.length,
+        totalProjectedSavingsPerSession: recommendations.reduce(
+          (sum, r) => sum + r.projectedSavings.perSessionUsd,
+          0,
+        ),
+        totalProjectedSavingsAcrossWindow: recommendations.reduce(
+          (sum, r) => sum + r.projectedSavings.acrossWindowUsd,
+          0,
+        ),
+      },
+    };
+  });
+}
+
+function parseTopN(v) {
+  if (typeof v !== 'number' || !Number.isFinite(v) || v <= 0) return 3;
+  return Math.floor(v);
+}
+
+function toProjectRelativePath(filePath, projectPath) {
+  const rel = path.relative(projectPath, filePath);
+  const display = rel && !rel.startsWith('..') ? rel : filePath;
+  return display.split(path.sep).join('/');
+}
+
+const FIDELITY_CHOICES = ['full', 'usage-only', 'aggregate-only', 'cost-only', 'partial'];
+
+// Per-(model, activity) comparison shape. Mirrors the archive-vs-ledger
+// branching `runCompare` ships in the CLI: archive when nothing forces a
+// per-turn walk (no fidelity gate, no provider filter), ledger walk
+// otherwise. Returns the same JSON object the CLI's `--json` mode emits so
+// the CLI becomes a thin presenter and a future `burn__compare` MCP tool
+// can wrap this directly.
+export async function compare(opts) {
+  if (!opts || !Array.isArray(opts.models) || opts.models.length < 2) {
+    throw new Error('compare: needs at least 2 models');
+  }
+  if (opts.minFidelity !== undefined && !FIDELITY_CHOICES.includes(opts.minFidelity)) {
+    throw new Error(
+      `compare: invalid minFidelity: ${opts.minFidelity} (expected one of ${FIDELITY_CHOICES.join(', ')})`,
+    );
+  }
+  return withHome(opts.ledgerHome, async () => {
+    const minFidelity = opts.minFidelity ?? 'usage-only';
+    const minSample = opts.minSample ?? DEFAULT_MIN_SAMPLE;
+    const providerFilter = normalizeProviderFilter(opts.provider);
+
+    const q = {};
+    const since = normalizeSince(opts.since);
+    if (since !== undefined) q.since = since;
+    if (opts.session !== undefined) q.sessionId = opts.session;
+    if (opts.project !== undefined) q.project = opts.project;
+    if (opts.workflow !== undefined || opts.agent !== undefined) {
+      q.enrichment = {};
+      if (opts.workflow !== undefined) q.enrichment.workflowId = opts.workflow;
+      if (opts.agent !== undefined) q.enrichment.agentId = opts.agent;
+    }
+
+    const pricing = await loadPricing();
+    const tableOpts = { pricing, minSample, models: opts.models };
+
+    // `RELAYBURN_ARCHIVE=0` (also `false`/`no`) is the documented escape
+    // hatch from the archive path — used by `burn compare --no-archive` for
+    // parity/debug workflows. Honor it before deciding whether to query the
+    // archive at all so the CLI flag actually forces the ledger walk even
+    // when the archive on disk is healthy.
+    const archiveEnabled = !envDisablesArchive();
+
+    // Archive path is additionally restricted to slices where nothing forces
+    // a per-turn walk: no fidelity gate (`partial` lets everything through)
+    // and no provider filter (provider is derived per turn from (model,
+    // source) at query time and the archive's grouped SQL doesn't expose
+    // that classifier).
+    const useArchive = archiveEnabled && minFidelity === 'partial' && !providerFilter;
+
+    let table;
+    let analyzedTurns;
+    let summary;
+    if (useArchive) {
+      try {
+        await buildArchive();
+        const archived = await compareFromArchive(q, tableOpts);
+        table = archived.table;
+        // For the fidelity-permissive mode we still emit a zero-excluded
+        // summary so the JSON schema stays stable. summarizeFidelity needs
+        // turn rows; pull them via the same archive-aware loader.
+        const turnsForSummary = await loadTurnsViaArchive(q, opts.onLog);
+        summary = summarizeFidelity(turnsForSummary);
+        analyzedTurns = turnsForSummary.length;
+        return shapeCompareResult(table, analyzedTurns, minFidelity, summary);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        opts.onLog?.(`archive compare failed, falling back to ledger walk: ${msg}`);
+        // Fall through to ledger path.
+      }
+    }
+
+    // Ledger-walk path. When the archive is disabled we go straight to
+    // `queryAll` (no `buildArchive` side effect); otherwise the
+    // archive-aware loader still wins on the hot path even when the gate
+    // forces post-load filtering.
+    const queriedTurns = archiveEnabled
+      ? await loadTurnsViaArchive(q, opts.onLog)
+      : await queryAll(q);
+    const turns = providerFilter ? filterTurnsByProvider(queriedTurns, providerFilter) : queriedTurns;
+    summary = summarizeFidelity(turns);
+    const filteredTurns = minFidelity === 'partial'
+      ? turns
+      : turns.filter((t) => hasMinimumFidelity(t.fidelity, minFidelity));
+    table = buildCompareTable(filteredTurns, tableOpts);
+    analyzedTurns = filteredTurns.length;
+    return shapeCompareResult(table, analyzedTurns, minFidelity, summary);
+  });
+}
+
+function envDisablesArchive() {
+  const v = process.env.RELAYBURN_ARCHIVE;
+  return v === '0' || v === 'false' || v === 'no';
+}
+
+function normalizeProviderFilter(provider) {
+  if (!provider) return undefined;
+  if (!Array.isArray(provider)) {
+    throw new Error('compare: provider must be an array of strings');
+  }
+  const normalized = provider
+    .map((p) => (typeof p === 'string' ? p.trim().toLowerCase() : ''))
+    .filter(Boolean);
+  if (normalized.length === 0) return undefined;
+  return new Set(normalized);
+}
+
+// Sum the byClass buckets that fall below the minimum fidelity. We never
+// exclude `unknown` (records without a fidelity field — `hasMinimumFidelity`
+// passes them for backward compat), so they don't get counted here.
+// `partial` is the "include everything" escape hatch; it always reports zero
+// excluded.
+export function computeCompareExcluded(summary, minimum) {
+  const out = { total: 0, aggregateOnly: 0, costOnly: 0, partial: 0, usageOnly: 0 };
+  if (minimum === 'partial') return out;
+  const order = ['cost-only', 'aggregate-only', 'partial', 'usage-only', 'full'];
+  const need = order.indexOf(minimum);
+  for (const cls of order) {
+    if (order.indexOf(cls) >= need) continue;
+    const n = summary.byClass[cls];
+    if (!n) continue;
+    out.total += n;
+    if (cls === 'aggregate-only') out.aggregateOnly += n;
+    else if (cls === 'cost-only') out.costOnly += n;
+    else if (cls === 'partial') out.partial += n;
+    else if (cls === 'usage-only') out.usageOnly += n;
+  }
+  return out;
+}
+
+function shapeCompareResult(table, analyzedTurns, minimum, summary) {
+  const excluded = computeCompareExcluded(summary, minimum);
+  const cells = [];
+  for (const m of table.models) {
+    for (const cat of table.categories) {
+      const c = table.cells[m][cat];
+      cells.push({
+        model: m,
+        category: cat,
+        turns: c.turns,
+        editTurns: c.editTurns,
+        oneShotTurns: c.oneShotTurns,
+        pricedTurns: c.pricedTurns,
+        totalCost: round(c.totalCost, 6),
+        costPerTurn: c.costPerTurn !== null ? round(c.costPerTurn, 6) : null,
+        oneShotRate: c.oneShotRate !== null ? round(c.oneShotRate, 4) : null,
+        cacheHitRate: c.cacheHitRate !== null ? round(c.cacheHitRate, 4) : null,
+        medianRetries: c.medianRetries,
+        noData: c.noData,
+        insufficientSample: c.insufficientSample,
+      });
+    }
+  }
+  return {
+    analyzedTurns,
+    minSample: table.minSample,
+    models: table.models,
+    categories: table.categories,
+    totals: table.totals,
+    cells,
+    fidelity: { minimum, excluded, summary },
+  };
+}
+
+function round(n, digits) {
+  return Number(n.toFixed(digits));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@relayburn/sdk",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "description": "Embeddable Relayburn SDK for in-process ingest, summary, and hotspots queries",
   "type": "module",
   "main": "./index.js",
@@ -16,9 +16,10 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@relayburn/analyze": "1.8.0",
-    "@relayburn/cli": "1.8.0",
-    "@relayburn/ledger": "1.8.0"
+    "@relayburn/analyze": "1.10.0",
+    "@relayburn/ingest": "1.10.0",
+    "@relayburn/ledger": "1.10.0",
+    "@relayburn/reader": "1.10.0"
   },
   "repository": {
     "type": "git",