refactor: remove test-only compatibility helpers in rollout and agent_savings (#4089)

## Description

This PR removes four compatibility helpers whose only callers were their
own tests:

| Name | What it was |
|---|---|
| `headroom.rollout.current_rollout(environ)` | A wrapper that only
called `resolve_rollout(environ)`. |
| `headroom.rollout.feature_enabled(feature, *, explicit, environ)` | A
wrapper around `resolve_rollout(environ,
requested=...).is_enabled(feature)`. |
| `headroom.rollout.Rollout` | The alias `Rollout = RolloutSnapshot`.
Its own comment called it an undocumented in-branch shim for callers
that were migrating. Those callers have migrated. |
| `headroom.agent_savings.with_target_savings(profile, target_savings)`
| A `dataclasses.replace` helper that nothing called. |

Why this is safe to delete rather than deprecate:
- Neither module has an `__all__`, and these names are not re-exported
anywhere.
- None of the names is documented in `docs/content/docs/`.
`configuration.mdx` documents the rollout environment variables, not
these functions.
- None of the org's consumer repos imports `headroom.rollout` or
`headroom.agent_savings`.

Evidence: a word-boundary search across `headroom`, `crates`, `plugins`,
`sdk`, `examples`, `benchmarks`, `scripts`, `e2e`, `docs`, `wiki`,
`.github`, `pyproject.toml`, `tests` and the consumer repos finds only
the definitions and their tests. The `feature_enabled` hits in
`tests/test_backends/test_litellm_bedrock_prompt_caching.py` are an
unrelated pytest fixture with the same name.

Refs #4136

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Performance improvement
- [x] Code refactoring (no functional changes)

## Changes Made

- `headroom/rollout.py`: delete `current_rollout`, `feature_enabled` and
the `Rollout` alias.
- `headroom/agent_savings.py`: delete `with_target_savings`, and the
`replace` import it alone used.
- `tests/test_rollout.py`:
`test_snapshot_query_and_compatibility_helpers` becomes
`test_snapshot_query_helpers`. It makes the same assertions through
`resolve_rollout(...)` directly, which is what the helpers wrapped.
- `tests/test_agent_savings.py`: delete
`test_with_target_savings_recomputes_target_ratio`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality
- [ ] Manual testing performed

### Test Output

```text
$ pytest -q -p no:cacheprovider tests/test_rollout.py tests/test_agent_savings.py tests/test_backends/test_litellm_bedrock_prompt_caching.py tests/test_config.py
146 passed in 6.83s
$ uvx ruff@0.16.8 check headroom/rollout.py headroom/agent_savings.py tests/test_rollout.py tests/test_agent_savings.py
All checks passed!
$ python -m mypy headroom/rollout.py headroom/agent_savings.py --ignore-missing-imports
Success: no issues found
$ rg -n 'current_rollout|feature_enabled\(|with_target_savings' headroom tests docs wiki
tests/test_backends/test_litellm_bedrock_prompt_caching.py:102:def feature_enabled(monkeypatch: pytest.MonkeyPatch) -> None:   # unrelated fixture
```

## Real Behavior Proof

- Environment: macOS, Python 3.12.13, this branch checked out in a
worktree, repo .venv; temp HOME and HEADROOM_WORKSPACE_DIR, offline.
- Exact command / steps: (1) The shared smoke harness `smoke.sh
<worktree>`: it starts a real proxy from this checkout against a local
fake upstream and sends one Anthropic and one OpenAI request with a
compressible tool result. (2) A direct command on this PR's own path:
`HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws
HEADROOM_ROLLOUT_CHANNEL=canary
HEADROOM_FEATURES=tool_result_interceptors python -m headroom.cli
rollout status`.
- Observed result: Both requests return 200 and `/stats` shows savings,
with only the expected offline-mode warnings in proxy.log. The direct
command's output is below.
- Not tested: An outside caller of the removed undocumented helpers;
none exists in the repo or the org's consumer repos.

```text
$ bash smoke.sh <worktree>
branch: cleanup/core-misc-test-only-helpers @ af71b61a
health: 200
POST /v1/messages        -> HTTP200 smoke-ok
POST /v1/chat/completions -> HTTP200 smoke-ok
stats: requests=2 failed=0 tokens_saved=13574 savings_percent=99.82
proxy.log WARNING/ERROR lines ($SMOKE_TMP/ws/logs/proxy-50198.log):
   2 headroom.proxy - WARNING - event=proxy_offline_mode air-gap active — every connection Headroom initiates is refused (telemetry, update check, license reporter, model/tokenizer/binary/dataset downloads, remote Kompress, OTLP/Langfuse export, Copilot auth, subscription polling, OpenAI embedders, Headroom Cloud compression). Still allowed on purpose: forwarding your requests to the upstream you configured, operator-configured local endpoints, loopback health probes.
   2 headroom.transforms.kompress_compressor - WARNING - Kompress: 'onnx/kompress-int8-wo.onnx' for chopratejas/kompress-v2-base is not cached and HEADROOM_OFFLINE forbids fetching it (HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.). Compression falls back to the non-ML path.
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch found no usable file for chopratejas/kompress-v2-base
   4 headroom.transforms.kompress_compressor - WARNING - Kompress: artifact prefetch refused for chopratejas/kompress-v2-base (HEADROOM_OFFLINE is set): HEADROOM_OFFLINE is set: refusing outbound network access for HuggingFace download of chopratejas/kompress-v2-base/onnx/kompress-int8-wo.onnx to huggingface.co. Unset HEADROOM_OFFLINE, or turn off the feature that needs this connection.
(smoke dir: $SMOKE_TMP)

$ HOME=$TMP/home HEADROOM_WORKSPACE_DIR=$TMP/ws HEADROOM_ROLLOUT_CHANNEL=canary HEADROOM_FEATURES=tool_result_interceptors python -m headroom.cli rollout status
Rollout channel: canary
Policy: 1 (sha256:7752c57ebd846a5cf5f1f3d56c1a1b3e84b69bef54b5e67da6353f51e5dded2f)
Snapshot: sha256:d0a3cdbe4b506547100168eeaba3ac4c1b086876ca1b97209962080146897b2f
Qualification eligible: true
  bedrock_openai_prompt_caching: enabled=false decision=not_requested
  proxy_output_shaper: enabled=false decision=not_requested
  read_maturation: enabled=false decision=not_requested
  tool_result_interceptors: enabled=true decision=explicit
exit=0
```

## Runtime Rollout Safety

- Rollout-managed feature(s): None changed. `resolve_rollout`,
`RolloutSnapshot` and `FEATURES` are untouched.
- Minimum rollout channel: N/A; dead-code removal.
- Stable/default behavior changed: No.
- Kill switch / disable path: Unchanged (`HEADROOM_DISABLE_FEATURES`).
- Unsafe override required: No.
- Qualification impact: None. The registry digest and snapshot format
are unchanged.
- Rollback path: Revert this commit.

## Review Readiness

- [x] I have performed a self-review
- [x] This PR is ready for human review

## Checklist

- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

Part of maintainer-requested cleanup #4136 (dead code, duplication,
debuggability), split into small PRs for review.

The parser helpers that were first planned for this PR,
`find_tool_units` and `get_message_content_text`, live in a
consumer-imported module. They are deprecated in a separate PR instead
of being deleted.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Tejas Chopra
2026-10-10 08:57:49 -07:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 63cc9afa9d
commit 310c108c24
4 changed files with 8 additions and 57 deletions
+1 -16
View File
@@ -5,7 +5,7 @@ from __future__ import annotations
import logging
import os
from collections.abc import MutableMapping
from dataclasses import dataclass, replace
from dataclasses import dataclass
from typing import Protocol
logger = logging.getLogger(__name__)
@@ -408,18 +408,3 @@ def seed_proxy_env_defaults(
# already in the env and otherwise falls back to DEFAULT_PROFILE (coding).
apply_agent_savings_env_defaults(target)
return frozenset(key for key in target if key not in before)
def with_target_savings(
profile: AgentSavingsProfile,
target_savings: float,
) -> AgentSavingsProfile:
"""Return a copy of ``profile`` adjusted to a specific savings target."""
if not 0 < target_savings < 1:
raise ValueError("target_savings must be between 0 and 1")
return replace(
profile,
target_savings=target_savings,
target_ratio=round(1 - target_savings, 4),
)
-23
View File
@@ -478,26 +478,3 @@ def _resolve_snapshot(
config=config,
decisions=tuple(decisions),
)
def current_rollout(environ: Mapping[str, str] | None = None) -> RolloutSnapshot:
"""Compatibility name for resolving a snapshot at a composition boundary."""
return resolve_rollout(environ)
def feature_enabled(
feature: str,
*,
explicit: bool = False,
environ: Mapping[str, str] | None = None,
) -> bool:
"""Compatibility helper for composition roots; do not use in deep components."""
requested = (feature,) if explicit else ()
return resolve_rollout(environ, requested=requested).is_enabled(feature)
# The PR was never released, but this narrow source alias keeps in-branch callers
# importable while the correction migrates them. It is intentionally undocumented.
Rollout = RolloutSnapshot
-8
View File
@@ -17,7 +17,6 @@ from headroom.agent_savings import (
get_agent_savings_profile,
proxy_pipeline_kwargs,
seed_proxy_env_defaults,
with_target_savings,
)
from headroom.cli import wrap as wrap_module
from headroom.cli.main import main
@@ -210,13 +209,6 @@ def test_unknown_agent_savings_profile_falls_back_to_default(
assert DEFAULT_PROFILE in caplog.text
def test_with_target_savings_recomputes_target_ratio() -> None:
profile = with_target_savings(get_agent_savings_profile("balanced"), 0.85)
assert profile.target_savings == 0.85
assert profile.target_ratio == 0.15
def test_agent_savings_cli_renders_shell_exports() -> None:
result = CliRunner().invoke(main, ["agent-savings", "--profile", "agent-90"])
+7 -10
View File
@@ -16,8 +16,6 @@ from headroom.rollout import (
RolloutChannel,
RolloutConfigurationError,
RolloutSnapshot,
current_rollout,
feature_enabled,
registry_digest,
resolve_rollout,
)
@@ -323,8 +321,8 @@ def test_worker_rollout_handoff_rejects_non_object_state() -> None:
RolloutSnapshot.from_internal_dict([]) # type: ignore[arg-type]
def test_snapshot_query_and_compatibility_helpers() -> None:
snapshot = current_rollout(
def test_snapshot_query_helpers() -> None:
snapshot = resolve_rollout(
{
"HEADROOM_ROLLOUT_CHANNEL": "canary",
"HEADROOM_FEATURES": "tool_result_interceptors",
@@ -335,12 +333,11 @@ def test_snapshot_query_and_compatibility_helpers() -> None:
assert snapshot.is_available("tool-result-interceptors") is True
assert snapshot.enabled == frozenset({"tool_result_interceptors"})
assert snapshot.disabled == frozenset({"read_maturation"})
assert feature_enabled(
"tool_result_interceptors",
explicit=True,
environ={"HEADROOM_ROLLOUT_CHANNEL": "canary"},
)
assert not feature_enabled("tool_result_interceptors", environ={})
assert resolve_rollout(
{"HEADROOM_ROLLOUT_CHANNEL": "canary"},
requested=("tool_result_interceptors",),
).is_enabled("tool_result_interceptors")
assert not resolve_rollout({}).is_enabled("tool_result_interceptors")
with pytest.raises(KeyError, match="missing"):
snapshot.decision("missing")