Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(savings): report how much smaller the input got, not only how much (#2461)
Raghav Chamadiya2357a937409f
diff --git a/packages/api-client/src/costs.ts b/packages/api-client/src/costs.tsindex 1455ac337..9c53695ab 100644--- a/packages/api-client/src/costs.ts+++ b/packages/api-client/src/costs.ts@@ -78,6 +78,16 @@ export interface Savings {unpriced_saved_output_tokens: number;priced_output_savings_usd: number;+ /** How much smaller the input got, over the events that carry a baseline.+ * The ratios are null when nothing in the window had a baseline to compare+ * against, which is distinct from a measured zero. */+ baseline_events: number;+ reducing_events: number;+ baseline_input_tokens: number;+ baseline_saved_input_tokens: number;+ input_reduction_ratio: number | null;+ input_reduction_ratio_p90: number | null;+per_operation: SavingsBreakdownRow[];per_surface: SavingsBreakdownRow[];per_agent: SavingsAgentRow[];diff --git a/packages/cli/src/repowise/cli/commands/saved_cmd.py b/packages/cli/src/repowise/cli/commands/saved_cmd.pyindex 370946fa2..9002c2e4d 100644--- a/packages/cli/src/repowise/cli/commands/saved_cmd.py+++ b/packages/cli/src/repowise/cli/commands/saved_cmd.py@@ -158,6 +158,12 @@ def saved_command("estimated_usd": report.priced_input_savings_usd,"mcp_queries_answered": report.mcp_queries_answered,"dead_ends": report.dead_ends,+ "baseline_events": report.baseline_events,+ "reducing_events": report.reducing_events,+ "baseline_input_tokens": report.baseline_input_tokens,+ "baseline_saved_input_tokens": report.baseline_saved_input_tokens,+ "input_reduction_ratio": report.input_reduction_ratio,+ "input_reduction_ratio_p90": report.input_reduction_ratio_p90,"first_event_at": report.first_event_at,"last_event_at": report.last_event_at,},@@ -286,6 +292,15 @@ def _print_evidence_and_pricing(report: SavingsReport) -> None:f" Measured: [bold]{report.measured_saved_input_tokens:,}[/bold] "f"Inferred: [bold]{report.inferred_saved_input_tokens:,}[/bold]")+ # Out of how much, not just how much. Both the aggregate and the peak,+ # because either alone misreads in whichever direction flatters.+ if report.input_reduction_ratio is not None and report.input_reduction_ratio_p90 is not None:+ console.print(+ f" Input reduction: [bold]{report.input_reduction_ratio:.0%}[/bold] "+ f"[dim]on {report.reducing_events:,} of {report.baseline_events:,} "+ f"comparable interactions; "+ f"{report.input_reduction_ratio_p90:.0%} at the 90th percentile[/dim]"+ )if report.priced_saved_input_tokens:console.print(f" Estimated saved: [bold green]${report.priced_input_savings_usd:.4f}[/bold green] "diff --git a/packages/core/src/repowise/core/savings/contracts.py b/packages/core/src/repowise/core/savings/contracts.pyindex f9844a396..843b39055 100644--- a/packages/core/src/repowise/core/savings/contracts.py+++ b/packages/core/src/repowise/core/savings/contracts.py@@ -340,6 +340,31 @@ class SavingsReport:priced_output_savings_usd: floatopportunity_count: intopportunity_tokens_excluded: int+ #: How much smaller the input got. The headline total answers "how many+ #: tokens"; this answers "out of how many", which is the only form in which+ #: one repository's savings compare with another's.+ #:+ #: Two populations, and both ship because either alone misleads.+ #: ``baseline_events`` counts every interaction that had something to+ #: compare against; ``reducing_events`` counts the subset where the input+ #: actually got smaller. The ratio below is over the subset -- "when it+ #: fires, by how much" -- and is only honest while the surface states the+ #: coverage beside it, which is what the two counts are for. An event with+ #: no baseline at all is in neither: it is not a reduction of nought.+ baseline_events: int = 0+ reducing_events: int = 0+ #: Both sides of the ratio, over ``reducing_events``, so the percentage is+ #: checkable rather than asserted.+ baseline_input_tokens: int = 0+ baseline_saved_input_tokens: int = 0+ #: ``baseline_saved_input_tokens / baseline_input_tokens``, and the+ #: nearest-rank 90th percentile of the same ratio taken per event. Both+ #: null when nothing in the window reduced anything. The aggregate is what+ #: a reduction is typically worth; the percentile says how far it goes on+ #: the outputs where it matters, and one without the other is a half-truth+ #: in whichever direction flatters.+ input_reduction_ratio: float | None = None+ input_reduction_ratio_p90: float | None = Noneper_operation: tuple[Mapping[str, Any], ...] = ()per_surface: tuple[Mapping[str, Any], ...] = ()#: Rows carry ``agent_display_name`` beside the slug, resolved from thediff --git a/packages/core/src/repowise/core/savings/formulas.py b/packages/core/src/repowise/core/savings/formulas.pyindex 88186ad14..875993eea 100644--- a/packages/core/src/repowise/core/savings/formulas.py+++ b/packages/core/src/repowise/core/savings/formulas.py@@ -72,3 +72,74 @@ def calculate_token_accounting(delivered_output_tokens=output_delivered,saved_output_tokens=saved_output,)+++#: The quantile the report publishes beside the aggregate reduction. High+#: enough to describe the large outputs where a reduction is worth having,+#: low enough not to be the single best call ever recorded.+REDUCTION_QUANTILE = 0.90+++def reduction_quantile_offset(population: int, quantile: float = REDUCTION_QUANTILE) -> int:+ """The 0-based rank in an ascending ratio list that names *quantile*.++ Defined once because two report builders have to land on the same row: the+ SQL path reaches it with ``ORDER BY ratio LIMIT 1 OFFSET n`` and the pure+ path indexes a sorted list. Nearest-rank, no interpolation -- an+ interpolating definition would make the two disagree in the last decimal+ and the parity test compares them exactly.+ """+ if population <= 0:+ return 0+ return min(population - 1, int(quantile * population))+++#: The same rule as :func:`reduction_denominator`, for the SQL report builder.+#: It has to exist twice because one builder is Python over domain records and+#: the other is a single aggregate query, but it is written once per language+#: and pinned by ``test_the_sql_report_and_the_pure_report_agree``, whose+#: fixture carries a measured MCP event whose pre-budget and baseline differ --+#: without that event the two definitions could disagree and still pass.+REDUCTION_DENOMINATOR_SQL = (+ "(CASE WHEN evidence_kind = 'measured' AND surface = 'mcp' "+ "THEN pre_budget_input_tokens ELSE baseline_input_tokens END)"+)+++def reduction_denominator(+ *,+ surface: str,+ evidence_kind: str,+ baseline_input_tokens: int | None,+ pre_budget_input_tokens: int | None,+) -> int | None:+ """What the saving on this event was actually computed against.++ The decision table gives a measured MCP event its ``pre_budget`` size as+ the formula baseline, not ``baseline_input_tokens``; the two differ, and+ that event's ``baseline`` can be an estimator floor an order of magnitude+ smaller. Dividing the saving by the wrong one of those produces reductions+ over 100%, which is how this was found -- a ledger read 424%.++ Because ``saved`` is ``clamp(this - delivered)``, the ratio it forms is in+ ``[0, 1]`` by construction on every event, whatever the surface.+ """+ if evidence_kind == "measured" and surface == "mcp":+ chosen = pre_budget_input_tokens+ else:+ chosen = baseline_input_tokens+ if chosen is None or chosen <= 0:+ return None+ return chosen+++def reduction_ratio(saved_input_tokens: int, baseline_input_tokens: int) -> float | None:+ """How much smaller the input got, over events that carry a baseline.++ ``None`` rather than zero when nothing in the window carried a baseline:+ "no basis to say" and "measured, and it was nothing" are different claims,+ which is the same rule the report applies to ``saved_output_tokens``.+ """+ if baseline_input_tokens <= 0:+ return None+ return saved_input_tokens / baseline_input_tokensdiff --git a/packages/core/src/repowise/core/savings/reporting.py b/packages/core/src/repowise/core/savings/reporting.pyindex 798399163..c0c78d066 100644--- a/packages/core/src/repowise/core/savings/reporting.py+++ b/packages/core/src/repowise/core/savings/reporting.py@@ -8,6 +8,11 @@ from datetime import datetime, timedeltafrom typing import Anyfrom repowise.core.savings.contracts import OpportunityObservation, SavingsEvent, SavingsReport+from repowise.core.savings.formulas import (+ reduction_denominator,+ reduction_quantile_offset,+ reduction_ratio,+)from repowise.core.savings.pricing import price_tokens#: Day-series cap, shared by both report builders. A year of daily rows is@@ -56,6 +61,44 @@ def _included(occurred_at: str, cutoff: datetime | None, as_of: datetime) -> booreturn timestamp <= as_of and (cutoff is None or timestamp >= cutoff)+def _reduction(scoped: list[SavingsEvent]) -> tuple[int, int, int, int, float | None]:+ """Coverage, both sides of the aggregate ratio, and its percentile.++ Two populations. ``pairs`` is every event with something to compare+ against -- an event with no baseline is not a reduction of nought, so it is+ in neither. ``reducing`` is the subset where the input actually got+ smaller, and the ratio is over that: "when it fires, by how much". Both+ counts are returned because the ratio only stays honest while the surface+ states its coverage.++ The denominator is what each event's saving was computed against, which is+ not always its ``baseline_input_tokens`` -- see+ :func:`reduction_denominator`.+ """+ pairs = [+ (event, denominator)+ for event in scoped+ if (+ denominator := reduction_denominator(+ surface=event.surface,+ evidence_kind=event.evidence_kind,+ baseline_input_tokens=event.baseline_input_tokens,+ pre_budget_input_tokens=event.pre_budget_input_tokens,+ )+ )+ is not None+ ]+ reducing = [(event, den) for event, den in pairs if event.saved_input_tokens > 0]+ ratios = sorted(event.saved_input_tokens / den for event, den in reducing)+ return (+ len(pairs),+ len(reducing),+ sum(den for _event, den in reducing),+ sum(event.saved_input_tokens for event, _den in reducing),+ ratios[reduction_quantile_offset(len(ratios))] if ratios else None,+ )++def build_report(events: Iterable[SavingsEvent],opportunities: Iterable[OpportunityObservation] = (),@@ -108,6 +151,9 @@ def build_report(output_usd += output_pricesaved_input = sum(event.saved_input_tokens for event in scoped)saved_output = sum(event.saved_output_tokens or 0 for event in scoped)+ baseline_events, reducing_events, baseline_input, baseline_saved, p90 = _reduction(+ scoped+ )limit = max(0, min(max_breakdowns, 100))def ranked(name: str) -> list[tuple[Any, ...]]:@@ -162,6 +208,12 @@ def build_report(priced_saved_output_tokens=priced_output,unpriced_saved_output_tokens=saved_output - priced_output,priced_output_savings_usd=output_usd,+ baseline_events=baseline_events,+ reducing_events=reducing_events,+ baseline_input_tokens=baseline_input,+ baseline_saved_input_tokens=baseline_saved,+ input_reduction_ratio=reduction_ratio(baseline_saved, baseline_input),+ input_reduction_ratio_p90=p90,opportunity_count=len(scoped_opportunities),opportunity_tokens_excluded=sum(item.estimated_potential_input_tokens for item in scoped_opportunitiesdiff --git a/packages/core/src/repowise/core/savings/repository.py b/packages/core/src/repowise/core/savings/repository.pyindex 1b93bc3d7..041ca2d48 100644--- a/packages/core/src/repowise/core/savings/repository.py+++ b/packages/core/src/repowise/core/savings/repository.py@@ -13,6 +13,11 @@ from repowise.core.savings.contracts import (SavingsReport,utc_text,)+from repowise.core.savings.formulas import (+ REDUCTION_DENOMINATOR_SQL,+ reduction_quantile_offset,+ reduction_ratio,+)from repowise.core.savings.reporting import (DAY_LIMIT,agent_breakdown_rows,@@ -178,6 +183,29 @@ class SavingsRepository:)return cursor.rowcount == 1+ def _reduction_p90(+ self, where: str, params: list[Any], population: int+ ) -> float | None:+ """The reduction ratio at the published quantile, over reducing events.++ One bounded row, not the population: a percentile is the value at a+ rank, so the database seeks to that rank rather than handing every+ ratio over to be sorted here, and the method stays as cheap as the+ aggregates beside it. ``reduction_quantile_offset`` is shared with the+ pure builder so the two land on the same row.+ """+ if not population:+ return None+ den = REDUCTION_DENOMINATOR_SQL+ hit = self._conn.execute(+ f"SELECT CAST(saved_input_tokens AS REAL) / {den} "+ f"FROM savings_events WHERE {where} AND {den} > 0 "+ "AND saved_input_tokens > 0 "+ "ORDER BY 1 ASC LIMIT 1 OFFSET ?",+ [*params, reduction_quantile_offset(population)],+ ).fetchone()+ return float(hit[0]) if hit is not None else None+def report(self,repository_id: str,@@ -202,6 +230,7 @@ class SavingsRepository:cutoff = as_of - timedelta(days=days)where += " AND occurred_at >= ?"params.append(utc_text(cutoff))+ den = REDUCTION_DENOMINATOR_SQLrow = self._conn.execute(f"""SELECT@@ -230,7 +259,14 @@ class SavingsRepository:THEN COALESCE(saved_output_tokens, 0) * output_rate_usd_per_million/ 1000000.0 ELSE 0 END), 0.0),MIN(occurred_at),- MAX(occurred_at)+ MAX(occurred_at),+ COALESCE(SUM(CASE WHEN {den} > 0 THEN 1 ELSE 0 END), 0),+ COALESCE(SUM(CASE WHEN {den} > 0 AND saved_input_tokens > 0+ THEN 1 ELSE 0 END), 0),+ COALESCE(SUM(CASE WHEN {den} > 0 AND saved_input_tokens > 0+ THEN {den} ELSE 0 END), 0),+ COALESCE(SUM(CASE WHEN {den} > 0 AND saved_input_tokens > 0+ THEN saved_input_tokens ELSE 0 END), 0)FROM savings_events WHERE {where}""",params,@@ -260,6 +296,11 @@ class SavingsRepository:"GROUP BY 1 ORDER BY 3 DESC, 1 ASC LIMIT ?",[*params, limit],).fetchall()+ baseline_events = int(row[16])+ reducing_events = int(row[17])+ baseline_input = int(row[18])+ baseline_saved = int(row[19])+ p90 = self._reduction_p90(where, params, reducing_events)saved_input = int(row[5])priced_input = int(row[8])saved_output = int(row[11])@@ -282,6 +323,12 @@ class SavingsRepository:priced_output_savings_usd=float(row[13]),opportunity_count=int(opportunity_count),opportunity_tokens_excluded=int(opportunity_tokens),+ baseline_events=baseline_events,+ reducing_events=reducing_events,+ baseline_input_tokens=baseline_input,+ baseline_saved_input_tokens=baseline_saved,+ input_reduction_ratio=reduction_ratio(baseline_saved, baseline_input),+ input_reduction_ratio_p90=p90,per_operation=breakdown_rows("operation", operations),per_surface=breakdown_rows("surface", surfaces),per_agent=agent_breakdown_rows(agents),diff --git a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.pyindex e4424e42e..ad874470a 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/counterfactual.py@@ -40,13 +40,28 @@ SEARCH_FLOOR_PER_HIT = 400#: thousands of tokens at that size) and opening five to fifteen files, so the#: real counterfactual sits higher still — the cap keeps the claim an undersell#: while leaving the per-file scaling meaningful for mid-sized modules.-CONTEXT_MODULE_FILE_FLOOR = 250-CONTEXT_MODULE_MAX = 12_000+CONTEXT_MODULE_FILE_FLOOR = 600+CONTEXT_MODULE_MAX = 20_000#: A ``get_context`` *symbol* card carries the signature, docstring and usage#: sites for one symbol — standing in for the agent locating and reading that-#: definition plus scanning who calls it. A single conservative floor.-CONTEXT_SYMBOL_FLOOR = 350+#: definition plus scanning who calls it. Finding it at all is a capped grep,+#: measured at 1,584 tokens of output on this repository (5,443 uncapped);+#: reading enough of the definition and its callers to answer the same question+#: is more again. Floored at well under half that measured grep alone.+CONTEXT_SYMBOL_FLOOR = 1_200++#: A ``get_context`` *file* card with no skeleton stands in for the agent+#: Reading that file. Skeleton-by-default was removed on 2026-08-11+#: (``tool_context/targets.py:87``) because the symbol-list card is cheaper,+#: and nothing replaced the credit — so the commonest call this tool serves has+#: been earning nothing at all. The card carries no size for the file it+#: describes and this module does no disk reads, so the credit is a flat floor+#: taken from the corpus rather than from the dict: across 4,115 source files+#: in this repository the p25 is 620 estimated tokens and the median is 1,296.+#: 600 is under the p25 — three quarters of real files cost more to Read than+#: this claims, which is the undersell this module is for.+CONTEXT_FILE_FLOOR = 600def _estimate_get_context(result: dict[str, Any]) -> int:@@ -83,6 +98,10 @@ def _estimate_get_context(result: dict[str, Any]) -> int:total += min(CONTEXT_MODULE_MAX, len(files) * CONTEXT_MODULE_FILE_FLOOR)elif target_type == "symbol":total += CONTEXT_SYMBOL_FLOOR+ elif target_type == "file":+ # Reached only when the caller did not ask for a skeleton, which is+ # the default since 2026-08-11. See CONTEXT_FILE_FLOOR.+ total += CONTEXT_FILE_FLOORreturn total@@ -114,14 +133,37 @@ ANSWER_READ_FLOOR_PER_FILE = 400#: usages across the tree to prove it unreachable — an expensive manual sweep.#: Floored conservatively between a single-file health call and a full overview.DEAD_CODE_FLOOR = 800-RISK_FLOOR = 500-WHY_FLOOR = 400-HEALTH_FLOOR = 400-OVERVIEW_FLOOR = 1200+RISK_FLOOR = 2_000+#: ``get_why`` replaces git archaeology on the code it is asked about. A single+#: ``git log -p -5`` on one file measures 4,834-7,108 estimated tokens across+#: three of this repository's hot files, and that is the cheapest form of the+#: question -- ``git blame --line-porcelain`` on the same files runs to+#: 416,000-562,000. Floored under half of the cheapest one.+WHY_FLOOR = 3_000+#: ``get_health`` replaces reading a file and judging its complexity by eye.+#: The per-file term is roughly the measured 1,296-token median source file;+#: the base covers locating the right files to look at in the first place.+HEALTH_FLOOR = 1_500+HEALTH_PER_FILE = 800+HEALTH_MAX = 12_000+#: ``get_overview`` replaces the README-plus-entry-points skim an agent does to+#: orient in an unfamiliar repository. This repository's README alone measures+#: 15,941 estimated tokens, so the old 1,200 credited 7.5% of one file; 6,000+#: is still barely a third of it, before any entry point is opened.+OVERVIEW_FLOOR = 6_000#: ``get_change_risk`` reasons about a whole diff's defect risk — standing in#: for the agent reading the diff and its coverage/co-change context by hand.+#: The flat floor was the most plainly wrong constant here: it credited 500+#: tokens against live delivered sizes of 4,439-4,671, so the tool recorded+#: itself as a net cost on every call. Reading the diff is what it replaces,+#: and ``git show`` with patch measures a 6,094-token median on this+#: repository's commits, so the per-file term is a quarter of that median+#: divided across a typical diff. The cap keeps a 200-file refactor from+#: claiming a number nobody would have read.CHANGE_RISK_FLOOR = 500+CHANGE_RISK_PER_FILE = 1_500+CHANGE_RISK_MAX = 12_000#: ``get_architecture`` renders the C4 map — replacing a read of many files and#: entry points to infer how the system is layered (workspace-level, so higher).ARCHITECTURE_FLOOR = 1200@@ -137,7 +179,11 @@ CONFORMANCE_FLOOR = 400#: undersold) instead of a flat floor.#: * ``get_risk`` — per assessed target (a file whose history the agent would#: reconstruct) plus per PR blast-radius file it surfaces.-RISK_PER_TARGET = 300+#: Reconstructing one file's history means reading the file (median 1,296+#: estimated tokens across this repository's 4,115 source files) and+#: grepping for what depends on it (a capped grep measures 1,584). The+#: per-target term is under the sum of the two.+RISK_PER_TARGET = 2_000RISK_PER_RELATED_FILE = 120#: * ``get_blast_radius`` — per downstream file that breaks (one the agent#: would otherwise trace across repos), capped so a huge fan-out still@@ -171,6 +217,42 @@ def _estimate_get_answer(result: dict[str, Any]) -> int:return ANSWER_SEARCH_FLOOR + len(paths) * ANSWER_READ_FLOOR_PER_FILE+def _estimate_get_change_risk(result: dict[str, Any]) -> int:+ """Floor plus a per-changed-file term — the diff the agent did not read.++ ``features.nf`` is the changed-file count the scorer already computed+ (``core/analysis/change_risk/service.py:316``), so this stays dict-only.+ Falls back to the flat floor when the payload carries no count.+ """+ if result.get("error"):+ return 0+ features = result.get("features")+ files = features.get("nf") if isinstance(features, dict) else None+ if not isinstance(files, int) or files <= 0:+ return CHANGE_RISK_FLOOR+ return min(CHANGE_RISK_MAX, CHANGE_RISK_FLOOR + files * CHANGE_RISK_PER_FILE)+++def _estimate_get_health(result: dict[str, Any]) -> int:+ """Floor plus a per-file term — the files the agent did not open to judge.++ ``targets`` (targets mode) and ``metrics`` (repository mode) each name the+ files the answer is about, and reading one to form the same judgement is+ roughly the measured 1,296-token median source file. Falls back to the+ flat floor when the payload names none.+ """+ if result.get("error"):+ return 0+ files = 0+ for key in ("targets", "metrics"):+ value = result.get(key)+ if isinstance(value, list):+ files = max(files, len(value))+ if not files:+ return HEALTH_FLOOR+ return min(HEALTH_MAX, HEALTH_FLOOR + files * HEALTH_PER_FILE)++def _fixed_floor(tokens: int) -> Callable[[dict[str, Any]], int]:"""Flat counterfactual for successful calls; errors contribute nothing."""@@ -310,10 +392,10 @@ _ESTIMATORS: dict[str, Callable[[dict[str, Any]], int]] = {"get_answer": _estimate_get_answer,"get_risk": _estimate_get_risk,"get_why": _fixed_floor(WHY_FLOOR),- "get_health": _fixed_floor(HEALTH_FLOOR),+ "get_health": _estimate_get_health,"get_overview": _fixed_floor(OVERVIEW_FLOOR),"get_dead_code": _fixed_floor(DEAD_CODE_FLOOR),- "get_change_risk": _fixed_floor(CHANGE_RISK_FLOOR),+ "get_change_risk": _estimate_get_change_risk,"get_blast_radius": _estimate_get_blast_radius,"get_execution_flows": _estimate_get_execution_flows,"get_architecture": _fixed_floor(ARCHITECTURE_FLOOR),diff --git a/packages/server/src/repowise/server/routers/costs.py b/packages/server/src/repowise/server/routers/costs.pyindex 419adab06..8358fd7dd 100644--- a/packages/server/src/repowise/server/routers/costs.py+++ b/packages/server/src/repowise/server/routers/costs.py@@ -185,6 +185,12 @@ async def get_savings(priced_saved_output_tokens=report.priced_saved_output_tokens,unpriced_saved_output_tokens=report.unpriced_saved_output_tokens,priced_output_savings_usd=report.priced_output_savings_usd,+ baseline_events=report.baseline_events,+ reducing_events=report.reducing_events,+ baseline_input_tokens=report.baseline_input_tokens,+ baseline_saved_input_tokens=report.baseline_saved_input_tokens,+ input_reduction_ratio=report.input_reduction_ratio,+ input_reduction_ratio_p90=report.input_reduction_ratio_p90,per_operation=_breakdown(report.per_operation, "operation"),per_surface=_breakdown(report.per_surface, "surface"),per_agent=[SavingsAgentRow(**row) for row in report.per_agent],diff --git a/packages/server/src/repowise/server/schemas/ui_helpers.py b/packages/server/src/repowise/server/schemas/ui_helpers.pyindex 675c7f29d..434650a0d 100644--- a/packages/server/src/repowise/server/schemas/ui_helpers.py+++ b/packages/server/src/repowise/server/schemas/ui_helpers.py@@ -161,6 +161,15 @@ class SavingsResponse(BaseModel):unpriced_saved_output_tokens: int = 0priced_output_savings_usd: float = 0.0+ #: How much smaller the input got, over the events that carry a baseline.+ #: Null ratios mean no event in the window had anything to compare against.+ baseline_events: int = 0+ reducing_events: int = 0+ baseline_input_tokens: int = 0+ baseline_saved_input_tokens: int = 0+ input_reduction_ratio: float | None = None+ input_reduction_ratio_p90: float | None = None+per_operation: list[SavingsBreakdownRow] = []per_surface: list[SavingsBreakdownRow] = []per_agent: list[SavingsAgentRow] = []diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 14d86c02c..29920cd5e 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -2580,6 +2580,12 @@ export interface SavingsResponse {priced_saved_output_tokens?: number;unpriced_saved_output_tokens?: number;priced_output_savings_usd?: number;+ baseline_events?: number;+ reducing_events?: number;+ baseline_input_tokens?: number;+ baseline_saved_input_tokens?: number;+ input_reduction_ratio?: number | null;+ input_reduction_ratio_p90?: number | null;per_operation?: SavingsBreakdownRow[];per_surface?: SavingsBreakdownRow[];per_agent?: SavingsAgentRow[];diff --git a/packages/ui/__tests__/savings/savings-surface.test.tsx b/packages/ui/__tests__/savings/savings-surface.test.tsxindex 37d59da58..b999468ee 100644--- a/packages/ui/__tests__/savings/savings-surface.test.tsx+++ b/packages/ui/__tests__/savings/savings-surface.test.tsx@@ -46,6 +46,12 @@ function makeSavings(overrides: Partial<SavingsView> = {}): SavingsView {priced_saved_output_tokens: 0,unpriced_saved_output_tokens: 0,priced_output_savings_usd: 0,+ baseline_events: 120,+ reducing_events: 110,+ baseline_input_tokens: 2_000_000,+ baseline_saved_input_tokens: 1_000_000,+ input_reduction_ratio: 0.5,+ input_reduction_ratio_p90: 0.88,per_operation: [{ group: "get_answer", events: 40, saved_input_tokens: 600_000 },{ group: "get_context", events: 20, saved_input_tokens: 400_000 },diff --git a/packages/ui/src/savings/savings-lede.tsx b/packages/ui/src/savings/savings-lede.tsxindex 41945d1b2..5cbe386f9 100644--- a/packages/ui/src/savings/savings-lede.tsx+++ b/packages/ui/src/savings/savings-lede.tsx@@ -31,6 +31,10 @@ export function SavingsLede({ data, methodologyHref, LinkComponent }: SavingsLedconst measured = data.measured_saved_input_tokens;const inferred = data.inferred_saved_input_tokens;const unpriced = data.unpriced_saved_input_tokens;+ // The total answers "how many tokens". This answers "out of how many", which+ // is the only form in which one repository's savings compare with another's.+ const ratio = data.input_reduction_ratio;+ const peak = data.input_reduction_ratio_p90;// "Estimated" for as long as any part of the total rests on a counterfactual// rather than a known before and after. The word is the honest one and it@@ -38,42 +42,7 @@ export function SavingsLede({ data, methodologyHref, LinkComponent }: SavingsLed// headline starts overclaiming.const label = inferred > 0 ? "Estimated agent savings" : "Agent savings";- const stats: RibbonStat[] = [- {- label: "Measured",- value: formatTokens(measured),- hint: "A known before and after: the tokens an operation that actually ran removed.",- sub: pctOf(measured, total),- },- {- label: "Inferred",- value: formatTokens(inferred),- hint: "A documented counterfactual: the exploration a Repowise answer replaced.",- sub: pctOf(inferred, total),- },- {- label: "Valued",- value: formatCost(data.priced_input_savings_usd),- hint: "Each event is priced at the rate recorded when it happened, so this covers only events that carried one.",- sub:- unpriced > 0- ? `on ${formatTokens(data.priced_saved_input_tokens)} of ${formatTokens(total)}`- : "on all savings",- },- {- label: "Interactions",- value: data.unique_events.toLocaleString(),- hint: "Logical agent interactions recorded. One interaction contributes to the total once.",- // "9 saved tokens" reads as nine tokens. It is nine interactions.- sub: `${data.saving_interactions.toLocaleString()} produced a saving`,- },- {- label: "MCP answered",- value: data.mcp_queries_answered.toLocaleString(),- hint: "MCP calls that returned an answer. Dead ends are counted separately and save nothing.",- ...(data.dead_ends > 0 ? { sub: `${data.dead_ends.toLocaleString()} dead ends` } : {}),- },- ];+ const stats = ribbonStats(data);return (<div className="flex flex-col gap-6">@@ -96,6 +65,18 @@ export function SavingsLede({ data, methodologyHref, LinkComponent }: SavingsLed: inferred > 0? "Part of the total is inferred, so the figure is an estimate rather than a measurement.": "Every part of the total is a measured before and after."}+ {/* The aggregate alone reads as a modest average and the peak alone+ reads as a cherry-pick. Both, or neither. */}+ {ratio === null || peak === null ? null : (+ <>+ {" "}+ On the {data.reducing_events.toLocaleString()} of{" "}+ {data.baseline_events.toLocaleString()} interactions that produced a saving,+ the input was {Math.round(ratio * 100)}% smaller than the work it replaced,+ and {Math.round(peak * 100)}% smaller at the{" "}+ {Math.round(REDUCTION_QUANTILE * 100)}th percentile.+ </>+ )}</p><p>{total <= 0 ? null : unpriced > 0 ? (@@ -171,6 +152,74 @@ function Coverage({/** A share, or nothing. A denominator of zero has no percentage, and "0%"* would be a claim rather than an absence. */+/**+ * The figures that qualify the headline, in the order they qualify it.+ *+ * Lifted out of the component because it is a list of data, not markup,+ * and because the component had grown past the point where the JSX it+ * returns was visible on one screen.+ */+function ribbonStats(data: SavingsView): RibbonStat[] {+ const total = data.saved_input_tokens;+ const measured = data.measured_saved_input_tokens;+ const inferred = data.inferred_saved_input_tokens;+ const unpriced = data.unpriced_saved_input_tokens;+ const ratio = data.input_reduction_ratio;+ return [+ // First, because it is the figure a reader is trying to arrive at when+ // they divide the headline by something in their head.+ ...(ratio === null+ ? []+ : [+ {+ label: "Input reduction",+ value: `${Math.round(ratio * 100)}%`,+ hint: "When Repowise replaces something, how much smaller the input is than what it stood in for. Measured over the interactions that produced a saving; the ones that produced none are counted beside it rather than folded in, and interactions with nothing to compare against are in neither.",+ sub: `on ${data.reducing_events.toLocaleString()} of ${data.baseline_events.toLocaleString()} comparable`,+ } satisfies RibbonStat,+ ]),+ {+ label: "Measured",+ value: formatTokens(measured),+ hint: "A known before and after: the tokens an operation that actually ran removed.",+ sub: pctOf(measured, total),+ },+ {+ label: "Inferred",+ value: formatTokens(inferred),+ hint: "A documented counterfactual: the exploration a Repowise answer replaced.",+ sub: pctOf(inferred, total),+ },+ {+ label: "Valued",+ value: formatCost(data.priced_input_savings_usd),+ hint: "Each event is priced at the rate recorded when it happened, so this covers only events that carried one.",+ sub:+ unpriced > 0+ ? `on ${formatTokens(data.priced_saved_input_tokens)} of ${formatTokens(total)}`+ : "on all savings",+ },+ {+ label: "Interactions",+ value: data.unique_events.toLocaleString(),+ hint: "Logical agent interactions recorded. One interaction contributes to the total once.",+ // "9 saved tokens" reads as nine tokens. It is nine interactions.+ sub: `${data.saving_interactions.toLocaleString()} produced a saving`,+ },+ {+ label: "MCP answered",+ value: data.mcp_queries_answered.toLocaleString(),+ hint: "MCP calls that returned an answer. Dead ends are counted separately and save nothing.",+ ...(data.dead_ends > 0 ? { sub: `${data.dead_ends.toLocaleString()} dead ends` } : {}),+ },+ ];+}++/** The quantile the report publishes beside the aggregate. Mirrors+ * `REDUCTION_QUANTILE` in `core/savings/formulas.py`; the server computes the+ * value, this only needs to say which one it is. */+const REDUCTION_QUANTILE = 0.9;+function pctOf(part: number, whole: number): string | undefined {if (whole <= 0) return undefined;return `${Math.round((part / whole) * 100)}% of total`;diff --git a/packages/ui/src/savings/types.ts b/packages/ui/src/savings/types.tsindex 998217805..c5709fd64 100644--- a/packages/ui/src/savings/types.ts+++ b/packages/ui/src/savings/types.ts@@ -67,6 +67,16 @@ export interface SavingsView {unpriced_saved_output_tokens: number;priced_output_savings_usd: number;+ /** How much smaller the input got, over the events that carry a baseline.+ * The ratios are null when nothing in the window had a baseline to compare+ * against, which is distinct from a measured zero. */+ baseline_events: number;+ reducing_events: number;+ baseline_input_tokens: number;+ baseline_saved_input_tokens: number;+ input_reduction_ratio: number | null;+ input_reduction_ratio_p90: number | null;+per_operation: SavingsBreakdownRow[];per_surface: SavingsBreakdownRow[];per_agent: SavingsAgentRow[];diff --git a/packages/web/src/app/repos/[id]/costs/page.test.tsx b/packages/web/src/app/repos/[id]/costs/page.test.tsxindex 6e80355b7..04bfe51c0 100644--- a/packages/web/src/app/repos/[id]/costs/page.test.tsx+++ b/packages/web/src/app/repos/[id]/costs/page.test.tsx@@ -82,6 +82,12 @@ function makeSavings(overrides: Partial<Savings> = {}): Savings {priced_saved_output_tokens: 0,unpriced_saved_output_tokens: 0,priced_output_savings_usd: 0,+ baseline_events: 120,+ reducing_events: 110,+ baseline_input_tokens: 2_000_000,+ baseline_saved_input_tokens: 1_000_000,+ input_reduction_ratio: 0.5,+ input_reduction_ratio_p90: 0.88,per_operation: [{ group: "rg", events: 9, saved_input_tokens: 400_000 }],per_surface: [{ group: "distill", events: 9, saved_input_tokens: 400_000 }],diff --git a/tests/unit/savings/test_service.py b/tests/unit/savings/test_service.pyindex 6deeeac07..483d88a38 100644--- a/tests/unit/savings/test_service.py+++ b/tests/unit/savings/test_service.py@@ -175,6 +175,18 @@ def test_the_sql_report_and_the_pure_report_agree(tmp_path: Path) -> None:occurred_at="2026-09-11T08:00:00.000000Z",priced=True,)+ # A measured MCP event whose pre-budget and baseline differ. The reduction+ # denominator is the one case where the two builders express the same rule+ # in two languages -- a Python branch and a SQL CASE -- and without this+ # event they would agree by accident on every fixture here.+ _record_raw(+ tmp_path,+ surface="mcp",+ evidence_kind="measured",+ baseline_input_tokens=400,+ pre_budget_input_tokens=30_000,+ delivered_input_tokens=2_000,+ )as_of = datetime.now(UTC)from_sql = load_report(tmp_path, as_of=as_of)@@ -211,3 +223,142 @@ def test_the_sql_report_and_the_pure_report_agree(tmp_path: Path) -> None:assert len(from_sql.per_day) == 3assert any(row["model"] is None for row in from_sql.per_model)assert from_sql.inferred_saved_input_tokens > 0+ # The reduction fields are only compared above while the fixture actually+ # carries baselines. The percentile in particular is a rank, so a builder+ # that was off by one would agree on a one-event population by accident.+ assert from_sql.baseline_events == 5+ assert from_sql.reducing_events == 5+ assert from_sql.input_reduction_ratio is not None+ assert from_sql.input_reduction_ratio_p90 is not None+++def test_a_measured_mcp_event_divides_by_what_its_saving_was_computed_against(+ tmp_path: Path,+) -> None:+ """The decision table gives a measured MCP event its pre-budget size as the+ formula baseline, not ``baseline_input_tokens``. Dividing by the wrong one+ reports a reduction over 100%: a real ledger read 424% before this.+ """+ _sidecar(tmp_path)+ _record_raw(+ tmp_path,+ surface="mcp",+ evidence_kind="measured",+ # An estimator floor, an order of magnitude under what was really shed.+ baseline_input_tokens=400,+ pre_budget_input_tokens=10_000,+ delivered_input_tokens=1_000,+ )+ report = load_report(tmp_path)+ assert report is not None+ assert report.saved_input_tokens == 9_000+ assert report.baseline_input_tokens == 10_000+ assert report.input_reduction_ratio == pytest.approx(0.9)+++def test_no_window_can_report_a_reduction_over_one(tmp_path: Path) -> None:+ """``saved`` is ``clamp(denominator - delivered)``, so the ratio it forms+ is in [0, 1] on every event whatever the surface. Asserted rather than+ reasoned about, across the mix of surfaces that made it false once.+ """+ _sidecar(tmp_path)+ _record_raw(+ tmp_path,+ surface="mcp",+ evidence_kind="measured",+ baseline_input_tokens=400,+ pre_budget_input_tokens=50_000,+ delivered_input_tokens=500,+ )+ _record_raw(+ tmp_path,+ surface="mcp",+ evidence_kind="inferred",+ baseline_input_tokens=8_000,+ pre_budget_input_tokens=2_000,+ delivered_input_tokens=1_500,+ )+ _record_raw(+ tmp_path,+ surface="distill",+ evidence_kind="measured",+ baseline_input_tokens=6_000,+ pre_budget_input_tokens=6_000,+ delivered_input_tokens=600,+ )+ report = load_report(tmp_path)+ assert report is not None+ assert report.input_reduction_ratio is not None+ assert 0.0 <= report.input_reduction_ratio <= 1.0+ assert report.input_reduction_ratio_p90 is not None+ assert 0.0 <= report.input_reduction_ratio_p90 <= 1.0+ assert report.baseline_saved_input_tokens <= report.baseline_input_tokens+++def _record_raw(+ repo: Path,+ *,+ surface: str,+ evidence_kind: str,+ baseline_input_tokens: int,+ pre_budget_input_tokens: int,+ delivered_input_tokens: int,+) -> None:+ """Record one event with every token dimension set independently.++ ``_record`` ties baseline and pre-budget together, which is exactly the+ case these two tests must not use.+ """+ event_id = new_event_id()+ recorder.record_event(+ repo,+ {+ "event_id": event_id,+ "idempotency_key": scoped_idempotency_key(str(repo), surface, event_id),+ "occurred_at": datetime.now(UTC),+ "surface": surface,+ "integration": "codex",+ "agent": "codex",+ "operation": "get_answer",+ "evidence_kind": evidence_kind,+ "estimator": "chars_per_token_floor_v1",+ "token_unit": "estimated_tokens",+ "result_state": "success",+ "is_usable": True,+ "baseline_input_tokens": baseline_input_tokens,+ "pre_budget_input_tokens": pre_budget_input_tokens,+ "delivered_input_tokens": delivered_input_tokens,+ },+ )+++def test_an_interaction_that_saved_nothing_is_counted_but_not_averaged_in(+ tmp_path: Path,+) -> None:+ """The ratio answers "when it fires, by how much", so a zero-saving+ interaction must not drag it down -- and must still be visible, or the+ ratio is a selection with the selection hidden."""+ _sidecar(tmp_path)+ _record_raw(+ tmp_path,+ surface="distill",+ evidence_kind="measured",+ baseline_input_tokens=1_000,+ pre_budget_input_tokens=1_000,+ delivered_input_tokens=200,+ )+ _record_raw(+ tmp_path,+ surface="distill",+ evidence_kind="measured",+ baseline_input_tokens=1_000,+ pre_budget_input_tokens=1_000,+ delivered_input_tokens=1_000,+ )+ report = load_report(tmp_path)+ assert report is not None+ assert report.baseline_events == 2+ assert report.reducing_events == 1+ # 800/1000, not 800/2000: the second interaction is coverage, not a zero.+ assert report.input_reduction_ratio == pytest.approx(0.8)+ assert report.baseline_input_tokens == 1_000diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.pyindex 534aa4d1d..c44284ddf 100644--- a/tests/unit/server/mcp/conftest.py+++ b/tests/unit/server/mcp/conftest.py@@ -715,3 +715,47 @@ def _no_savings_writes_outside_a_test_repo(monkeypatch):from repowise.core.savings import recordermonkeypatch.setattr(recorder, "record_event", lambda repo_root, payload: False)++[email protected](autouse=True)+def _no_omission_writes_outside_a_test_repo(monkeypatch, tmp_path):+ """Send dropped content somewhere disposable, not the developer's store.++ The other half of the same leak. Clearing the repo path is not enough here+ either: with no root to resolve from, ``default_store_path`` falls back to+ the current working directory, which under pytest is the checkout, so a+ test driving the budget layer wrote omission rows into the real+ ``.repowise``. Twelve of them accumulated there carrying 1,047,171 tokens+ of fixture padding, and because ``original_tokens`` is honest about the+ size of synthetic content they read as the largest omissions in the store.++ Redirected at the resolver rather than stubbed out, unlike the savings+ writer above: the budget tests assert that a dropped value comes back, so+ the store has to keep working. It just works somewhere else.+ """+ from repowise.core.distill import store as store_module+ from repowise.server.mcp_server._budget import collector++ store = tmp_path / "omissions" / "omissions.db"+ store.parent.mkdir(parents=True, exist_ok=True)+ real = store_module.default_store_path++ def resolve(start=None):+ """Redirect only the rootless fallback, which is the whole leak.++ A test that stands up its own repository and asks for *that* path gets+ the real answer: several of them write through the budget layer and+ then read the dropped content back out of the store they named, and a+ blanket redirect sends the write to one database and the read to+ another. What has no defensible answer under pytest is ``start=None``,+ where the resolver falls back to the current working directory and+ finds the developer's own checkout.+ """+ return store if start is None else real(start)++ # Both, and the pair is the point. The collector imported the resolver by+ # name at module scope, so patching only its source misses the write; every+ # reader imports it inside the function, so patching only the collector+ # misses the read.+ monkeypatch.setattr(store_module, "default_store_path", resolve)+ monkeypatch.setattr(collector, "default_store_path", resolve)diff --git a/tests/unit/server/mcp/test_counterfactual.py b/tests/unit/server/mcp/test_counterfactual.pyindex ba22387c4..3926a33f2 100644--- a/tests/unit/server/mcp/test_counterfactual.py+++ b/tests/unit/server/mcp/test_counterfactual.py@@ -249,3 +249,88 @@ def test_dead_end_records_debit_row(tmp_path, monkeypatch) -> None:assert per["saved_tokens"] == -350finally:store.close()+++def test_a_file_card_without_a_skeleton_earns_the_file_floor() -> None:+ """Skeleton-by-default went away on 2026-08-11 and nothing replaced the+ credit, so the commonest ``get_context`` call earned nothing at all."""+ result = {"targets": {"a.py": {"target": "a.py", "type": "file"}}, "_meta": {}}+ assert cf.replaced_tokens_for("get_context", result) == cf.CONTEXT_FILE_FLOOR+++def test_a_skeleton_still_wins_over_the_file_floor() -> None:+ """The floor is the fallback, never an addition: an exact size beats it."""+ result = {+ "targets": {"a.py": {"target": "a.py", "type": "file", "skeleton": {"full_tokens": 4321}}},+ "_meta": {},+ }+ assert cf.replaced_tokens_for("get_context", result) == 4321+++def test_a_failed_file_target_earns_nothing() -> None:+ result = {"targets": {"a.py": {"target": "a.py", "type": "file", "error": "nope"}}, "_meta": {}}+ assert cf.replaced_tokens_for("get_context", result) == 0+++def test_change_risk_scales_with_the_files_in_the_diff() -> None:+ """The flat floor credited 500 against live delivered sizes of 4,439-4,671,+ so the tool recorded itself as a net cost on every call it answered."""+ three = {"summary": "x", "features": {"nf": 3}}+ assert cf.replaced_tokens_for("get_change_risk", three) == (+ cf.CHANGE_RISK_FLOOR + 3 * cf.CHANGE_RISK_PER_FILE+ )+++def test_change_risk_is_capped_on_a_huge_diff() -> None:+ huge = {"summary": "x", "features": {"nf": 500}}+ assert cf.replaced_tokens_for("get_change_risk", huge) == cf.CHANGE_RISK_MAX+++def test_change_risk_falls_back_to_the_floor_without_a_file_count() -> None:+ """A payload with no ``features.nf`` keeps the old behaviour rather than+ guessing a diff size."""+ assert cf.replaced_tokens_for("get_change_risk", {"summary": "x"}) == cf.CHANGE_RISK_FLOOR+ assert cf.replaced_tokens_for("get_change_risk", {"features": {"nf": 0}}) == (+ cf.CHANGE_RISK_FLOOR+ )+ assert cf.replaced_tokens_for("get_change_risk", {"features": {"nf": "three"}}) == (+ cf.CHANGE_RISK_FLOOR+ )+++def test_health_scales_with_the_files_it_judged() -> None:+ """A flat 400 credited less than a third of one median source file, on a+ tool whose whole job is telling you about several of them."""+ result = {"targets": [{"path": "a.py"}, {"path": "b.py"}, {"path": "c.py"}]}+ assert cf.replaced_tokens_for("get_health", result) == (+ cf.HEALTH_FLOOR + 3 * cf.HEALTH_PER_FILE+ )+++def test_health_reads_repository_mode_metrics_too() -> None:+ """Targets mode names ``targets``; repository mode names ``metrics``."""+ result = {"metrics": [{"path": "a.py"}, {"path": "b.py"}]}+ assert cf.replaced_tokens_for("get_health", result) == (+ cf.HEALTH_FLOOR + 2 * cf.HEALTH_PER_FILE+ )+++def test_health_is_capped_and_falls_back_to_its_floor() -> None:+ assert cf.replaced_tokens_for("get_health", {"targets": [{}] * 500}) == cf.HEALTH_MAX+ assert cf.replaced_tokens_for("get_health", {"summary": "x"}) == cf.HEALTH_FLOOR+ assert cf.replaced_tokens_for("get_health", {"error": "no index"}) == 0+++def test_the_raised_floors_stay_under_the_artifact_they_stand_for() -> None:+ """The bar these floors are set against, asserted so a later bump has to+ argue with a measurement rather than with a feeling.++ Measured on this repository: the README is 15,941 estimated tokens; a+ ``git log -p -5`` on one hot file is 4,834-7,108; the median source file+ across 4,115 of them is 1,296 and a capped grep is 1,584.+ """+ assert cf.OVERVIEW_FLOOR < 15_941, "get_overview must undersell one README"+ assert cf.WHY_FLOOR < 4_834, "get_why must undersell one git log -p"+ assert cf.RISK_PER_TARGET < 1_296 + 1_584, "a target is a read plus a grep"+ assert cf.HEALTH_PER_FILE < 1_296, "a judged file must undersell reading it"+ assert cf.CONTEXT_FILE_FLOOR < 620, "the file floor must sit under the p25"diff --git a/tests/unit/server/test_savings_endpoint.py b/tests/unit/server/test_savings_endpoint.pyindex 9dfe74313..ac8dcbff7 100644--- a/tests/unit/server/test_savings_endpoint.py+++ b/tests/unit/server/test_savings_endpoint.py@@ -278,5 +278,13 @@ async def test_the_endpoint_and_the_core_report_agree("priced_input_savings_usd","mcp_queries_answered","dead_ends",+ # A named allowlist, so a field added to the report and forgotten at+ # the endpoint would pass this test silently. Added here on purpose.+ "baseline_events",+ "reducing_events",+ "baseline_input_tokens",+ "baseline_saved_input_tokens",+ "input_reduction_ratio",+ "input_reduction_ratio_p90",):assert data[field] == pytest.approx(getattr(report, field)), field