Hoist CLI-side summary/hotspots aggregation into a richer relayburn-sdk verb

[willwashburn]

Current status

Still valid for burn summary; partially resolved for burn hotspots.

Checked against origin/main at e0c8fa0eefe3ffde27debe5afc2db4ca956bba86 after #367, #369, and #370.

• burn summary is still the main layering issue. crates/relayburn-cli/src/commands/summary.rs opens the ledger, runs ingest, queries raw turns, applies presenter-local filters, and composes the output from SDK primitives rather than from one richer SDK-owned summary result. The default grouped path still calls summarize_fidelity, summarize_replacement_savings, aggregate_by_provider, and a CLI-local aggregate_by_model:

  burn/crates/relayburn-cli/src/commands/summary.rs

  Lines 228 to 251 in e0c8fa0

  	let fidelity = summarize_fidelity(&turns);
  	let savings = summarize_replacement_savings(&turns, None);
  	let quality = if args.quality && !globals.json {
  	Some(compute_quality_for_turns(handle.raw(), &turns)?)
  	} else {
  	None
  	};
  	if args.by_provider {
  	let rows = aggregate_by_provider(&turns, AggregateByProviderOptions::new(&pricing));
  	let provider_rows: Vec<UsageCostAggregateRow> =
  	rows.into_iter().map(provider_to_aggregate_row).collect();
  	emit_grouped(
  	globals,
  	true,
  	&provider_rows,
  	&turns,
  	&ingest_report,
  	&fidelity,
  	&savings,
  	quality.as_ref(),
  	);
  	} else {
  	let rows = aggregate_by_model(&turns, &pricing);

• The CLI still owns summary composition helpers for model aggregation, coverage accumulation, per-cell fidelity, fidelity JSON key ordering, partial markers, replacement-savings rendering, and quality rendering. Examples:

  burn/crates/relayburn-cli/src/commands/summary.rs

  Line 474 in e0c8fa0

  fn aggregate_by_model(

  and

  burn/crates/relayburn-cli/src/commands/summary.rs

  Lines 1765 to 1820 in e0c8fa0

  	fn fidelity_summary_to_json(s: &FidelitySummary) -> Value {
  	let mut by_class = Map::new();
  	for class in [
  	FidelityClass::Full,
  	FidelityClass::UsageOnly,
  	FidelityClass::AggregateOnly,
  	FidelityClass::CostOnly,
  	FidelityClass::Partial,
  	] {
  	by_class.insert(
  	class.wire_str().to_string(),
  	json!(*s.by_class.get(&class).unwrap_or(&0)),
  	);
  	}
  	let mut by_granularity = Map::new();
  	for g in [
  	relayburn_sdk::UsageGranularity::PerTurn,
  	relayburn_sdk::UsageGranularity::PerMessage,
  	relayburn_sdk::UsageGranularity::PerSessionAggregate,
  	relayburn_sdk::UsageGranularity::CostOnly,
  	] {
  	by_granularity.insert(
  	g.wire_str().to_string(),
  	json!(*s.by_granularity.get(&g).unwrap_or(&0)),
  	);
  	}
  	let mut missing = Map::new();
  	for field in [
  	"hasInputTokens",
  	"hasOutputTokens",
  	"hasReasoningTokens",
  	"hasCacheReadTokens",
  	"hasCacheCreateTokens",
  	"hasToolCalls",
  	"hasToolResultEvents",
  	"hasSessionRelationships",
  	"hasRawContent",
  	] {
  	missing.insert(
  	field.to_string(),
  	json!(*s.missing_coverage.get(field).unwrap_or(&0)),
  	);
  	}
  	let mut out = Map::new();
  	out.insert("total".into(), json!(s.total));
  	out.insert("byClass".into(), Value::Object(by_class));
  	out.insert("byGranularity".into(), Value::Object(by_granularity));
  	out.insert("missingCoverage".into(), Value::Object(missing));
  	out.insert("unknown".into(), json!(s.unknown));
  	Value::Object(out)
  	}
  	fn build_per_cell_fidelity(rows: &[UsageCostAggregateRow], by_provider: bool) -> Value {

• relayburn_sdk::summary is still a slim embedding API shape (total_tokens, total_cost, turn_count, by_tool, by_model, optional replacement_savings) and does not expose the composed view that burn summary --json / human rendering needs:

  burn/crates/relayburn-sdk/src/query_verbs.rs

  Lines 234 to 241 in e0c8fa0

  	pub struct Summary {
  	pub total_tokens: u64,
  	pub total_cost: f64,
  	pub turn_count: u64,
  	pub by_tool: Vec<SummaryToolRow>,
  	pub by_model: Vec<SummaryModelRow>,
  	#[serde(default, skip_serializing_if = "Option::is_none")]
  	pub replacement_savings: Option<ReplacementSavingsSummary>,

• hotspots is less affected now. Compute hotspots per-source coverage gap in SDK #370 moved the per-source excluded-turn breakdown into the SDK via HotspotsFidelityBlock::excluded_by_source, closing Rust perf: hotspots presenter walks the ledger twice per invocation #342. The CLI no longer performs the second ledger walk originally called out here.
• hotspots still has some presenter-side shape work (hotspots_result_to_json, reorder_fidelity_summary) for TS-compatible JSON ordering, but the major duplicated compute from the original issue has been addressed:

  burn/crates/relayburn-cli/src/commands/hotspots.rs

  Lines 170 to 285 in e0c8fa0

  	let mut value = hotspots_result_to_json(result);
  	coerce_whole_f64_to_int(&mut value);
  	let mut out = serde_json::to_string_pretty(&value).unwrap_or_default();
  	out.push('\n');
  	print!("{}", out);
  	}
  	fn hotspots_result_to_json(result: &HotspotsResult) -> Value {
  	match result {
  	HotspotsResult::Attribution(a) => attribution_to_json(a),
  	HotspotsResult::Bash {
  	rows,
  	refused,
  	refusal_reason,
  	} => json!({
  	"rows": rows.iter().map(bash_to_json).collect::<Vec<_>>(),
  	"refused": refused,
  	"refusalReason": refusal_reason,
  	}),
  	HotspotsResult::BashVerb {
  	rows,
  	refused,
  	refusal_reason,
  	} => json!({
  	"rows": rows.iter().map(bash_verb_to_json).collect::<Vec<_>>(),
  	"refused": refused,
  	"refusalReason": refusal_reason,
  	}),
  	HotspotsResult::File {
  	rows,
  	refused,
  	refusal_reason,
  	} => json!({
  	"rows": rows.iter().map(file_to_json).collect::<Vec<_>>(),
  	"refused": refused,
  	"refusalReason": refusal_reason,
  	}),
  	HotspotsResult::Subagent {
  	rows,
  	refused,
  	refusal_reason,
  	} => json!({
  	"rows": rows.iter().map(subagent_to_json).collect::<Vec<_>>(),
  	"refused": refused,
  	"refusalReason": refusal_reason,
  	}),
  	HotspotsResult::Findings { findings, summary } => json!({
  	"findings": findings,
  	"summary": summary,
  	}),
  	}
  	}
  	fn attribution_to_json(a: &HotspotsAttributionResult) -> Value {
  	let mut out = Map::new();
  	out.insert("turnsAnalyzed".into(), json!(a.turns_analyzed));
  	out.insert("grandTotal".into(), json!(a.grand_total));
  	out.insert("attributedTotal".into(), json!(a.attributed_total));
  	out.insert("unattributedTotal".into(), json!(a.unattributed_total));
  	out.insert("attributionDegraded".into(), json!(a.attribution_degraded));
  	out.insert(
  	"sessions".into(),
  	Value::Array(a.sessions.iter().map(session_total_to_json).collect()),
  	);
  	out.insert(
  	"files".into(),
  	Value::Array(a.files.iter().map(file_to_json).collect()),
  	);
  	out.insert(
  	"bashVerbs".into(),
  	Value::Array(a.bash_verbs.iter().map(bash_verb_to_json).collect()),
  	);
  	out.insert(
  	"bash".into(),
  	Value::Array(a.bash.iter().map(bash_to_json).collect()),
  	);
  	out.insert(
  	"subagents".into(),
  	Value::Array(a.subagents.iter().map(subagent_to_json).collect()),
  	);
  	out.insert(
  	"fidelity".into(),
  	json!({
  	"analyzed": a.fidelity.analyzed,
  	"excluded": a.fidelity.excluded,
  	"summary": reorder_fidelity_summary(&a.fidelity.summary),
  	"refused": a.fidelity.refused,
  	}),
  	);
  	if let Some(refused) = a.refused {
  	out.insert("refused".into(), json!(refused));
  	}
  	if let Some(reason) = a.refusal_reason.as_ref() {
  	out.insert("refusalReason".into(), json!(reason));
  	}
  	Value::Object(out)
  	}
  	fn session_total_to_json(s: &HotspotsSessionTotal) -> Value {
  	json!({
  	"sessionId": s.session_id,
  	"grandCost": s.grand_cost,
  	"attributedCost": s.attributed_cost,
  	"unattributedCost": s.unattributed_cost,
  	"attributionMethod": attribution_method_key(s.attribution_method),
  	})
  	}
  	/// Re-order the SDK-emitted fidelity summary so the JSON keys match the
  	/// TS-CLI snapshot ordering. The SDK builds `byClass` /
  	/// `byGranularity` / `missingCoverage` from `HashMap`s so iteration
  	/// order is non-deterministic; we reach into the `Value`, pull out the
  	/// numbers, and reassemble the object in the canonical order the TS
  	/// implementation uses (which is also the iteration order of the
  	/// upstream enum).
  	fn reorder_fidelity_summary(summary: &Value) -> Value {

• burn mcp-server now exists (relayburn-cli: burn ingest + burn mcp-server (#248 D8, closes #210) #319), but Rust summary / hotspots MCP tools are still follow-ups. The duplication risk remains if those tools need the same CLI-composed summary shape.

Problem

The Rust-port design rule still applies:

CLI dogfoods SDK. SDK owns composition. CLI owns presentation. A CLI command should be let result = sdk::verb(opts)?; render(result). Composed shapes that any consumer (CLI, MCP, wash, SDK-node callers) might want belong in the SDK as typed return shapes, not assembled client-side.

Today, the summary command violates that rule more than it did when this issue was opened: #367 implemented broader Rust summary parity, and #369 added tag filtering, but the composition still lives in crates/relayburn-cli/src/commands/summary.rs.

Proposed direction

Move the current burn summary compute/composition into an SDK-owned typed result. This can be either a compatible widening of relayburn_sdk::summary or an additive richer verb/result type if semver makes widening the existing public Summary struct wrong.

The SDK-owned result should cover the composed data the CLI currently builds:

• grouped rows by model and provider, including usage, cost, and row coverage
• per-cell coverage/fidelity metadata in stable order
• aggregate fidelity summary in stable order, without CLI-side HashMap reordering
• replacement-savings summary assembled once from SDK data
• quality, by-tool, subagent-type, relationship, tag/provider/workflow/agent filters, where the logic is shared compute rather than pure rendering

Then reduce commands/summary.rs to flag parsing, the CLI-specific ingest-before-render behavior, one SDK call, and render/JSON formatting.

For hotspots, keep this issue limited to the remaining shape-ordering cleanup unless new duplicated compute appears. The concrete second-ledger-walk problem is already handled by #370 / #342.

Also audit the broad public re-exports added for the original CLI assembly path. Keep low-level primitives public only if they are intentionally part of the embedding API; otherwise prefer the richer SDK result as the supported surface.

Constraints

• The original "relayburn-sdk is still 0.0.0" note is stale. The workspace is now 2.3.0, so changing public Rust structs is no longer automatically non-breaking. Use a semver-compatible path or schedule any breaking shape change deliberately.
• The @relayburn/sdk: npm umbrella + napi-rs CI matrix + conformance scaffold (#247 part b) #308 conformance gate and relayburn-sdk-node bindings still need to pass. If TypeScript @relayburn/sdk keeps the slim summary() shape, compare a compatible subset or expose the richer shape behind a separate result/verb.
• Preserve the Rust CLI golden snapshots and TS-compatible JSON field ordering while moving compute out of the CLI.

References

• Wave 2 D1 PR: relayburn-cli: burn summary + hotspots presenters (#248 D1) #315
• Summary parity expansion: Implement Rust summary parity #367
• Summary tag filtering: Add --tag and --by-tag filtering to burn summary #369
• Hotspots per-source breakdown moved into SDK: Compute hotspots per-source coverage gap in SDK #370 / Rust perf: hotspots presenter walks the ledger twice per invocation #342
• burn ingest + burn mcp-server: relayburn-cli: burn ingest + burn mcp-server (#248 D8, closes #210) #319
• Replacement savings on SDK summary: relayburn-sdk: surface replacement savings on summary(); deprecate sdk@1.x #366
• Wave 2 D2 PR (followed the codified rule): relayburn-cli: burn overhead + overhead trim presenters (#248 D2) #312
• Sibling design rationale comment: relayburn-cli: burn overhead + overhead trim presenters (#248 D2) #312 (comment)
• Parent epic: Epic: rewrite burn in Rust (v2 — supersedes #222) #240