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): record one canonical event per logical interaction (#2401)
Raghav Chamadiya7d1e806246db
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.pyindex 57a19e4e4..1d13e4443 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/_shared.py@@ -212,9 +212,15 @@ def record_saving(command: str,raw_tokens: int,distilled_tokens: int,+ hook_adapter: str | None = None,) -> None:"""Bill one replacement to the savings ledger so ``repowise saved`` sees it.+ Writes the legacy row and the canonical event. The legacy one stays until+ the costs endpoint, the overview headline and ``repowise saved`` read the+ canonical report instead; writing both means this change neither regresses+ a published figure nor claims the old row improved.+Never creates the omission store: its absence means this repo has notopted into distill bookkeeping, and a hook is not the place to decideotherwise. Any failure is swallowed, because accounting must not cost the agent an@@ -238,12 +244,77 @@ def record_saving(raw_tokens=raw_tokens,distilled_tokens=distilled_tokens,)+ _record_event(+ con,+ repo_path,+ filter_name=filter_name,+ raw_tokens=raw_tokens,+ distilled_tokens=distilled_tokens,+ hook_adapter=hook_adapter,+ )finally:con.close()except Exception:return+def _record_event(+ connection: object,+ repo_path: Path,+ *,+ filter_name: str,+ raw_tokens: int,+ distilled_tokens: int,+ hook_adapter: str | None,+) -> None:+ """Record the canonical event for one hook replacement. Never raises.++ Written on the connection this function's caller already opened, which is+ the point. Reaching the ledger through ``OmissionStore`` would import+ ``distill.store`` and therefore structlog -- roughly 250ms, on the surface+ whose entire justification is latency, and the exact import+ :func:`_omission_db` spells its path out to avoid. This still runs before+ the hook process exits, so the agent does wait on it; "after the response+ is computed" is not the same as free.++ Attribution is real here rather than ``unknown``. The hook was handed the+ serving agent's own adapter, so which agent saved these tokens is evidence,+ not a guess.+ """+ try:+ from datetime import UTC, datetime++ from repowise.core.agents.identity import slug_for_hook_adapter+ from repowise.core.savings import recorder+ from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key++ agent = slug_for_hook_adapter(hook_adapter)+ event_id = new_event_id()+ recorder.record_event_on(+ connection,+ repo_path,+ {+ "event_id": event_id,+ "idempotency_key": scoped_idempotency_key(str(repo_path), "hook", event_id),+ "occurred_at": datetime.now(UTC),+ "surface": "hook",+ "integration": agent,+ "agent": agent,+ "operation": filter_name,+ "evidence_kind": "measured",+ "estimator": "chars_per_token_floor_v1",+ "token_unit": "estimated_tokens",+ "result_state": "success",+ "is_usable": True,+ "baseline_input_tokens": raw_tokens,+ "pre_budget_input_tokens": raw_tokens,+ "delivered_input_tokens": distilled_tokens,+ },+ )+ except Exception:+ return++def record_forgone(repo_path: Path,*,@@ -281,6 +352,51 @@ def record_forgone(con.close()except Exception:return+ _record_opportunity(+ repo_path,+ filter_name=filter_name or source,+ raw_tokens=raw_tokens,+ distilled_tokens=distilled_tokens,+ )+++def _record_opportunity(+ repo_path: Path,+ *,+ filter_name: str,+ raw_tokens: int,+ distilled_tokens: int,+) -> None:+ """Record a forgone saving as an observed opportunity. Never raises.++ An opportunity, not an event, and that distinction is the whole reason this+ is a separate function: this repository did not save these tokens, it only+ could have. The canonical ledger keeps the two in different tables so no+ later aggregation can accidentally sum a hypothetical into what was actually+ achieved.++ The path is deliberately not carried over. The legacy table stores it to+ tell a user which file to turn the surface on for; an opportunity row only+ needs the size of what was missed, and a repo-relative path is still a path.+ """+ try:+ from datetime import UTC, datetime++ from repowise.core.savings import recorder+ from repowise.core.savings.correlation import new_event_id++ recorder.record_opportunity(+ repo_path,+ {+ "observation_id": new_event_id(),+ "occurred_at": datetime.now(UTC),+ "integration": "unknown",+ "kind": f"hook_surface_disabled:{filter_name}",+ "estimated_potential_input_tokens": max(raw_tokens - distilled_tokens, 0),+ },+ )+ except Exception:+ returndef _relativize(file_path: str, repo_path: Path) -> str | None:diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.py b/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.pyindex 2dd807ebc..649bddc67 100644--- a/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.py+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/replacement.py@@ -211,13 +211,19 @@ def offer(if payload is None:return None, Nonecandidate.payload = payload- return candidate, _saving_writer(repo_path, candidate, source)+ return candidate, _saving_writer(repo_path, candidate, source, adapter)except Exception:return None, None-def _saving_writer(repo_path: Path, served: Offer, source: str) -> Callable[[], None]:- """The savings-ledger write for a replacement the agent received."""+def _saving_writer(+ repo_path: Path, served: Offer, source: str, adapter: AgentAdapter+) -> Callable[[], None]:+ """The savings-ledger write for a replacement the agent received.++ The adapter comes along because it names the agent being served, which is+ the one surface where attribution is known rather than inferred.+ """def _write() -> None:try:@@ -228,6 +234,7 @@ def _saving_writer(repo_path: Path, served: Offer, source: str) -> Callable[[],command=served.key,raw_tokens=served.raw_tokens,distilled_tokens=served.new_tokens,+ hook_adapter=getattr(adapter, "name", None),)except Exception:returndiff --git a/packages/core/src/repowise/core/agents/__init__.py b/packages/core/src/repowise/core/agents/__init__.pyindex 84b525c16..63da17258 100644--- a/packages/core/src/repowise/core/agents/__init__.py+++ b/packages/core/src/repowise/core/agents/__init__.py@@ -25,6 +25,7 @@ from repowise.core.agents.identity import (normalize_client_name,register_identity,resolve_client_identity,+ slug_for_hook_adapter,unregister_identity,)@@ -40,5 +41,6 @@ __all__ = ["normalize_client_name","register_identity","resolve_client_identity",+ "slug_for_hook_adapter","unregister_identity",]diff --git a/packages/core/src/repowise/core/agents/identity.py b/packages/core/src/repowise/core/agents/identity.pyindex a5046ea4f..a2366377a 100644--- a/packages/core/src/repowise/core/agents/identity.py+++ b/packages/core/src/repowise/core/agents/identity.py@@ -219,6 +219,22 @@ def get_identity(slug: str) -> AgentIdentity | None:return _REGISTERED.get(slug)+def slug_for_hook_adapter(name: str | None) -> str:+ """The agent behind a hook adapter's name, or :data:`UNKNOWN_AGENT`.++ The hook path knows exactly which agent it is serving — it was handed that+ agent's adapter — so attribution there is evidence rather than inference.+ This is the lookup that turns the adapter's own spelling back into the+ canonical one, instead of a caller re-deriving it.+ """+ if not name:+ return UNKNOWN_AGENT+ for identity in _REGISTERED.values():+ if identity.hook_adapter == name:+ return identity.slug+ return UNKNOWN_AGENT++def identity_for_target_id(target_id: str) -> AgentIdentity | None:"""The identity behind a ``--target=`` id."""return get_identity(target_id.replace("-", "_"))diff --git a/packages/core/src/repowise/core/distill/engine.py b/packages/core/src/repowise/core/distill/engine.pyindex 2a98df561..dcb0d007b 100644--- a/packages/core/src/repowise/core/distill/engine.py+++ b/packages/core/src/repowise/core/distill/engine.py@@ -20,6 +20,7 @@ from __future__ import annotationsimport contextlibfrom dataclasses import dataclass+from datetime import UTC, datetimefrom pathlib import Pathimport structlog@@ -66,6 +67,77 @@ class DistillResult:return savings_pct(self.raw_tokens, self.distilled_tokens)+def _record_event(+ store: OmissionStore,+ *,+ source: str,+ filter_name: str,+ ref: str,+ raw_tokens: int,+ distilled_tokens: int,+) -> None:+ """Record the canonical savings event beside the legacy ledger row.++ Written through the store already open here rather than by reopening the+ sidecar, and never raising: this sits inside the block whose failure mode is+ "fall back to raw output", and a ledger problem must not cost the user their+ distillation.++ The repository is derived from the store's own path, which is the only+ source available here: ``distill_output`` is reached from callers that do+ not all know a repository root.++ That derivation is only valid for a repo-local sidecar.+ ``OmissionStore.open_default`` falls back to ``~/.repowise`` when there is+ no repository, and the same arithmetic would then call the user's home+ directory a repository -- merging every uninitialized directory on the+ machine into one ledger keyed on ``/home/<user>``, which is precisely what+ the recorder exists to prevent. So a store that is not+ ``<root>/.repowise/omissions/omissions.db`` records nothing. An event+ attributed to the wrong repository is worse than one not recorded.++ Attribution stays ``unknown``. The source distinguishes the CLI from the+ rewrite hook's shell, which is not the same thing as knowing which agent ran+ it, and the contract says an unknown field stays unknown rather than being+ filled with the likeliest answer.+ """+ from repowise.core.savings import recorder+ from repowise.core.savings.correlation import new_event_id, scoped_idempotency_key++ try:+ repo_root = store.db_path.parents[2]+ if store.db_path != recorder.sidecar_path(repo_root) or repo_root == Path.home():+ return+ event_id = new_event_id()+ recorder.record_event_in(+ store,+ repo_root,+ {+ "event_id": event_id,+ "idempotency_key": scoped_idempotency_key(str(repo_root), "distill", event_id),+ "occurred_at": datetime.now(UTC),+ # The rewrite hook tags its shell; everything else is the CLI.+ "surface": "hook" if source.startswith("hook") else "distill",+ "integration": "unknown",+ "agent": "unknown",+ "operation": filter_name,+ "evidence_kind": "measured",+ "estimator": "chars_per_token_floor_v1",+ "token_unit": "estimated_tokens",+ "result_state": "success",+ "is_usable": True,+ # Host-capped, because bytes past the host's own truncation were+ # never going to reach the model and cannot be claimed.+ "baseline_input_tokens": raw_tokens,+ "pre_budget_input_tokens": raw_tokens,+ "delivered_input_tokens": distilled_tokens,+ "omission_refs": (ref,),+ },+ )+ except Exception:+ logger.debug("distill savings event failed", exc_info=True)++def distill_output(output: str,*,@@ -141,6 +213,14 @@ def distill_output(raw_tokens=raw_tokens,distilled_tokens=distilled_tokens,)+ _record_event(+ store,+ source=source,+ filter_name=chosen.name,+ ref=ref,+ raw_tokens=raw_tokens,+ distilled_tokens=distilled_tokens,+ )return DistillResult(text=text,distilled=True,diff --git a/packages/core/src/repowise/core/distill/store.py b/packages/core/src/repowise/core/distill/store.pyindex cb4395d44..f221f5e98 100644--- a/packages/core/src/repowise/core/distill/store.py+++ b/packages/core/src/repowise/core/distill/store.py@@ -22,6 +22,7 @@ import structlogfrom repowise.core.distill import trackingfrom repowise.core.distill.markers import REF_LENGTH, is_valid_reffrom repowise.core.savings import schema as savings_schema+from repowise.core.savings.repository import SavingsRepositoryfrom repowise.core.sqlite_pragmas import apply_sqlite_pragmaslogger = structlog.get_logger(__name__)@@ -242,6 +243,15 @@ class OmissionStore:"""Grouped ledger totals (see :func:`tracking.savings_rollup`)."""return tracking.savings_rollup(self._conn, by=by, since=since)+ def savings(self) -> SavingsRepository:+ """The canonical event ledger, sharing this store's connection.++ The event tables live in this same file, installed by the same schema+ upgrade the constructor runs, so they are reached through the store that+ already owns the connection rather than by opening a second one.+ """+ return SavingsRepository(self._conn)+# -- lifecycle ---------------------------------------------------------def close(self) -> None:diff --git a/packages/core/src/repowise/core/savings/recorder.py b/packages/core/src/repowise/core/savings/recorder.pynew file mode 100644index 000000000..7ab977bac--- /dev/null+++ b/packages/core/src/repowise/core/savings/recorder.py@@ -0,0 +1,202 @@+"""The one way a capture surface records what it saved.++Every surface — distill, the hooks, MCP, the native VS Code tools — writes+through this function. Not because the write is complicated, but because the+rules around it are, and they were previously re-decided per surface: which+database to open, whether to create one, and what to do when the write fails.+Three surfaces answered those three questions three ways.++Two of those answers are load-bearing and are fixed here.++**The sidecar is repo-local and is never created.** A savings row belongs to the+repository it describes, in the same file the costs page reads. Falling back to+``~/.repowise`` would put a row somewhere no dashboard looks and mix unrelated+repositories into one ledger, so an absent sidecar means the repository never+opted in and the event is dropped.++**Recording never raises.** Accounting sits behind a live tool call, a hook, and+a shell command. A ledger that can fail a user's command is worse than no+ledger, so every failure here is swallowed and logged at debug. The return value+says whether a row landed, for callers that want to stamp metadata only when one+did; nobody has to check it.++Short and WAL-friendly by construction: open, write, close. No handle outlives+the call, because two of the callers are hot paths and one of them is a hook+that runs on every tool use.+"""++from __future__ import annotations++import contextlib+import logging+from collections.abc import Mapping+from pathlib import Path+from typing import Any++logger = logging.getLogger(__name__)+++#: Spelled out rather than imported from ``distill.store``, which owns these+#: constants but costs a structlog import to read them -- the same reason the+#: hook path spells the path out. Kept honest by+#: ``test_the_sidecar_path_matches_the_store_that_owns_it``.+_SIDECAR_PARTS = (".repowise", "omissions", "omissions.db")+++def sidecar_path(repo_root: str | Path) -> Path:+ """Where a repository's savings sidecar lives."""+ return Path(repo_root).joinpath(*_SIDECAR_PARTS)+++def record_event(repo_root: str | Path | None, payload: Mapping[str, Any]) -> bool:+ """Record one savings event against *repo_root*. Never raises.++ *payload* is the mapping :meth:`SavingsEvent.from_mapping` validates, minus+ ``repository_id``, which is taken from *repo_root* so a caller cannot+ attribute an event to a repository it is not writing to.++ Returns True only when a row was actually inserted. A retry of an event+ already recorded returns False, as does a dropped one, because in both cases+ this call added nothing.+ """+ try:+ if not repo_root:+ return False+ db_path = sidecar_path(repo_root)+ if not db_path.is_file():+ return False+ event = _build(payload, repo_root)+ if event is None:+ return False+ # ``distill.store`` pulls structlog, which is why this is not imported+ # at module scope. A surface that measures its latency in milliseconds+ # reaches the ledger through :func:`record_event_on` instead.+ from repowise.core.distill.store import OmissionStore++ store = OmissionStore(db_path)+ except Exception:+ logger.debug("savings recorder could not open the sidecar", exc_info=True)+ return False+ try:+ return _write(store.savings(), event)+ finally:+ with contextlib.suppress(Exception):+ store.close()+++def record_event_in(store: Any, repo_root: str | Path | None, payload: Mapping[str, Any]) -> bool:+ """Record an event through an already-open store. Never raises.++ Same rules as :func:`record_event`, minus the open and close. A surface that+ already holds the sidecar open uses this rather than the other: a second+ connection to the same file, while the first one holds a write lock, is a+ lock fight rather than a second writer.+ """+ if store is None or not repo_root:+ return False+ event = _build(payload, repo_root)+ if event is None:+ return False+ try:+ return _write(store.savings(), event)+ except Exception:+ logger.debug("savings write failed; dropping silently", exc_info=True)+ return False+++def record_event_on(+ connection: Any, repo_root: str | Path | None, payload: Mapping[str, Any]+) -> bool:+ """Record an event on a raw sqlite connection. Never raises.++ For the surface that cannot afford :class:`OmissionStore`. The hook budgets+ itself in milliseconds and opens the sidecar with plain ``sqlite3``+ precisely so it never imports ``distill.store``, which pulls structlog at+ roughly 250ms. It reaches the ledger through the same validation and against+ the same repository as every other surface, on the connection it already+ holds.++ The ceiling: a raw connection does not run the schema upgrade, so an event+ written against a sidecar older than the event tables is dropped rather than+ migrating the store from inside a hook. Any other opener repairs it, and+ paying a migration on a latency-critical path is the worse trade.+ """+ if connection is None or not repo_root:+ return False+ event = _build(payload, repo_root)+ if event is None:+ return False+ try:+ from repowise.core.savings.repository import SavingsRepository++ return _write(SavingsRepository(connection), event)+ except Exception:+ logger.debug("savings write failed; dropping silently", exc_info=True)+ return False+++def _build(payload: Mapping[str, Any], repo_root: str | Path) -> Any:+ """Validate *payload* into an event, or ``None`` when it is malformed.++ The repository is taken from the path being written to, overriding whatever+ the payload said, so a surface holding a stale id cannot file one+ repository's savings under another. A malformed event is a bug in the+ calling surface, not in the user's command: loud in the log, invisible to+ them.++ ``accept_event_id`` is set, so the id the surface minted is the id stored.+ Without it the contract quietly substitutes a fresh one, and then nothing+ can join a log line to its row, and the idempotency key is scoped on an id+ that was discarded -- which makes retry deduplication unreachable while+ appearing to work.+ """+ try:+ from repowise.core.savings.contracts import SavingsEvent++ return SavingsEvent.from_mapping(+ {**payload, "repository_id": str(repo_root)}, accept_event_id=True+ )+ except Exception:+ logger.debug("savings event rejected before write", exc_info=True)+ return None+++def _write(repository: Any, event: Any) -> bool:+ try:+ return bool(repository.record_event(event))+ except Exception:+ logger.debug("savings write failed; dropping silently", exc_info=True)+ return False+++def record_opportunity(repo_root: str | Path | None, payload: Mapping[str, Any]) -> bool:+ """Record one observed opportunity. Never raises.++ Kept deliberately separate from :func:`record_event`. An opportunity is+ behaviour that *could* have been optimised and was not, so it must never+ reach a total of what was saved; giving it its own function means no caller+ can pass one to the other by filling in a different field.+ """+ try:+ if not repo_root:+ return False+ db_path = sidecar_path(repo_root)+ if not db_path.is_file():+ return False++ from repowise.core.distill.store import OmissionStore+ from repowise.core.savings.contracts import OpportunityObservation++ observation = OpportunityObservation.from_mapping(payload, repository_id=str(repo_root))+ store = OmissionStore(db_path)+ except Exception:+ logger.debug("opportunity rejected before write", exc_info=True)+ return False+ try:+ return bool(store.savings().record_opportunity(observation))+ except Exception:+ logger.debug("opportunity write failed; dropping silently", exc_info=True)+ return False+ finally:+ with contextlib.suppress(Exception):+ store.close()diff --git a/packages/server/src/repowise/server/mcp_server/__init__.py b/packages/server/src/repowise/server/mcp_server/__init__.pyindex a9a32469d..59b21a4f0 100644--- a/packages/server/src/repowise/server/mcp_server/__init__.py+++ b/packages/server/src/repowise/server/mcp_server/__init__.py@@ -97,12 +97,23 @@ def tool_middleware(fn: Any) -> Any:the whole session), so it must see the raw tool.2. ``trust`` — adds the final transport trust envelope.3. ``quantize`` — rounds every float in the response. Outside the shield so- shaped error responses are covered too, and inside the savings layer so- the ledger measures the payload as actually delivered.- 4. ``budget`` — caps the delivered shape before savings are measured.- 5. ``instrument`` — records the bounded result and adds savings metadata.+ shaped error responses are covered too.+ 4. ``budget`` — caps the delivered shape. Also reports the raw tool output+ size to the interaction: this is the only layer that sees it before+ anything has been shed.+ 5. ``instrument`` — derives the counterfactual and adds savings metadata.+ It must be here rather than further out, because the estimators read+ fields a later budget pass is free to drop.6. ``timed`` — stamps ``_meta.timing_ms`` for any tool that did not.7. ``budget`` — accounts for those final middleware fields and rechecks.+ 8. ``record`` — writes the one savings event for the call.++ Layer 8 is outside everything for a reason. The ledger row used to be+ written at layer 5, after which ``timed`` stamped ``_meta`` and layer 7 ran+ the budgeter twice more, free to shed content and re-stamp sizes. The+ recorded delivered size was therefore one the agent never received. Each+ layer now reports what only it can see, and the event is written when the+ payload is final.Named rather than inlined at the ``apply`` call so tests can wrap a tool inthe real composition; ``tests/unit/server/mcp/test_number_precision.py``@@ -119,7 +130,9 @@ def tool_middleware(fn: Any) -> Any:from repowise.server.mcp_server._failure_shield import shieldfrom repowise.server.mcp_server._meta import finalize_trust_envelopefrom repowise.server.mcp_server._rounding import quantize+ from repowise.server.mcp_server._savings import event as savings_eventfrom repowise.server.mcp_server._savings import instrument+ from repowise.server.mcp_server._savings import interaction as savings_interactionevidence_kind = getattr(fn, "__repowise_trust_kind__", None)signature = inspect.signature(fn)@@ -156,9 +169,19 @@ def tool_middleware(fn: Any) -> Any:@wraps(inner)async def wrapped(*args: Any, **kwargs: Any) -> Any:repo_root = await resolve_response_budget_repo_root(signature, args, kwargs)+ raw = await inner(*args, **kwargs)+ live = savings_interaction.current()+ if live is not None:+ # Both instantiations run this closure, and the inner one runs+ # first, so only its value has seen untrimmed output. Guarded+ # rather than merely ignored: the measurement serializes the+ # whole payload, and the outer layer's result is discarded.+ if live.pre_budget_input_tokens is None:+ live.observe_pre_budget(savings_event.raw_response_tokens(raw))+ live.repo_root = live.repo_root or (str(repo_root) if repo_root else None)result = enforce_response_budget(fn.__name__,- await inner(*args, **kwargs),+ raw,signature=signature,args=args,kwargs=kwargs,@@ -176,7 +199,19 @@ def tool_middleware(fn: Any) -> Any:return wrapped- return budget(timed(instrument(budget(quantize(trust(shield(fn)))))))+ def record(inner: Any) -> Any:+ """Open the interaction, then write its one event once nothing can change."""++ @wraps(inner)+ async def wrapped(*args: Any, **kwargs: Any) -> Any:+ with savings_interaction.begin(fn.__name__) as live:+ result = await inner(*args, **kwargs)+ savings_event.record(live, result)+ return result++ return wrapped++ return record(budget(timed(instrument(budget(quantize(trust(shield(fn))))))))def ensure_full_surface() -> Any:diff --git a/packages/server/src/repowise/server/mcp_server/_savings/event.py b/packages/server/src/repowise/server/mcp_server/_savings/event.pynew file mode 100644index 000000000..e89479a09--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/_savings/event.py@@ -0,0 +1,165 @@+"""Turn a finished MCP invocation into exactly one canonical savings event.++This runs outside every other layer, which is the whole point. The previous+ledger row was written at the savings layer, five of seven layers deep: after+it, ``timed`` stamped ``_meta`` and the outer budget ran the budgeter twice+more, free to shed list entries, replace protected dicts with omission markers+and pop whole keys. So the recorded delivered size was a size the agent never+received, the row overstated what arrived, and anything the outer layer dropped+was invisible to the accounting. Measuring here is measuring the bytes that+actually left.++The evidence split follows the accounting contract exactly. With a+counterfactual the saving is ``replaced - delivered`` and the correlated+truncation is diagnostic only, never added a second time. Without one the+saving is the measured truncation, ``raw - delivered``, and nothing is inferred.+"""++from __future__ import annotations++import logging+from typing import Any++from repowise.core.savings.correlation import scoped_idempotency_key++from .interaction import Interaction++logger = logging.getLogger(__name__)++#: The estimator every repowise savings figure is reported on: floor(chars / 4).+_ESTIMATOR = "chars_per_token_floor_v1"+_TOKEN_UNIT = "estimated_tokens"+++def _outcome(result: Any) -> tuple[str, bool]:+ """Classify the delivered response as the contract's result state.++ Three states, and the two that are missing are deliberate. A shaped error is+ an ``error``: it saved nothing, and its delivered overhead is recorded as+ diagnostic rather than as the negative saving the legacy ledger wrote, which+ is how a session that net-spent could still report a credit.++ ``partial`` means content was omitted but is recoverable, so what arrived is+ usable. Both ways of being partial count: a tool that declared itself+ partial at the trust layer, and a response the budgeter shed content from,+ which sets ``state.truncated`` later and is the far more common case.+ Reporting a truncated response as a plain success would credit the bytes+ repowise discarded to a call the agent received incomplete, with nothing in+ the row saying so. The saving is unchanged either way -- the contract gives+ a usable partial the same formula -- so this is about what the row admits,+ not about the number.++ ``dead_end`` is not produced here: a call that succeeds while answering+ nothing needs a per-tool notion of "answered", and inventing one from the+ response shape would be guessing. A tool that knows it dead-ended can say+ so; until one does, such a call is a success that saved zero, which is what+ the contract says a zero-delta success is.+ """+ if not isinstance(result, dict):+ return "success", True+ if result.get("error"):+ return "error", False+ meta = result.get("_meta")+ state = meta.get("state") if isinstance(meta, dict) else None+ if isinstance(state, dict) and (state.get("partial") or state.get("truncated")):+ return "partial", True+ return "success", True+++def raw_response_tokens(result: Any) -> int | None:+ """Size an unbudgeted tool response, or ``None`` when it cannot be sized.++ Distinct from the delivered measurement: nothing has stamped a size on this+ payload yet, so it is serialized here, compactly, on the same+ ``floor(chars / 4)`` scale every repowise savings figure uses.+ """+ import json++ from repowise.core.distill.budget import estimate_tokens++ try:+ return estimate_tokens(json.dumps(result, separators=(",", ":"), default=str))+ except Exception:+ return None+++def _omission_refs(result: Any) -> tuple[str, ...]:+ """Recovery references this invocation produced, as bare store keys.++ Read off the settled response rather than from the collectors, because a+ single call builds up to four of them across the two budget layers and+ ``attach`` has already merged their refs into one place.++ The response carries them in their public shape, ``repowise#<hex>``, while+ the store keys on the bare hex and the ledger's foreign key expects the+ same. Normalized through the one helper that knows every public shape, so a+ prefixed ref cannot reach validation and silently drop the whole event --+ which it did, on exactly the truncated responses where a saving is largest.+ """+ from repowise.core.distill.markers import normalize_ref++ if not isinstance(result, dict):+ return ()+ meta = result.get("_meta")+ omitted = meta.get("omitted") if isinstance(meta, dict) else None+ refs = omitted.get("refs") if isinstance(omitted, dict) else None+ if not isinstance(refs, list):+ return ()+ normalized = (normalize_ref(ref) for ref in refs if isinstance(ref, str))+ return tuple(ref for ref in normalized if ref is not None)+++def record(interaction: Interaction, result: Any) -> bool:+ """Record the one event for *interaction*. Never raises."""+ try:+ return _record(interaction, result)+ except Exception: # pragma: no cover - accounting never breaks a tool call+ logger.debug("mcp savings event failed for %s", interaction.tool, exc_info=True)+ return False+++def _record(interaction: Interaction, result: Any) -> bool:+ from repowise.core.savings import recorder++ from .wrapper import response_tokens++ if not interaction.repo_root:+ return False++ delivered = response_tokens(result)+ result_state, is_usable = _outcome(result)+ baseline = interaction.baseline_input_tokens+ inferred = baseline is not None++ payload: dict[str, Any] = {+ "event_id": interaction.event_id,+ "idempotency_key": scoped_idempotency_key(+ str(interaction.repo_root), "mcp", interaction.event_id+ ),+ "occurred_at": _now(),+ "surface": "mcp",+ "integration": interaction.agent,+ "agent": interaction.agent,+ "session_id": interaction.session_id,+ "request_id": interaction.request_id,+ "operation": interaction.tool,+ # Inferred only when a counterfactual was actually derived. Truncation+ # on its own is a measured before/after of bytes that really moved.+ "evidence_kind": "inferred" if inferred else "measured",+ "estimator": _ESTIMATOR,+ "token_unit": _TOKEN_UNIT,+ "result_state": result_state,+ "is_usable": is_usable,+ "baseline_input_tokens": baseline,+ "pre_budget_input_tokens": interaction.pre_budget_input_tokens,+ "delivered_input_tokens": delivered,+ "omission_refs": _omission_refs(result),+ "metadata": interaction.identity_metadata or None,+ }+ return recorder.record_event(interaction.repo_root, payload)+++def _now() -> str:+ from datetime import UTC, datetime++ return datetime.now(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")diff --git a/packages/server/src/repowise/server/mcp_server/_savings/interaction.py b/packages/server/src/repowise/server/mcp_server/_savings/interaction.pynew file mode 100644index 000000000..87c4c29f7--- /dev/null+++ b/packages/server/src/repowise/server/mcp_server/_savings/interaction.py@@ -0,0 +1,173 @@+"""One logical MCP invocation, as seen by every layer that measures part of it.++No single middleware layer can account for a tool call on its own, and that is+why the numbers were wrong rather than merely incomplete. The three input sizes+the accounting contract wants are observable at three different depths:++* the **raw tool output**, visible only inside the innermost budget layer,+ before anything has been shed;+* the **counterfactual baseline**, computable only at the savings layer, because+ the estimators read fields (``results[].target_path``,+ ``targets[].skeleton.full_tokens``) that a later budget pass may drop;+* the **delivered payload**, final only after the outermost budget has run,+ which is *after* the old ledger row was written.++So the invocation gets an identity at the outermost layer and each depth records+what only it can see. One event per call, measured where each number is true.++The carrier is a context variable rather than a parameter because FastMCP builds+each tool's input schema from its signature: threading state through the call+would change the schema every layer is carefully written to preserve.+"""++from __future__ import annotations++import contextlib+import logging+from collections.abc import Iterator+from contextlib import contextmanager+from contextvars import ContextVar+from dataclasses import dataclass, field+from typing import Any+from weakref import WeakKeyDictionary++from repowise.core.agents.identity import UNKNOWN_AGENT+from repowise.core.savings.correlation import new_event_id++logger = logging.getLogger(__name__)+++@dataclass+class Interaction:+ """What one MCP tool call accumulated on its way out."""++ event_id: str+ tool: str+ #: Set by the budget layers, which already resolve it; recording it here+ #: saves a third resolution per call on a path that runs per tool use.+ repo_root: str | None = None+ agent: str = UNKNOWN_AGENT+ identity_metadata: dict[str, str] = field(default_factory=dict)+ session_id: str | None = None+ request_id: str | None = None+ #: The counterfactual the answer replaced, when one could be derived.+ baseline_input_tokens: int | None = None+ #: Raw tool output, before any budget shed anything.+ pre_budget_input_tokens: int | None = None++ def observe_pre_budget(self, tokens: int | None) -> None:+ """Record the raw size, first positive writer only.++ Both budget layers run this closure, and the innermost one runs first,+ so the first value is the only one that has seen the untrimmed output.++ Non-positive values are refused rather than accepted, because the+ failure modes of the two later reporters are ``0`` and ``None``, not an+ exception. Letting a ``0`` win would pin the raw size at zero and report+ a call that shed megabytes as having saved nothing -- silently, and only+ on the responses big enough to fail serialization.+ """+ if self.pre_budget_input_tokens is None and tokens is not None and tokens > 0:+ self.pre_budget_input_tokens = tokens+++_CURRENT: ContextVar[Interaction | None] = ContextVar("_repowise_mcp_interaction", default=None)++#: Per-connection attribution, resolved once and reused.+#:+#: ``clientInfo`` is announced at initialize and cannot change within a session,+#: so resolving it per event would be pure repetition on a hot path. Keyed+#: weakly on the session object, so a closed connection's entry goes away with+#: it rather than accumulating for the life of the server.+_SESSIONS: WeakKeyDictionary[Any, tuple[str, dict[str, str], str]] = WeakKeyDictionary()+++def current() -> Interaction | None:+ """The invocation in flight, or ``None`` outside one."""+ return _CURRENT.get()+++@contextmanager+def begin(tool: str) -> Iterator[Interaction]:+ """Open an invocation, mint its id, and attribute it. Never raises."""+ interaction = Interaction(event_id=new_event_id(), tool=tool)+ try:+ interaction.agent, interaction.identity_metadata, interaction.session_id = _attribution()+ interaction.request_id = _request_id()+ except Exception: # pragma: no cover - attribution is best-effort+ logger.debug("mcp attribution failed for %s", tool, exc_info=True)+ token = _CURRENT.set(interaction)+ try:+ yield interaction+ finally:+ _CURRENT.reset(token)+++def _context() -> Any | None:+ """The FastMCP request context, or ``None`` when there is no live request.++ ``get_context()`` swallows the missing-contextvar ``LookupError`` and hands+ back a context whose ``session`` property then raises, so both have to be+ guarded here rather than at the call site.+ """+ try:+ from repowise.server.mcp_server._server import mcp++ return mcp.get_context()+ except Exception:+ return None+++def _attribution() -> tuple[str, dict[str, str], str | None]:+ """Resolve who is calling, once per connection.++ Returns ``unknown`` for a client that announced nothing. Never the CLI's+ auto-detection fallback: guessing here would file one host's traffic under+ another, which is worse than admitting we cannot tell.+ """+ from repowise.core.savings.normalization import normalize_mcp_identity++ # ``session`` is a property that raises outside a request rather than+ # returning None, and ``getattr`` with a default does not suppress an+ # exception raised *by* a property. So the access itself is the guard.+ try:+ session = _context().session # type: ignore[union-attr]+ except Exception:+ session = None+ if session is None:+ return UNKNOWN_AGENT, {}, None++ cached = _SESSIONS.get(session)+ if cached is not None:+ return cached++ announced = None+ params = getattr(session, "client_params", None)+ client_info = getattr(params, "clientInfo", None)+ if client_info is not None:+ announced = getattr(client_info, "name", None)+ agent, metadata = normalize_mcp_identity(announced)++ # A server-minted namespace, not a protocol value: stdio exposes no session+ # id, and the JSON-RPC request id is client-chosen and per-request. This is+ # stable for the life of the connection, which is what a session means here.+ resolved = (agent, metadata, new_event_id())+ with contextlib.suppress(TypeError): # a session that cannot be weak-referenced+ _SESSIONS[session] = resolved+ return resolved+++def _request_id() -> str | None:+ """The JSON-RPC request id, for correlation only.++ Client-chosen and connection-scoped, so it is never an event id and is+ hashed rather than stored by the time it reaches the ledger.+ """+ context = _context()+ if context is None:+ return None+ try:+ value = context.request_id+ except Exception:+ return None+ return str(value) if value not in (None, "") else Nonediff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.pyindex 39470a627..bc924e49b 100644--- a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py+++ b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py@@ -34,9 +34,7 @@ import loggingfrom collections.abc import Callablefrom typing import Any-from repowise.core.distill.budget import estimate_tokens--from . import counterfactual+from . import counterfactual, interactionfrom .recorder import record_mcp_dead_end, record_mcp_savinglogger = logging.getLogger(__name__)@@ -185,42 +183,72 @@ def _declared_tokens(result: Any) -> int | None:return value if isinstance(value, int) and value > 0 else None-def _delivered_tokens(result: Any) -> int:- """Estimate tokens the agent actually received for *result*."""- try:- text = json.dumps(result, default=str)- except Exception:- return 0- return estimate_tokens(text)-+def response_tokens(result: Any) -> int:+ """Tokens the agent actually received for *result*.-def _record(tool: str, result: Any) -> None:- """Measure, derive the counterfactual, and record — all best-effort."""+ Reads the budgeter's own compact serialization, which is the measurement+ the budget decisions were made against. The old helper here serialized with+ default separators instead, so the ledger's delivered size and the+ telemetry's response size disagreed for the same call, and the ledger's was+ systematically the larger of the two.+ """+ size = _response_size(result)+ return size[1] if size is not None else 0+++def _observe_baseline(tool: str, result: Any) -> None:+ """Derive the counterfactual here, and write the legacy row as before.++ The counterfactual must be derived at this depth: the estimators read fields+ a later budget pass is free to drop — a search reply's+ ``results[].target_path``, a context reply's ``targets[].skeleton.full_tokens``+ — so computing it further out would silently fall to zero on exactly the+ large responses where it matters most. The number is carried on the+ interaction, and the canonical event is written outside every layer, once+ the delivered size is final.++ The legacy ``savings`` row is still written, and still measured here rather+ than at the end, because the costs endpoint, the overview headline and+ ``repowise saved`` all still read that table and move to the canonical+ report as their own change.++ One thing about it did change: delivered size now comes from+ :func:`response_tokens`, which reads the budgeter's compact serialization,+ where this used to serialize with default separators. Compact JSON is+ smaller, so the legacy row's ``distilled_tokens`` drops and its saving+ rises. That is a one-time step up in the published MCP figure. It is the+ right number -- the old one disagreed with the telemetry's size for the+ same call -- but it is a change, not a no-op.+ """declared = _declared_tokens(result)replaced = (declared if declared is not None else counterfactual.replaced_tokens_for(tool, result))+ live = interaction.current()+ if live is not None:+ live.observe_pre_budget(response_tokens(result))+ if replaced > 0:+ live.baseline_input_tokens = replaced+if replaced <= 0:- # Dead-end debit: an error response delivered tokens and replaced- # nothing — net negative for the session, and the ledger must say so.if isinstance(result, dict) and result.get("error"):from repowise.server.mcp_server import _staterecord_mcp_dead_end(- getattr(_state, "_repo_path", None), tool, _delivered_tokens(result)+ getattr(_state, "_repo_path", None), tool, response_tokens(result))return- delivered = _delivered_tokens(result)-- # Resolve the repo the MCP server is scoped to. Lazy import keeps this- # module free of package import-ordering coupling.+ delivered = response_tokens(result)from repowise.server.mcp_server import _staterepo_root = getattr(_state, "_repo_path", None)if record_mcp_saving(repo_root, tool, replaced, delivered) and isinstance(result, dict):meta = result.setdefault("_meta", {})if isinstance(meta, dict):+ # Stamped before the outer budget runs, so these bytes are budgeted+ # and counted. An agent-facing hint, not the ledger: the canonical+ # event's delivered size is measured after this.meta["replaced_tokens"] = replacedmeta["tokens_saved"] = max(0, replaced - delivered)@@ -244,7 +272,7 @@ def instrument(fn: Callable[..., Any]) -> Callable[..., Any]:result = await fn(*args, **kwargs)duration_ms = int((time.perf_counter() - _t0) * 1000)try:- _record(tool, result)+ _observe_baseline(tool, result)except Exception: # pragma: no cover - defensive; savings never break a toollogger.debug("mcp savings instrumentation failed for %s", tool, exc_info=True)try:diff --git a/tests/integration/mcp/test_savings_event.py b/tests/integration/mcp/test_savings_event.pynew file mode 100644index 000000000..3489f1d0e--- /dev/null+++ b/tests/integration/mcp/test_savings_event.py@@ -0,0 +1,386 @@+"""One canonical savings event per MCP invocation, measured when it is final.++Driven through the real ``tool_middleware`` composition rather than through+``instrument`` alone, because the defect these tests pin is an ordering defect:+every individual layer was correct and the number was still wrong. A test that+wraps one layer cannot see that, which is why the old ledger row was measured+five layers deep for as long as it was.+"""++from __future__ import annotations++from datetime import UTC, datetime+from pathlib import Path++import pytest++from repowise.core.distill.store import OmissionStore+from repowise.server.mcp_server import _state, tool_middleware+from repowise.server.mcp_server._savings import declare_replaced+++def _repo_db(repo: Path) -> Path:+ return repo / ".repowise" / "omissions" / "omissions.db"+++def repo(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:+ OmissionStore(_repo_db(tmp_path)).close()+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path), raising=False)+ return tmp_path+++def _events(repo: Path) -> list[dict]:+ with OmissionStore(_repo_db(repo)) as store:+ store._conn.row_factory = __import__("sqlite3").Row+ rows = store._conn.execute("SELECT * FROM savings_events ORDER BY occurred_at").fetchall()+ return [dict(row) for row in rows]+++def _report(repo: Path):+ with OmissionStore(_repo_db(repo)) as store:+ return store.savings().report(str(repo), as_of=datetime.now(UTC))+++async def test_one_invocation_produces_exactly_one_event(repo: Path) -> None:+ async def get_context(targets: list[str], compact: bool = True) -> dict:+ return {+ "targets": {targets[0]: {"skeleton": {"tokens": 200, "full_tokens": 4000}}},+ "_meta": {"timing_ms": 1.0},+ }++ await tool_middleware(get_context)(["a.py"])++ events = _events(repo)+ assert len(events) == 1+ event = events[0]+ assert event["surface"] == "mcp"+ assert event["operation"] == "get_context"+ assert event["result_state"] == "success"+ assert event["is_usable"] == 1+ assert event["estimator"] == "chars_per_token_floor_v1"+ assert event["token_unit"] == "estimated_tokens"+ assert event["schema_version"] == 1+++async def test_a_counterfactual_is_inferred_and_the_drop_is_not_added_twice(+ repo: Path,+) -> None:+ """``saved = replaced - delivered``, with truncation kept as diagnostic.++ The correlated drop is evidence *inside* this interaction, so adding it to+ the counterfactual would count one interaction's saving twice.+ """++ async def get_symbol(symbol_id: str) -> dict:+ response = {"symbol_id": symbol_id, "source": "def f(): ...", "_meta": {}}+ declare_replaced(response, 5000)+ return response++ await tool_middleware(get_symbol)("a.py::f")++ event = _events(repo)[0]+ assert event["evidence_kind"] == "inferred"+ assert event["baseline_input_tokens"] == 5000+ delivered = event["delivered_input_tokens"]+ assert event["saved_input_tokens"] == 5000 - delivered+ # The truncation is still recorded, as its own dimension, so the diagnostic+ # survives without the counterfactual absorbing it.+ assert event["dropped_input_tokens"] == max(event["pre_budget_input_tokens"] - delivered, 0)+++async def test_delivered_is_measured_after_the_outermost_budget(repo: Path) -> None:+ """The ordering fix, stated as a number.++ ``instrument`` sits five layers deep. After it, ``timed`` stamps ``_meta``+ and the outer budget runs the budgeter twice more. So the delivered size has+ to be at least the size of everything stamped after the old measurement+ point, and the event's own ``_meta`` fields have to be inside it.+ """++ async def get_context(targets: list[str], compact: bool = True) -> dict:+ return {+ "targets": {targets[0]: {"skeleton": {"tokens": 200, "full_tokens": 4000}}},+ "_meta": {},+ }++ out = await tool_middleware(get_context)(["a.py"])+ event = _events(repo)[0]++ # timing_ms is stamped by a layer outside the old measurement point.+ assert out["_meta"]["timing_ms"] is not None+ import json++ final_chars = len(json.dumps(out, separators=(",", ":"), default=str))+ assert event["delivered_input_tokens"] == pytest.approx(final_chars // 4, abs=2)+++async def test_two_calls_to_the_same_tool_stay_independent(repo: Path) -> None:+ """Deduplication is per interaction, never per tool name.++ The legacy summary applied counterfactual precedence across a whole tool, so+ one counterfactual row discarded every truncation row for that tool,+ including later unrelated calls.+ """++ async def get_risk(targets: list[str]) -> dict:+ return {"targets": [{"path": targets[0]}], "_meta": {}}++ wrapped = tool_middleware(get_risk)+ await wrapped(["a.py"])+ await wrapped(["b.py"])++ events = _events(repo)+ assert len(events) == 2+ assert len({event["event_id"] for event in events}) == 2+ assert len({event["idempotency_key"] for event in events}) == 2+ assert _report(repo).unique_events == 2+++async def test_an_error_saves_nothing_and_is_not_an_answered_query(repo: Path) -> None:+ """The legacy ledger wrote a *negative* saving here.++ That is how a session that net-spent could still report a credit. Under the+ contract a failed call saves zero and its delivered overhead is diagnostic.+ """++ async def get_why(query: str) -> dict:+ return {"error": "not indexed", "_meta": {}}++ await tool_middleware(get_why)("x")++ event = _events(repo)[0]+ assert event["result_state"] == "error"+ assert event["is_usable"] == 0+ assert event["saved_input_tokens"] == 0+ assert event["delivered_input_tokens"] > 0++ report = _report(repo)+ assert report.saved_input_tokens == 0+ assert report.mcp_queries_answered == 0+ assert report.saving_interactions == 0+++async def test_a_mutating_tool_can_neither_earn_credit_nor_take_a_debit(+ repo: Path,+) -> None:+ """``set_finding_status`` has no counterfactual, and should not have one.++ It changes state rather than replacing exploration, so there is nothing it+ could have saved. The explicit decision is that it records a zero-saving+ success, not that it is exempt from the ledger: an event with+ ``saved = 0`` is how "this ran and saved nothing" is stated.+ """++ async def set_finding_status(finding_id: str, status: str) -> dict:+ return {"ok": True, "_meta": {}}++ await tool_middleware(set_finding_status)("f1", "accepted")++ event = _events(repo)[0]+ assert event["evidence_kind"] == "measured"+ assert event["baseline_input_tokens"] is None+ assert event["saved_input_tokens"] == 0+ assert event["result_state"] == "success"+++async def test_attribution_is_unknown_without_an_announced_client(repo: Path) -> None:+ """No clientInfo is reachable in-process, so nothing may be guessed.++ Specifically not ``claude_code``, which is what the CLI falls back to when+ it detects nothing; using it here would file every anonymous client's+ traffic under one agent.+ """++ async def get_health(path: str) -> dict:+ return {"score": 7.0, "_meta": {}}++ await tool_middleware(get_health)("a.py")++ event = _events(repo)[0]+ assert event["agent"] == "unknown"+ assert event["integration"] == "unknown"+++async def test_a_repository_without_a_sidecar_records_nothing(+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """An absent sidecar is an opt-out, and a tool call must still succeed."""+ monkeypatch.setattr(_state, "_repo_path", str(tmp_path), raising=False)++ async def get_overview() -> dict:+ return {"summary": "x", "_meta": {}}++ out = await tool_middleware(get_overview)()+ assert out["summary"] == "x"+ assert not _repo_db(tmp_path).exists()+++async def test_the_tool_still_answers_when_recording_fails(+ repo: Path, monkeypatch: pytest.MonkeyPatch+) -> None:+ """Accounting is never allowed to fail a user's tool call."""+ from repowise.server.mcp_server._savings import event as savings_event++ def explode(*args: object, **kwargs: object) -> bool:+ raise RuntimeError("ledger on fire")++ monkeypatch.setattr(savings_event, "_record", explode)++ async def get_dead_code() -> dict:+ return {"files": [], "_meta": {}}++ out = await tool_middleware(get_dead_code)()+ assert out["files"] == []+ assert _events(repo) == []+++async def test_the_raw_size_is_observed_before_anything_is_shed(repo: Path) -> None:+ """Which layer wins the measurement, stated as a number.++ ``observe_pre_budget`` takes the first positive value only. The innermost+ budget runs first, so the value that lands is the untrimmed tool output. If+ that order ever inverted, the recorded raw size would be a post-shed size+ and the measured truncation would collapse to almost nothing -- on this+ response, from thousands of tokens to under two hundred.+ """+ from repowise.server.mcp_server._savings import interaction as interaction_module++ observed: list[tuple[int | None, bool]] = []+ original = interaction_module.Interaction.observe_pre_budget++ def traced(self: interaction_module.Interaction, tokens: int | None) -> None:+ accepted = self.pre_budget_input_tokens is None and tokens is not None+ observed.append((tokens, accepted))+ original(self, tokens)++ interaction_module.Interaction.observe_pre_budget = traced # type: ignore[method-assign]+ try:++ async def get_context(targets: list[str]) -> dict:+ return {+ "targets": {targets[0]: {"skeleton": {"tokens": 200, "full_tokens": 4000}}},+ "filler": ["y" * 400 for _ in range(60)],+ "_meta": {},+ }++ await tool_middleware(get_context)(["a.py"])+ finally:+ interaction_module.Interaction.observe_pre_budget = original # type: ignore[method-assign]++ # Two observations, not three: the outermost budget is guarded and does not+ # serialize the payload again for a value that would be discarded. The+ # first is kept and is by far the largest.+ assert [accepted for _, accepted in observed] == [True, False]+ kept = observed[0][0]+ assert kept is not None+ assert all(kept > later for later, _ in observed[1:])++ event = _events(repo)[0]+ assert event["pre_budget_input_tokens"] == kept+ assert event["dropped_input_tokens"] == kept - event["delivered_input_tokens"]+++async def test_a_truncated_response_links_its_recovery_reference(repo: Path) -> None:+ """The event points at what was dropped, and dropping it is not optional.++ The response carries refs as ``repowise#<hex>`` while the store and the+ ledger's foreign key use the bare hex. Passing the public shape through+ failed validation and took the *whole event* with it -- silently, and on+ exactly the truncated responses where the saving is largest. So this+ asserts the link, not just that an event exists.+ """++ async def get_context(targets: list[str]) -> dict:+ return {+ "targets": {targets[0]: {"skeleton": {"tokens": 200, "full_tokens": 4000}}},+ "filler": ["y" * 400 for _ in range(60)],+ "_meta": {},+ }++ out = await tool_middleware(get_context)(["a.py"])+ assert out["_meta"]["omitted"]["refs"], "expected this response to be truncated"++ with OmissionStore(_repo_db(repo)) as store:+ linked = [+ row[0]+ for row in store._conn.execute("SELECT omission_ref FROM savings_event_omissions")+ ]+ stored = [row[0] for row in store._conn.execute("SELECT ref FROM omissions")]+ assert linked, "a truncated response recorded no recovery link"+ assert set(linked) <= set(stored)+ for ref in linked:+ assert not ref.startswith("repowise#")+ assert store_ref_is_bare_hex(ref)+++def store_ref_is_bare_hex(ref: str) -> bool:+ from repowise.core.distill.markers import is_valid_ref++ return is_valid_ref(ref)+++async def test_a_budget_truncated_response_is_partial_not_a_plain_success(+ repo: Path,+) -> None:+ """The agent received less than the tool produced, and the row says so.++ Recording it as a plain success would credit the bytes repowise discarded to+ a call that arrived incomplete, with nothing in the row admitting it. The+ saving is the same either way -- a usable partial gets the same formula --+ so this is about what the event states, not about the number.+ """++ async def get_context(targets: list[str]) -> dict:+ return {+ "targets": {targets[0]: {"skeleton": {"tokens": 200, "full_tokens": 4000}}},+ "filler": ["y" * 400 for _ in range(60)],+ "_meta": {},+ }++ out = await tool_middleware(get_context)(["a.py"])+ assert out["_meta"]["state"]["truncated"], "expected the budgeter to have shed content"++ event = _events(repo)[0]+ assert event["result_state"] == "partial"+ assert event["is_usable"] == 1+ # Still counted and still credited: a usable partial is an achieved saving.+ assert event["saved_input_tokens"] > 0+ assert _report(repo).successful_or_usable_partial_events == 1+++async def test_the_minted_event_id_reaches_the_row(repo: Path) -> None:+ """The interaction's identity has to be the row's identity, or it is not one."""+ seen: list[str] = []+ from repowise.server.mcp_server._savings import event as savings_event++ original = savings_event._record++ def capture(interaction, result): # type: ignore[no-untyped-def]+ seen.append(interaction.event_id)+ return original(interaction, result)++ savings_event._record = capture # type: ignore[assignment]+ try:++ async def get_health(path: str) -> dict:+ return {"score": 7.0, "_meta": {}}++ await tool_middleware(get_health)("a.py")+ finally:+ savings_event._record = original # type: ignore[assignment]++ assert _events(repo)[0]["event_id"] == seen[0]diff --git a/tests/unit/cli/test_augment_hook_perf.py b/tests/unit/cli/test_augment_hook_perf.pyindex b10b2ecd6..d6e0059cf 100644--- a/tests/unit/cli/test_augment_hook_perf.py+++ b/tests/unit/cli/test_augment_hook_perf.py@@ -198,10 +198,29 @@ def _read_payload_probe(repo: Path, rel: str) -> str:)-def _indexed_repo(tmp_path: Path, *, opted_in: bool) -> tuple[Path, str]:- """A repo the Read hook will take all the way to the skeleton path."""+def _indexed_repo(+ tmp_path: Path, *, opted_in: bool, with_sidecar: bool = False+) -> tuple[Path, str]:+ """A repo the Read hook will take all the way to the skeleton path.++ *with_sidecar* decides whether the savings ledger exists. It matters more+ than it looks: ``record_saving`` returns early when the sidecar is absent,+ so without one this guard never reaches the ledger write at all and passes+ without covering it. That is how a structlog import on the write path could+ hide behind a green guard.+ """repo = tmp_path / "repo"(repo / ".repowise").mkdir(parents=True)+ if with_sidecar:+ sidecar = repo / ".repowise" / "omissions"+ sidecar.mkdir(parents=True, exist_ok=True)+ ledger = sqlite3.connect(sidecar / "omissions.db")+ try:+ from repowise.core.savings.schema import initialize_savings_schema++ initialize_savings_schema(ledger)+ finally:+ ledger.close()rel = "big.py"lines = []for i in range(60):@@ -307,12 +326,9 @@ def _indexed_search_repo(tmp_path: Path) -> Path:"CREATE TABLE wiki_symbols (repository_id TEXT, file_path TEXT, name TEXT, ""kind TEXT, start_line INTEGER)")+ con.execute("INSERT INTO wiki_symbols VALUES ('r1', 'src/b.py', 'parse_yaml', 'function', 42)")con.execute(- "INSERT INTO wiki_symbols VALUES ('r1', 'src/b.py', 'parse_yaml', 'function', 42)"- )- con.execute(- "CREATE TABLE graph_nodes (repository_id TEXT, node_id TEXT, node_type TEXT, "- "pagerank REAL)"+ "CREATE TABLE graph_nodes (repository_id TEXT, node_id TEXT, node_type TEXT, pagerank REAL)")for node_id, pagerank in (("src/a.py", 0.9), ("src/b.py", 0.1)):con.execute("INSERT INTO graph_nodes VALUES ('r1', ?, 'file', ?)", (node_id, pagerank))@@ -330,9 +346,7 @@ def test_a_triage_that_queries_the_index_imports_nothing_heavy(tmp_path: Path) -silent-invocation test above it can only pass by actually emitting."""repo = _indexed_search_repo(tmp_path)- content = "\n".join(- f"src/{'a' if i % 2 else 'b'}.py:{i}:parse_yaml(x)" for i in range(1, 21)- )+ content = "\n".join(f"src/{'a' if i % 2 else 'b'}.py:{i}:parse_yaml(x)" for i in range(1, 21))payload = {"hook_event_name": "PostToolUse","tool_name": "Grep",@@ -492,9 +506,7 @@ def _modules_added_by(statement: str) -> set[str]:f"{statement} ""print('\\n'.join(sorted(set(sys.modules) - before)))")- out = subprocess.run(- [sys.executable, "-c", code], capture_output=True, text=True, check=True- )+ out = subprocess.run([sys.executable, "-c", code], capture_output=True, text=True, check=True)return set(out.stdout.split())@@ -543,3 +555,51 @@ def test_a_silent_invocation_imports_nothing_heavy(tmp_path: Path) -> None:env=_fake_home(tmp_path),)assert out.stdout.strip() == "", f"a silent hook invocation pulled in:\n{out.stdout}"+++def test_the_ledger_write_does_not_import_the_store(tmp_path: Path) -> None:+ """The savings write must not drag in ``distill.store``, i.e. structlog.++ The canonical recorder normally reaches the ledger through+ ``OmissionStore``, which imports structlog at roughly 216ms. The hook+ cannot afford that, so it writes on the raw connection it already opened+ and reads the sidecar path from a spelled-out constant. Both halves are+ easy to undo by "simplifying" the recorder, and every other guard in this+ file stops before the write -- a repo with no sidecar returns early -- so+ this is the only thing covering it.++ Asserted in a clean interpreter against a real sidecar, so it exercises the+ write rather than the early return.+ """+ sidecar = tmp_path / ".repowise" / "omissions"+ sidecar.mkdir(parents=True)+ db = sidecar / "omissions.db"+ con = sqlite3.connect(db)+ try:+ from repowise.core.savings.schema import initialize_savings_schema++ initialize_savings_schema(con)+ finally:+ con.close()++ code = (+ "import sys, json; from pathlib import Path;"+ "from repowise.cli.commands.augment_cmd import _shared;"+ f"_shared.record_saving(Path({str(tmp_path)!r}),"+ " source='hook-read', filter_name='read_skeleton', command='big.py',"+ " raw_tokens=4000, distilled_tokens=400, hook_adapter='claude-code');"+ f"heavy = sorted(m for m in sys.modules if m.startswith({_HEAVY_PREFIXES!r}));"+ "print(json.dumps(heavy))"+ )+ out = subprocess.run(+ [sys.executable, "-c", code], capture_output=True, text=True, env=_fake_home(tmp_path)+ )+ assert out.returncode == 0, out.stderr+ assert json.loads(out.stdout) == [], f"the ledger write pulled in: {out.stdout}"++ # Guard the guard: a write that silently did nothing would also import nothing.+ con = sqlite3.connect(db)+ try:+ assert con.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 1+ finally:+ con.close()diff --git a/tests/unit/cli/test_hook_savings_event.py b/tests/unit/cli/test_hook_savings_event.pynew file mode 100644index 000000000..a4ee76281--- /dev/null+++ b/tests/unit/cli/test_hook_savings_event.py@@ -0,0 +1,147 @@+"""The hook surfaces record canonical events, attributed to the real agent.++This is the one surface where attribution is evidence rather than inference:+the hook is handed the serving agent's own adapter, so it knows which agent+saved the tokens. MCP has to resolve a self-declared name, and distill does not+know at all.+"""++from __future__ import annotations++from datetime import UTC, datetime+from pathlib import Path+from sqlite3 import Row++import pytest++from repowise.cli.commands.augment_cmd import _shared+from repowise.core.distill.store import OmissionStore+from repowise.core.savings import recorder+++def repo(tmp_path: Path) -> Path:+ OmissionStore(recorder.sidecar_path(tmp_path)).close()+ return tmp_path+++def _events(repo: Path) -> list[dict]:+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ store._conn.row_factory = Row+ return [dict(row) for row in store._conn.execute("SELECT * FROM savings_events")]+++def _record(repo: Path, **overrides: object) -> None:+ kwargs: dict = {+ "source": "hook-read",+ "filter_name": "read_skeleton",+ "command": "src/app.py",+ "raw_tokens": 4000,+ "distilled_tokens": 400,+ "hook_adapter": "claude-code",+ }+ kwargs.update(overrides)+ _shared.record_saving(repo, **kwargs)+++def test_a_served_replacement_records_a_measured_hook_event(repo: Path) -> None:+ _record(repo)+ events = _events(repo)+ assert len(events) == 1+ event = events[0]+ assert event["surface"] == "hook"+ assert event["operation"] == "read_skeleton"+ assert event["evidence_kind"] == "measured"+ assert event["result_state"] == "success"+ assert event["baseline_input_tokens"] == 4000+ assert event["delivered_input_tokens"] == 400+ assert event["saved_input_tokens"] == 3600+++ ("adapter", "expected"),+ [("claude-code", "claude_code"), ("codex", "codex"), (None, "unknown"), ("nope", "unknown")],+)+def test_the_adapter_names_the_agent_that_saved_the_tokens(+ repo: Path, adapter: str | None, expected: str+) -> None:+ """Resolved through the identity registry, not a second mapping here.++ An adapter name the registry does not know resolves to ``unknown`` rather+ than being stored raw: the hook adapter spelling is not the canonical slug,+ and storing it would put a fourth spelling in the ledger.+ """+ _record(repo, hook_adapter=adapter)+ event = _events(repo)[0]+ assert event["agent"] == expected+ assert event["integration"] == expected+++def test_the_legacy_row_is_still_written(repo: Path) -> None:+ """Both ledgers, until the reporting consumers move to the canonical one."""+ _record(repo)+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ legacy = store.savings_summary()+ assert legacy["saved_tokens"] == 3600+ assert _events(repo)[0]["saved_input_tokens"] == 3600+++def test_the_replaced_path_is_never_persisted(repo: Path) -> None:+ """``command`` is a file path on this surface, and paths are not telemetry."""+ _record(repo, command="/home/someone/secret-project/app.py")+ stored = str(_events(repo)[0])+ assert "secret-project" not in stored+ assert "someone" not in stored+++def test_a_repository_without_a_sidecar_records_nothing(tmp_path: Path) -> None:+ """A hook is not the place to decide a repo has opted into bookkeeping."""+ _record(tmp_path)+ assert not recorder.sidecar_path(tmp_path).exists()+++def test_two_replacements_stay_two_interactions(repo: Path) -> None:+ _record(repo)+ _record(repo)+ events = _events(repo)+ assert len(events) == 2+ assert len({event["event_id"] for event in events}) == 2+++def test_a_forgone_saving_is_an_opportunity_not_an_achievement(repo: Path) -> None:+ """The repo did not save these tokens; it only could have.++ They must never reach a total of what was saved, which is why they land in+ a different table rather than behind a flag on the same one.+ """+ _shared.record_forgone(+ repo,+ source="hook-read",+ path="src/app.py",+ raw_tokens=4000,+ distilled_tokens=400,+ filter_name="read_skeleton",+ )+ assert _events(repo) == []+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ report = store.savings().report(str(repo), as_of=datetime.now(UTC))+ row = store._conn.execute("SELECT kind FROM savings_opportunities").fetchone()+ assert report.saved_input_tokens == 0+ assert report.opportunity_count == 1+ assert report.opportunity_tokens_excluded == 3600+ assert row[0] == "hook_surface_disabled:read_skeleton"+++def test_a_forgone_saving_does_not_record_the_path(repo: Path) -> None:+ _shared.record_forgone(+ repo,+ source="hook-read",+ path="/home/someone/secret-project/app.py",+ raw_tokens=4000,+ distilled_tokens=400,+ filter_name="read_skeleton",+ )+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ store._conn.row_factory = Row+ stored = str([dict(r) for r in store._conn.execute("SELECT * FROM savings_opportunities")])+ assert "secret-project" not in storeddiff --git a/tests/unit/distill/test_savings_event.py b/tests/unit/distill/test_savings_event.pynew file mode 100644index 000000000..d563dff86--- /dev/null+++ b/tests/unit/distill/test_savings_event.py@@ -0,0 +1,147 @@+"""Distillation records a canonical event beside its legacy ledger row.++The legacy row stays for now because the costs endpoint, the overview headline+and ``repowise saved`` all still read it. So the property under test is that+both land and agree, not that one replaced the other.+"""++from __future__ import annotations++from datetime import UTC, datetime+from pathlib import Path+from sqlite3 import Row++import pytest++from repowise.core.distill.engine import distill_output+from repowise.core.distill.store import OmissionStore+from repowise.core.savings import recorder++# Long enough to beat the filter's min_lines and the net-positive floor.+PYTEST_OUTPUT = "\n".join(+ ["=" * 70, "FAILED tests/test_a.py::test_one - AssertionError: nope"]+ + [f" boilerplate line {index} that carries no signal whatsoever" for index in range(400)]+ + ["1 failed, 399 passed in 12.34s"]+)+++def store(tmp_path: Path):+ opened = OmissionStore(recorder.sidecar_path(tmp_path))+ try:+ yield opened+ finally:+ opened.close()+++def _events(store: OmissionStore) -> list[dict]:+ store._conn.row_factory = Row+ return [dict(row) for row in store._conn.execute("SELECT * FROM savings_events")]+++def test_a_distillation_records_one_measured_event(store: OmissionStore) -> None:+ result = distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ assert result.distilled++ events = _events(store)+ assert len(events) == 1+ event = events[0]+ assert event["surface"] == "distill"+ assert event["operation"] == result.filter_name+ assert event["evidence_kind"] == "measured"+ assert event["estimator"] == "chars_per_token_floor_v1"+ assert event["result_state"] == "success"+ assert event["baseline_input_tokens"] == result.raw_tokens+ assert event["delivered_input_tokens"] == result.distilled_tokens+ assert event["saved_input_tokens"] == result.raw_tokens - result.distilled_tokens+++def test_the_event_agrees_with_the_legacy_row_it_sits_beside(store: OmissionStore) -> None:+ distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ legacy = store.savings_summary()+ event = _events(store)[0]+ assert event["saved_input_tokens"] == legacy["saved_tokens"]+ assert event["delivered_input_tokens"] == legacy["distilled_tokens"]+++def test_the_recovery_reference_links_the_event_to_its_artifact(store: OmissionStore) -> None:+ """The event points at the omission rather than duplicating its content."""+ result = distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ linked = store._conn.execute("SELECT omission_ref FROM savings_event_omissions").fetchall()+ assert [row[0] for row in linked] == [result.ref]+ assert store.get(result.ref) is not None+++def test_the_rewrite_hooks_shell_is_a_hook_not_the_cli(store: OmissionStore) -> None:+ """``source`` separates the surfaces; it does not name an agent."""+ distill_output(PYTEST_OUTPUT, command="pytest", source="hook-bash", store=store)+ event = _events(store)[0]+ assert event["surface"] == "hook"+ assert event["agent"] == "unknown"+ assert event["integration"] == "unknown"+++def test_output_not_worth_distilling_records_nothing(store: OmissionStore) -> None:+ """No saving, no event. A zero-token row would only dilute the ledger."""+ assert not distill_output("one short line\n", command="pytest", store=store).distilled+ assert _events(store) == []+++def test_the_command_is_never_persisted(store: OmissionStore) -> None:+ """A command line can carry paths, hostnames and secrets."""+ distill_output(+ PYTEST_OUTPUT,+ command="pytest --token=hunter2 /home/someone/private",+ source="cli",+ store=store,+ )+ stored = str(_events(store)[0])+ assert "hunter2" not in stored+ assert "private" not in stored+++def test_two_distillations_of_identical_output_stay_independent(store: OmissionStore) -> None:+ """The omission ref is a content hash, so two identical runs share one.++ The events must not collapse with it: they are two interactions that each+ really saved tokens, and the ledger counts interactions.+ """+ first = distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ second = distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ assert first.ref == second.ref++ events = _events(store)+ assert len(events) == 2+ assert len({event["event_id"] for event in events}) == 2+ report = store.savings().report(str(store.db_path.parents[2]), as_of=datetime.now(UTC))+ assert report.unique_events == 2+ assert report.saving_interactions == 2+++def test_the_event_is_attributed_to_the_repository_not_to_a_derivation(+ tmp_path: Path, store: OmissionStore+) -> None:+ """Spelled out rather than recomputed from the expression under test."""+ distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=store)+ assert _events(store)[0]["repository_id"] == str(tmp_path)+++def test_a_home_directory_store_is_refused(tmp_path: Path, monkeypatch) -> None:+ """``open_default`` falls back to ``~/.repowise`` when there is no repo.++ The same path arithmetic would then call the home directory a repository and+ merge every uninitialized directory on the machine into one ledger. The+ legacy row still lands there, as it always has; the canonical event does not.+ """+ home = tmp_path / "home"+ monkeypatch.setenv("USERPROFILE", str(home))+ monkeypatch.setenv("HOME", str(home))+ monkeypatch.setattr(Path, "home", classmethod(lambda cls: home))+ opened = OmissionStore(home / ".repowise" / "omissions" / "omissions.db")+ try:+ result = distill_output(PYTEST_OUTPUT, command="pytest", source="cli", store=opened)+ assert result.distilled, "the distillation itself must still work"+ assert _events(opened) == []+ assert opened.savings_summary()["saved_tokens"] > 0+ finally:+ opened.close()diff --git a/tests/unit/savings/test_recorder.py b/tests/unit/savings/test_recorder.pynew file mode 100644index 000000000..5175f9fcf--- /dev/null+++ b/tests/unit/savings/test_recorder.py@@ -0,0 +1,191 @@+"""The one write path every capture surface goes through.++The behaviours here are the ones that used to be re-decided per surface, and+the ones a surface must be able to rely on without checking: an absent sidecar+is an opt-out rather than something to create, a malformed event never reaches+the caller as an exception, and a repository cannot be attributed an event it+is not writing to.+"""++from __future__ import annotations++from datetime import UTC, datetime+from pathlib import Path++import pytest++from repowise.core.distill.store import OmissionStore+from repowise.core.savings import recorder+from repowise.core.savings.correlation import scoped_idempotency_key+++def _event(index: int = 1, **overrides: object) -> dict:+ payload = {+ "idempotency_key": scoped_idempotency_key("repo", "mcp", index),+ "occurred_at": f"2026-09-18T00:00:0{index}Z",+ "surface": "mcp",+ "integration": "claude_code",+ "agent": "claude_code",+ "operation": "get_risk",+ "evidence_kind": "measured",+ "estimator": "chars_per_token_floor_v1",+ "token_unit": "estimated_tokens",+ "result_state": "success",+ "is_usable": True,+ "baseline_input_tokens": 100,+ "pre_budget_input_tokens": 100,+ "delivered_input_tokens": 40,+ }+ payload.update(overrides)+ return payload+++def repo(tmp_path: Path) -> Path:+ """A repository that has opted in, i.e. one whose sidecar exists."""+ OmissionStore(recorder.sidecar_path(tmp_path)).close()+ return tmp_path+++def test_an_event_is_written_and_attributed_to_the_repository(repo: Path) -> None:+ assert recorder.record_event(repo, _event()) is True+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ row = store._conn.execute(+ "SELECT repository_id, agent, saved_input_tokens FROM savings_events"+ ).fetchone()+ assert tuple(row) == (str(repo), "claude_code", 60)+++def test_a_repository_cannot_be_attributed_an_event_it_is_not_writing(repo: Path) -> None:+ """``repository_id`` comes from the path written to, never from the payload.++ Otherwise a surface holding a stale repo id files one repository's savings+ under another, and nothing downstream could tell.+ """+ recorder.record_event(repo, _event(repository_id="/somewhere/else"))+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ stored = store._conn.execute("SELECT repository_id FROM savings_events").fetchone()[0]+ assert stored == str(repo)+++def test_a_retry_of_the_same_event_reports_that_it_added_nothing(repo: Path) -> None:+ assert recorder.record_event(repo, _event()) is True+ assert recorder.record_event(repo, _event()) is False+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ assert store._conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 1+++def test_an_absent_sidecar_is_an_opt_out_rather_than_something_to_create(+ tmp_path: Path,+) -> None:+ """A repository that never ran ``init`` does not acquire a ledger by being used."""+ assert recorder.record_event(tmp_path, _event()) is False+ assert not recorder.sidecar_path(tmp_path).exists()+++def test_no_repository_means_no_guess(tmp_path: Path) -> None:+ """Never fall back to a home-directory store: the dashboard would not see it."""+ assert recorder.record_event(None, _event()) is False+ assert recorder.record_event("", _event()) is False+++ "broken",+ [+ {"surface": "telepathy"},+ {"agent": "Claude Code"},+ {"result_state": "success", "is_usable": False},+ {"metadata": {"prompt": "do not persist"}},+ {"occurred_at": "not a timestamp"},+ ],+)+def test_a_malformed_event_is_dropped_rather_than_raised(repo: Path, broken: dict) -> None:+ """A ledger that can fail a live tool call is worse than no ledger."""+ assert recorder.record_event(repo, _event(**broken)) is False+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ assert store._conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 0+++def test_a_write_failure_is_swallowed(repo: Path, monkeypatch: pytest.MonkeyPatch) -> None:+ """The surface keeps working when the database does not."""+ import repowise.core.savings.repository as repository_module++ def explode(self: object, event: object) -> bool:+ raise RuntimeError("disk gone")++ monkeypatch.setattr(repository_module.SavingsRepository, "record_event", explode)+ assert recorder.record_event(repo, _event()) is False+++def test_an_opportunity_never_reaches_the_event_ledger(repo: Path) -> None:+ """Separate functions, so no caller can file one as the other."""+ assert (+ recorder.record_opportunity(+ repo,+ {+ "observation_id": "obs-1",+ "occurred_at": "2026-09-18T00:00:02Z",+ "integration": "claude_code",+ "kind": "bypassed_distillation",+ "estimated_potential_input_tokens": 500,+ },+ )+ is True+ )+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ assert store._conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 0+ report = store.savings().report(str(repo), as_of=datetime(2026, 9, 19, tzinfo=UTC))+ assert report.saved_input_tokens == 0+ assert report.opportunity_count == 1+ assert report.opportunity_tokens_excluded == 500+++def test_a_malformed_opportunity_is_dropped_rather_than_raised(repo: Path) -> None:+ assert recorder.record_opportunity(repo, {"kind": "missing everything else"}) is False+++def test_the_id_the_surface_minted_is_the_id_stored(repo: Path) -> None:+ """Otherwise nothing joins a log line, or a response, to its ledger row.++ The contract substitutes a fresh id unless told to accept one, and the+ substitution is silent: the row exists, it just is not the event the surface+ thinks it wrote. It also scopes the idempotency key on an id that was thrown+ away, which makes retry deduplication unreachable while appearing to work.+ """+ minted = "11111111-2222-3333-4444-555555555555"+ assert recorder.record_event(repo, _event(event_id=minted)) is True+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ stored = store._conn.execute("SELECT event_id FROM savings_events").fetchone()[0]+ assert stored == minted+++def test_the_sidecar_path_matches_the_store_that_owns_it(tmp_path: Path) -> None:+ """The path is spelled out here to avoid a structlog import; keep it honest."""+ from repowise.core.distill.store import OMISSIONS_DB_FILENAME, OMISSIONS_DIRNAME++ assert recorder.sidecar_path(tmp_path) == (+ tmp_path / ".repowise" / OMISSIONS_DIRNAME / OMISSIONS_DB_FILENAME+ )+++def test_a_raw_connection_reaches_the_same_ledger(repo: Path) -> None:+ """The hook writes on the connection it already has, importing nothing heavy.++ Reaching the ledger through ``OmissionStore`` would pull structlog, roughly+ 250ms, on the surface whose whole justification is latency.+ """+ import sqlite3++ connection = sqlite3.connect(str(recorder.sidecar_path(repo)), timeout=2)+ try:+ assert recorder.record_event_on(connection, repo, _event()) is True+ finally:+ connection.close()+ with OmissionStore(recorder.sidecar_path(repo)) as store:+ assert store._conn.execute("SELECT COUNT(*) FROM savings_events").fetchone()[0] == 1+++def test_a_bad_repository_argument_does_not_raise(repo: Path) -> None:+ """ "Never raises" has to hold for the argument too, not just the write."""+ assert recorder.record_event(object(), _event()) is False # type: ignore[arg-type]+ assert recorder.record_opportunity(object(), {}) is False # type: ignore[arg-type]