feat(cli): wire burn compare --provider/--workflow/--agent filters (#415)

* feat(cli): wire `burn compare` --provider/--workflow/--agent filters

Drops the runtime "not yet wired" branches in `burn compare`:

- `--provider` is parsed as a lower-cased CSV allow-list and applied
  after `query_turns` via `provider_for`, matching `summary
  --by-provider` classification.
- `--workflow` / `--agent` fold through `Query.enrichment`
  (`workflowId` / `agentId` keys); both required when both flags
  are passed.
- Re-export `filter_turns_by_provider` / `ProviderFilter` from the
  SDK top-level surface so embedders can reuse the same filter.

Also documents the pre-query ingest decision: `burn compare` is a
presenter verb and does not run `ingest_all` first (chain
`burn ingest && burn compare` for fresh data) — the JSON envelope
stays byte-equivalent with the TS golden snapshot.

Closes #377.

* review: address coderabbit suggestions on #415

- README: `--provider <list>` → `--provider <csv>` to match the
  hotspots table convention.
- CHANGELOG: trim the compare bullet to user-impact-first.
- query_verbs: add intersection regression test pinning AND-semantics
  on combined `--workflow` + `--agent` enrichment filters.

* review: re-export ProviderRule + AsTurnLike alongside filter helpers

Codex flagged that `filter_turns_by_provider_with_rules` is callable from
the lib root but its argument types weren't, leaving the new public
surface partially unusable for embedders that want to supply custom
rules or implement the trait for their own row type.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: willwashburn

CHANGELOG.md

@@ -4,6 +4,12 @@ Cross-package release notes for relayburn. Package changelogs contain package-le
 
 ## [Unreleased]
 
+### Changed
+
+- `relayburn-cli`: `burn compare` now applies `--provider`, `--workflow`, and
+  `--agent` filters at runtime. It still reads the current ledger snapshot
+  (no pre-query ingest); run `burn ingest` first for freshest data.
+
 ## [2.8.1] - 2026-05-11
 
 ### Changed

README.md

@@ -123,12 +123,19 @@ testing, review, exploration, docs, and refactoring.
 | `--since <range>` | Limit to a relative range or ISO timestamp. |
 | `--project <path>` | Limit to a project. |
 | `--session <id>` | Limit to one session. |
+| `--workflow <id>` | Limit to turns folded with stamp `workflowId=<id>`. |
+| `--agent <id>` | Limit to turns folded with stamp `agentId=<id>`. |
+| `--provider <csv>` | Comma-separated effective providers (case-insensitive). |
 | `--min-sample <n>` | Flag cells below the sample threshold. Default: `5`. |
 | `--fidelity <class>` | Minimum data quality: `full`, `usage-only`, `aggregate-only`, `cost-only`, or `partial`. |
 | `--include-partial` | Include every turn. Shorthand for `--fidelity partial`. |
 | `--json` | Emit a stable JSON object. |
 | `--csv` | Emit one row per model/activity pair. |
 
+`burn compare` reads the ledger as-is — it does NOT run an ingest sweep
+first. Chain `burn ingest && burn compare …` (or run `burn ingest --watch`
+in the background) when you need the freshest data.
+
 | Example | Result |
 |---|---|
 | `burn compare claude-sonnet-4-6,claude-haiku-4-5 --since 30d` | Side-by-side activity table. |

crates/relayburn-cli/src/commands/compare.rs

@@ -7,15 +7,35 @@
 //! TS source of truth: `packages/cli/src/commands/compare.ts`. The wire
 //! shape (cells ordering, rounding rules, fidelity-summary key order)
 //! mirrors that file byte-for-byte against the cli-golden snapshot.
+//!
+//! ## Pre-query ingest decision
+//!
+//! Unlike `burn summary` and `burn hotspots`, this command intentionally does
+//! NOT run a pre-query `ingest_all` sweep. Two reasons:
+//!
+//! 1. The JSON envelope above (`analyzedTurns`, `models`, `categories`,
+//!    `cells`, `fidelity`) is byte-equivalent with the TS golden snapshot;
+//!    bolting on an `ingest` block to mirror summary would break that.
+//! 2. Compare is a presenter verb — answering "given my ledger, which model
+//!    won?". Callers who want the freshest answer can chain
+//!    `burn ingest && burn compare`; the steady-state setup is to run
+//!    `burn ingest --watch` once per host so every read verb sees current data.
+//!
+//! Filter wiring: `--project` / `--session` / `--since` lower into the
+//! `Query` struct directly; `--workflow` / `--agent` fold through
+//! `Query.enrichment` (`workflowId` / `agentId` keys, both required when
+//! both flags are passed); `--provider` is a post-query CSV allow-list
+//! resolved via `provider_for`, matching `summary --by-provider`'s
+//! synthetic-rule-aware classification.
 
-use std::collections::BTreeSet;
+use std::collections::{BTreeMap, BTreeSet};
 
 use anyhow::{anyhow, Result};
 use relayburn_sdk::{
-    build_compare_table, has_minimum_fidelity, load_pricing, summarize_fidelity,
+    build_compare_table, has_minimum_fidelity, load_pricing, provider_for, summarize_fidelity,
     AnalyzeCompareOptions as CompareOptions, CompareCell, CompareTable, EnrichedTurn,
-    FidelityClass, FidelitySummary, Ledger, LedgerOpenOptions, Query, UsageGranularity,
-    DEFAULT_MIN_SAMPLE,
+    FidelityClass, FidelitySummary, Ledger, LedgerOpenOptions, ProviderFilter, Query,
+    UsageGranularity, DEFAULT_MIN_SAMPLE,
 };
 use serde_json::{json, Value};
 
@@ -111,17 +131,10 @@ fn run_inner(globals: &GlobalArgs, args: CompareArgs) -> Result<i32> {
         return Err(anyhow!("--json and --csv are mutually exclusive; pick one."));
     }
 
-    // 4. Provider filter. Surfaced as an explicit "not yet wired" error
-    //    rather than a silent no-op — the SDK's provider filter is private
-    //    to the analyze module today, and exposing it through a typed
-    //    top-level surface is part of the broader provider-classifier
-    //    follow-up. The cli-golden corpus exercises compare without a
-    //    provider filter, so this is unblocked for parity.
-    if args.provider.is_some() {
-        return Err(anyhow!(
-            "burn compare: --provider filter is not yet wired through the Rust SDK (#246 follow-up)"
-        ));
-    }
+    // 4. Provider filter. Lower-cased CSV; turns whose effective provider
+    //    (per `provider_for`) isn't in the set get dropped after the ledger
+    //    query but before the fidelity gate, matching the TS pipeline order.
+    let provider_filter = parse_provider_filter(args.provider.as_deref())?;
 
     // 5. min-sample.
     let min_sample = args.min_sample.unwrap_or(DEFAULT_MIN_SAMPLE);
@@ -144,14 +157,19 @@ fn run_inner(globals: &GlobalArgs, args: CompareArgs) -> Result<i32> {
     if let Some(s) = args.session.as_deref() {
         q.session_id = Some(s.to_string());
     }
-    // `workflow` / `agent` flow through the stamp-based enrichment filter
-    // which the Rust ledger query layer doesn't yet expose. Surface the
-    // gap explicitly rather than silently dropping the flag — when the
-    // ledger gains enrichment-filter support, this branch comes out.
-    if args.workflow.is_some() || args.agent.is_some() {
-        return Err(anyhow!(
-            "burn compare: --workflow / --agent filters are not yet wired through the Rust ledger query (#246 follow-up)"
-        ));
+    // `workflow` / `agent` fold through stamp enrichment. Both keys live in
+    // the same `Enrichment` map (`workflowId`, `agentId`), and the ledger's
+    // `Query.enrichment` predicate requires every key/value pair to match —
+    // so passing both narrows to the intersection.
+    let mut enrichment = BTreeMap::new();
+    if let Some(workflow) = args.workflow.as_deref() {
+        enrichment.insert("workflowId".to_string(), workflow.to_string());
+    }
+    if let Some(agent) = args.agent.as_deref() {
+        enrichment.insert("agentId".to_string(), agent.to_string());
+    }
+    if !enrichment.is_empty() {
+        q.enrichment = Some(enrichment);
     }
 
     // 8. Open ledger and walk turns.
@@ -165,9 +183,20 @@ fn run_inner(globals: &GlobalArgs, args: CompareArgs) -> Result<i32> {
     progress.set_task("loading turns");
     let queried_turns: Vec<EnrichedTurn> = handle.raw().query_turns(&q)?;
 
-    // 9. Provider filter is rejected up-front (see step 4). Pipeline
-    //    treats every queried turn as eligible.
-    let filtered_by_provider: Vec<EnrichedTurn> = queried_turns;
+    // 9. Drop turns whose effective provider isn't in the allow-list. The
+    //    provider is resolved via `provider_for` (synthetic-rule first,
+    //    then `provider/model` prefix, then collector-implied) so the CLI
+    //    matches `summary --by-provider` semantics 1:1.
+    let filtered_by_provider: Vec<EnrichedTurn> = match provider_filter.as_ref() {
+        Some(filter) => queried_turns
+            .into_iter()
+            .filter(|et| {
+                let provider = provider_for(&et.turn).provider;
+                filter.contains(&provider.to_ascii_lowercase())
+            })
+            .collect(),
+        None => queried_turns,
+    };
 
     // 10. Fidelity summary is computed BEFORE the fidelity gate so the
     //     `summary` block in the JSON envelope reflects the queried slice.
@@ -223,6 +252,26 @@ fn run_inner(globals: &GlobalArgs, args: CompareArgs) -> Result<i32> {
 // helpers
 // ---------------------------------------------------------------------------
 
+/// Parse `--provider` CSV → lower-cased `ProviderFilter`. Mirrors the
+/// `summary --provider` parser: trim entries, drop empties, lower-case for
+/// case-insensitive matches, and reject an all-empty list with the same
+/// error shape (`burn: --provider requires a value`). Returns `Ok(None)`
+/// when the flag wasn't passed.
+fn parse_provider_filter(raw: Option<&str>) -> Result<Option<ProviderFilter>> {
+    let Some(raw) = raw else {
+        return Ok(None);
+    };
+    let providers: ProviderFilter = raw
+        .split(',')
+        .map(|s| s.trim().to_ascii_lowercase())
+        .filter(|s| !s.is_empty())
+        .collect();
+    if providers.is_empty() {
+        return Err(anyhow!("--provider requires a value"));
+    }
+    Ok(Some(providers))
+}
+
 fn parse_fidelity(s: &str) -> Result<FidelityClass> {
     match s {
         "full" => Ok(FidelityClass::Full),
@@ -1114,6 +1163,27 @@ mod tests {
         assert_eq!(v.to_string(), "0.01125");
     }
 
+    #[test]
+    fn parse_provider_filter_trims_lowercases_and_dedupes() {
+        let got = parse_provider_filter(Some(" Anthropic,OPENAI ,, anthropic"))
+            .unwrap()
+            .unwrap();
+        assert!(got.contains("anthropic"));
+        assert!(got.contains("openai"));
+        assert_eq!(got.len(), 2, "duplicates should collapse: got {got:?}");
+    }
+
+    #[test]
+    fn parse_provider_filter_returns_none_when_flag_absent() {
+        assert!(parse_provider_filter(None).unwrap().is_none());
+    }
+
+    #[test]
+    fn parse_provider_filter_rejects_all_empty_input() {
+        let err = parse_provider_filter(Some(" , ,, ")).unwrap_err();
+        assert!(format!("{err}").contains("--provider requires a value"));
+    }
+
     #[test]
     fn parse_fidelity_known_classes() {
         assert!(matches!(parse_fidelity("full").unwrap(), FidelityClass::Full));

crates/relayburn-sdk/src/lib.rs

@@ -89,10 +89,12 @@ pub use crate::analyze::{
     aggregate_by_subagent, aggregate_subagent_type_stats, attribute_hotspots, attribute_overhead,
     build_compare_table, build_subagent_tree, build_trim_recommendations, compare_from_archive,
     compute_quality, cost_for_turn, cost_for_usage, describe_applies_to, detect_patterns,
-    detect_tool_call_patterns, detect_tool_output_bloat, find_overhead_files,
-    findings_from_patterns, has_minimum_fidelity, load_overhead_file, load_pricing, provider_for,
-    render_unified_diff_for_recommendation, sum_costs, summarize_fidelity,
-    summarize_replacement_savings, AggregateByProviderOptions, AttributeOverheadInput,
+    detect_tool_call_patterns, detect_tool_output_bloat, filter_turns_by_provider,
+    filter_turns_by_provider_with_rules, find_overhead_files, findings_from_patterns,
+    has_minimum_fidelity, load_overhead_file, load_pricing, provider_for, AsTurnLike,
+    ProviderFilter, ProviderRule, render_unified_diff_for_recommendation, sum_costs,
+    summarize_fidelity, summarize_replacement_savings, AggregateByProviderOptions,
+    AttributeOverheadInput,
     AttributionMethod, BashAggregation, BashVerbAggregation, BuildSubagentTreeOptions,
     CompareCategory, CompareCell, CompareFromArchiveResult,
     CompareOptions as AnalyzeCompareOptions, CompareTable, CompareTotals, ComputeQualityOptions,

crates/relayburn-sdk/src/query_verbs.rs

@@ -4458,6 +4458,137 @@ mod tests {
         assert_eq!(missed.analyzed_turns, 0);
     }
 
+    #[test]
+    fn compare_filters_by_folded_agent_enrichment() {
+        let (_dir, mut handle) = fixture_handle();
+        let mut enrichment = crate::Enrichment::new();
+        enrichment.insert("agentId".into(), "agent-7".into());
+        let stamp = crate::Stamp::new(
+            "2026-04-22T00:00:00.000Z",
+            crate::StampSelector {
+                session_id: Some("sess-a".into()),
+                ..Default::default()
+            },
+            enrichment,
+        )
+        .unwrap();
+        handle.raw_mut().append_stamp(&stamp).unwrap();
+
+        let matched = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                agent: Some("agent-7".into()),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(matched.analyzed_turns, 2);
+
+        let missed = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                agent: Some("agent-missing".into()),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(missed.analyzed_turns, 0);
+    }
+
+    #[test]
+    fn compare_filters_by_effective_provider() {
+        // Fixture has 2 sonnet-4-6 turns (collector-implied `anthropic`).
+        // A matching filter keeps them; a non-matching one drops them.
+        let (_dir, handle) = fixture_handle();
+
+        let matched = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                provider: Some(vec!["anthropic".into()]),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(matched.analyzed_turns, 2);
+
+        let missed = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                provider: Some(vec!["openai".into()]),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(missed.analyzed_turns, 0);
+
+        // Case-insensitive: upper-case input must still match `anthropic`.
+        let mixed_case = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                provider: Some(vec!["ANTHROPIC".into()]),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(mixed_case.analyzed_turns, 2);
+    }
+
+    #[test]
+    fn compare_filters_by_workflow_and_agent_intersection() {
+        // `Query.enrichment` is AND-semantics: every key/value pair must
+        // match. Pin that here so a future drift to OR-semantics regresses
+        // visibly. Stamp folds both keys onto sess-a's two turns.
+        let (_dir, mut handle) = fixture_handle();
+        let mut enrichment = crate::Enrichment::new();
+        enrichment.insert("workflowId".into(), "wf-1".into());
+        enrichment.insert("agentId".into(), "agent-7".into());
+        let stamp = crate::Stamp::new(
+            "2026-04-22T00:00:00.000Z",
+            crate::StampSelector {
+                session_id: Some("sess-a".into()),
+                ..Default::default()
+            },
+            enrichment,
+        )
+        .unwrap();
+        handle.raw_mut().append_stamp(&stamp).unwrap();
+
+        let matched = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                workflow: Some("wf-1".into()),
+                agent: Some("agent-7".into()),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(matched.analyzed_turns, 2);
+
+        // Workflow matches but agent does not → 0.
+        let agent_missing = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                workflow: Some("wf-1".into()),
+                agent: Some("agent-missing".into()),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(agent_missing.analyzed_turns, 0);
+
+        // Agent matches but workflow does not → 0.
+        let workflow_missing = handle
+            .compare(CompareOptions {
+                models: vec!["claude-sonnet-4-6".into(), "claude-haiku-4-5".into()],
+                workflow: Some("wf-missing".into()),
+                agent: Some("agent-7".into()),
+                min_fidelity: Some(FidelityClass::Partial),
+                ..CompareOptions::default()
+            })
+            .unwrap();
+        assert_eq!(workflow_missing.analyzed_turns, 0);
+    }
+
     #[test]
     fn free_function_summary_round_trips_through_ledger_home() {
         let dir = tempfile::tempdir().unwrap();