@relayburn/sdk 1.8.0 → 1.9.0

package/CHANGELOG.md

@@ -4,12 +4,28 @@ All notable changes to `@relayburn/sdk`.
 
 ## [Unreleased]
 
+## [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,43 @@
 # @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 });
+
 const findings = await hotspots({ session: 'session-id', patterns: ['retry-loop'] });
 ```
+
+`summary`, `sessionCost`, `compare`, `overhead`, and `overheadTrim` 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,8 +4,141 @@ 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 interface HotspotsOptions {
   session?: string;
@@ -23,3 +156,79 @@ export interface HotspotsOptions {
   ledgerHome?: string;
 }
 export declare function hotspots(opts?: HotspotsOptions): Promise<unknown>
+
+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,44 @@
-import { queryAll, queryUserTurns, queryToolResultEvents } from '@relayburn/ledger';
 import {
-  loadPricing,
+  buildArchive,
+  queryAll,
+  queryAllFromArchive,
+  queryTurnsFromArchive,
+  queryUserTurns,
+  queryToolResultEvents,
+} from '@relayburn/ledger';
+import {
+  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 { 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 +51,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 +126,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,7 +160,71 @@ 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()],
+    };
+  });
+}
+
+// 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 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 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(),
+    };
   });
 }
 
@@ -146,3 +292,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.9.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.9.0",
+    "@relayburn/ingest": "1.9.0",
+    "@relayburn/ledger": "1.9.0",
+    "@relayburn/reader": "1.9.0"
   },
   "repository": {
     "type": "git",