Compute hotspots per-source coverage gap in SDK

[willwashburn]

Summary

• Widens HotspotsFidelityBlock (in relayburn-sdk) with a non-serialized excluded_by_source field that records the per-source coverage gap during the same eligible/excluded split that produces the rest of the attribution result.
• Drops the second ledger walk in crates/relayburn-cli/src/commands/hotspots.rs (describe_excluded_turns and the local CoverageGapBreakdown/SourceClause types). The CLI is now a pure renderer over the SDK's breakdown, matching the layering rule from Hoist CLI-side summary/hotspots aggregation into a richer relayburn-sdk verb #316.
• JSON contract is unchanged: the new field is #[serde(skip)], so the attribution result still serializes exactly as before, and the golden tests under crates/relayburn-cli/tests/golden.rs remain byte-identical against the TS CLI.

For a many-month ledger this halves the I/O burn hotspots does on the Rust path.

Closes #342

Test plan

• cargo build -p relayburn-sdk -p relayburn-cli
• cargo test -p relayburn-sdk -p relayburn-cli
• cargo test -p relayburn-cli --test golden (TS-conformance goldens)
• Spot-check burn hotspots on a real ledger with mixed sources (excluded codex + opencode turns) to confirm the inline coverage clause still names each source

https://claude.ai/code/session_01M2cRDSDfUwi4MPSxRq3WaA

---

Generated by Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1d25bda4-59a7-47f8-9a46-6ef9cc71ed80

📥 Commits

Reviewing files that changed from the base of the PR and between 9973768 and 170b5e7.

📒 Files selected for processing (2)

• crates/relayburn-cli/src/commands/hotspots.rs
• crates/relayburn-sdk/src/query_verbs.rs

---

📝 Walkthrough

Walkthrough

The PR eliminates a redundant ledger walk in the hotspots CLI command by moving per-source coverage-gap breakdown computation from the CLI into the SDK. The SDK now embeds this breakdown in HotspotsFidelityBlock; the CLI simplifies by calling the SDK directly and rendering output from the embedded breakdown instead of re-reading the ledger.

Changes

Hotspots Per-Source Coverage Breakdown

Layer / File(s)	Summary
SDK Exclusion Breakdown Types crates/relayburn-sdk/src/query_verbs.rs	Introduces HotspotsExcludedBreakdown and HotspotsExcludedSourceRow types; extends HotspotsFidelityBlock with excluded_by_source field to embed per-source coverage-gap details (source wire, missing coverage labels, granularity buckets).
SDK Hotspots Computation & Breakdown Population crates/relayburn-sdk/src/query_verbs.rs	Populates per-source breakdown during eligible/excluded split by initializing accumulator, recording each excluded turn via new record_excluded_source helper, and threading breakdown through refusal and success paths.
CLI Command Main Flow Simplification crates/relayburn-cli/src/commands/hotspots.rs	Removes imports for ledger-query plumbing (Query, normalize_since, BTreeMap); simplifies run_inner to call sdk_hotspots(...) directly and branch into JSON/human rendering without pre-computing a local CoverageGapBreakdown.
CLI Rendering: Human Output from SDK Breakdown crates/relayburn-cli/src/commands/hotspots.rs	Updates emit_human and emit_human_attribution signatures; refactors coverage_notice to render from SDK-provided fidelity.excluded_by_source; adds render_source_clauses helper and updates render_inline_source_clause to operate on SDK HotspotsExcludedSourceRow.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related issues

• Rust perf: hotspots presenter walks the ledger twice per invocation #342: This PR directly addresses the issue by moving per-source breakdown computation into the SDK, eliminating the second ledger walk in describe_excluded_turns.

Possibly related PRs

• AgentWorkforce/burn#301: Implemented the initial hotspots verb and result types in the SDK; this PR extends those types with the excluded_by_source field.
• AgentWorkforce/burn#315: Introduced the CLI-side per-source coverage re-walk in hotspots; this PR removes that re-walk by switching to the SDK-provided breakdown.

Poem

🐰 Hops skip the second ledger stroll,
SDK now owns the coverage toll,
Fidelity fields speak per-source fate,
CLI renders faster, computations wait! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'Compute hotspots per-source coverage gap in SDK' directly and clearly summarizes the main change: moving the per-source coverage gap computation from the CLI to the SDK.
Description check	✅ Passed	The description is thorough and directly related to the changeset, explaining the SDK widening, CLI simplification, JSON contract preservation, and performance benefits.
Linked Issues check	✅ Passed	All coding objectives from issue #342 are met: per-source coverage breakdown is now computed in SDK (HotspotsExcludedBreakdown/HotspotsExcludedSourceRow), second ledger walk is removed from CLI, and CLI becomes a pure renderer of SDK data.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to resolving issue #342: SDK enhancement to track per-source coverage gap and CLI simplification to eliminate duplicate ledger walk. No extraneous modifications detected.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/fix-issue-342-Vv238

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}