fix(router): keep tagged blocks out of the lossy size-gate fallback (#4543)

## Description

When a text block is over the Kompress size gate
(`HEADROOM_KOMPRESS_MAX_TOKENS`, default 50000) and contains protected
custom tags, `ContentRouter._try_ml_compressor` passed the
`{{HEADROOM_TAG_N}}` placeholder text to the TextCrusher / LogCompressor
fallback. Two things went wrong:

1. Neither fallback takes a `ccr_original` argument, so CCR stored the
placeholder text. `headroom_retrieve` returned `{{HEADROOM_TAG_0}}`,
`{{HEADROOM_TAG_1}}`, ... instead of the tagged content.
2. When the fallback dropped the lines holding the placeholders,
`restore_tags` discarded each lost wrap (by design,
`tag_protector_placeholder_lost`). The tagged content was then gone from
the output sent upstream too.

This is the same defect class as #1209 (Kompress stored the placeholder
intermediate) and #2694 (SmartCrusher, `ccr_source`), on the size-gate
branch those fixes did not reach.

The fix: when tags were protected, the size-gate branch returns the
original `content` unchanged instead of running the lossy fallback. That
is what the request-budget branch directly above it already does for the
same reason (the bytes must stay stable and intact). I chose this over
threading a `ccr_original` through the fallbacks because
`TextCrusher.compress` and `LogCompressor.compress` have no such
parameter, and the output would still lose the tagged lines through
`restore_tags`. Passing through is the smallest change and loses
nothing; the cost is that a gated block with custom tags is no longer
shrunk by the fallback.

Fixes #4542

## Type of Change

- [x] 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
- [ ] Code refactoring (no functional changes)

## Changes Made

- `headroom/transforms/content_router.py`: in the Kompress size-gate
branch of `_try_ml_compressor`, return `content` unchanged when
`protected` is non-empty. The now-unreachable `restore_tags` call at the
end of that branch is removed (the fallback only runs when nothing is
protected).
- `tests/test_transforms/test_kompress_size_gate.py`: new regression
test `test_gate_keeps_tagged_blocks_out_of_lossy_fallback`.

## Testing

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

### Test Output

Fail before (fix reverted, new test kept):

```text
FAILED tests/test_transforms/test_kompress_size_gate.py::test_gate_keeps_tagged_blocks_out_of_lossy_fallback
========================= 1 failed, 5 passed in 2.19s ==========================
```

Pass after:

```text
tests/test_transforms/test_kompress_size_gate.py ......                  [100%]

============================== 6 passed in 1.70s ===============================
```

Related suites (`tests/test_transforms` plus
`tests/test_ccr_tag_placeholder_regression.py`, excluding
`test_text_crusher_cjk_eval.py`, which imports `benchmarks/` that my
test copy does not include):

```text
FAILED tests/test_transforms/test_kompress_compressor.py::TestLazyImports::test_unloadable_native_dep_degrades_instead_of_raising
1 failed, 520 passed, 78 skipped in 24.66s
```

That one failure (`assert attempts["torch"] == 1`) is identical with my
change reverted (`1 failed, 30 passed, 11 skipped` on
`test_kompress_compressor.py` alone), so it is not caused by this PR.

```text
$ ruff check headroom/transforms/content_router.py tests/test_transforms/test_kompress_size_gate.py
All checks passed!
$ ruff format --check <same files>
2 files already formatted
```

## Real Behavior Proof

- Environment: Ubuntu (WSL2), Python 3.12.15, `main` at `a2d4fe72` with
the `_core` extension from the 0.42.0 wheel (no commits under
`tag_protector.rs`, `log_compressor.rs` or `crates/headroom-py` since
0.42.0), `HEADROOM_OFFLINE=1`, in-memory CCR.
- Exact command / steps: ran the script from #4542 (a short header, then
N lines of `<item>row i value</item> note text here for item number i`,
through `ContentRouter(config=ContentRouterConfig()).compress(text)`)
for N=3000 and N=4000, before and after the change, and retrieved the
CCR entry behind any `hash=` marker.
- Observed result: before the change, N=4000 became `[4006 lines
omitted]\n[4006 lines compressed to 0. Retrieve more:
hash=dda7b8a79b740b17a0a5461b]`, and the retrieved original was 229,839
bytes, not equal to the input, with 0 `<item>` and 4,000
`{{HEADROOM_TAG`. After the change, N=4000 comes back byte-identical
(253,839 chars, 4,000 `<item>`, 0 placeholders, no CCR marker). N=3000
is unchanged in both runs (189,839 chars, 3,000 `<item>`).
- Not tested: the Rust-side `tag_protector` and a freshly built `_core`
(I used the prebuilt 0.42.0 wheel's); a live proxy run; mypy; the case
where the gated block has no protected tags (unchanged code path,
covered by the existing gate tests); other platforms.

## Runtime Rollout Safety

- Rollout-managed feature(s): None. This is a bug fix inside the
existing size-gate branch.
- Minimum rollout channel: N/A
- Stable/default behavior changed: Yes, narrowly. A block over the size
gate that contains protected custom tags is now returned unchanged
instead of being run through TextCrusher/LogCompressor with the tags
lost. Blocks with no protected tags take the same path as before.
- Kill switch / disable path: `HEADROOM_KOMPRESS_MAX_TOKENS=0` disables
the gate entirely (existing behavior).
- Unsafe override required: No
- Qualification impact: None expected. Token savings drop only for gated
blocks that carry custom tags, which previously lost the tagged content.
- 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
- [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
- [x] 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 (one
unrelated failure, see Test Output)
- [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

Docs unchanged: no public API or documented behavior changes. An
alternative would be to teach TextCrusher/LogCompressor a `ccr_original`
and also keep the tagged lines; that touches two compressors (and the
Rust side) for a block shape that is rare, so I kept the change to the
router. Happy to do it that way if you prefer.

Produced with AI assistance (Claude Code) operated by me (HetCreep); the
reproduction was run on my machine against a clone of the repository.

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

<!-- devin-review-badge-begin -->

---

<a href="https://app.devin.ai/review/headroomlabs-ai/headroom/pull/4543"
target="_blank"><picture><source media="(prefers-color-scheme: dark)"
srcset="https://static.devin.ai/assets/gh-devin-review-dark.svg?v=4"><img
src="https://static.devin.ai/assets/gh-devin-review-light.svg?v=4"
alt="Devin Review"></picture></a>
<!-- devin-review-badge-end -->

### Maintainer current-main requalification

Exact head `38f4e6e6c37ae4b7b46bf97be50ad5fe320c2094`, upstream main
`e4a60ed72f6ef5b28569f8bfbe2163cfda32c948`.

Mechanically merged upstream/main e4a60ed7 and re-reviewed the combined
size-gate branch and existing review discussion. Protected tagged blocks
return original content before either lossy fallback can consume
placeholder text; unprotected fallback behavior remains intact. No
contributor production logic was rewritten. All 11 size-gate and CCR
tag-regression tests pass with the existing development native
extension; Ruff lint/format and whitespace checks pass. The existing
documented before/after router reproduction remains applicable; this is
not a fresh native-build or live-proxy qualification claim.

The shared test-only Gemini streamed-request fixture repair addresses
independently established main failures while preserving existing
assertions; all ten affected cases pass. Formal approval awaits
exact-head hosted qualification.


Exact-head hosted checks are being handled by maintainers. No new
finding in the reviewed scope; formal approval awaits exact-head hosted
qualification; nothing merged.


Maintainer commit-message qualification repair: current head
addf0470b7. Corrected only the maintainer
main-sync commit message to Conventional Commit format. The complete
file tree is byte-identical to the previously tested head; exact-head
hosted checks are being refreshed. Nothing merged.

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
This commit is contained in:
HetCreep
2026-11-05 10:44:09 -06:00
committed by GitHub
co-authored by Claude Opus 5.5 JD Davis
parent e51b8065a4
commit f333edf20f
2 changed files with 32 additions and 2 deletions
+7 -2
View File
@@ -5193,6 +5193,13 @@ class ContentRouter(Transform):
self._kompress_max_tokens,
self._kompress_gate_fires,
)
if protected:
# The fallback compressors take no ``ccr_original`` and would
# store the ``{{HEADROOM_TAG_N}}`` placeholder text in CCR; any
# placeholder line they drop is also discarded by
# ``restore_tags``, losing the tagged block outright. Pass the
# original through unchanged instead (as the budget branch above).
return content, _estimate_tokens(content)
out = text_to_compress
crusher = self._get_text_crusher()
if crusher is not None:
@@ -5213,8 +5220,6 @@ class ContentRouter(Transform):
"Kompress size-gate -> LogCompressor failed (%s); passing through", e
)
out = text_to_compress
if protected:
out = restore_tags(out, protected)
return out, _estimate_tokens(out)
# Reached only when the gate is enabled and this eligible block is
@@ -74,3 +74,28 @@ def test_gate_fires_through_strategy_dispatch(monkeypatch, strategy):
router._apply_strategy_to_content(big, strategy, "")
assert router._kompress_gate_fires == 1
def test_gate_keeps_tagged_blocks_out_of_lossy_fallback(monkeypatch):
# Over the gate, with custom tags protected: the TextCrusher/LogCompressor
# fallback must not see the {{HEADROOM_TAG_N}} placeholder text. It would
# store the placeholders in CCR and ``restore_tags`` discards any wrap whose
# placeholder line it dropped, so the tagged content would vanish from both
# the output and the retrieval path.
router = ContentRouter()
router._kompress_max_tokens = 50 # tiny ceiling (x4 = 200 chars)
def _boom():
raise AssertionError("kompress must not be invoked for oversized (gated) input")
monkeypatch.setattr(router, "_get_kompress", _boom)
lines = [f"<item>row {i} value</item> note text here for item number {i}" for i in range(200)]
text = "Results from the fetch tool:\n\n" + "\n".join(lines)
out, _ = router._try_ml_compressor(text, "")
assert router._kompress_gate_fires == 1
assert out == text
assert out.count("<item>") == 200
assert "{{HEADROOM_TAG" not in out