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): add canonical event accounting (#2248)

Raghav Chamadiyab5c1b277d8ad
diff --git a/docs/architecture/savings-accounting.md b/docs/architecture/savings-accounting.md
new file mode 100644
index 000000000..add0b745d
--- /dev/null
+++ b/docs/architecture/savings-accounting.md
@@ -0,0 +1,214 @@
+# Savings accounting contract
+
+Status: Phase 0 decision record for the costs-and-savings overhaul. This document
+locks the v1 accounting truth before schema, capture, reporting, or UI work begins.
+
+## Reporting vocabulary
+
+- **Measured reduction** compares two observed artifacts on the same token scale.
+- **Inferred avoidance** compares delivered input with a versioned, documented
+ counterfactual. It is never presented as directly measured.
+- **Observed opportunity** describes potentially avoidable activity. It is not a
+ savings event and never enters achieved totals.
+- **Metered spend** is provider-reported input/output usage for Repowise model
+ work. It is reported separately from agent savings.
+- **Unknown** means evidence was unavailable. It is not rewritten to a guessed
+ agent, model, price, zero, or unsupported claim.
+
+The achieved headline is `saved_input_tokens`. Measured and inferred composition
+must be adjacent to it. If inferred tokens are nonzero, label the headline
+`Estimated agent savings`. Output savings, when explicitly evidenced, remain a
+separate dimension and do not inflate the input headline.
+
+Current distill and MCP sizes use `chars_per_token_floor_v1`, defined as
+`floor(serialized_characters / 4)`. These are estimated tokens measured on a
+stable local scale, not provider-billed tokenizer counts. Every event names its
+unit and estimator; reports must not silently combine unlike units.
+
+## Canonical dimensions and nulls
+
+Every stored v1 event has a server-generated UUID `event_id`, an idempotency key,
+UTC occurrence time, repository identity, surface, operation, evidence kind,
+confidence, result state, an explicit `is_usable` flag, and all token-dimension keys. Token values are
+nonnegative integers or `null`. `confidence` is a calibrated value from zero to
+one for the event's savings evidence, or null when evidence is insufficient; its
+meaning is versioned with the estimator.
+
+- `baseline_input_tokens`: input that would have reached the agent without the
+ evidenced Repowise operation.
+- `pre_budget_input_tokens`: observed serialized input immediately before the
+ adapter's final response budget. For distill/hook this equals the bounded raw
+ baseline; for counterfactual MCP it can differ from the replaced-input estimate.
+- `delivered_input_tokens`: final serialized input actually delivered, including
+ recoverability markers and final metadata.
+- `dropped_input_tokens`: observed input removed by the operation,
+ `clamp(pre_budget_input_tokens - delivered_input_tokens)`. It is diagnostic
+ when a counterfactual exists and is never added twice.
+- `saved_input_tokens`: achieved input avoidance after the decision table below.
+- `baseline_output_tokens`, `delivered_output_tokens`, `saved_output_tokens`:
+ the equivalent output dimensions. They are `null` unless an adapter observes
+ explicit output evidence; no fixed or estimated call-completion credit exists.
+- `omission_refs`: zero or more content-recovery references. An empty list means
+ no recovery artifact was linked, not zero savings.
+
+`null` means unavailable or not observed. Applicability comes from surface,
+evidence kind, and result state; consumers must not infer zero from `null`.
+Enum attribution uses the literal `unknown` instead of null. Optional correlation,
+model, and pricing fields use null when unavailable. Canonical serialized fields
+are present even when null, so field omission never acquires a second meaning.
+
+## Decision table
+
+All subtraction is clamped. `clamp(x)` means `max(x, 0)`.
+
+| Event/evidence | Required observed input | Canonical input formula | Evidence label | Counting rule |
+|---|---|---|---|---|
+| Distill or hook replacement | bounded raw input `B`; final delivered input `D` including marker | `dropped = clamp(B-D)`; `saved = dropped` | measured | one idempotent logical interaction |
+| MCP with counterfactual | versioned replaced-input estimate `R`; final delivered input `D`; optional pre-budget `P` | `saved = clamp(R-D)`; if `P` exists, `dropped = clamp(P-D)` for diagnostics only | inferred | counterfactual wins only for the same `event_id`; its correlated drop is not added |
+| MCP truncation without counterfactual | pre-budget response `P`; final delivered response `D` | `dropped = clamp(P-D)`; `saved = dropped` | measured | a different call to the same tool remains independently countable |
+| Native VS Code or future adapter | the same explicit pair required by the applicable row above | use the applicable measured or inferred formula | measured/inferred as evidenced | no credit merely for invoking Repowise |
+| Explicit avoided output | observed output baseline `OB`; observed delivered output `OD` | `saved_output = clamp(OB-OD)` | measured or versioned inferred | separate output total; never the input headline |
+| Successful zero/negative delta | applicable evidence exists but baseline is not greater than delivered | `saved = 0` | retain evidence kind | counts as a successful call, not a saving interaction |
+| Partial usable result | applicable evidence exists and final delivered content is usable; any omitted content is recoverable | same clamped formula as its event kind | retain evidence kind and `partial` state | reported separately from full success |
+| Partial result without sufficient evidence | one or more required dimensions unavailable | `saved = 0`; unavailable dimensions are null | unknown coverage | never infer the missing side |
+| Dead end or error | delivered overhead may be observed | `saved = 0`; overhead is diagnostic | retain evidence kind if known | not an answered query and never a negative saving |
+| Unknown result state | insufficient evidence to prove success or useful partial result | `saved = 0` | unknown coverage | excluded from achieved savings |
+| Opportunity observation | observed behavior/window only | no savings event and no achieved formula | opportunity | excluded from every achieved total |
+| Retry/duplicate | same scoped idempotency key | keep one canonical event | unchanged | duplicates do not change tokens or counts |
+
+An MCP query count is the number of unique successful or usable-partial MCP
+interactions after idempotency, including a valid zero-saving result. Dead ends,
+errors, unknown results, ledger rows, omission rows, and recovery blobs are not
+queries answered. A saving-interaction count additionally requires
+`saved_input_tokens > 0`.
+
+`is_usable` describes whether the delivered result can be consumed by the agent;
+it is independent of whether the baseline needed to calculate savings is known.
+Success requires true, dead end/error/unknown require false, and partial may be
+either. Query counts use result state plus `is_usable`, never token-field presence.
+
+## Correlation and attribution
+
+MCP JSON-RPC request IDs are client-chosen and connection-scoped, so they are not
+canonical event IDs. The server generates a UUID per invocation. Where available,
+the adapter uses request ID plus a server/session namespace to form bounded,
+hashed correlation evidence and an idempotency key; raw client IDs are not
+persisted. The same generated `event_id` must reach response budgeting,
+counterfactual estimation, dead-end handling, and the final writer.
+
+FastMCP exposes a request ID across stdio, SSE, and streamable HTTP. On normal
+stateful sessions it also exposes initialize-time `clientInfo`, which is
+client-declared rather than authenticated. Mapping version `mcp_client_info_v1`
+lowercases the name and removes non-alphanumerics, then accepts only:
+`claude`/`claudecode` -> `claude_code`, `codex` -> `codex`, `opencode` ->
+`opencode`, `hermes` -> `hermes`, `cursor` -> `cursor`, and `vscode` ->
+`vscode`. Every other value, including a generic MCP client, maps to `unknown`.
+Never infer agent or
+model from headers, capabilities, environment variables, executable parents, or
+transport. Session/request/tool-call IDs and model remain null until an adapter
+explicitly supplies trustworthy evidence.
+
+The v1 metadata allow-list is `client_info_normalized` and
+`identity_mapping_version`. Values are bounded strings; no raw prompts,
+transcripts, commands, headers, environment values, or secrets are accepted.
+
+Native VS Code LM invocations generate an internal UUID at invocation entry and
+carry it through REST work and final response bounding. The opaque VS Code
+`toolInvocationToken` is not stringified or persisted. If server-side correlation
+is later required, use an internal request header and request-local state; do not
+expand public response models or use a process-global value. Delivered size is
+measured after the VS Code host's final cap.
+
+## Legacy omission fields
+
+The legacy `omissions` table is a recovery store, not an accounting event log.
+Its content hash `ref` identifies content, so byte-identical omissions from two
+calls collapse to one row. Its row count cannot represent logical interactions.
+
+- MCP budgeting persists the dropped recovery document or inline chunk.
+ `original_tokens` is the estimated size of that persisted dropped artifact,
+ including recovery-document framing where present; `kept_tokens` is always
+ zero. Neither is whole-response before/after size.
+- Distill persists the entire raw command artifact. `original_tokens` is that
+ artifact's estimated size and `kept_tokens` is the retained filtered body
+ before the recoverability marker. Actual delivered input includes the marker.
+
+Therefore the columns have producer-specific meanings. Preserve them and
+`evidence_references` for expand/recovery, but do not use either column or the
+omission row count in canonical savings arithmetic. New events link omission
+references without duplicating their content.
+
+## Pricing
+
+Price each event only from the model, source/version, currency, and input/output
+rates captured with that event. Savings reports expose priced and unpriced tokens
+separately. They never reprice history from the newest session. Input and output
+rates apply only to their matching dimensions. The old fixed 60-output-token
+credit is removed; nullable output fields remain so explicit evidence can be
+supported without invention.
+
+Repowise's own `llm_costs` provider-token spend is a separate metered-spend
+section. It is not subtracted from or merged into achieved agent-token savings.
+
+## Hosted and shared-presentation boundary
+
+The verified hosted backend defines `total_cents` as the lifetime absolute value
+of negative `credit_transactions.amount_cents`, scoped to authenticated user and
+repository. `by_type` partitions those debits into indexing, chat, reindex, and
+other, so its money buckets sum to `total_cents`; positive/zero rows do not add
+spend. The current `transaction_count` is the number of fetched ledger rows and
+can include non-debits. Anonymous public-snapshot callers receive zero billing
+spend. Hosted engine `llm_costs` telemetry is a separate field.
+
+Accordingly, hosted credit spend remains a named host-only billing section. It is
+not equivalent to OSS `wiki.db.llm_costs` and is not mapped into canonical
+repository model spend or savings.
+
+`frontend/docs/DESIGN_LANGUAGE.md` remains binding for hosted and OSS. The shared
+`@repowise-dev/ui` savings surface receives a pure, already-derived presentation
+model plus link/action capabilities. It performs no fetching, authentication,
+routing, pricing, correlation, or accounting and contains no `isHosted` branch.
+Hosts adapt their real wire contracts and retain hosted-only billing as a sibling
+capability. Visual hierarchy, evidence labels, and interaction semantics stay
+shared.
+
+## Savings reset disclosure
+
+The clean telemetry reset is a user-visible methodology change, not silent data
+loss. On the first costs-page visit after the reset, show a calm inline
+informational notice beside the savings lede:
+
+> **Savings accounting has been upgraded**
+> Savings now use interaction-level evidence for more accurate, auditable totals.
+> Previous savings estimates were not compatible with the new methodology, so
+> savings history restarted on **[reset date]**. Omission history and other
+> repository data were not deleted.
+
+The notice has a normal `See what changed` link and a dismiss control. It is not a
+modal, warning, error, toast, or global promotional banner: it must not steal
+focus or interrupt work. After dismissal, the reset date and methodology link
+remain quietly visible near the total.
+
+Presentation is a reusable controlled `DismissibleNotice` primitive in
+`@repowise-dev/ui`. It accepts content, neutral/info tone, optional action/link,
+and `onDismiss`; it owns no storage, fetching, routes, or host detection. Each host
+decides whether it is visible and persists a versioned dismissal key scoped to
+repository plus accounting-method version. This keeps localStorage, user
+preferences, and future server persistence interchangeable without turning a rare
+announcement into a general modal framework. Existing feature-specific banners
+may migrate only when doing so is independently useful, not as required scope for
+this overhaul.
+
+## Frozen diagnostic baseline
+
+On 2026-09-13 a SQLite online backup of the worktree-local omission database at
+commit `a3e49b7692be` was frozen, queried, and deleted. Its SHA-256 was
+`23E44B9E4C16A29087D5A9C2FB4F5EACF366C16E126281D44CA9B135941A5298`.
+It contained 953 MCP ledger rows and 36 MCP omission artifacts. The legacy
+tool-wide algorithm reported 7,495,645 MCP tokens; blindly adding both signal
+sets produced 7,959,262. The clamped non-MCP ledger reduction was 1,276,569.
+
+These values are diagnostic reproduction evidence only. No canonical historical
+MCP total can be reconstructed because there is no interaction ID and identical
+omitted content is hash-deduplicated. Product expectations come exclusively from
+the deterministic fixture in `tests/fixtures/savings/mixed_agents_v1.json`.
diff --git a/packages/core/src/repowise/core/distill/store.py b/packages/core/src/repowise/core/distill/store.py
index 34a176869..cb4395d44 100644
--- a/packages/core/src/repowise/core/distill/store.py
+++ b/packages/core/src/repowise/core/distill/store.py
@@ -21,6 +21,7 @@ import structlog
from repowise.core.distill import tracking
from repowise.core.distill.markers import REF_LENGTH, is_valid_ref
+from repowise.core.savings import schema as savings_schema
from repowise.core.sqlite_pragmas import apply_sqlite_pragmas
logger = structlog.get_logger(__name__)
@@ -36,35 +37,6 @@ DEFAULT_MAX_MB = 50
#: Retry window for a contended open, in milliseconds.
_BUSY_TIMEOUT_MS = 5000
-_SCHEMA = """
-CREATE TABLE IF NOT EXISTS omissions (
- ref TEXT PRIMARY KEY,
- content BLOB NOT NULL,
- source TEXT NOT NULL,
- created_at REAL NOT NULL,
- original_tokens INTEGER NOT NULL,
- kept_tokens INTEGER NOT NULL,
- access_count INTEGER NOT NULL DEFAULT 0
-);
-CREATE TABLE IF NOT EXISTS evidence_references (
- ref TEXT PRIMARY KEY,
- content BLOB NOT NULL,
- repository TEXT NOT NULL,
- created_at REAL NOT NULL
-);
-CREATE TABLE IF NOT EXISTS savings (
- id INTEGER PRIMARY KEY AUTOINCREMENT,
- created_at REAL NOT NULL,
- filter TEXT NOT NULL,
- source TEXT NOT NULL,
- command TEXT,
- raw_tokens INTEGER NOT NULL,
- distilled_tokens INTEGER NOT NULL
-);
-CREATE INDEX IF NOT EXISTS idx_omissions_created ON omissions(created_at);
-CREATE INDEX IF NOT EXISTS idx_savings_created ON savings(created_at);
-"""
-
def default_store_path(start: Path | None = None) -> Path:
"""Resolve the omissions DB path for the repo containing *start*.
@@ -107,10 +79,9 @@ class OmissionStore:
self.ttl_days = ttl_days
self.max_mb = max_mb
db_path.parent.mkdir(parents=True, exist_ok=True)
- self._conn = sqlite3.connect(db_path)
+ self._conn = sqlite3.connect(db_path, isolation_level=None)
apply_sqlite_pragmas(self._conn, _BUSY_TIMEOUT_MS)
- self._conn.executescript(_SCHEMA)
- self._conn.commit()
+ savings_schema.initialize_savings_schema(self._conn)
@classmethod
def open_default(cls, start: Path | None = None) -> OmissionStore:
@@ -211,9 +182,7 @@ class OmissionStore:
# -- machine-joinable evidence references -----------------------------
- def put_evidence_reference(
- self, ref: str, content: str, *, repository: str
- ) -> None:
+ def put_evidence_reference(self, ref: str, content: str, *, repository: str) -> None:
"""Persist one exact evidence object under its canonical public id."""
blob = zlib.compress(content.encode("utf-8"))
@@ -291,8 +260,8 @@ def _filter_lines(content: str, query: str) -> str:
try:
pattern = re.compile(query)
- matcher = pattern.search
except re.error:
- matcher = lambda line: query in line # noqa: E731
- matched = [line for line in content.splitlines() if matcher(line)]
+ matched = [line for line in content.splitlines() if query in line]
+ else:
+ matched = [line for line in content.splitlines() if pattern.search(line)]
return "\n".join(matched)
diff --git a/packages/core/src/repowise/core/savings/__init__.py b/packages/core/src/repowise/core/savings/__init__.py
new file mode 100644
index 000000000..a1816e9f8
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/__init__.py
@@ -0,0 +1,22 @@
+"""Canonical savings accounting domain."""
+
+from repowise.core.savings.contracts import OpportunityObservation, SavingsEvent, SavingsReport
+from repowise.core.savings.correlation import (
+ hash_correlation_evidence,
+ new_event_id,
+ scoped_idempotency_key,
+)
+from repowise.core.savings.formulas import TokenAccounting, calculate_token_accounting
+from repowise.core.savings.repository import SavingsRepository
+
+__all__ = [
+ "OpportunityObservation",
+ "SavingsEvent",
+ "SavingsReport",
+ "SavingsRepository",
+ "TokenAccounting",
+ "calculate_token_accounting",
+ "hash_correlation_evidence",
+ "new_event_id",
+ "scoped_idempotency_key",
+]
diff --git a/packages/core/src/repowise/core/savings/contracts.py b/packages/core/src/repowise/core/savings/contracts.py
new file mode 100644
index 000000000..d01c2d652
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/contracts.py
@@ -0,0 +1,316 @@
+"""Versioned, validated contracts for savings events and reports."""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any
+from uuid import UUID
+
+from repowise.core.savings.correlation import hash_correlation_evidence, new_event_id
+from repowise.core.savings.formulas import TokenAccounting, calculate_token_accounting
+from repowise.core.savings.normalization import normalize_metadata
+
+SCHEMA_VERSION = 1
+SURFACES = frozenset({"distill", "hook", "mcp", "vscode_lm"})
+EVIDENCE_KINDS = frozenset({"measured", "inferred"})
+RESULT_STATES = frozenset({"success", "dead_end", "error", "partial", "unknown"})
+IDENTITIES = frozenset(
+ {"claude_code", "codex", "opencode", "hermes", "cursor", "vscode", "unknown"}
+)
+_HASH_RE = re.compile(r"sha256:[0-9a-f]{64}\Z")
+
+
+def utc_text(value: str | datetime) -> str:
+ """Normalize an aware timestamp to a lexically sortable UTC string."""
+ parsed = (
+ datetime.fromisoformat(value.replace("Z", "+00:00")) if isinstance(value, str) else value
+ )
+ if parsed.tzinfo is None:
+ raise ValueError("occurred_at must include a timezone")
+ return parsed.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def _bounded(value: object | None, name: str, limit: int = 128) -> str | None:
+ if value is None:
+ return None
+ if not isinstance(value, str) or not value or len(value) > limit:
+ raise ValueError(f"{name} must be a non-empty string of at most {limit} characters")
+ return value
+
+
+def _correlation(
+ value: object | None, *, kind: str, repository_id: str, surface: str
+) -> str | None:
+ bounded = _bounded(value, f"{kind}_id", 128)
+ if bounded is None or _HASH_RE.fullmatch(bounded):
+ return bounded
+ return hash_correlation_evidence(f"{repository_id}:{surface}:{kind}", bounded)
+
+
+@dataclass(frozen=True, slots=True)
+class _Semantics:
+ surface: str
+ evidence_kind: str
+ result_state: str
+ integration: str
+ agent: str
+ is_usable: bool
+
+
+@dataclass(frozen=True, slots=True)
+class _Pricing:
+ confidence: float | None
+ model: str | None
+ currency: str | None
+ source: str | None
+ version: str | None
+ input_rate: float | None
+ output_rate: float | None
+
+
+def _event_identity(value: Mapping[str, Any], accept_event_id: bool) -> tuple[str, str]:
+ event_id = value.get("event_id") if accept_event_id else None
+ event_id = str(event_id or new_event_id())
+ UUID(event_id)
+ idempotency_key = str(value["idempotency_key"])
+ if not _HASH_RE.fullmatch(idempotency_key):
+ raise ValueError("idempotency_key must be a sha256 digest")
+ return event_id, idempotency_key
+
+
+def _semantics(value: Mapping[str, Any]) -> _Semantics:
+ surface = str(value["surface"])
+ evidence_kind = str(value["evidence_kind"])
+ result_state = str(value["result_state"])
+ integration = str(value.get("integration", "unknown"))
+ agent = str(value.get("agent", "unknown"))
+ if surface not in SURFACES:
+ raise ValueError(f"unsupported surface: {surface}")
+ if evidence_kind not in EVIDENCE_KINDS:
+ raise ValueError(f"unsupported evidence kind: {evidence_kind}")
+ if result_state not in RESULT_STATES:
+ raise ValueError(f"unsupported result state: {result_state}")
+ if integration not in IDENTITIES or agent not in IDENTITIES:
+ raise ValueError("integration and agent must use the v1 identity vocabulary")
+ is_usable = value.get("is_usable")
+ if not isinstance(is_usable, bool):
+ raise ValueError("is_usable must be explicit")
+ expected_unusable = result_state in {"dead_end", "error", "unknown"}
+ if (result_state == "success" and not is_usable) or (expected_unusable and is_usable):
+ raise ValueError("is_usable conflicts with result_state")
+ return _Semantics(surface, evidence_kind, result_state, integration, agent, is_usable)
+
+
+def _accounting(value: Mapping[str, Any], semantics: _Semantics) -> TokenAccounting:
+ accounting = calculate_token_accounting(
+ surface=semantics.surface,
+ evidence_kind=semantics.evidence_kind,
+ result_state=semantics.result_state,
+ is_usable=semantics.is_usable,
+ baseline_input_tokens=value.get("baseline_input_tokens"),
+ pre_budget_input_tokens=value.get("pre_budget_input_tokens"),
+ delivered_input_tokens=value.get("delivered_input_tokens"),
+ baseline_output_tokens=value.get("baseline_output_tokens"),
+ delivered_output_tokens=value.get("delivered_output_tokens"),
+ )
+ for name in ("dropped_input_tokens", "saved_input_tokens", "saved_output_tokens"):
+ if name in value and value[name] != getattr(accounting, name):
+ raise ValueError(f"{name} does not match the v1 formula")
+ return accounting
+
+
+def _pricing(value: Mapping[str, Any]) -> _Pricing:
+ confidence = value.get("confidence")
+ if confidence is not None:
+ confidence = float(confidence)
+ if not 0 <= confidence <= 1:
+ raise ValueError("confidence must be between zero and one")
+ input_value = value.get("input_rate_usd_per_million")
+ output_value = value.get("output_rate_usd_per_million")
+ input_rate = float(input_value) if input_value is not None else None
+ output_rate = float(output_value) if output_value is not None else None
+ rates = (input_rate, output_rate)
+ if any(rate is not None and (not math.isfinite(rate) or rate < 0) for rate in rates):
+ raise ValueError("pricing rates must be finite and nonnegative")
+ currency = _bounded(value.get("currency"), "currency", 3)
+ source = _bounded(value.get("pricing_source"), "pricing_source", 64)
+ version = _bounded(value.get("pricing_version"), "pricing_version", 64)
+ model = _bounded(value.get("model"), "model", 128)
+ if any(rate is not None for rate in rates) and (
+ currency != "USD" or not model or not source or not version
+ ):
+ raise ValueError("priced events require model and a complete USD pricing snapshot")
+ return _Pricing(confidence, model, currency, source, version, input_rate, output_rate)
+
+
+def _omission_refs(value: Mapping[str, Any]) -> tuple[str, ...]:
+ refs = tuple(dict.fromkeys(value.get("omission_refs") or ()))
+ if any(not isinstance(ref, str) or not re.fullmatch(r"[0-9a-f]{12}", ref) for ref in refs):
+ raise ValueError("omission_refs must contain canonical 12-hex references")
+ return refs
+
+
+@dataclass(frozen=True, slots=True)
+class SavingsEvent:
+ event_id: str
+ idempotency_key: str
+ occurred_at: str
+ repository_id: str
+ surface: str
+ integration: str
+ agent: str
+ operation: str
+ evidence_kind: str
+ confidence: float | None
+ estimator: str
+ token_unit: str
+ result_state: str
+ is_usable: bool
+ baseline_input_tokens: int | None
+ pre_budget_input_tokens: int | None
+ delivered_input_tokens: int | None
+ dropped_input_tokens: int | None
+ saved_input_tokens: int
+ baseline_output_tokens: int | None
+ delivered_output_tokens: int | None
+ saved_output_tokens: int | None
+ subagent_id: str | None = None
+ session_id: str | None = None
+ request_id: str | None = None
+ tool_call_id: str | None = None
+ model: str | None = None
+ currency: str | None = None
+ pricing_source: str | None = None
+ pricing_version: str | None = None
+ input_rate_usd_per_million: float | None = None
+ output_rate_usd_per_million: float | None = None
+ omission_refs: tuple[str, ...] = ()
+ metadata: Mapping[str, str] = field(default_factory=dict)
+ schema_version: int = SCHEMA_VERSION
+
+ @classmethod
+ def from_mapping(
+ cls, value: Mapping[str, Any], *, accept_event_id: bool = False
+ ) -> SavingsEvent:
+ """Validate and normalize an adapter payload into a canonical event."""
+ event_id, idempotency_key = _event_identity(value, accept_event_id)
+ semantics = _semantics(value)
+ accounting = _accounting(value, semantics)
+ pricing = _pricing(value)
+ refs = _omission_refs(value)
+ repository_id = _bounded(value["repository_id"], "repository_id", 256) or ""
+ session_id = _correlation(
+ value.get("session_id"),
+ kind="session",
+ repository_id=repository_id,
+ surface=semantics.surface,
+ )
+ request_id = _correlation(
+ value.get("request_id"),
+ kind="request",
+ repository_id=repository_id,
+ surface=semantics.surface,
+ )
+ tool_call_id = _correlation(
+ value.get("tool_call_id"),
+ kind="tool_call",
+ repository_id=repository_id,
+ surface=semantics.surface,
+ )
+
+ return cls(
+ event_id=event_id,
+ idempotency_key=idempotency_key,
+ occurred_at=utc_text(value["occurred_at"]),
+ repository_id=repository_id,
+ surface=semantics.surface,
+ integration=semantics.integration,
+ agent=semantics.agent,
+ operation=_bounded(value["operation"], "operation", 128) or "",
+ evidence_kind=semantics.evidence_kind,
+ confidence=pricing.confidence,
+ estimator=_bounded(value["estimator"], "estimator", 128) or "",
+ token_unit=_bounded(value["token_unit"], "token_unit", 64) or "",
+ result_state=semantics.result_state,
+ is_usable=semantics.is_usable,
+ baseline_input_tokens=accounting.baseline_input_tokens,
+ pre_budget_input_tokens=accounting.pre_budget_input_tokens,
+ delivered_input_tokens=accounting.delivered_input_tokens,
+ dropped_input_tokens=accounting.dropped_input_tokens,
+ saved_input_tokens=accounting.saved_input_tokens,
+ baseline_output_tokens=accounting.baseline_output_tokens,
+ delivered_output_tokens=accounting.delivered_output_tokens,
+ saved_output_tokens=accounting.saved_output_tokens,
+ subagent_id=_bounded(value.get("subagent_id"), "subagent_id"),
+ session_id=session_id,
+ request_id=request_id,
+ tool_call_id=tool_call_id,
+ model=pricing.model,
+ currency=pricing.currency,
+ pricing_source=pricing.source,
+ pricing_version=pricing.version,
+ input_rate_usd_per_million=pricing.input_rate,
+ output_rate_usd_per_million=pricing.output_rate,
+ omission_refs=refs,
+ metadata=normalize_metadata(value.get("metadata")),
+ )
+
+ def metadata_json(self) -> str:
+ return json.dumps(dict(self.metadata), sort_keys=True, separators=(",", ":"))
+
+
+@dataclass(frozen=True, slots=True)
+class OpportunityObservation:
+ observation_id: str
+ occurred_at: str
+ repository_id: str
+ integration: str
+ kind: str
+ estimated_potential_input_tokens: int
+
+ @classmethod
+ def from_mapping(
+ cls, value: Mapping[str, Any], *, repository_id: str | None = None
+ ) -> OpportunityObservation:
+ integration = str(value.get("integration", "unknown"))
+ if integration not in IDENTITIES:
+ integration = "unknown"
+ tokens = value.get("estimated_potential_input_tokens", 0)
+ if isinstance(tokens, bool) or not isinstance(tokens, int):
+ raise TypeError("estimated opportunity tokens must be an integer")
+ return cls(
+ observation_id=_bounded(value["observation_id"], "observation_id", 128) or "",
+ occurred_at=utc_text(value["occurred_at"]),
+ repository_id=_bounded(repository_id or value["repository_id"], "repository_id", 256)
+ or "",
+ integration=integration,
+ kind=_bounded(value["kind"], "kind", 128) or "",
+ estimated_potential_input_tokens=max(tokens, 0),
+ )
+
+
+@dataclass(frozen=True, slots=True)
+class SavingsReport:
+ unique_events: int
+ successful_or_usable_partial_events: int
+ saving_interactions: int
+ mcp_queries_answered: int
+ dead_ends: int
+ saved_input_tokens: int
+ measured_saved_input_tokens: int
+ inferred_saved_input_tokens: int
+ priced_saved_input_tokens: int
+ unpriced_saved_input_tokens: int
+ priced_input_savings_usd: float
+ saved_output_tokens: int | None
+ priced_saved_output_tokens: int
+ unpriced_saved_output_tokens: int
+ priced_output_savings_usd: float
+ opportunity_count: int
+ opportunity_tokens_excluded: int
+ per_operation: tuple[Mapping[str, Any], ...] = ()
diff --git a/packages/core/src/repowise/core/savings/correlation.py b/packages/core/src/repowise/core/savings/correlation.py
new file mode 100644
index 000000000..c335337df
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/correlation.py
@@ -0,0 +1,39 @@
+"""Privacy-conscious identity and correlation helpers."""
+
+from __future__ import annotations
+
+import hashlib
+from uuid import uuid4
+
+
+def new_event_id() -> str:
+ """Return a server-owned UUID for one logical interaction."""
+ return str(uuid4())
+
+
+def _digest(*parts: str) -> str:
+ digest = hashlib.sha256()
+ for part in parts:
+ value = part.encode("utf-8", errors="strict")
+ digest.update(len(value).to_bytes(8, "big"))
+ digest.update(value)
+ return f"sha256:{digest.hexdigest()}"
+
+
+def hash_correlation_evidence(namespace: str, value: object) -> str:
+ """Hash connection-scoped evidence without persisting its raw value."""
+ if not namespace or value is None or str(value) == "":
+ raise ValueError("correlation namespace and value must be non-empty")
+ return _digest(namespace, str(value))
+
+
+def scoped_idempotency_key(repository_id: str, surface: str, *parts: object) -> str:
+ """Build a bounded repository/surface-scoped retry key."""
+ if (
+ not repository_id
+ or not surface
+ or not parts
+ or any(part is None or str(part) == "" for part in parts)
+ ):
+ raise ValueError("repository, surface, and evidence are required")
+ return _digest(repository_id, surface, *(str(part) for part in parts))
diff --git a/packages/core/src/repowise/core/savings/formulas.py b/packages/core/src/repowise/core/savings/formulas.py
new file mode 100644
index 000000000..88186ad14
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/formulas.py
@@ -0,0 +1,74 @@
+"""Pure, clamped token-accounting formulas."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class TokenAccounting:
+ baseline_input_tokens: int | None
+ pre_budget_input_tokens: int | None
+ delivered_input_tokens: int | None
+ dropped_input_tokens: int | None
+ saved_input_tokens: int
+ baseline_output_tokens: int | None
+ delivered_output_tokens: int | None
+ saved_output_tokens: int | None
+
+
+def _token(value: int | None) -> int | None:
+ if value is None:
+ return None
+ if isinstance(value, bool) or not isinstance(value, int):
+ raise TypeError("token dimensions must be integers or None")
+ return max(value, 0)
+
+
+def _delta(before: int | None, after: int | None) -> int | None:
+ if before is None or after is None:
+ return None
+ return max(before - after, 0)
+
+
+def calculate_token_accounting(
+ *,
+ surface: str,
+ evidence_kind: str,
+ result_state: str,
+ is_usable: bool,
+ baseline_input_tokens: int | None,
+ pre_budget_input_tokens: int | None,
+ delivered_input_tokens: int | None,
+ baseline_output_tokens: int | None = None,
+ delivered_output_tokens: int | None = None,
+) -> TokenAccounting:
+ """Normalize dimensions and apply the v1 decision table."""
+ baseline = _token(baseline_input_tokens)
+ pre_budget = _token(pre_budget_input_tokens)
+ delivered = _token(delivered_input_tokens)
+ output_baseline = _token(baseline_output_tokens)
+ output_delivered = _token(delivered_output_tokens)
+ dropped = _delta(pre_budget, delivered)
+
+ achieved = result_state == "success" or (result_state == "partial" and is_usable)
+ if not achieved:
+ saved = 0
+ saved_output = 0 if output_baseline is not None and output_delivered is not None else None
+ else:
+ formula_baseline = baseline
+ if evidence_kind == "measured" and surface == "mcp":
+ formula_baseline = pre_budget
+ saved = _delta(formula_baseline, delivered) or 0
+ saved_output = _delta(output_baseline, output_delivered)
+
+ return TokenAccounting(
+ baseline_input_tokens=baseline,
+ pre_budget_input_tokens=pre_budget,
+ delivered_input_tokens=delivered,
+ dropped_input_tokens=dropped,
+ saved_input_tokens=saved,
+ baseline_output_tokens=output_baseline,
+ delivered_output_tokens=output_delivered,
+ saved_output_tokens=saved_output,
+ )
diff --git a/packages/core/src/repowise/core/savings/normalization.py b/packages/core/src/repowise/core/savings/normalization.py
new file mode 100644
index 000000000..2e9378ca4
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/normalization.py
@@ -0,0 +1,42 @@
+"""Pure normalization rules shared by future capture adapters."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+
+IDENTITY_MAPPING_VERSION = "mcp_client_info_v1"
+_IDENTITIES = {
+ "claude": "claude_code",
+ "claudecode": "claude_code",
+ "codex": "codex",
+ "opencode": "opencode",
+ "hermes": "hermes",
+ "cursor": "cursor",
+ "vscode": "vscode",
+}
+METADATA_ALLOWLIST = frozenset({"client_info_normalized", "identity_mapping_version"})
+
+
+def normalize_mcp_identity(client_name: object | None) -> tuple[str, dict[str, str]]:
+ """Map self-declared MCP clientInfo through the versioned allow-list."""
+ normalized = re.sub(r"[^a-z0-9]", "", str(client_name or "").lower())[:64]
+ identity = _IDENTITIES.get(normalized, "unknown")
+ metadata = {"identity_mapping_version": IDENTITY_MAPPING_VERSION}
+ if normalized:
+ metadata["client_info_normalized"] = normalized
+ return identity, metadata
+
+
+def normalize_metadata(metadata: Mapping[str, object] | None) -> dict[str, str]:
+ """Reject arbitrary telemetry and bound the two permitted string fields."""
+ if metadata is None:
+ return {}
+ if not set(metadata) <= METADATA_ALLOWLIST:
+ raise ValueError(f"metadata keys must be drawn from {sorted(METADATA_ALLOWLIST)}")
+ normalized: dict[str, str] = {}
+ for key, value in metadata.items():
+ if not isinstance(value, str) or not value or len(value) > 64:
+ raise ValueError(f"metadata.{key} must be a non-empty string of at most 64 characters")
+ normalized[key] = value
+ return normalized
diff --git a/packages/core/src/repowise/core/savings/pricing.py b/packages/core/src/repowise/core/savings/pricing.py
new file mode 100644
index 000000000..ca4091218
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/pricing.py
@@ -0,0 +1,14 @@
+"""Per-event pricing projections; history is never repriced."""
+
+from __future__ import annotations
+
+import math
+
+
+def price_tokens(tokens: int, usd_per_million: float | None) -> float | None:
+ """Price one token dimension from its captured event-time rate."""
+ if usd_per_million is None:
+ return None
+ if not math.isfinite(usd_per_million) or usd_per_million < 0:
+ raise ValueError("pricing rate must be finite and nonnegative")
+ return max(tokens, 0) * usd_per_million / 1_000_000
diff --git a/packages/core/src/repowise/core/savings/reporting.py b/packages/core/src/repowise/core/savings/reporting.py
new file mode 100644
index 000000000..8f1282a8d
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/reporting.py
@@ -0,0 +1,96 @@
+"""Pure report construction over already-normalized domain records."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+from datetime import datetime, timedelta
+
+from repowise.core.savings.contracts import OpportunityObservation, SavingsEvent, SavingsReport
+from repowise.core.savings.pricing import price_tokens
+
+
+def _included(occurred_at: str, cutoff: datetime | None, as_of: datetime) -> bool:
+ timestamp = datetime.fromisoformat(occurred_at.replace("Z", "+00:00"))
+ return timestamp <= as_of and (cutoff is None or timestamp >= cutoff)
+
+
+def build_report(
+ events: Iterable[SavingsEvent],
+ opportunities: Iterable[OpportunityObservation] = (),
+ *,
+ as_of: datetime,
+ days: int | None = None,
+ max_breakdowns: int = 100,
+) -> SavingsReport:
+ """Build a hand-checkable report while keeping opportunities separate."""
+ if as_of.tzinfo is None:
+ raise ValueError("as_of must include a timezone")
+ if days is not None and days < 0:
+ raise ValueError("days cannot be negative")
+ cutoff = as_of - timedelta(days=days) if days is not None else None
+ scoped = [event for event in events if _included(event.occurred_at, cutoff, as_of)]
+ scoped_opportunities = [
+ item for item in opportunities if _included(item.occurred_at, cutoff, as_of)
+ ]
+ per_operation: dict[str, list[int]] = defaultdict(lambda: [0, 0])
+ input_usd = 0.0
+ output_usd = 0.0
+ priced_input = 0
+ priced_output = 0
+ output_evidence_events = 0
+ for event in scoped:
+ per_operation[event.operation][0] += 1
+ per_operation[event.operation][1] += event.saved_input_tokens
+ input_price = price_tokens(event.saved_input_tokens, event.input_rate_usd_per_million)
+ if input_price is not None:
+ priced_input += event.saved_input_tokens
+ input_usd += input_price
+ if event.saved_output_tokens is not None:
+ output_evidence_events += 1
+ output_price = price_tokens(
+ event.saved_output_tokens, event.output_rate_usd_per_million
+ )
+ if output_price is not None:
+ priced_output += event.saved_output_tokens
+ 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)
+ breakdown = tuple(
+ {"operation": operation, "events": values[0], "saved_input_tokens": values[1]}
+ for operation, values in sorted(
+ per_operation.items(), key=lambda item: (-item[1][1], item[0])
+ )[: max(0, min(max_breakdowns, 100))]
+ )
+
+ def answered(event: SavingsEvent) -> bool:
+ return event.result_state == "success" or (
+ event.result_state == "partial" and event.is_usable
+ )
+
+ return SavingsReport(
+ unique_events=len(scoped),
+ successful_or_usable_partial_events=sum(answered(event) for event in scoped),
+ saving_interactions=sum(event.saved_input_tokens > 0 for event in scoped),
+ mcp_queries_answered=sum(event.surface == "mcp" and answered(event) for event in scoped),
+ dead_ends=sum(event.result_state == "dead_end" for event in scoped),
+ saved_input_tokens=saved_input,
+ measured_saved_input_tokens=sum(
+ event.saved_input_tokens for event in scoped if event.evidence_kind == "measured"
+ ),
+ inferred_saved_input_tokens=sum(
+ event.saved_input_tokens for event in scoped if event.evidence_kind == "inferred"
+ ),
+ priced_saved_input_tokens=priced_input,
+ unpriced_saved_input_tokens=saved_input - priced_input,
+ priced_input_savings_usd=input_usd,
+ saved_output_tokens=saved_output if output_evidence_events else None,
+ priced_saved_output_tokens=priced_output,
+ unpriced_saved_output_tokens=saved_output - priced_output,
+ priced_output_savings_usd=output_usd,
+ opportunity_count=len(scoped_opportunities),
+ opportunity_tokens_excluded=sum(
+ item.estimated_potential_input_tokens for item in scoped_opportunities
+ ),
+ per_operation=breakdown,
+ )
diff --git a/packages/core/src/repowise/core/savings/repository.py b/packages/core/src/repowise/core/savings/repository.py
new file mode 100644
index 000000000..d925c5295
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/repository.py
@@ -0,0 +1,217 @@
+"""Short transactional writes and bounded aggregate reads for savings data."""
+
+from __future__ import annotations
+
+import sqlite3
+from datetime import datetime, timedelta
+from typing import Any
+
+from repowise.core.savings.contracts import (
+ OpportunityObservation,
+ SavingsEvent,
+ SavingsReport,
+ utc_text,
+)
+
+_EVENT_COLUMNS = (
+ "event_id",
+ "schema_version",
+ "idempotency_key",
+ "occurred_at",
+ "repository_id",
+ "surface",
+ "integration",
+ "agent",
+ "subagent_id",
+ "session_id",
+ "request_id",
+ "tool_call_id",
+ "operation",
+ "evidence_kind",
+ "confidence",
+ "estimator",
+ "token_unit",
+ "result_state",
+ "is_usable",
+ "baseline_input_tokens",
+ "pre_budget_input_tokens",
+ "delivered_input_tokens",
+ "dropped_input_tokens",
+ "saved_input_tokens",
+ "baseline_output_tokens",
+ "delivered_output_tokens",
+ "saved_output_tokens",
+ "model",
+ "currency",
+ "pricing_source",
+ "pricing_version",
+ "input_rate_usd_per_million",
+ "output_rate_usd_per_million",
+ "metadata_json",
+)
+
+
+class SavingsRepository:
+ """Repository over an initialized omissions-sidecar connection."""
+
+ def __init__(self, connection: sqlite3.Connection) -> None:
+ self._conn = connection
+
+ def record_event(self, event: SavingsEvent) -> bool:
+ """Atomically insert an event and its links; return false for a retry."""
+ values = [getattr(event, column) for column in _EVENT_COLUMNS[:-1]]
+ values[18] = int(event.is_usable)
+ values.append(event.metadata_json())
+ placeholders = ",".join("?" for _ in _EVENT_COLUMNS)
+ self._conn.execute("BEGIN IMMEDIATE")
+ try:
+ cursor = self._conn.execute(
+ f"INSERT OR IGNORE INTO savings_events ({','.join(_EVENT_COLUMNS)}) "
+ f"VALUES ({placeholders})",
+ values,
+ )
+ if cursor.rowcount == 0:
+ existing = self._conn.execute(
+ f"SELECT {','.join(_EVENT_COLUMNS[1:])} FROM savings_events "
+ "WHERE repository_id = ? AND idempotency_key = ?",
+ (event.repository_id, event.idempotency_key),
+ ).fetchone()
+ if existing is None or tuple(existing) != tuple(values[1:]):
+ raise ValueError("idempotency key conflicts with a different event payload")
+ self._conn.commit()
+ return False
+ self._conn.executemany(
+ "INSERT INTO savings_event_omissions(event_id, omission_ref) VALUES (?, ?)",
+ ((event.event_id, ref) for ref in event.omission_refs),
+ )
+ correlations = {
+ "session": event.session_id,
+ "request": event.request_id,
+ "tool_call": event.tool_call_id,
+ }
+ self._conn.executemany(
+ "INSERT INTO savings_event_correlations(event_id, kind, value_hash) "
+ "VALUES (?, ?, ?)",
+ (
+ (event.event_id, kind, value)
+ for kind, value in correlations.items()
+ if value is not None
+ ),
+ )
+ self._conn.commit()
+ return True
+ except BaseException:
+ self._conn.rollback()
+ raise
+
+ def record_opportunity(self, observation: OpportunityObservation) -> bool:
+ """Insert an opportunity outside the achieved-event ledger."""
+ cursor = self._conn.execute(
+ """
+ INSERT OR IGNORE INTO savings_opportunities
+ (observation_id, occurred_at, repository_id, integration, kind,
+ estimated_potential_input_tokens)
+ VALUES (?, ?, ?, ?, ?, ?)
+ """,
+ (
+ observation.observation_id,
+ observation.occurred_at,
+ observation.repository_id,
+ observation.integration,
+ observation.kind,
+ observation.estimated_potential_input_tokens,
+ ),
+ )
+ return cursor.rowcount == 1
+
+ def report(
+ self,
+ repository_id: str,
+ *,
+ as_of: datetime,
+ days: int | None = None,
+ max_breakdowns: int = 100,
+ ) -> SavingsReport:
+ """Read totals with three bounded aggregate queries and no writes."""
+ if as_of.tzinfo is None:
+ raise ValueError("as_of must include a timezone")
+ if days is not None and days < 0:
+ raise ValueError("days cannot be negative")
+ where = "repository_id = ? AND occurred_at <= ?"
+ params: list[Any] = [repository_id, utc_text(as_of)]
+ if days is not None:
+ cutoff = as_of - timedelta(days=days)
+ where += " AND occurred_at >= ?"
+ params.append(utc_text(cutoff))
+ row = self._conn.execute(
+ f"""
+ SELECT
+ COUNT(*),
+ COALESCE(SUM(CASE WHEN result_state = 'success'
+ OR (result_state = 'partial' AND is_usable = 1) THEN 1 ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN saved_input_tokens > 0 THEN 1 ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN surface = 'mcp' AND (result_state = 'success'
+ OR (result_state = 'partial' AND is_usable = 1)) THEN 1 ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN result_state = 'dead_end' THEN 1 ELSE 0 END), 0),
+ COALESCE(SUM(saved_input_tokens), 0),
+ COALESCE(SUM(CASE WHEN evidence_kind = 'measured'
+ THEN saved_input_tokens ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN evidence_kind = 'inferred'
+ THEN saved_input_tokens ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN input_rate_usd_per_million IS NOT NULL
+ THEN saved_input_tokens ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN input_rate_usd_per_million IS NOT NULL
+ THEN saved_input_tokens * input_rate_usd_per_million / 1000000.0
+ ELSE 0 END), 0.0),
+ COUNT(saved_output_tokens),
+ COALESCE(SUM(saved_output_tokens), 0),
+ COALESCE(SUM(CASE WHEN output_rate_usd_per_million IS NOT NULL
+ THEN COALESCE(saved_output_tokens, 0) ELSE 0 END), 0),
+ COALESCE(SUM(CASE WHEN output_rate_usd_per_million IS NOT NULL
+ THEN COALESCE(saved_output_tokens, 0) * output_rate_usd_per_million
+ / 1000000.0 ELSE 0 END), 0.0)
+ FROM savings_events WHERE {where}
+ """,
+ params,
+ ).fetchone()
+ limit = max(0, min(int(max_breakdowns), 100))
+ operations = self._conn.execute(
+ f"""
+ SELECT operation, COUNT(*), COALESCE(SUM(saved_input_tokens), 0)
+ FROM savings_events WHERE {where}
+ GROUP BY operation ORDER BY 3 DESC, 1 ASC LIMIT ?
+ """,
+ [*params, limit],
+ ).fetchall()
+ opportunity_count, opportunity_tokens = self._conn.execute(
+ "SELECT COUNT(*), COALESCE(SUM(estimated_potential_input_tokens), 0) "
+ f"FROM savings_opportunities WHERE {where}",
+ params,
+ ).fetchone()
+ saved_input = int(row[5])
+ priced_input = int(row[8])
+ saved_output = int(row[11])
+ priced_output = int(row[12])
+ return SavingsReport(
+ unique_events=int(row[0]),
+ successful_or_usable_partial_events=int(row[1]),
+ saving_interactions=int(row[2]),
+ mcp_queries_answered=int(row[3]),
+ dead_ends=int(row[4]),
+ saved_input_tokens=saved_input,
+ measured_saved_input_tokens=int(row[6]),
+ inferred_saved_input_tokens=int(row[7]),
+ priced_saved_input_tokens=priced_input,
+ unpriced_saved_input_tokens=saved_input - priced_input,
+ priced_input_savings_usd=float(row[9]),
+ saved_output_tokens=saved_output if int(row[10]) else None,
+ priced_saved_output_tokens=priced_output,
+ unpriced_saved_output_tokens=saved_output - priced_output,
+ priced_output_savings_usd=float(row[13]),
+ opportunity_count=int(opportunity_count),
+ opportunity_tokens_excluded=int(opportunity_tokens),
+ per_operation=tuple(
+ {"operation": item[0], "events": item[1], "saved_input_tokens": item[2]}
+ for item in operations
+ ),
+ )
diff --git a/packages/core/src/repowise/core/savings/schema.py b/packages/core/src/repowise/core/savings/schema.py
new file mode 100644
index 000000000..8f6e01276
--- /dev/null
+++ b/packages/core/src/repowise/core/savings/schema.py
@@ -0,0 +1,206 @@
+"""Transactional schema upgrade for the omissions/savings sidecar."""
+
+from __future__ import annotations
+
+import sqlite3
+
+SAVINGS_SCHEMA_VERSION = 1
+
+_PRESERVED_TABLES = (
+ """
+ CREATE TABLE IF NOT EXISTS omissions (
+ ref TEXT PRIMARY KEY,
+ content BLOB NOT NULL,
+ source TEXT NOT NULL,
+ created_at REAL NOT NULL,
+ original_tokens INTEGER NOT NULL,
+ kept_tokens INTEGER NOT NULL,
+ access_count INTEGER NOT NULL DEFAULT 0
+ )
+ """,
+ """
+ CREATE TABLE IF NOT EXISTS evidence_references (
+ ref TEXT PRIMARY KEY,
+ content BLOB NOT NULL,
+ repository TEXT NOT NULL,
+ created_at REAL NOT NULL
+ )
+ """,
+ "CREATE INDEX IF NOT EXISTS idx_omissions_created ON omissions(created_at)",
+)
+
+_LEGACY_SAVINGS_TABLE = """
+CREATE TABLE savings (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ created_at REAL NOT NULL,
+ filter TEXT NOT NULL,
+ source TEXT NOT NULL,
+ command TEXT,
+ raw_tokens INTEGER NOT NULL,
+ distilled_tokens INTEGER NOT NULL
+)
+"""
+
+_V1_TABLES = (
+ """
+ CREATE TABLE savings_events (
+ event_id TEXT PRIMARY KEY,
+ schema_version INTEGER NOT NULL,
+ idempotency_key TEXT NOT NULL,
+ occurred_at TEXT NOT NULL,
+ repository_id TEXT NOT NULL,
+ surface TEXT NOT NULL,
+ integration TEXT NOT NULL,
+ agent TEXT NOT NULL,
+ subagent_id TEXT,
+ session_id TEXT,
+ request_id TEXT,
+ tool_call_id TEXT,
+ operation TEXT NOT NULL,
+ evidence_kind TEXT NOT NULL,
+ confidence REAL,
+ estimator TEXT NOT NULL,
+ token_unit TEXT NOT NULL,
+ result_state TEXT NOT NULL,
+ is_usable INTEGER NOT NULL,
+ baseline_input_tokens INTEGER,
+ pre_budget_input_tokens INTEGER,
+ delivered_input_tokens INTEGER,
+ dropped_input_tokens INTEGER,
+ saved_input_tokens INTEGER NOT NULL,
+ baseline_output_tokens INTEGER,
+ delivered_output_tokens INTEGER,
+ saved_output_tokens INTEGER,
+ model TEXT,
+ currency TEXT,
+ pricing_source TEXT,
+ pricing_version TEXT,
+ input_rate_usd_per_million REAL,
+ output_rate_usd_per_million REAL,
+ metadata_json TEXT NOT NULL,
+ UNIQUE(repository_id, idempotency_key),
+ CHECK(schema_version = 1),
+ CHECK(surface IN ('distill','hook','mcp','vscode_lm')),
+ CHECK(evidence_kind IN ('measured','inferred')),
+ CHECK(result_state IN ('success','dead_end','error','partial','unknown')),
+ CHECK(is_usable IN (0,1)),
+ CHECK(result_state != 'success' OR is_usable = 1),
+ CHECK(result_state NOT IN ('dead_end','error','unknown') OR is_usable = 0),
+ CHECK(confidence IS NULL OR confidence BETWEEN 0 AND 1),
+ CHECK(baseline_input_tokens IS NULL OR baseline_input_tokens >= 0),
+ CHECK(pre_budget_input_tokens IS NULL OR pre_budget_input_tokens >= 0),
+ CHECK(delivered_input_tokens IS NULL OR delivered_input_tokens >= 0),
+ CHECK(dropped_input_tokens IS NULL OR dropped_input_tokens >= 0),
+ CHECK(saved_input_tokens >= 0),
+ CHECK(baseline_output_tokens IS NULL OR baseline_output_tokens >= 0),
+ CHECK(delivered_output_tokens IS NULL OR delivered_output_tokens >= 0),
+ CHECK(saved_output_tokens IS NULL OR saved_output_tokens >= 0),
+ CHECK(input_rate_usd_per_million IS NULL OR input_rate_usd_per_million >= 0),
+ CHECK(output_rate_usd_per_million IS NULL OR output_rate_usd_per_million >= 0)
+ )
+ """,
+ """
+ CREATE TABLE savings_event_omissions (
+ event_id TEXT NOT NULL REFERENCES savings_events(event_id) ON DELETE CASCADE,
+ omission_ref TEXT NOT NULL,
+ PRIMARY KEY(event_id, omission_ref)
+ )
+ """,
+ """
+ CREATE TABLE savings_event_correlations (
+ event_id TEXT NOT NULL REFERENCES savings_events(event_id) ON DELETE CASCADE,
+ kind TEXT NOT NULL,
+ value_hash TEXT NOT NULL,
+ PRIMARY KEY(event_id, kind, value_hash),
+ CHECK(length(value_hash) = 71)
+ )
+ """,
+ """
+ CREATE TABLE savings_opportunities (
+ observation_id TEXT PRIMARY KEY,
+ occurred_at TEXT NOT NULL,
+ repository_id TEXT NOT NULL,
+ integration TEXT NOT NULL,
+ kind TEXT NOT NULL,
+ estimated_potential_input_tokens INTEGER NOT NULL,
+ CHECK(integration IN
+ ('claude_code','codex','opencode','hermes','cursor','vscode','unknown')),
+ CHECK(estimated_potential_input_tokens >= 0)
+ )
+ """,
+)
+
+_V1_INDEXES = (
+ "CREATE INDEX idx_savings_events_repo_time ON savings_events(repository_id, occurred_at)",
+ "CREATE INDEX idx_savings_events_surface_time ON savings_events(surface, occurred_at)",
+ "CREATE INDEX idx_savings_events_operation_time ON savings_events(operation, occurred_at)",
+ "CREATE INDEX idx_savings_events_agent_time ON savings_events(agent, occurred_at)",
+ "CREATE INDEX idx_savings_event_omissions_ref ON savings_event_omissions(omission_ref)",
+ "CREATE INDEX idx_savings_correlations_hash ON savings_event_correlations(kind, value_hash)",
+ "CREATE INDEX idx_savings_opportunities_repo_time ON savings_opportunities(repository_id, occurred_at)",
+ "CREATE INDEX idx_savings_created ON savings(created_at)",
+)
+
+_V1_REQUIRED_TABLES = frozenset(
+ {
+ "omissions",
+ "evidence_references",
+ "savings",
+ "savings_events",
+ "savings_event_omissions",
+ "savings_event_correlations",
+ "savings_opportunities",
+ }
+)
+
+
+def _has_v1_schema(conn: sqlite3.Connection) -> bool:
+ tables = {row[0] for row in conn.execute("SELECT name FROM sqlite_master WHERE type = 'table'")}
+ return tables >= _V1_REQUIRED_TABLES
+
+
+def _apply_v1(conn: sqlite3.Connection) -> None:
+ """Reset obsolete telemetry and install v1; caller owns the transaction."""
+ for statement in _PRESERVED_TABLES:
+ conn.execute(statement)
+ for table in (
+ "savings_event_omissions",
+ "savings_event_correlations",
+ "savings_opportunities",
+ "savings_events",
+ "savings",
+ ):
+ conn.execute(f"DROP TABLE IF EXISTS {table}")
+ conn.execute(_LEGACY_SAVINGS_TABLE)
+ for statement in _V1_TABLES:
+ conn.execute(statement)
+ for statement in _V1_INDEXES:
+ conn.execute(statement)
+
+
+def initialize_savings_schema(conn: sqlite3.Connection) -> None:
+ """Upgrade once under a write lock, recording version only after success."""
+ conn.execute("PRAGMA foreign_keys=ON")
+ version = int(conn.execute("PRAGMA user_version").fetchone()[0])
+ if version > SAVINGS_SCHEMA_VERSION:
+ raise RuntimeError(
+ f"savings sidecar schema {version} is newer than supported "
+ f"version {SAVINGS_SCHEMA_VERSION}"
+ )
+ if version == SAVINGS_SCHEMA_VERSION and _has_v1_schema(conn):
+ return
+ conn.execute("BEGIN IMMEDIATE")
+ try:
+ version = int(conn.execute("PRAGMA user_version").fetchone()[0])
+ if version > SAVINGS_SCHEMA_VERSION:
+ raise RuntimeError(
+ f"savings sidecar schema {version} is newer than supported "
+ f"version {SAVINGS_SCHEMA_VERSION}"
+ )
+ if version < SAVINGS_SCHEMA_VERSION or not _has_v1_schema(conn):
+ _apply_v1(conn)
+ conn.execute(f"PRAGMA user_version={SAVINGS_SCHEMA_VERSION}")
+ conn.commit()
+ except BaseException:
+ conn.rollback()
+ raise
diff --git a/tests/fixtures/savings/mixed_agents_v1.json b/tests/fixtures/savings/mixed_agents_v1.json
new file mode 100644
index 000000000..4333a98bb
--- /dev/null
+++ b/tests/fixtures/savings/mixed_agents_v1.json
@@ -0,0 +1,632 @@
+{
+ "fixture_version": 1,
+ "as_of": "2026-09-13T12:00:00Z",
+ "window_boundary": "occurred_at >= as_of - window",
+ "token_unit": {
+ "name": "estimated_tokens",
+ "estimator": "chars_per_token_floor_v1",
+ "formula": "floor(serialized_characters / 4)"
+ },
+ "pricing_unit": "usd_per_million_estimated_tokens",
+ "identity_mapping": {
+ "version": "mcp_client_info_v1",
+ "normalization": "lowercase and remove non-alphanumeric characters",
+ "recognized": {
+ "claude": "claude_code",
+ "claudecode": "claude_code",
+ "codex": "codex",
+ "opencode": "opencode",
+ "hermes": "hermes",
+ "cursor": "cursor",
+ "vscode": "vscode"
+ },
+ "fallback": "unknown"
+ },
+ "records": [
+ {
+ "attempt_id": "attempt-distill-codex-1",
+ "event_id": "00000000-0000-4000-8000-000000000001",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000001",
+ "occurred_at": "2026-08-01T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "distill",
+ "integration": "codex",
+ "agent": "codex",
+ "subagent_id": null,
+ "session_id": "session-codex",
+ "request_id": null,
+ "tool_call_id": null,
+ "operation": "test_output",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 1000,
+ "pre_budget_input_tokens": 1000,
+ "delivered_input_tokens": 250,
+ "dropped_input_tokens": 750,
+ "saved_input_tokens": 750,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-a",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-08-01",
+ "input_rate_usd_per_million": 2.0,
+ "output_rate_usd_per_million": 8.0,
+ "omission_refs": ["aaaaaaaaaaaa"]
+ },
+ {
+ "attempt_id": "attempt-hook-claude-1",
+ "event_id": "00000000-0000-4000-8000-000000000002",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000002",
+ "occurred_at": "2026-08-20T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "hook",
+ "integration": "claude_code",
+ "agent": "claude_code",
+ "subagent_id": "worker-1",
+ "session_id": "session-claude",
+ "request_id": null,
+ "tool_call_id": "hook-call-1",
+ "operation": "rewrite",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 800,
+ "pre_budget_input_tokens": 800,
+ "delivered_input_tokens": 200,
+ "dropped_input_tokens": 600,
+ "saved_input_tokens": 600,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-a",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-08-15",
+ "input_rate_usd_per_million": 3.0,
+ "output_rate_usd_per_million": 9.0,
+ "omission_refs": ["bbbbbbbbbbbb"]
+ },
+ {
+ "attempt_id": "attempt-hook-claude-retry",
+ "event_id": "00000000-0000-4000-8000-000000000002",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000002",
+ "occurred_at": "2026-08-20T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "hook",
+ "integration": "claude_code",
+ "agent": "claude_code",
+ "subagent_id": "worker-1",
+ "session_id": "session-claude",
+ "request_id": null,
+ "tool_call_id": "hook-call-1",
+ "operation": "rewrite",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 800,
+ "pre_budget_input_tokens": 800,
+ "delivered_input_tokens": 200,
+ "dropped_input_tokens": 600,
+ "saved_input_tokens": 600,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-a",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-08-15",
+ "input_rate_usd_per_million": 3.0,
+ "output_rate_usd_per_million": 9.0,
+ "omission_refs": ["bbbbbbbbbbbb"]
+ },
+ {
+ "attempt_id": "attempt-mcp-opencode-1",
+ "event_id": "00000000-0000-4000-8000-000000000003",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000003",
+ "occurred_at": "2026-09-10T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "opencode",
+ "agent": "opencode",
+ "subagent_id": null,
+ "session_id": "session-opencode",
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000003",
+ "tool_call_id": null,
+ "operation": "get_context",
+ "evidence_kind": "inferred",
+ "confidence": 0.75,
+ "estimator": "get_context_counterfactual_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 1200,
+ "pre_budget_input_tokens": 700,
+ "delivered_input_tokens": 300,
+ "dropped_input_tokens": 400,
+ "saved_input_tokens": 900,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-c",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-09-01",
+ "input_rate_usd_per_million": 4.0,
+ "output_rate_usd_per_million": 10.0,
+ "omission_refs": ["cccccccccccc"]
+ },
+ {
+ "attempt_id": "attempt-mcp-hermes-1",
+ "event_id": "00000000-0000-4000-8000-000000000004",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000004",
+ "occurred_at": "2026-09-11T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "hermes",
+ "agent": "hermes",
+ "subagent_id": null,
+ "session_id": "session-hermes",
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000004",
+ "tool_call_id": null,
+ "operation": "get_context",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 800,
+ "pre_budget_input_tokens": 800,
+ "delivered_input_tokens": 500,
+ "dropped_input_tokens": 300,
+ "saved_input_tokens": 300,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": ["dddddddddddd"]
+ },
+ {
+ "attempt_id": "attempt-mcp-unknown-1",
+ "event_id": "00000000-0000-4000-8000-000000000005",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000005",
+ "occurred_at": "2026-09-12T09:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "unknown",
+ "agent": "unknown",
+ "subagent_id": null,
+ "session_id": null,
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000005",
+ "tool_call_id": null,
+ "operation": "get_risk",
+ "evidence_kind": "inferred",
+ "confidence": 0.6,
+ "estimator": "get_risk_counterfactual_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 200,
+ "pre_budget_input_tokens": 350,
+ "delivered_input_tokens": 250,
+ "dropped_input_tokens": 100,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": ["eeeeeeeeeeee"]
+ },
+ {
+ "attempt_id": "attempt-mcp-cursor-dead-1",
+ "event_id": "00000000-0000-4000-8000-000000000006",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000006",
+ "occurred_at": "2026-09-12T10:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "cursor",
+ "agent": "cursor",
+ "subagent_id": null,
+ "session_id": "session-cursor",
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000006",
+ "tool_call_id": null,
+ "operation": "get_health",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "dead_end",
+ "is_usable": false,
+ "baseline_input_tokens": null,
+ "pre_budget_input_tokens": 170,
+ "delivered_input_tokens": 120,
+ "dropped_input_tokens": 50,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-c",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-09-01",
+ "input_rate_usd_per_million": 4.0,
+ "output_rate_usd_per_million": 10.0,
+ "omission_refs": ["ffffffffffff"]
+ },
+ {
+ "attempt_id": "attempt-vscode-output-1",
+ "event_id": "00000000-0000-4000-8000-000000000007",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000007",
+ "occurred_at": "2026-09-12T11:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "vscode_lm",
+ "integration": "vscode",
+ "agent": "vscode",
+ "subagent_id": null,
+ "session_id": "session-vscode",
+ "request_id": "10000000-0000-4000-8000-000000000007",
+ "tool_call_id": null,
+ "operation": "get_symbol",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "explicit_output_fixture_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 400,
+ "pre_budget_input_tokens": 400,
+ "delivered_input_tokens": 400,
+ "dropped_input_tokens": 0,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": 100,
+ "delivered_output_tokens": 40,
+ "saved_output_tokens": 60,
+ "model": "fixture-model-output",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-09-01",
+ "input_rate_usd_per_million": 5.0,
+ "output_rate_usd_per_million": 10.0,
+ "omission_refs": []
+ },
+ {
+ "attempt_id": "attempt-generic-unknown-boundary-30d",
+ "event_id": "00000000-0000-4000-8000-000000000008",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000008",
+ "occurred_at": "2026-08-14T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "unknown",
+ "agent": "unknown",
+ "subagent_id": null,
+ "session_id": null,
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000008",
+ "tool_call_id": null,
+ "operation": "list_repos",
+ "evidence_kind": "inferred",
+ "confidence": null,
+ "estimator": "list_repos_counterfactual_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "unknown",
+ "is_usable": false,
+ "baseline_input_tokens": null,
+ "pre_budget_input_tokens": null,
+ "delivered_input_tokens": 100,
+ "dropped_input_tokens": null,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": [],
+ "metadata": {
+ "client_info_normalized": "fixturegenericclient",
+ "identity_mapping_version": "mcp_client_info_v1"
+ }
+ },
+ {
+ "attempt_id": "attempt-error-outside-30d",
+ "event_id": "00000000-0000-4000-8000-000000000009",
+ "idempotency_key": "sha256:0000000000000000000000000000000000000000000000000000000000000009",
+ "occurred_at": "2026-08-14T11:59:59Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "codex",
+ "agent": "codex",
+ "subagent_id": null,
+ "session_id": "session-codex",
+ "request_id": "sha256:1000000000000000000000000000000000000000000000000000000000000009",
+ "tool_call_id": null,
+ "operation": "get_answer",
+ "evidence_kind": "inferred",
+ "confidence": 0.7,
+ "estimator": "get_answer_counterfactual_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "error",
+ "is_usable": false,
+ "baseline_input_tokens": null,
+ "pre_budget_input_tokens": null,
+ "delivered_input_tokens": 80,
+ "dropped_input_tokens": null,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": "fixture-model-a",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-08-15",
+ "input_rate_usd_per_million": 3.0,
+ "output_rate_usd_per_million": 9.0,
+ "omission_refs": []
+ },
+ {
+ "attempt_id": "attempt-partial-usable-boundary-7d",
+ "event_id": "00000000-0000-4000-8000-00000000000a",
+ "idempotency_key": "sha256:000000000000000000000000000000000000000000000000000000000000000a",
+ "occurred_at": "2026-09-06T12:00:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "opencode",
+ "agent": "opencode",
+ "subagent_id": null,
+ "session_id": "session-opencode",
+ "request_id": "sha256:100000000000000000000000000000000000000000000000000000000000000a",
+ "tool_call_id": null,
+ "operation": "get_context",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "partial",
+ "is_usable": true,
+ "baseline_input_tokens": 100,
+ "pre_budget_input_tokens": 100,
+ "delivered_input_tokens": 80,
+ "dropped_input_tokens": 20,
+ "saved_input_tokens": 20,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": ["121212121212"]
+ },
+ {
+ "attempt_id": "attempt-partial-insufficient-outside-7d",
+ "event_id": "00000000-0000-4000-8000-00000000000b",
+ "idempotency_key": "sha256:000000000000000000000000000000000000000000000000000000000000000b",
+ "occurred_at": "2026-09-06T11:59:59Z",
+ "repository_id": "fixture-repo",
+ "surface": "mcp",
+ "integration": "hermes",
+ "agent": "hermes",
+ "subagent_id": null,
+ "session_id": "session-hermes",
+ "request_id": "sha256:100000000000000000000000000000000000000000000000000000000000000b",
+ "tool_call_id": null,
+ "operation": "get_context",
+ "evidence_kind": "measured",
+ "confidence": null,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "partial",
+ "is_usable": false,
+ "baseline_input_tokens": null,
+ "pre_budget_input_tokens": null,
+ "delivered_input_tokens": 70,
+ "dropped_input_tokens": null,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": []
+ },
+ {
+ "attempt_id": "attempt-measured-negative-clamp",
+ "event_id": "00000000-0000-4000-8000-00000000000c",
+ "idempotency_key": "sha256:000000000000000000000000000000000000000000000000000000000000000c",
+ "occurred_at": "2026-09-12T11:15:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "distill",
+ "integration": "codex",
+ "agent": "codex",
+ "subagent_id": null,
+ "session_id": "session-codex",
+ "request_id": null,
+ "tool_call_id": null,
+ "operation": "logs",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "chars_per_token_floor_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 50,
+ "pre_budget_input_tokens": 50,
+ "delivered_input_tokens": 80,
+ "dropped_input_tokens": 0,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": null,
+ "delivered_output_tokens": null,
+ "saved_output_tokens": null,
+ "model": null,
+ "currency": null,
+ "pricing_source": null,
+ "pricing_version": null,
+ "input_rate_usd_per_million": null,
+ "output_rate_usd_per_million": null,
+ "omission_refs": []
+ },
+ {
+ "attempt_id": "attempt-output-negative-clamp",
+ "event_id": "00000000-0000-4000-8000-00000000000d",
+ "idempotency_key": "sha256:000000000000000000000000000000000000000000000000000000000000000d",
+ "occurred_at": "2026-09-12T11:30:00Z",
+ "repository_id": "fixture-repo",
+ "surface": "vscode_lm",
+ "integration": "vscode",
+ "agent": "vscode",
+ "subagent_id": null,
+ "session_id": "session-vscode",
+ "request_id": "10000000-0000-4000-8000-00000000000d",
+ "tool_call_id": null,
+ "operation": "get_context",
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "explicit_output_fixture_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": true,
+ "baseline_input_tokens": 100,
+ "pre_budget_input_tokens": 100,
+ "delivered_input_tokens": 100,
+ "dropped_input_tokens": 0,
+ "saved_input_tokens": 0,
+ "baseline_output_tokens": 40,
+ "delivered_output_tokens": 100,
+ "saved_output_tokens": 0,
+ "model": "fixture-model-output",
+ "currency": "USD",
+ "pricing_source": "fixture-prices",
+ "pricing_version": "2026-09-01",
+ "input_rate_usd_per_million": 5.0,
+ "output_rate_usd_per_million": 10.0,
+ "omission_refs": []
+ }
+ ],
+ "opportunities": [
+ {
+ "observation_id": "opportunity-command-1",
+ "occurred_at": "2026-09-12T08:00:00Z",
+ "integration": "codex",
+ "kind": "command_bypassed_distill",
+ "estimated_potential_input_tokens": 96000
+ },
+ {
+ "observation_id": "opportunity-reread-1",
+ "occurred_at": "2026-09-12T08:30:00Z",
+ "integration": "unknown",
+ "kind": "unchanged_file_reread",
+ "estimated_potential_input_tokens": 635
+ },
+ {
+ "observation_id": "opportunity-boundary-7d",
+ "occurred_at": "2026-09-06T12:00:00Z",
+ "integration": "opencode",
+ "kind": "command_bypassed_distill",
+ "estimated_potential_input_tokens": 1000
+ },
+ {
+ "observation_id": "opportunity-outside-7d",
+ "occurred_at": "2026-09-06T11:59:59Z",
+ "integration": "hermes",
+ "kind": "command_bypassed_distill",
+ "estimated_potential_input_tokens": 2000
+ },
+ {
+ "observation_id": "opportunity-boundary-30d",
+ "occurred_at": "2026-08-14T12:00:00Z",
+ "integration": "codex",
+ "kind": "unchanged_file_reread",
+ "estimated_potential_input_tokens": 3000
+ },
+ {
+ "observation_id": "opportunity-outside-30d",
+ "occurred_at": "2026-08-14T11:59:59Z",
+ "integration": "unknown",
+ "kind": "unchanged_file_reread",
+ "estimated_potential_input_tokens": 4000
+ }
+ ],
+ "expected": {
+ "all": {
+ "unique_events": 13,
+ "successful_or_usable_partial_events": 9,
+ "saving_interactions": 5,
+ "mcp_queries_answered": 4,
+ "dead_ends": 1,
+ "saved_input_tokens": 2570,
+ "measured_saved_input_tokens": 1670,
+ "inferred_saved_input_tokens": 900,
+ "priced_saved_input_tokens": 2250,
+ "unpriced_saved_input_tokens": 320,
+ "priced_input_savings_usd": 0.0069,
+ "saved_output_tokens": 60,
+ "priced_output_savings_usd": 0.0006,
+ "opportunity_count": 6,
+ "opportunity_tokens_excluded": 106635
+ },
+ "30d": {
+ "unique_events": 11,
+ "successful_or_usable_partial_events": 8,
+ "saving_interactions": 4,
+ "mcp_queries_answered": 4,
+ "dead_ends": 1,
+ "saved_input_tokens": 1820,
+ "measured_saved_input_tokens": 920,
+ "inferred_saved_input_tokens": 900,
+ "priced_saved_input_tokens": 1500,
+ "unpriced_saved_input_tokens": 320,
+ "priced_input_savings_usd": 0.0054,
+ "saved_output_tokens": 60,
+ "priced_output_savings_usd": 0.0006,
+ "opportunity_count": 5,
+ "opportunity_tokens_excluded": 102635
+ },
+ "7d": {
+ "unique_events": 8,
+ "successful_or_usable_partial_events": 7,
+ "saving_interactions": 3,
+ "mcp_queries_answered": 4,
+ "dead_ends": 1,
+ "saved_input_tokens": 1220,
+ "measured_saved_input_tokens": 320,
+ "inferred_saved_input_tokens": 900,
+ "priced_saved_input_tokens": 900,
+ "unpriced_saved_input_tokens": 320,
+ "priced_input_savings_usd": 0.0036,
+ "saved_output_tokens": 60,
+ "priced_output_savings_usd": 0.0006,
+ "opportunity_count": 3,
+ "opportunity_tokens_excluded": 97635
+ }
+ }
+}
diff --git a/tests/unit/distill/test_savings_contract_fixture.py b/tests/unit/distill/test_savings_contract_fixture.py
new file mode 100644
index 000000000..60aa1e28d
--- /dev/null
+++ b/tests/unit/distill/test_savings_contract_fixture.py
@@ -0,0 +1,265 @@
+"""Phase 0 invariants for the hand-calculable savings contract fixture."""
+
+from __future__ import annotations
+
+import json
+import re
+from datetime import datetime, timedelta
+from pathlib import Path
+from uuid import UUID
+
+import pytest
+
+FIXTURE = Path(__file__).parents[2] / "fixtures" / "savings" / "mixed_agents_v1.json"
+
+
+def _load() -> dict:
+ return json.loads(FIXTURE.read_text(encoding="utf-8"))
+
+
+def _unique_events(payload: dict) -> list[dict]:
+ events: dict[str, dict] = {}
+ for record in payload["records"]:
+ key = record["idempotency_key"]
+ comparable = {k: v for k, v in record.items() if k != "attempt_id"}
+ if key in events:
+ prior = {k: v for k, v in events[key].items() if k != "attempt_id"}
+ assert comparable == prior, f"retry {key} changed its accounting payload"
+ continue
+ events[key] = record
+ return list(events.values())
+
+
+def _scope(records: list[dict], as_of: datetime, days: int | None) -> list[dict]:
+ if days is None:
+ return records
+ cutoff = as_of - timedelta(days=days)
+ return [record for record in records if datetime.fromisoformat(record["occurred_at"]) >= cutoff]
+
+
+def _is_answered(event: dict) -> bool:
+ return event["result_state"] in {"success", "partial"} and event["is_usable"]
+
+
+def _totals(events: list[dict]) -> dict:
+ saved = sum(event["saved_input_tokens"] for event in events)
+ measured = sum(
+ event["saved_input_tokens"] for event in events if event["evidence_kind"] == "measured"
+ )
+ inferred = sum(
+ event["saved_input_tokens"] for event in events if event["evidence_kind"] == "inferred"
+ )
+ priced = sum(
+ event["saved_input_tokens"]
+ for event in events
+ if event["input_rate_usd_per_million"] is not None
+ )
+ input_usd = sum(
+ event["saved_input_tokens"] * (event["input_rate_usd_per_million"] or 0) / 1_000_000
+ for event in events
+ )
+ output_tokens = sum(event["saved_output_tokens"] or 0 for event in events)
+ output_usd = sum(
+ (event["saved_output_tokens"] or 0)
+ * (event["output_rate_usd_per_million"] or 0)
+ / 1_000_000
+ for event in events
+ )
+ return {
+ "unique_events": len(events),
+ "successful_or_usable_partial_events": sum(_is_answered(event) for event in events),
+ "saving_interactions": sum(event["saved_input_tokens"] > 0 for event in events),
+ "mcp_queries_answered": sum(
+ event["surface"] == "mcp" and _is_answered(event) for event in events
+ ),
+ "dead_ends": sum(event["result_state"] == "dead_end" for event in events),
+ "saved_input_tokens": saved,
+ "measured_saved_input_tokens": measured,
+ "inferred_saved_input_tokens": inferred,
+ "priced_saved_input_tokens": priced,
+ "unpriced_saved_input_tokens": saved - priced,
+ "priced_input_savings_usd": input_usd,
+ "saved_output_tokens": output_tokens,
+ "priced_output_savings_usd": output_usd,
+ }
+
+
+def test_fixture_has_deterministic_identity_and_formula_coverage() -> None:
+ payload = _load()
+ events = _unique_events(payload)
+
+ assert len(payload["records"]) == 14
+ assert len(events) == 13
+ assert {event["agent"] for event in events} == {
+ "claude_code",
+ "codex",
+ "cursor",
+ "hermes",
+ "opencode",
+ "unknown",
+ "vscode",
+ }
+ assert {event["surface"] for event in events} == {"distill", "hook", "mcp", "vscode_lm"}
+ assert {event["result_state"] for event in events} == {
+ "dead_end",
+ "error",
+ "partial",
+ "success",
+ "unknown",
+ }
+ assert any(event["subagent_id"] for event in events)
+ assert any(event["model"] is None for event in events)
+ assert any(event["saved_output_tokens"] is not None for event in events)
+
+ required_keys = {
+ "event_id",
+ "idempotency_key",
+ "occurred_at",
+ "repository_id",
+ "surface",
+ "integration",
+ "agent",
+ "subagent_id",
+ "session_id",
+ "request_id",
+ "tool_call_id",
+ "operation",
+ "evidence_kind",
+ "confidence",
+ "estimator",
+ "token_unit",
+ "result_state",
+ "is_usable",
+ "baseline_input_tokens",
+ "pre_budget_input_tokens",
+ "delivered_input_tokens",
+ "dropped_input_tokens",
+ "saved_input_tokens",
+ "baseline_output_tokens",
+ "delivered_output_tokens",
+ "saved_output_tokens",
+ "model",
+ "currency",
+ "pricing_source",
+ "pricing_version",
+ "input_rate_usd_per_million",
+ "output_rate_usd_per_million",
+ "omission_refs",
+ }
+
+ for event in events:
+ allowed_keys = required_keys | {"attempt_id", "metadata"}
+ assert set(event) <= allowed_keys
+ UUID(event["event_id"])
+ assert re.fullmatch(r"sha256:[0-9a-f]{64}", event["idempotency_key"])
+ assert event["token_unit"] == payload["token_unit"]["name"]
+ assert event["confidence"] is None or 0 <= event["confidence"] <= 1
+ if event["result_state"] == "success":
+ assert event["is_usable"] is True
+ if event["result_state"] in {"dead_end", "error", "unknown"}:
+ assert event["is_usable"] is False
+ assert event["saved_input_tokens"] >= 0
+ if event["result_state"] in {"dead_end", "error", "unknown"}:
+ assert event["saved_input_tokens"] == 0
+ if event["surface"] in {"distill", "hook"} and event["baseline_input_tokens"] is not None:
+ expected = max(event["baseline_input_tokens"] - event["delivered_input_tokens"], 0)
+ assert event["saved_input_tokens"] == expected == event["dropped_input_tokens"]
+ if (
+ event["surface"] == "mcp"
+ and event["evidence_kind"] == "inferred"
+ and event["result_state"] in {"success", "partial"}
+ and event["baseline_input_tokens"] is not None
+ ):
+ expected = max(event["baseline_input_tokens"] - event["delivered_input_tokens"], 0)
+ assert event["saved_input_tokens"] == expected
+ if (
+ event["surface"] == "mcp"
+ and event["evidence_kind"] == "measured"
+ and event["result_state"] in {"success", "partial"}
+ and event["baseline_input_tokens"] is not None
+ ):
+ expected = max(event["baseline_input_tokens"] - event["delivered_input_tokens"], 0)
+ assert event["saved_input_tokens"] == expected == event["dropped_input_tokens"]
+ if (
+ event["pre_budget_input_tokens"] is not None
+ and event["delivered_input_tokens"] is not None
+ and event["dropped_input_tokens"] is not None
+ ):
+ assert event["dropped_input_tokens"] == max(
+ event["pre_budget_input_tokens"] - event["delivered_input_tokens"], 0
+ )
+ if event["baseline_output_tokens"] is not None:
+ assert event["saved_output_tokens"] == max(
+ event["baseline_output_tokens"] - event["delivered_output_tokens"], 0
+ )
+ if event["surface"] == "mcp" and event["request_id"] is not None:
+ assert re.fullmatch(r"sha256:[0-9a-f]{64}", event["request_id"])
+ if event["surface"] == "vscode_lm":
+ UUID(event["request_id"])
+ if (
+ event["input_rate_usd_per_million"] is not None
+ or event["output_rate_usd_per_million"] is not None
+ ):
+ assert event["currency"] == "USD"
+
+ metadata = event.get("metadata", {})
+ assert set(metadata) <= {"client_info_normalized", "identity_mapping_version"}
+ assert all(isinstance(value, str) and len(value) <= 64 for value in metadata.values())
+ forbidden = {
+ "prompt",
+ "transcript",
+ "command",
+ "raw_command",
+ "header",
+ "headers",
+ "secret",
+ }
+ assert forbidden.isdisjoint(event)
+ assert forbidden.isdisjoint(metadata)
+
+ model_a = [event for event in events if event["model"] == "fixture-model-a"]
+ assert {
+ (event["pricing_version"], event["input_rate_usd_per_million"]) for event in model_a
+ } >= {
+ ("2026-08-01", 2.0),
+ ("2026-08-15", 3.0),
+ }
+
+ generic = next(
+ event for event in events if event.get("metadata", {}).get("client_info_normalized")
+ )
+ assert (
+ generic["metadata"]["client_info_normalized"]
+ not in payload["identity_mapping"]["recognized"]
+ )
+ assert generic["integration"] == generic["agent"] == payload["identity_mapping"]["fallback"]
+
+
[email protected](("scope", "days"), [("all", None), ("30d", 30), ("7d", 7)])
+def test_fixture_totals_are_hand_calculable(scope: str, days: int | None) -> None:
+ payload = _load()
+ as_of = datetime.fromisoformat(payload["as_of"])
+ actual = _totals(_scope(_unique_events(payload), as_of, days))
+ expected = payload["expected"][scope]
+
+ for key, value in actual.items():
+ if isinstance(value, float):
+ assert value == pytest.approx(expected[key])
+ else:
+ assert value == expected[key]
+
+
[email protected](("scope", "days"), [("all", None), ("30d", 30), ("7d", 7)])
+def test_opportunities_are_windowed_and_excluded_from_achieved_savings(
+ scope: str, days: int | None
+) -> None:
+ payload = _load()
+ as_of = datetime.fromisoformat(payload["as_of"])
+ opportunities = _scope(payload["opportunities"], as_of, days)
+ opportunity_tokens = sum(item["estimated_potential_input_tokens"] for item in opportunities)
+
+ assert len(opportunities) == payload["expected"][scope]["opportunity_count"]
+ assert opportunity_tokens == payload["expected"][scope]["opportunity_tokens_excluded"]
+ assert opportunity_tokens not in {
+ payload["expected"][window]["saved_input_tokens"] for window in ("all", "30d", "7d")
+ }
diff --git a/tests/unit/distill/test_store.py b/tests/unit/distill/test_store.py
index 27191836b..86e2548ab 100644
--- a/tests/unit/distill/test_store.py
+++ b/tests/unit/distill/test_store.py
@@ -160,17 +160,26 @@ def test_distill_summary_excludes_mcp_rows(store: OmissionStore) -> None:
# Distill surface rows…
store.record_saving(
- filter_name="test_output", source="cli", command="pytest",
- raw_tokens=1000, distilled_tokens=100,
+ filter_name="test_output",
+ source="cli",
+ command="pytest",
+ raw_tokens=1000,
+ distilled_tokens=100,
)
store.record_saving(
- filter_name="git_log", source="hook-bash", command="git log",
- raw_tokens=500, distilled_tokens=50,
+ filter_name="git_log",
+ source="hook-bash",
+ command="git log",
+ raw_tokens=500,
+ distilled_tokens=50,
)
# …and an MCP counterfactual row in the same ledger, which distill must skip.
store.record_saving(
- filter_name="get_context", source="mcp:get_context", command=None,
- raw_tokens=4000, distilled_tokens=400,
+ filter_name="get_context",
+ source="mcp:get_context",
+ command=None,
+ raw_tokens=4000,
+ distilled_tokens=400,
)
summary = distill_summary(store._conn)
@@ -181,52 +190,6 @@ def test_distill_summary_excludes_mcp_rows(store: OmissionStore) -> None:
assert "get_context" not in summary["per_filter"]
-def test_mcp_savings_summary_counterfactual_precedence(store: OmissionStore) -> None:
- from repowise.core.distill.tracking import mcp_savings_summary
-
- # Counterfactual ledger rows for two tools (these subsume their own
- # truncation, since delivered is measured post-truncation).
- store.record_saving(
- filter_name="get_symbol", source="mcp:get_symbol", command=None,
- raw_tokens=3000, distilled_tokens=300,
- )
- store.record_saving(
- filter_name="get_symbol", source="mcp:get_symbol", command=None,
- raw_tokens=1000, distilled_tokens=200,
- )
- store.record_saving(
- filter_name="get_context", source="mcp:get_context", command=None,
- raw_tokens=2000, distilled_tokens=500,
- )
- # Truncation drops: get_symbol also has drops (must NOT be added on top —
- # counterfactual wins); get_risk has ONLY drops (its sole signal).
- store.put("x" * 400, source="mcp:get_symbol", original_tokens=900, kept_tokens=0)
- store.put("y" * 400, source="mcp:get_risk", original_tokens=700, kept_tokens=0)
- # A distill omission must never leak into the MCP view.
- store.put("z" * 400, source="cli:logs", original_tokens=999, kept_tokens=0)
-
- summary = mcp_savings_summary(store._conn)
- by_tool = {row["tool"]: row for row in summary["per_tool"]}
-
- # get_symbol → counterfactual saved 2700+800=3500, drops ignored.
- assert by_tool["get_symbol"] == {
- "tool": "get_symbol", "events": 2, "tokens": 3500, "kind": "counterfactual",
- }
- # get_context → counterfactual saved 1500.
- assert by_tool["get_context"]["tokens"] == 1500
- assert by_tool["get_context"]["kind"] == "counterfactual"
- # get_risk → truncation only.
- assert by_tool["get_risk"] == {
- "tool": "get_risk", "events": 1, "tokens": 700, "kind": "truncation",
- }
- # queries counts counterfactual events only; tokens is the merged total.
- assert summary["queries"] == 3
- assert summary["tokens"] == 3500 + 1500 + 700
- assert summary["events"] == 2 + 1 + 1
- # Ordered by tokens desc.
- assert [r["tool"] for r in summary["per_tool"]] == ["get_symbol", "get_context", "get_risk"]
-
-
def test_mcp_savings_summary_empty(store: OmissionStore) -> None:
from repowise.core.distill.tracking import mcp_savings_summary
diff --git a/tests/unit/savings/test_contracts.py b/tests/unit/savings/test_contracts.py
new file mode 100644
index 000000000..1cb0bd9ad
--- /dev/null
+++ b/tests/unit/savings/test_contracts.py
@@ -0,0 +1,193 @@
+"""Core savings normalization, formulas, pricing, and fixture reporting."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from datetime import UTC, datetime
+from pathlib import Path
+
+import pytest
+
+from repowise.core.savings.contracts import OpportunityObservation, SavingsEvent
+from repowise.core.savings.correlation import (
+ hash_correlation_evidence,
+ new_event_id,
+ scoped_idempotency_key,
+)
+from repowise.core.savings.formulas import calculate_token_accounting
+from repowise.core.savings.normalization import normalize_mcp_identity
+from repowise.core.savings.pricing import price_tokens
+from repowise.core.savings.reporting import build_report
+
+FIXTURE = Path(__file__).parents[2] / "fixtures" / "savings" / "mixed_agents_v1.json"
+
+
+def _fixture_domain() -> tuple[dict, list[SavingsEvent], list[OpportunityObservation]]:
+ payload = json.loads(FIXTURE.read_text(encoding="utf-8"))
+ events: dict[str, SavingsEvent] = {}
+ for record in payload["records"]:
+ event = SavingsEvent.from_mapping(record, accept_event_id=True)
+ events.setdefault(event.idempotency_key, event)
+ opportunities = [
+ OpportunityObservation.from_mapping(item, repository_id="fixture-repo")
+ for item in payload["opportunities"]
+ ]
+ return payload, list(events.values()), opportunities
+
+
[email protected](("scope", "days"), [("all", None), ("30d", 30), ("7d", 7)])
+def test_core_report_reproduces_the_hand_calculable_fixture(scope: str, days: int | None) -> None:
+ payload, events, opportunities = _fixture_domain()
+ report = build_report(
+ events,
+ opportunities,
+ as_of=datetime.fromisoformat(payload["as_of"]),
+ days=days,
+ )
+ actual = asdict(report)
+ for key, expected in payload["expected"][scope].items():
+ if isinstance(expected, float):
+ assert actual[key] == pytest.approx(expected)
+ else:
+ assert actual[key] == expected
+
+
+def test_same_tool_events_correlate_independently_and_zero_saving_counts() -> None:
+ base = {
+ "occurred_at": "2026-09-14T00:00:00Z",
+ "repository_id": "repo",
+ "surface": "mcp",
+ "integration": "codex",
+ "agent": "codex",
+ "operation": "get_risk",
+ "confidence": 1.0,
+ "estimator": "fixture_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_output_tokens": None,
+ "delivered_output_tokens": None,
+ "model": None,
+ "currency": None,
+ "pricing_source": None,
+ "pricing_version": None,
+ "input_rate_usd_per_million": None,
+ "output_rate_usd_per_million": None,
+ "omission_refs": [],
+ }
+ inferred = SavingsEvent.from_mapping(
+ {
+ **base,
+ "idempotency_key": scoped_idempotency_key("repo", "mcp", "call-a"),
+ "evidence_kind": "inferred",
+ "baseline_input_tokens": 1000,
+ "pre_budget_input_tokens": 500,
+ "delivered_input_tokens": 200,
+ "dropped_input_tokens": 300,
+ "saved_input_tokens": 800,
+ "saved_output_tokens": None,
+ }
+ )
+ measured = SavingsEvent.from_mapping(
+ {
+ **base,
+ "idempotency_key": scoped_idempotency_key("repo", "mcp", "call-b"),
+ "evidence_kind": "measured",
+ "baseline_input_tokens": 800,
+ "pre_budget_input_tokens": 800,
+ "delivered_input_tokens": 500,
+ "dropped_input_tokens": 300,
+ "saved_input_tokens": 300,
+ "saved_output_tokens": None,
+ }
+ )
+ zero = SavingsEvent.from_mapping(
+ {
+ **base,
+ "idempotency_key": scoped_idempotency_key("repo", "mcp", "call-zero"),
+ "evidence_kind": "inferred",
+ "baseline_input_tokens": 200,
+ "pre_budget_input_tokens": 350,
+ "delivered_input_tokens": 250,
+ "dropped_input_tokens": 100,
+ "saved_input_tokens": 0,
+ "saved_output_tokens": None,
+ }
+ )
+ report = build_report([inferred, measured, zero], as_of=datetime.now(UTC))
+
+ assert report.saved_input_tokens == 1100
+ assert report.mcp_queries_answered == 3
+ assert report.saving_interactions == 2
+
+
+def test_dimensions_clamp_and_unusable_results_never_save() -> None:
+ measured = calculate_token_accounting(
+ surface="distill",
+ evidence_kind="measured",
+ result_state="success",
+ is_usable=True,
+ baseline_input_tokens=-10,
+ pre_budget_input_tokens=-20,
+ delivered_input_tokens=50,
+ baseline_output_tokens=10,
+ delivered_output_tokens=20,
+ )
+ assert measured.saved_input_tokens == measured.dropped_input_tokens == 0
+ assert measured.saved_output_tokens == 0
+
+ for state, usable in (
+ ("dead_end", False),
+ ("error", False),
+ ("unknown", False),
+ ("partial", False),
+ ):
+ result = calculate_token_accounting(
+ surface="mcp",
+ evidence_kind="measured",
+ result_state=state,
+ is_usable=usable,
+ baseline_input_tokens=1000,
+ pre_budget_input_tokens=1000,
+ delivered_input_tokens=100,
+ )
+ assert result.dropped_input_tokens == 900
+ assert result.saved_input_tokens == 0
+
+
+def test_identity_metadata_correlation_and_pricing_are_bounded() -> None:
+ assert normalize_mcp_identity("Claude-Code")[0] == "claude_code"
+ identity, metadata = normalize_mcp_identity("Untrusted Client!" * 20)
+ assert identity == "unknown"
+ assert len(metadata["client_info_normalized"]) == 64
+ correlation = hash_correlation_evidence("session", "raw-secret-request-id")
+ assert correlation.startswith("sha256:") and len(correlation) == 71
+ assert "raw-secret" not in correlation
+ assert new_event_id() != new_event_id()
+ assert price_tokens(1000, 2.5) == pytest.approx(0.0025)
+ assert price_tokens(1000, None) is None
+ for missing in (None, ""):
+ with pytest.raises(ValueError, match="evidence"):
+ scoped_idempotency_key("repo", "mcp", missing)
+ for invalid_rate in (float("nan"), float("inf"), -1.0):
+ with pytest.raises(ValueError, match="finite and nonnegative"):
+ price_tokens(1000, invalid_rate)
+
+ payload, _, _ = _fixture_domain()
+ bad = dict(payload["records"][0], metadata={"prompt": "do not persist"})
+ with pytest.raises(ValueError, match="metadata keys"):
+ SavingsEvent.from_mapping(bad, accept_event_id=True)
+ bad_price = dict(payload["records"][0], input_rate_usd_per_million=float("nan"))
+ with pytest.raises(ValueError, match="finite and nonnegative"):
+ SavingsEvent.from_mapping(bad_price, accept_event_id=True)
+
+
+def test_report_keeps_unobserved_output_savings_unknown() -> None:
+ event = _fixture_domain()[1][0]
+ report = build_report([event], as_of=datetime.now(UTC))
+
+ assert event.saved_output_tokens is None
+ assert report.saved_output_tokens is None
+ assert report.priced_saved_output_tokens == 0
+ assert report.unpriced_saved_output_tokens == 0
diff --git a/tests/unit/savings/test_repository.py b/tests/unit/savings/test_repository.py
new file mode 100644
index 000000000..9b7862bfc
--- /dev/null
+++ b/tests/unit/savings/test_repository.py
@@ -0,0 +1,260 @@
+"""Transactional sidecar upgrade, concurrency, idempotency, and reports."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import asdict
+from datetime import datetime
+from pathlib import Path
+
+import pytest
+
+from repowise.core.distill.store import OmissionStore
+from repowise.core.savings import schema
+from repowise.core.savings.contracts import OpportunityObservation, SavingsEvent
+from repowise.core.savings.correlation import scoped_idempotency_key
+from repowise.core.savings.repository import SavingsRepository
+from repowise.core.sqlite_pragmas import apply_sqlite_pragmas
+
+FIXTURE = Path(__file__).parents[2] / "fixtures" / "savings" / "mixed_agents_v1.json"
+
+
+def _event(index: int, *, operation: str = "get_risk") -> SavingsEvent:
+ return SavingsEvent.from_mapping(
+ {
+ "idempotency_key": scoped_idempotency_key("repo", "mcp", index),
+ "occurred_at": f"2026-09-14T00:00:{index:02d}Z",
+ "repository_id": "repo",
+ "surface": "mcp",
+ "integration": "codex",
+ "agent": "codex",
+ "session_id": f"session-{index}",
+ "request_id": scoped_idempotency_key("repo", "request", index),
+ "tool_call_id": None,
+ "operation": operation,
+ "evidence_kind": "measured",
+ "confidence": 1.0,
+ "estimator": "fixture_v1",
+ "token_unit": "estimated_tokens",
+ "result_state": "success",
+ "is_usable": True,
+ "baseline_input_tokens": 100,
+ "pre_budget_input_tokens": 100,
+ "delivered_input_tokens": 40,
+ "baseline_output_tokens": None,
+ "delivered_output_tokens": None,
+ "omission_refs": [f"{index:012x}"],
+ }
+ )
+
+
+def _seed_legacy(db_path: Path) -> None:
+ conn = sqlite3.connect(db_path)
+ conn.executescript(
+ """
+ CREATE TABLE omissions (
+ ref TEXT PRIMARY KEY, content BLOB NOT NULL, source TEXT NOT NULL,
+ created_at REAL NOT NULL, original_tokens INTEGER NOT NULL,
+ kept_tokens INTEGER NOT NULL, access_count INTEGER NOT NULL DEFAULT 0
+ );
+ CREATE TABLE evidence_references (
+ ref TEXT PRIMARY KEY, content BLOB NOT NULL, repository TEXT NOT NULL,
+ created_at REAL NOT NULL
+ );
+ CREATE TABLE savings (
+ id INTEGER PRIMARY KEY AUTOINCREMENT, created_at REAL NOT NULL,
+ filter TEXT NOT NULL, source TEXT NOT NULL, command TEXT,
+ raw_tokens INTEGER NOT NULL, distilled_tokens INTEGER NOT NULL
+ );
+ CREATE TABLE other_data (value TEXT NOT NULL);
+ INSERT INTO omissions VALUES ('aaaaaaaaaaaa', X'010203', 'mcp:get_risk', 1, 9, 0, 4);
+ INSERT INTO evidence_references VALUES ('ev_1', X'040506', 'repo', 2);
+ INSERT INTO savings(created_at, filter, source, command, raw_tokens, distilled_tokens)
+ VALUES (3, 'get_risk', 'mcp:get_risk', NULL, 100, 10);
+ INSERT INTO other_data VALUES ('keep me');
+ """
+ )
+ conn.close()
+
+
+def test_clean_install_has_versioned_event_link_and_query_indexes(tmp_path: Path) -> None:
+ store = OmissionStore(tmp_path / "omissions.db")
+ try:
+ assert store._conn.execute("PRAGMA user_version").fetchone()[0] == 1
+ tables = {
+ row[0]
+ for row in store._conn.execute("SELECT name FROM sqlite_master WHERE type = 'table'")
+ }
+ assert {
+ "omissions",
+ "evidence_references",
+ "savings",
+ "savings_events",
+ "savings_event_omissions",
+ "savings_event_correlations",
+ "savings_opportunities",
+ } <= tables
+ indexes = {
+ row[0]
+ for row in store._conn.execute("SELECT name FROM sqlite_master WHERE type = 'index'")
+ }
+ assert {
+ "idx_savings_events_repo_time",
+ "idx_savings_events_surface_time",
+ "idx_savings_correlations_hash",
+ "idx_savings_event_omissions_ref",
+ } <= indexes
+ finally:
+ store.close()
+
+
+def test_old_sidecar_reset_is_scoped_and_preserves_recovery_bytes(tmp_path: Path) -> None:
+ db_path = tmp_path / "omissions.db"
+ _seed_legacy(db_path)
+ store = OmissionStore(db_path)
+ try:
+ assert store._conn.execute("SELECT * FROM omissions").fetchall() == [
+ ("aaaaaaaaaaaa", b"\x01\x02\x03", "mcp:get_risk", 1.0, 9, 0, 4)
+ ]
+ assert store._conn.execute("SELECT * FROM evidence_references").fetchall() == [
+ ("ev_1", b"\x04\x05\x06", "repo", 2.0)
+ ]
+ assert store._conn.execute("SELECT COUNT(*) FROM savings").fetchone()[0] == 0
+ assert store._conn.execute("SELECT * FROM other_data").fetchall() == [("keep me",)]
+ finally:
+ store.close()
+
+
+def test_claimed_current_but_incomplete_sidecar_is_repaired(tmp_path: Path) -> None:
+ db_path = tmp_path / "omissions.db"
+ _seed_legacy(db_path)
+ with sqlite3.connect(db_path) as conn:
+ conn.execute("PRAGMA user_version=1")
+ with OmissionStore(db_path) as store:
+ assert store._conn.execute("SELECT COUNT(*) FROM savings").fetchone()[0] == 0
+ assert store._conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 0
+ assert store._conn.execute("SELECT content FROM omissions").fetchone()[0] == b"\x01\x02\x03"
+
+
+def test_failed_upgrade_rolls_back_tables_rows_and_version(tmp_path: Path, monkeypatch) -> None:
+ db_path = tmp_path / "omissions.db"
+ _seed_legacy(db_path)
+ conn = sqlite3.connect(db_path, isolation_level=None)
+ apply_sqlite_pragmas(conn, 5000)
+ original = schema._apply_v1
+
+ def fail_after_changes(connection: sqlite3.Connection) -> None:
+ original(connection)
+ raise RuntimeError("simulated upgrade failure")
+
+ monkeypatch.setattr(schema, "_apply_v1", fail_after_changes)
+ with pytest.raises(RuntimeError, match="simulated upgrade failure"):
+ schema.initialize_savings_schema(conn)
+ assert conn.execute("PRAGMA user_version").fetchone()[0] == 0
+ assert conn.execute("SELECT COUNT(*) FROM savings").fetchone()[0] == 1
+ assert conn.execute("SELECT content FROM omissions").fetchone()[0] == b"\x01\x02\x03"
+ assert conn.execute("SELECT content FROM evidence_references").fetchone()[0] == b"\x04\x05\x06"
+ assert (
+ conn.execute(
+ "SELECT COUNT(*) FROM sqlite_master WHERE type='table' AND name='savings_events'"
+ ).fetchone()[0]
+ == 0
+ )
+ conn.close()
+
+
+def test_two_concurrent_openers_upgrade_once(tmp_path: Path) -> None:
+ db_path = tmp_path / "omissions.db"
+ _seed_legacy(db_path)
+
+ def open_and_read_version(_: int) -> int:
+ with OmissionStore(db_path) as store:
+ return store._conn.execute("PRAGMA user_version").fetchone()[0]
+
+ with ThreadPoolExecutor(max_workers=2) as executor:
+ assert list(executor.map(open_and_read_version, range(2))) == [1, 1]
+ with sqlite3.connect(db_path) as conn:
+ assert conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 0
+
+
+def test_concurrent_writers_and_retry_dedupe_are_atomic(tmp_path: Path) -> None:
+ db_path = tmp_path / "omissions.db"
+ OmissionStore(db_path).close()
+
+ def write(index: int) -> bool:
+ with OmissionStore(db_path) as store:
+ return SavingsRepository(store._conn).record_event(_event(index))
+
+ with ThreadPoolExecutor(max_workers=8) as executor:
+ assert all(executor.map(write, range(20)))
+ assert write(0) is False
+ with sqlite3.connect(db_path) as conn:
+ assert conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 20
+ assert conn.execute("SELECT COUNT(*) FROM savings_event_omissions").fetchone()[0] == 20
+ correlations = conn.execute(
+ "SELECT kind, value_hash FROM savings_event_correlations"
+ ).fetchall()
+ assert len(correlations) == 40
+ assert all(len(value_hash) == 71 for _, value_hash in correlations)
+ assert not any("session-" in value_hash for _, value_hash in correlations)
+ stored_ids = conn.execute(
+ "SELECT session_id, request_id, tool_call_id FROM savings_events"
+ ).fetchall()
+ assert all(
+ value is None or (value.startswith("sha256:") and len(value) == 71)
+ for row in stored_ids
+ for value in row
+ )
+
+
+def test_fixture_roundtrip_report_prices_each_historical_event(tmp_path: Path) -> None:
+ payload = json.loads(FIXTURE.read_text(encoding="utf-8"))
+ with OmissionStore(tmp_path / "omissions.db") as store:
+ repository = SavingsRepository(store._conn)
+ inserted: dict[str, bool] = {}
+ for record in payload["records"]:
+ event = SavingsEvent.from_mapping(record, accept_event_id=True)
+ inserted[record["attempt_id"]] = repository.record_event(event)
+ for item in payload["opportunities"]:
+ repository.record_opportunity(
+ OpportunityObservation.from_mapping(item, repository_id="fixture-repo")
+ )
+
+ assert inserted["attempt-hook-claude-retry"] is False
+ for scope, days in (("all", None), ("30d", 30), ("7d", 7)):
+ report = repository.report(
+ "fixture-repo", as_of=datetime.fromisoformat(payload["as_of"]), days=days
+ )
+ actual = asdict(report)
+ for key, expected in payload["expected"][scope].items():
+ if isinstance(expected, float):
+ assert actual[key] == pytest.approx(expected)
+ else:
+ assert actual[key] == expected
+
+
+def test_report_queries_are_read_only_and_breakdowns_are_bounded(tmp_path: Path) -> None:
+ db_path = tmp_path / "omissions.db"
+ with OmissionStore(db_path) as store:
+ writer = SavingsRepository(store._conn)
+ for index in range(10):
+ writer.record_event(_event(index, operation=f"tool-{index}"))
+
+ uri = f"file:{db_path.as_posix()}?mode=ro"
+ conn = sqlite3.connect(uri, uri=True, isolation_level=None)
+ statements: list[str] = []
+ conn.set_trace_callback(statements.append)
+ report = SavingsRepository(conn).report(
+ "repo", as_of=datetime.fromisoformat("2026-09-14T01:00:00+00:00"), max_breakdowns=3
+ )
+ conn.close()
+
+ assert report.unique_events == 10
+ assert report.saved_output_tokens is None
+ assert report.priced_saved_output_tokens == 0
+ assert report.unpriced_saved_output_tokens == 0
+ assert len(report.per_operation) == 3
+ assert len(statements) == 3
+ assert all(statement.lstrip().upper().startswith("SELECT") for statement in statements)