relayburn-sdk: surface replacement savings on summary(); deprecate sdk@1.x (#366)

Widens `Summary` in the Rust SDK to include an optional
`replacement_savings` field (calls, collapsedCalls, estimatedTokensSaved,
byTool). Populated from `summarize_replacement_savings()` in
`analyze/replacement_savings.rs`; elided when no replacement-tool calls
exist in the queried window.

Mirrors the new field into the napi-rs binding (`relayburn-sdk-node`) and
the TypeScript .d.ts for `@relayburn/sdk@2.x`. Adds unit tests in
`query_verbs.rs` asserting `Some(_)` for sessions with replacement calls
and `None` for clean sessions.

Adds a deprecation banner to `packages/sdk/README.md` and matching
CHANGELOG entries in both `@relayburn/sdk` (1.x maintenance freeze) and
`@relayburn/sdk` 2.x. Refs #365.

Author: willwashburn

crates/relayburn-sdk-node/src/lib.rs

@@ -399,13 +399,50 @@ pub struct SummaryModelRow {
     pub cost: f64,
 }
 
+#[napi(object)]
+pub struct ReplacementSavingsToolRow {
+    pub tool: String,
+    pub calls: BigInt,
+    pub collapsed_calls: BigInt,
+    pub estimated_tokens_saved: BigInt,
+}
+
+#[napi(object)]
+pub struct ReplacementSavingsSummary {
+    pub calls: BigInt,
+    pub collapsed_calls: BigInt,
+    pub estimated_tokens_saved: BigInt,
+    pub by_tool: Vec<ReplacementSavingsToolRow>,
+}
+
+impl From<sdk::ReplacementSavingsSummary> for ReplacementSavingsSummary {
+    fn from(s: sdk::ReplacementSavingsSummary) -> Self {
+        ReplacementSavingsSummary {
+            calls: u64_to_bigint(s.calls),
+            collapsed_calls: u64_to_bigint(s.collapsed_calls),
+            estimated_tokens_saved: u64_to_bigint(s.estimated_tokens_saved),
+            by_tool: s
+                .by_tool
+                .into_iter()
+                .map(|(tool, agg)| ReplacementSavingsToolRow {
+                    tool,
+                    calls: u64_to_bigint(agg.calls),
+                    collapsed_calls: u64_to_bigint(agg.collapsed_calls),
+                    estimated_tokens_saved: u64_to_bigint(agg.estimated_tokens_saved),
+                })
+                .collect(),
+        }
+    }
+}
+
 #[napi(object)]
 pub struct Summary {
     pub total_tokens: BigInt,
     pub total_cost: f64,
     pub turn_count: BigInt,
     pub by_tool: Vec<SummaryToolRow>,
     pub by_model: Vec<SummaryModelRow>,
+    pub replacement_savings: Option<ReplacementSavingsSummary>,
 }
 
 impl From<sdk::Summary> for Summary {
@@ -433,6 +470,7 @@ impl From<sdk::Summary> for Summary {
                     cost: r.cost,
                 })
                 .collect(),
+            replacement_savings: s.replacement_savings.map(ReplacementSavingsSummary::from),
         }
     }
 }

crates/relayburn-sdk/src/analyze/replacement_savings.rs

@@ -52,14 +52,16 @@ pub struct ToolCallSavings {
     pub estimated_tokens_saved: u64,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
+#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
 pub struct ToolSavingsAggregate {
     pub calls: u64,
     pub collapsed_calls: u64,
     pub estimated_tokens_saved: u64,
 }
 
-#[derive(Debug, Clone, PartialEq, Eq, Default)]
+#[derive(Debug, Clone, PartialEq, Eq, Default, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "camelCase")]
 pub struct ReplacementSavingsSummary {
     pub calls: u64,
     pub collapsed_calls: u64,

crates/relayburn-sdk/src/query_verbs.rs

@@ -21,16 +21,16 @@ use crate::analyze::{
     DetectToolCallPatternsOptions, DetectToolOutputBloatOptions, FidelitySummary, FileAggregation,
     GhostSurfaceFindingOptions, HotspotsOptions as AnalyzeHotspotsOptions, LoadedClaudeSettings,
     MarkdownSection, OverheadFile, OverheadFileKind, ParsedOverheadFile, PricingTable,
-    ProviderFilter, SessionClaudeMdCost, SubagentAggregation, WasteFinding, aggregate_by_bash,
-    aggregate_by_bash_verb, aggregate_by_file, aggregate_by_subagent, attribute_hotspots,
-    attribute_overhead, build_compare_table, build_ghost_surface_inputs,
-    build_trim_recommendations, cost_for_turn, detect_ghost_surface, detect_patterns,
-    detect_tool_call_patterns, detect_tool_output_bloat, find_overhead_files,
+    ProviderFilter, ReplacementSavingsSummary, SessionClaudeMdCost, SubagentAggregation,
+    WasteFinding, aggregate_by_bash, aggregate_by_bash_verb, aggregate_by_file,
+    aggregate_by_subagent, attribute_hotspots, attribute_overhead, build_compare_table,
+    build_ghost_surface_inputs, build_trim_recommendations, cost_for_turn, detect_ghost_surface,
+    detect_patterns, detect_tool_call_patterns, detect_tool_output_bloat, find_overhead_files,
     findings_from_patterns, ghost_surface_to_finding, has_minimum_fidelity, load_claude_settings,
     load_overhead_file, load_pricing, project_claude_settings_path,
     render_unified_diff_for_recommendation, sum_costs, summarize_fidelity,
-    summarize_fidelity_from_iter, tool_call_pattern_to_finding, tool_output_bloat_to_finding,
-    user_claude_settings_path,
+    summarize_fidelity_from_iter, summarize_replacement_savings, tool_call_pattern_to_finding,
+    tool_output_bloat_to_finding, user_claude_settings_path,
 };
 use crate::ledger::Query;
 use crate::reader::{
@@ -237,6 +237,8 @@ pub struct Summary {
     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>,
 }
 
 impl LedgerHandle {
@@ -307,6 +309,9 @@ fn compute_summary(turns: &[TurnRecord], pricing: &PricingTable) -> Summary {
         }
     }
 
+    let savings = summarize_replacement_savings(turns, None);
+    let replacement_savings = if savings.calls > 0 { Some(savings) } else { None };
+
     Summary {
         total_tokens,
         total_cost,
@@ -319,6 +324,7 @@ fn compute_summary(turns: &[TurnRecord], pricing: &PricingTable) -> Summary {
             .into_iter()
             .map(|k| by_model.remove(&k).unwrap())
             .collect(),
+        replacement_savings,
     }
 }
 
@@ -2421,4 +2427,83 @@ mod tests {
             std::env::set_var("RELAYBURN_CONTENT_TTL_DAYS", v);
         }
     }
+
+    // -----------------------------------------------------------------------
+    // compute_summary — replacement_savings field
+    // -----------------------------------------------------------------------
+
+    fn make_turn_with_calls(calls: Vec<ToolCall>) -> TurnRecord {
+        TurnRecord {
+            v: 1,
+            source: SourceKind::ClaudeCode,
+            session_id: "s".to_string(),
+            session_path: None,
+            message_id: "m".to_string(),
+            turn_index: 0,
+            ts: "2026-04-20T00:00:00.000Z".to_string(),
+            model: "claude-sonnet-4-6".to_string(),
+            project: None,
+            project_key: None,
+            usage: Usage {
+                input: 100,
+                output: 50,
+                reasoning: 0,
+                cache_read: 0,
+                cache_create_5m: 0,
+                cache_create_1h: 0,
+            },
+            tool_calls: calls,
+            files_touched: None,
+            subagent: None,
+            stop_reason: None,
+            activity: None,
+            retries: None,
+            has_edits: None,
+            fidelity: None,
+        }
+    }
+
+    #[test]
+    fn compute_summary_replacement_savings_some_when_replacement_tool_present() {
+        let tc = ToolCall {
+            id: "tc-1".into(),
+            name: "relaywash__Search".into(),
+            target: None,
+            args_hash: "h".into(),
+            is_error: None,
+            edit_pre_hash: None,
+            edit_post_hash: None,
+            skill_name: None,
+            replaced_tools: Some(vec!["Glob".into(), "Grep".into(), "Read".into()]),
+            collapsed_calls: Some(9),
+        };
+        let turns = vec![make_turn_with_calls(vec![tc])];
+        let pricing = load_pricing(None);
+        let result = compute_summary(&turns, &pricing);
+        let savings = result.replacement_savings.expect("should have replacement_savings");
+        assert_eq!(savings.calls, 1);
+        assert_eq!(savings.collapsed_calls, 9);
+        assert!(!savings.by_tool.is_empty());
+        assert!(savings.by_tool.contains_key("relaywash__Search"));
+    }
+
+    #[test]
+    fn compute_summary_replacement_savings_none_when_no_replacement_tools() {
+        let tc = ToolCall {
+            id: "tc-1".into(),
+            name: "Bash".into(),
+            target: None,
+            args_hash: "h".into(),
+            is_error: None,
+            edit_pre_hash: None,
+            edit_post_hash: None,
+            skill_name: None,
+            replaced_tools: None,
+            collapsed_calls: None,
+        };
+        let turns = vec![make_turn_with_calls(vec![tc])];
+        let pricing = load_pricing(None);
+        let result = compute_summary(&turns, &pricing);
+        assert!(result.replacement_savings.is_none());
+    }
 }

packages/sdk-node/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `summary()` result now includes `replacementSavings` — a rollup of per-tool collapsed-call counts and tokens-saved estimates derived from `_meta`-annotated tool results. Omitted (field absent) when no replacement-tool calls exist in the queried window.
+
 ## [2.0.0] - 2026-05-07
 
 - Initial scaffolding: umbrella package layout (`@relayburn/sdk`) +

packages/sdk-node/src/index.d.ts

@@ -47,6 +47,17 @@ export declare function summary(opts?: SummaryOptions): Promise<{
   turnCount: number;
   byTool: Array<{ tool: string; tokens: number | bigint; cost: number; count: number }>;
   byModel: Array<{ model: string; tokens: number | bigint; cost: number }>;
+  replacementSavings?: {
+    calls: number | bigint;
+    collapsedCalls: number | bigint;
+    estimatedTokensSaved: number | bigint;
+    byTool: Array<{
+      tool: string;
+      calls: number | bigint;
+      collapsedCalls: number | bigint;
+      estimatedTokensSaved: number | bigint;
+    }>;
+  };
 }>
 
 export interface SessionCostOptions {

packages/sdk/CHANGELOG.md

@@ -4,6 +4,10 @@ All notable changes to `@relayburn/sdk`.
 
 ## [Unreleased]
 
+### Deprecation
+
+- `@relayburn/sdk@1.x` is now in maintenance-only mode. New query-surface work lands in `@relayburn/sdk@2.x` (napi-rs binding over the Rust `relayburn-sdk` crate). The 1.x type surface is frozen; see [#249](https://github.com/AgentWorkforce/burn/issues/249).
+
 ## [1.10.0] - 2026-05-03
 
 ### Breaking Changes

packages/sdk/README.md

@@ -1,3 +1,5 @@
+ **Deprecated.** `@relayburn/sdk@1.x` is in maintenance-only mode. New work lands in `@relayburn/sdk@2.x` (the napi-rs binding over the Rust `relayburn-sdk` crate). Embedders should pin `^2.0.0` once it ships. The 1.x type surface is frozen and will not gain new fields. See [#249](https://github.com/AgentWorkforce/burn/issues/249) for the cutover schedule.
+
 # @relayburn/sdk
 
 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.