Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

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.ts
index 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.py
index 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.py
index 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: float
opportunity_count: int
opportunity_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 = None
per_operation: tuple[Mapping[str, Any], ...] = ()
per_surface: tuple[Mapping[str, Any], ...] = ()
#: Rows carry ``agent_display_name`` beside the slug, resolved from the
diff --git a/packages/core/src/repowise/core/savings/formulas.py b/packages/core/src/repowise/core/savings/formulas.py
index 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_tokens
diff --git a/packages/core/src/repowise/core/savings/reporting.py b/packages/core/src/repowise/core/savings/reporting.py
index 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, timedelta
from typing import Any
from 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) -> boo
return 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_price
saved_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_opportunities
diff --git a/packages/core/src/repowise/core/savings/repository.py b/packages/core/src/repowise/core/savings/repository.py
index 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_SQL
row = 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.py
index 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 = 600
def _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_FLOOR
return 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_000
RISK_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.py
index 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.py
index 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 = 0
priced_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.ts
index 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.tsx
index 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.tsx
index 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 }: SavingsLed
const 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.ts
index 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.tsx
index 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.py
index 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) == 3
assert 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_000
diff --git a/tests/unit/server/mcp/conftest.py b/tests/unit/server/mcp/conftest.py
index 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 recorder
monkeypatch.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.py
index 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"] == -350
finally:
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.py
index 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