Skip to content

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

feat(savings): 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.py
index 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 not
opted into distill bookkeeping, and a hook is not the place to decide
otherwise. 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:
+ return
def _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.py
index 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, None
candidate.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:
return
diff --git a/packages/core/src/repowise/core/agents/__init__.py b/packages/core/src/repowise/core/agents/__init__.py
index 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.py
index 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.py
index 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 annotations
import contextlib
from dataclasses import dataclass
+from datetime import UTC, datetime
from pathlib import Path
import 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.py
index 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 structlog
from repowise.core.distill import tracking
from repowise.core.distill.markers import REF_LENGTH, is_valid_ref
from repowise.core.savings import schema as savings_schema
+from repowise.core.savings.repository import SavingsRepository
from repowise.core.sqlite_pragmas import apply_sqlite_pragmas
logger = 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.py
new file mode 100644
index 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__.py
index 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 in
the 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 shield
from repowise.server.mcp_server._meta import finalize_trust_envelope
from repowise.server.mcp_server._rounding import quantize
+ from repowise.server.mcp_server._savings import event as savings_event
from repowise.server.mcp_server._savings import instrument
+ from repowise.server.mcp_server._savings import interaction as savings_interaction
evidence_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.py
new file mode 100644
index 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.py
new file mode 100644
index 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 None
diff --git a/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py b/packages/server/src/repowise/server/mcp_server/_savings/wrapper.py
index 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 logging
from collections.abc import Callable
from typing import Any
-from repowise.core.distill.budget import estimate_tokens
-
-from . import counterfactual
+from . import counterfactual, interaction
from .recorder import record_mcp_dead_end, record_mcp_saving
logger = 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 _state
record_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 _state
repo_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"] = replaced
meta["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 tool
logger.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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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 stored
diff --git a/tests/unit/distill/test_savings_event.py b/tests/unit/distill/test_savings_event.py
new file mode 100644
index 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.py
new file mode 100644
index 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]