Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(savings): add canonical event accounting (#2248)
Raghav Chamadiyab5c1b277d8ad
diff --git a/docs/architecture/savings-accounting.md b/docs/architecture/savings-accounting.mdnew file mode 100644index 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.pyindex 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 structlogfrom repowise.core.distill import trackingfrom repowise.core.distill.markers import REF_LENGTH, is_valid_ref+from repowise.core.savings import schema as savings_schemafrom repowise.core.sqlite_pragmas import apply_sqlite_pragmaslogger = 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_daysself.max_mb = max_mbdb_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)@classmethoddef 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.searchexcept 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 normalizeddiff --git a/packages/core/src/repowise/core/savings/pricing.py b/packages/core/src/repowise/core/savings/pricing.pynew file mode 100644index 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_000diff --git a/packages/core/src/repowise/core/savings/reporting.py b/packages/core/src/repowise/core/savings/reporting.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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()+ raisediff --git a/tests/fixtures/savings/mixed_agents_v1.json b/tests/fixtures/savings/mixed_agents_v1.jsonnew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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_summarydiff --git a/tests/unit/savings/test_contracts.py b/tests/unit/savings/test_contracts.pynew file mode 100644index 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 == 0diff --git a/tests/unit/savings/test_repository.py b/tests/unit/savings/test_repository.pynew file mode 100644index 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)