feat(content-router): accept any real compression (remove min-savings floor) (#1771)

## Description

The compression acceptance gate rejected any compression that saved less
than ~15% (`min_ratio` interpolated 0.85 at low context pressure → 0.65
under pressure). That floor was a crude proxy for "big enough to justify
busting the prefix cache," but it dropped genuine token savings —
notably lossless code/log folds that shrink <15% (the `ratio_too_high`
rejections).

This makes the gate accept **any real shrink** (`ratio < 1.0`): any
token saved is worth taking. The two guards that actually protect
correctness are untouched:
- **Reversibility gate** — lossy, unmarked tool output still stays
verbatim (accuracy; #1307).
- **Net-cost policy** (`HEADROOM_NET_COST_POLICY=1`, opt-in) — precisely
accounts for the prefix-cache-bust economics (savings × expected-reads
vs one-time suffix re-write) when a session wants that protection.

Lowering the two values back to `0.85`/`0.65` restores the savings
floor.

Closes #

## Type of Change

- [x] New feature (non-breaking change that adds functionality)
- [x] Performance improvement

## Changes Made

- `ContentRouterConfig.min_ratio_relaxed`: `0.85 → 1.0`
- `ContentRouterConfig.min_ratio_aggressive`: `0.65 → 1.0`
- Gate now accepts any `compression_ratio < 1.0` at every context
pressure; reversibility + net-cost guards unchanged.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check`)
- [x] Type checking passes (`mypy headroom`)
- [ ] New tests added for new functionality (existing gate-mechanism
tests cover it; they pass explicit `min_ratio` values and are
unaffected)
- [ ] Manual testing performed

### Test Output

```text
# content-router + compression suites (default-config paths):
tests/test_transforms/test_content_router.py ......... 139 passed
# broad compression sweep (-k compress/router/crush/kompress/lossless/ccr/savings/...):
1 failed, 1940 passed, 54 skipped in 181.25s
#   the 1 failure = test_lossless_mode::test_router_lossless_search_no_marker_and_recoverable
#   — a local fastembed-cache state-leak flake; passes in isolation (1 passed in 3.15s),
#   and is in lossless mode which bypasses this gate entirely.
ruff check headroom/transforms/content_router.py  -> All checks passed!
mypy headroom/transforms/content_router.py         -> Success: no issues found
```

## Real Behavior Proof

- Environment: local worktree, Python 3.12, `PYTHONPATH` pinned to the
branch checkout.
- Exact command / steps: ran the content-router acceptance-gate suites
and a compression-adjacent sweep against the branch; verified the flaky
test passes in isolation.
- Observed result: gate-mechanism tests (explicit `min_ratio`)
unaffected; no default-floor test regressed; blocks that previously
produced `ratio_too_high` at ratios in `[0.85, 1.0)` are now accepted.
- Not tested: no live end-to-end proxy run was performed for this
specific change; the behavioral effect (more `router:*` acceptances,
fewer `ratio_too_high`) is inferred from the gate logic + suite.

## 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
- [x] 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 (existing gate
tests cover the mechanism)
- [x] New and existing unit tests pass locally with my changes
- [ ] I have updated the CHANGELOG.md if applicable (handled at release
time)

## Additional Notes

Deliberate tradeoff (discussed and chosen): without the net-cost policy
enabled, accepting sub-15% wins can be net-negative on prompt-cached
sessions, because compressing a block invalidates the cached suffix (a
one-time re-write, at 1.25× on Anthropic). If that shows up in practice,
enable `HEADROOM_NET_COST_POLICY=1` (the precise economics guard) or
restore a floor by lowering the two `min_ratio_*` values.
This commit is contained in:
Tejas Chopra 2026-07-03 14:40:33 -07:00 committed by GitHub
parent f4ecdebb1b
commit 6c31db97fb
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -919,18 +919,18 @@ class ContentRouterConfig:
0.0 # 0.0 = protect ALL excluded-tool outputs (safest for coding agents)
)
# Adaptive acceptance threshold, scaling with context pressure. The gate
# accepts a compression when compression_ratio < min_ratio (ratio =
# compressed/original, so LOWER ratio = bigger savings). Thus a HIGHER
# min_ratio is MORE lenient (accepts marginal wins) and a LOWER one is
# stricter (only big wins clear it). min_ratio is interpolated
# 0.85 (empty context) -> 0.65 (full), i.e. acceptance gets STRICTER as
# context fills, so only large savings justify busting the prefix cache
# under pressure. (Direction is deliberate; whether a full context should
# instead accept *more* to reclaim space is a design question flagged for
# an eval — do not flip without measuring.)
min_ratio_relaxed: float = 0.85 # low pressure: lenient, accept marginal wins
min_ratio_aggressive: float = 0.65 # high pressure: strict, big wins only
# Acceptance threshold. The gate accepts a compression when
# compression_ratio < min_ratio (ratio = compressed/original). Default 1.0 at
# every pressure = accept ANY real shrink (ratio < 1.0): any token saved is
# worth taking. The prefix-cache-bust cost this once guarded against (a small
# win can cost more than it saves once the invalidated suffix is re-written)
# is instead handled precisely by the opt-in net-cost policy
# (HEADROOM_NET_COST_POLICY=1); tool-output accuracy by the reversibility
# gate — both independent of this floor. Lower these (e.g. 0.85/0.65) to
# restore a savings floor that only accepts wins big enough to justify the
# cache bust as context fills.
min_ratio_relaxed: float = 1.0 # accept any shrink (no savings floor)
min_ratio_aggressive: float = 1.0 # same under pressure; net-cost is the guard
# CCR (Compress-Cache-Retrieve) settings for SmartCrusher
ccr_enabled: bool = True # Enable CCR marker injection for reversible compression