Skip to content

Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.

fix(transforms): Python parity port of CompressionPolicy + cache_aligner gate (F2.1 c4/5)

chopratejasde8e24599039
diff --git a/headroom/transforms/cache_aligner.py b/headroom/transforms/cache_aligner.py
index f6aba3ef0..2faa9efe7 100644
--- a/headroom/transforms/cache_aligner.py
+++ b/headroom/transforms/cache_aligner.py
@@ -239,9 +239,23 @@ class CacheAligner(Transform):
Detection is cheap; we run it whenever ``enabled`` is set so the
warning log line is emitted on every relevant turn.
+
+ Phase F PR-F2.1 c4/5: when the request's
+ :class:`~headroom.transforms.compression_policy.CompressionPolicy`
+ is passed via ``kwargs["compression_policy"]`` and has
+ ``cache_aligner_enabled=False`` (Subscription auth mode under
+ the enforcement flag), this method returns ``False`` so the
+ detector is skipped for that request. The hidden state
+ ``self._previous_prefix_hash`` is NOT cleared on skip — the
+ field is per-pipeline-instance, not per-request, so clearing
+ it would race with concurrent PAYG requests on the same
+ pipeline (which is the production shape).
"""
if not self.config.enabled:
return False
+ policy = kwargs.get("compression_policy")
+ if policy is not None and not policy.cache_aligner_enabled:
+ return False
for msg in messages:
if msg.get("role") == "system":
content = msg.get("content", "")
diff --git a/headroom/transforms/compression_policy.py b/headroom/transforms/compression_policy.py
new file mode 100644
index 000000000..a52e19f1d
--- /dev/null
+++ b/headroom/transforms/compression_policy.py
@@ -0,0 +1,80 @@
+"""Per-auth-mode compression policy — Phase F PR-F2.1, Python parity.
+
+Hand-mirrored port of `headroom_core::compression_policy::CompressionPolicy`
+(Rust). The Rust crate is the source of truth; this module exists so
+the Python proxy's `TransformPipeline` (which still runs `CacheAligner`
+and other detector-only transforms) can read the same per-mode flags
+the Rust dispatcher does.
+
+A parity test (`tests/test_compression_policy.py`) instantiates one of
+each variant and asserts the field map matches what the Rust unit
+tests assert. F2.2 should consider exposing the Rust struct via PyO3
+to retire this hand-mirror — that's deliberately out of scope here so
+F2.1 can ship.
+
+See `crates/headroom-core/src/compression_policy.rs` for the canonical
+docstring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from headroom.proxy.auth_mode import AuthMode
+
+
+@dataclass(frozen=True, slots=True)
+class CompressionPolicy:
+ """Per-auth-mode policy that downstream compression stages consult.
+
+ Two fields in F2.1 — `live_zone_only` and `cache_aligner_enabled`.
+ F2.2 will add tuning fields (per-mode volatile threshold,
+ max-lossy-ratio cap, per-mode TOIN read-only flag) once telemetry
+ from F2.1's bake on `main` shows what each mode actually costs/saves.
+ """
+
+ live_zone_only: bool
+ """When True, transforms MUST NOT modify bytes outside the post-
+ cache-marker live zone. The Rust live-zone dispatcher is already
+ live-zone-only by construction, so this flag is effectively a
+ no-op on the Rust path; it exists for the Python TransformPipeline
+ where transforms like CacheAligner inspect the cached prefix."""
+
+ cache_aligner_enabled: bool
+ """When False, the CacheAligner transform's `should_apply` MUST
+ return False — that's the load-bearing F2.1 gate for the cache-
+ instability complaints in #327 / #388."""
+
+
+def policy_for_mode(mode: AuthMode) -> CompressionPolicy:
+ """Resolve the F2.1 policy for an auth mode.
+
+ PAYG and OAuth are identical in F2.1 (aggressive: live-zone-not-
+ only, cache-aligner on). Subscription is the user-visible win:
+ live-zone-only with cache aligner disabled.
+
+ F2.2 may diverge OAuth from PAYG once telemetry is collected.
+ """
+ if mode == AuthMode.PAYG:
+ return CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)
+ if mode == AuthMode.OAUTH:
+ # Identical to PAYG in F2.1. The parity test in
+ # `tests/test_compression_policy.py` is the canary that
+ # catches a future divergence and forces a deliberate
+ # update there + in the Rust crate.
+ return CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)
+ if mode == AuthMode.SUBSCRIPTION:
+ return CompressionPolicy(live_zone_only=True, cache_aligner_enabled=False)
+ raise ValueError(f"Unhandled AuthMode variant: {mode!r}")
+
+
+def policy_default_payg() -> CompressionPolicy:
+ """The PAYG-equivalent policy used when the
+ ``HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT`` flag is disabled
+ (default in F2.1 c1-c4; flips to enabled in c5/5).
+
+ Centralised so the proxy handlers do not duplicate the constant,
+ and so a future change to PAYG semantics propagates to both the
+ enforcement-on and enforcement-off paths.
+ """
+ return policy_for_mode(AuthMode.PAYG)
diff --git a/tests/test_cache_aligner_detector_only.py b/tests/test_cache_aligner_detector_only.py
index 5001a5b46..8579797fd 100644
--- a/tests/test_cache_aligner_detector_only.py
+++ b/tests/test_cache_aligner_detector_only.py
@@ -194,6 +194,40 @@ def test_should_apply_false_without_system_message(tokenizer: Tokenizer) -> None
assert not aligner.should_apply(messages, tokenizer)
+def test_should_apply_false_when_policy_disables_aligner(tokenizer: Tokenizer) -> None:
+ """F2.1 c4/5: ``compression_policy.cache_aligner_enabled=False``
+ must disable the detector even when content + config would
+ otherwise opt in.
+
+ This is the canary that the per-auth-mode plumbing actually
+ reaches CacheAligner. A regression here means subscription
+ requests would silently keep updating
+ ``self._previous_prefix_hash`` and emitting volatility warnings,
+ which are the exact log lines #327/#388 reporters complained
+ about.
+ """
+ from headroom.transforms.compression_policy import CompressionPolicy
+
+ messages = _system_user_messages("Session: 550e8400-e29b-41d4-a716-446655440000")
+ aligner = CacheAligner(CacheAlignerConfig(enabled=True))
+ # Sanity: without a policy, the detector opts in.
+ assert aligner.should_apply(messages, tokenizer)
+ # F2.1 gate: with the subscription policy, the detector opts out.
+ sub_policy = CompressionPolicy(live_zone_only=True, cache_aligner_enabled=False)
+ assert not aligner.should_apply(messages, tokenizer, compression_policy=sub_policy)
+
+
+def test_should_apply_true_when_policy_enables_aligner(tokenizer: Tokenizer) -> None:
+ """F2.1 c4/5: ``compression_policy.cache_aligner_enabled=True``
+ must NOT short-circuit. PAYG/OAuth keep current behaviour."""
+ from headroom.transforms.compression_policy import CompressionPolicy
+
+ messages = _system_user_messages("Session: 550e8400-e29b-41d4-a716-446655440000")
+ aligner = CacheAligner(CacheAlignerConfig(enabled=True))
+ payg_policy = CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)
+ assert aligner.should_apply(messages, tokenizer, compression_policy=payg_policy)
+
+
# ---------------------------------------------------------------------------
# Pure-function detection tests
# ---------------------------------------------------------------------------
diff --git a/tests/test_compression_policy.py b/tests/test_compression_policy.py
new file mode 100644
index 000000000..b2a1d15e3
--- /dev/null
+++ b/tests/test_compression_policy.py
@@ -0,0 +1,92 @@
+"""Tests for the Python ``CompressionPolicy`` and its parity with Rust.
+
+The Python module is a hand-mirror of
+``headroom_core::compression_policy::CompressionPolicy``. These tests
+pin both halves: that the per-mode values are right, and that the
+Python and Rust sides agree on the field map. F2.2 will likely retire
+the hand-mirror via PyO3 — until then, this file is the canary.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from headroom.proxy.auth_mode import AuthMode
+from headroom.transforms.compression_policy import (
+ CompressionPolicy,
+ policy_default_payg,
+ policy_for_mode,
+)
+
+
+class TestCompressionPolicyForMode:
+ """Per-mode field assertions. Mirrors the three Rust unit tests in
+ `crates/headroom-core/src/compression_policy.rs`.
+ """
+
+ def test_payg_is_aggressive(self):
+ p = policy_for_mode(AuthMode.PAYG)
+ assert p.live_zone_only is False, "PAYG can touch outside live zone"
+ assert p.cache_aligner_enabled is True, "PAYG runs cache aligner"
+
+ def test_oauth_matches_payg_today(self):
+ # Canary: when F2.2 diverges OAuth from PAYG, this test fails
+ # and forces a deliberate update on BOTH sides (Rust + Python).
+ oauth = policy_for_mode(AuthMode.OAUTH)
+ payg = policy_for_mode(AuthMode.PAYG)
+ assert oauth == payg, (
+ "F2.1 ships OAuth=PAYG; F2.2 will diverge based on telemetry. "
+ "If you are reading this assertion failure: also update "
+ "crates/headroom-core/src/compression_policy.rs "
+ "::oauth_matches_payg_today, otherwise the Rust + Python "
+ "parities silently drift apart."
+ )
+
+ def test_subscription_disables_cache_aligner(self):
+ p = policy_for_mode(AuthMode.SUBSCRIPTION)
+ assert p.live_zone_only is True, "Subscription is live-zone-only"
+ assert p.cache_aligner_enabled is False, (
+ "Subscription MUST skip cache aligner — load-bearing for issues #327 / #388"
+ )
+
+
+class TestPolicyDefaultPayg:
+ """The constant used when the enforcement flag is disabled."""
+
+ def test_default_payg_equals_for_mode_payg(self):
+ assert policy_default_payg() == policy_for_mode(AuthMode.PAYG)
+
+
+class TestImmutability:
+ """The struct is `frozen=True`; mutation must raise."""
+
+ def test_policy_is_frozen(self):
+ p = policy_for_mode(AuthMode.PAYG)
+ with pytest.raises((AttributeError, Exception)):
+ # Attempting to mutate a frozen dataclass raises
+ # FrozenInstanceError (subclass of AttributeError on
+ # CPython 3.10+). Catch both for compatibility.
+ p.live_zone_only = True # type: ignore[misc]
+
+
+class TestRustParityFieldMap:
+ """The Python policy must have the same fields as the Rust struct.
+
+ The canonical Rust struct lives at
+ ``crates/headroom-core/src/compression_policy.rs``. When you add a
+ field there for F2.2, add it here AND update this test. Otherwise
+ the parity silently drifts.
+ """
+
+ def test_field_set_matches_rust(self):
+ # Hard-coded set — when Rust grows fields, this test fails until
+ # Python catches up.
+ expected_fields = {"live_zone_only", "cache_aligner_enabled"}
+ actual_fields = {f.name for f in CompressionPolicy.__dataclass_fields__.values()}
+ assert actual_fields == expected_fields, (
+ f"Python CompressionPolicy fields drifted from Rust. "
+ f"Expected exactly {expected_fields}, got {actual_fields}. "
+ f"Update both `headroom/transforms/compression_policy.py` "
+ f"and `crates/headroom-core/src/compression_policy.rs` in "
+ f"the same commit."
+ )