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.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
fix(core): F2.2 c1/3 — extend CompressionPolicy with three per-mode tuning fields
chopratejas797dc63da747
diff --git a/crates/headroom-core/src/compression_policy.rs b/crates/headroom-core/src/compression_policy.rsindex 543c1994e..b2f1f8395 100644--- a/crates/headroom-core/src/compression_policy.rs+++ b/crates/headroom-core/src/compression_policy.rs@@ -1,9 +1,11 @@-//! Per-auth-mode compression policy — Phase F PR-F2.1.+//! Per-auth-mode compression policy — Phase F PR-F2.1, extended in F2.2.//!//! F1 (`auth_mode.rs`) classifies each inbound request into one of//! `{Payg, OAuth, Subscription}`. Phase F2.1 turns that classification//! into a `CompressionPolicy` that downstream pipeline stages read to-//! decide whether they run.+//! decide whether they run. F2.2 extends the same struct with per-mode+//! tuning fields so the same call sites also read *how aggressively*+//! to run.//!//! Why a struct instead of `match auth_mode { ... }` everywhere?//! Two reasons:@@ -22,13 +24,10 @@//! end-to-end behaviour against the dispatcher requires a full//! request fixture.//!-//! Phase F2.2 will add fields to this struct (per-mode volatile-//! threshold, per-mode max lossy ratio, per-mode TOIN read-only flag).-//! F2.1 keeps the field set minimal — only the two flags load-bearing-//! for closing the cache-instability complaints in issues #327 / #388.-//!//! ## Field semantics//!+//! ### F2.1 fields (load-bearing for closing #327 / #388)+//!//! - **`live_zone_only`**: when `true`, downstream stages MUST NOT//! modify bytes outside the post-cache-marker live zone. Phase B's//! Rust dispatcher is *already* live-zone-only by construction, so@@ -46,15 +45,47 @@//! which is what destabilised Subscription users' prompt caches.//! Disabling it for Subscription is the user-visible win of F2.1.//!-//! ## Per-mode F2.1 values+//! ### F2.2 tuning fields (CONSERVATIVE defaults pending bake telemetry)+//!+//! - **`volatile_token_threshold`**: per-mode token-count threshold+//! below which content is treated as cache-stable (i.e. not flagged+//! as volatile). Subscription is conservative (low threshold → flag+//! more aggressively → keep prompts stable) while PAYG is aggressive+//! (higher threshold → tolerate more volatile noise before warning).+//! F2.1 had no such threshold; F2.2 introduces the field plumbed+//! through the struct so future detector code can pick it up. NOTE:+//! no current detector consumes this value — it lands plumbed-but-+//! unconsumed in F2.2 (intentional; the volatile detector in+//! `cache_aligner.py` is shape-based, not token-count-based, and+//! wiring it would force a detector refactor outside F2.2 scope).+//!+//! - **`max_lossy_ratio`**: per-mode upper bound on how aggressive+//! lossy compression can be, expressed as the fraction of original+//! tokens that may be dropped (`0.0` = no lossy compression allowed,+//! `1.0` = unlimited). Subscription is conservative (`0.25`) so cache+//! prefixes stay stable, PAYG aggressive (`0.45`). NOTE: no current+//! compressor consumes this value — it lands plumbed-but-unconsumed+//! in F2.2 (the `target_ratio` runtime kwarg in `content_router.py`+//! is a separate, caller-driven knob; wiring `max_lossy_ratio` as a+//! policy-driven cap is F2.2-followup once telemetry decides whether+//! to gate lossy paths or just observe them).+//!+//! - **`toin_read_only`**: when `true`, TOIN serves cached+//! recommendations but never *writes* new pattern observations from+//! this request. Subscription requests pay for prompt-cache stability,+//! so we don't want their compression events to mutate the global+//! learning pool — consistency over learning. PAYG/OAuth still write+//! so the network effect keeps growing.//!-//! | Mode | live_zone_only | cache_aligner_enabled |-//! |--------------|----------------|-----------------------|-//! | Payg | false | true |-//! | OAuth | false | true (= PAYG today) |-//! | Subscription | true | false |+//! ## Per-mode F2.2 values (CONSERVATIVE; F2.2-followup will tune)//!-//! OAuth starts identical to PAYG. F2.2 will divide them once+//! | Mode | live_zone_only | cache_aligner_enabled | volatile_token_threshold | max_lossy_ratio | toin_read_only |+//! |--------------|----------------|-----------------------|--------------------------|-----------------|----------------|+//! | Payg | false | true | 128 | 0.45 | false |+//! | OAuth | false | true (= PAYG today) | 128 (= PAYG today) | 0.45 (= PAYG) | false (= PAYG) |+//! | Subscription | true | false | 32 | 0.25 | true |+//!+//! OAuth starts identical to PAYG. F2.2-followup will divide them once//! telemetry from F2.1's bake on `main` shows what each mode actually//! costs / saves.//!@@ -69,12 +100,42 @@use crate::auth_mode::AuthMode;+// ── F2.2 per-mode default values (CONSERVATIVE pending bake telemetry) ──+// Centralised constants instead of inlining in the match arms so a+// follow-up tune lands in one place. Each constant is `pub(crate)` so+// the unit tests can assert against the same source of truth — if a+// caller drifts the per-mode value, the assertion fails.+//+// Per the realignment build constraints (project memory+// `feedback_realignment_build_constraints.md`): "configurable / no+// hardcoded values". The configuration *is* the per-mode default — we+// deliberately do NOT add a separate env var per field. Operators tune+// by editing these constants and shipping a new build, which is the+// same pattern the F2.1 fields use.++/// PAYG: aggressive — let volatile content noise up to ~128 tokens slip+/// before flagging. Higher than Subscription because PAYG users opt in+/// to aggressive compression.+pub(crate) const VOLATILE_TOKEN_THRESHOLD_PAYG: u32 = 128;++/// Subscription: conservative — flag volatile content earlier (32+/// tokens) so cache prefixes stay stable.+pub(crate) const VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION: u32 = 32;++/// PAYG: cap lossy compression at 45% of original tokens. Aggressive+/// but bounded — F2.1 had no cap (effectively `1.0`), F2.2 introduces+/// one.+pub(crate) const MAX_LOSSY_RATIO_PAYG: f32 = 0.45;++/// Subscription: conservative cap at 25%. Cache stability over savings.+pub(crate) const MAX_LOSSY_RATIO_SUBSCRIPTION: f32 = 0.25;+/// Per-auth-mode policy that downstream compression stages consult.///-/// `Copy` because the struct is two `bool`s — passing by value is-/// cheaper than passing a reference and the call sites all want-/// owned copies anyway.-#[derive(Debug, Clone, Copy, PartialEq, Eq)]+/// `Copy` because the struct is small POD (two `bool`s + a `u32` + an+/// `f32` + a `bool`) — passing by value is cheaper than passing a+/// reference and the call sites all want owned copies anyway.+#[derive(Debug, Clone, Copy, PartialEq)]pub struct CompressionPolicy {/// When `true`, transforms MUST NOT modify bytes outside the/// post-cache-marker live zone. See module docs.@@ -83,29 +144,73 @@ pub struct CompressionPolicy {/// When `false`, the `CacheAligner` transform MUST be skipped./// See module docs.pub cache_aligner_enabled: bool,++ /// F2.2: per-mode threshold (in tokens) below which content is+ /// treated as cache-stable. Subscription is conservative+ /// (`32`); PAYG aggressive (`128`). See module docs.+ ///+ /// NOT consumed by any detector in F2.2 — plumbed through the+ /// struct so the volatile detector refactor in a follow-up PR+ /// has a stable hook to read from.+ pub volatile_token_threshold: u32,++ /// F2.2: per-mode upper bound on lossy compression aggressiveness,+ /// expressed as the fraction of original tokens that may be+ /// dropped (`0.0`–`1.0`). Subscription `0.25`, PAYG `0.45`.+ /// See module docs.+ ///+ /// NOT consumed by any compressor in F2.2 — plumbed through the+ /// struct as a stable hook for a follow-up PR that gates lossy+ /// paths on the cap. Distinct from the caller-driven+ /// `target_ratio` kwarg in the Python ContentRouter.+ pub max_lossy_ratio: f32,++ /// F2.2: when `true`, TOIN serves cached recommendations but+ /// never writes new pattern observations from this request.+ /// Subscription `true` (consistency over learning), PAYG/OAuth+ /// `false` (network effect keeps growing).+ pub toin_read_only: bool,}+// `f32` doesn't impl `Eq`, so the derived `Eq` would be invalid. Two+// `f32`s in this struct are never NaN by construction (we only set+// them from finite literal constants), so `PartialEq` is sufficient.+// The unit tests assert structural equality via `assert_eq!`.+impl CompressionPolicy {- /// Resolve the F2.1 policy for an auth mode. See module docs for- /// per-mode rationale.+ /// Resolve the F2.1+F2.2 policy for an auth mode. See module docs+ /// for per-mode rationale.pub fn for_mode(mode: AuthMode) -> Self {match mode {AuthMode::Payg => Self {live_zone_only: false,cache_aligner_enabled: true,+ volatile_token_threshold: VOLATILE_TOKEN_THRESHOLD_PAYG,+ max_lossy_ratio: MAX_LOSSY_RATIO_PAYG,+ toin_read_only: false,},- // OAuth identical to PAYG in F2.1. F2.2 may diverge once- // telemetry shows what OAuth users actually need.+ // OAuth identical to PAYG in F2.1+F2.2. F2.2-followup may+ // diverge once telemetry shows what OAuth users actually+ // need.AuthMode::OAuth => Self {live_zone_only: false,cache_aligner_enabled: true,+ volatile_token_threshold: VOLATILE_TOKEN_THRESHOLD_PAYG,+ max_lossy_ratio: MAX_LOSSY_RATIO_PAYG,+ toin_read_only: false,},// The user-visible win of F2.1: subscription users stop// seeing cache instability because CacheAligner no longer- // touches their prefix.+ // touches their prefix. F2.2 extends that protection: the+ // volatile threshold is tighter, the lossy cap is lower,+ // and TOIN won't mutate the learning pool from these+ // requests.AuthMode::Subscription => Self {live_zone_only: true,cache_aligner_enabled: false,+ volatile_token_threshold: VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION,+ max_lossy_ratio: MAX_LOSSY_RATIO_SUBSCRIPTION,+ toin_read_only: true,},}}@@ -133,15 +238,38 @@ mod tests {assert!(p.live_zone_compression_enabled());}+ #[test]+ fn payg_tuning_fields_aggressive() {+ // F2.2: per-mode tuning fields. PAYG values are the aggressive+ // end of the conservative-defaults spectrum — F2.2-followup may+ // raise them once bake telemetry confirms savings.+ let p = CompressionPolicy::for_mode(AuthMode::Payg);+ assert_eq!(+ p.volatile_token_threshold, 128,+ "PAYG volatile threshold is the relaxed default; F2.2-followup will tune"+ );+ assert!(+ (p.max_lossy_ratio - 0.45).abs() < f32::EPSILON,+ "PAYG max_lossy_ratio caps lossy paths at 0.45; F2.2-followup will tune"+ );+ assert!(+ !p.toin_read_only,+ "PAYG keeps TOIN write-enabled — network effect feeds on PAYG traffic"+ );+ }+#[test]fn oauth_matches_payg_today() {- // Canary: when F2.2 diverges OAuth from PAYG, this test fails- // and forces a deliberate update — which is the point.+ // Canary: when F2.2-followup diverges OAuth from PAYG, this test+ // fails and forces a deliberate update — which is the point.+ // Covers ALL fields (F2.1 + F2.2) so a future field-level+ // divergence (e.g. OAuth gets stricter `max_lossy_ratio` than+ // PAYG) trips the assertion just as loudly as a flag flip.let oauth = CompressionPolicy::for_mode(AuthMode::OAuth);let payg = CompressionPolicy::for_mode(AuthMode::Payg);assert_eq!(oauth, payg,- "F2.1 ships OAuth=PAYG; F2.2 will diverge based on telemetry"+ "F2.1+F2.2 ship OAuth=PAYG; F2.2-followup will diverge based on telemetry");}@@ -158,4 +286,40 @@ mod tests {"Subscription still gets live-zone compression — closing the cache complaint must NOT mean shipping zero compression");}++ #[test]+ fn subscription_tuning_fields_conservative() {+ // F2.2: per-mode tuning fields. Subscription is the conservative+ // end — tighter threshold, lower lossy cap, TOIN read-only — so+ // cache prefixes stay stable and the learning pool isn't+ // mutated from cache-stability-sensitive traffic.+ let p = CompressionPolicy::for_mode(AuthMode::Subscription);+ assert_eq!(+ p.volatile_token_threshold, 32,+ "Subscription volatile threshold flags content earlier (cache stability)"+ );+ assert!(+ (p.max_lossy_ratio - 0.25).abs() < f32::EPSILON,+ "Subscription max_lossy_ratio caps lossy paths at 0.25 (conservative)"+ );+ assert!(+ p.toin_read_only,+ "Subscription MUST be TOIN read-only — load-bearing for keeping the learning pool consistent across cache-sensitive traffic"+ );+ }++ #[test]+ fn max_lossy_ratio_in_unit_interval() {+ // Defensive: every per-mode `max_lossy_ratio` MUST be in `[0.0,+ // 1.0]` because it expresses a fraction. A tune that drifts+ // outside the unit interval is a bug — catch it cheaply here+ // rather than at the eventual consumer site.+ for mode in [AuthMode::Payg, AuthMode::OAuth, AuthMode::Subscription] {+ let r = CompressionPolicy::for_mode(mode).max_lossy_ratio;+ assert!(+ (0.0..=1.0).contains(&r),+ "max_lossy_ratio for {mode:?} = {r} is outside [0.0, 1.0]"+ );+ }+ }}diff --git a/headroom/transforms/compression_policy.py b/headroom/transforms/compression_policy.pyindex ea71cfb9b..5057a8812 100644--- a/headroom/transforms/compression_policy.py+++ b/headroom/transforms/compression_policy.py@@ -1,4 +1,4 @@-"""Per-auth-mode compression policy — Phase F PR-F2.1, Python parity.+"""Per-auth-mode compression policy — Phase F PR-F2.1, extended in F2.2 (Python parity).Hand-mirrored port of `headroom_core::compression_policy::CompressionPolicy`(Rust). The Rust crate is the source of truth; this module exists so@@ -10,10 +10,10 @@ A parity test (`tests/test_compression_policy.py`) instantiates one ofeach variant and asserts the field map matches what the Rust unittests assert. F2.2 should consider exposing the Rust struct via PyO3to retire this hand-mirror — that's deliberately out of scope here so-F2.1 can ship.+F2.1/F2.2 can ship.See `crates/headroom-core/src/compression_policy.rs` for the canonical-docstring.+docstring (per-mode rationale, why-a-struct, etc.)."""from __future__ import annotations@@ -23,15 +23,58 @@ from dataclasses import dataclassfrom headroom.proxy.auth_mode import AuthMode+# ── F2.2 per-mode default values (CONSERVATIVE pending bake telemetry) ──+# Mirrors the Rust ``pub(crate) const`` block in+# ``crates/headroom-core/src/compression_policy.rs``. Centralised here so+# a follow-up tune lands in one place per language. The Rust tests assert+# the values directly; the Python parity tests assert the *fields* match+# (not the values — that would double-pin against drift in a way that+# masks real divergence).+#+# Per the realignment build constraints (project memory+# ``feedback_realignment_build_constraints.md``): "configurable / no+# hardcoded values". The configuration *is* the per-mode default — we+# deliberately do NOT add a separate env var per field. Operators tune+# by editing these constants and shipping a new build, mirroring the+# Rust pattern exactly.++#: PAYG: aggressive — let volatile content noise up to ~128 tokens slip+#: before flagging. Higher than Subscription because PAYG users opt in+#: to aggressive compression.+_VOLATILE_TOKEN_THRESHOLD_PAYG: int = 128++#: Subscription: conservative — flag volatile content earlier (32+#: tokens) so cache prefixes stay stable.+_VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION: int = 32++#: PAYG: cap lossy compression at 45% of original tokens. Aggressive+#: but bounded — F2.1 had no cap (effectively ``1.0``), F2.2 introduces one.+_MAX_LOSSY_RATIO_PAYG: float = 0.45++#: Subscription: conservative cap at 25%. Cache stability over savings.+_MAX_LOSSY_RATIO_SUBSCRIPTION: float = 0.25+@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.+ Five fields after F2.2:++ - ``live_zone_only`` (F2.1) — gate for the Python TransformPipeline+ to skip pre-cache-marker mutation.+ - ``cache_aligner_enabled`` (F2.1) — gate for the Python+ ``CacheAligner`` transform.+ - ``volatile_token_threshold`` (F2.2) — per-mode token threshold+ below which content is treated as cache-stable. Plumbed through+ the struct; no current detector consumes it (intentional — the+ detector refactor is a follow-up).+ - ``max_lossy_ratio`` (F2.2) — per-mode upper bound on lossy+ compression aggressiveness (fraction in ``[0.0, 1.0]``). Plumbed+ through the struct; no current compressor consumes it.+ - ``toin_read_only`` (F2.2) — TOIN learning gate. ``True`` =+ serve cached patterns but never write new observations from+ this request (Subscription)."""live_zone_only: bool@@ -46,33 +89,76 @@ class CompressionPolicy:return False — that's the load-bearing F2.1 gate for the cache-instability complaints in #327 / #388."""+ volatile_token_threshold: int+ """F2.2: per-mode token-count threshold below which content is+ treated as cache-stable. Subscription is conservative+ (low → flag aggressively → keep prompts stable); PAYG aggressive+ (high → tolerate more volatile noise). Plumbed but unconsumed in+ F2.2 — the volatile detector in ``cache_aligner.py`` is shape-+ based, not token-count-based; wiring it is a follow-up."""++ max_lossy_ratio: float+ """F2.2: per-mode upper bound on lossy compression aggressiveness,+ expressed as the fraction of original tokens that may be dropped+ (``0.0`` = no lossy, ``1.0`` = unlimited). Subscription ``0.25``;+ PAYG ``0.45``. Plumbed but unconsumed in F2.2 — distinct from the+ caller-driven ``target_ratio`` kwarg in the Python ContentRouter."""++ toin_read_only: bool+ """F2.2: when True, TOIN serves cached recommendations but+ never writes new pattern observations from this request.+ Subscription True (consistency over learning); PAYG/OAuth False+ (network effect keeps growing). The gate is read by+ ``smart_crusher.py`` and ``content_router.py`` at the+ ``record_compression`` call sites."""+def policy_for_mode(mode: AuthMode) -> CompressionPolicy:- """Resolve the F2.1 policy for an auth mode.+ """Resolve the F2.1+F2.2 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.+ PAYG and OAuth are identical (aggressive: live-zone-not-only,+ cache-aligner on, relaxed thresholds, TOIN write-enabled).+ Subscription is the user-visible win: live-zone-only with cache+ aligner disabled, tighter thresholds, TOIN read-only.- F2.2 may diverge OAuth from PAYG once telemetry is collected.+ F2.2-followup may diverge OAuth from PAYG once telemetry is+ collected."""if mode == AuthMode.PAYG:- return CompressionPolicy(live_zone_only=False, cache_aligner_enabled=True)+ return CompressionPolicy(+ live_zone_only=False,+ cache_aligner_enabled=True,+ volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_PAYG,+ max_lossy_ratio=_MAX_LOSSY_RATIO_PAYG,+ toin_read_only=False,+ )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)+ # Identical to PAYG in F2.1/F2.2. 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,+ volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_PAYG,+ max_lossy_ratio=_MAX_LOSSY_RATIO_PAYG,+ toin_read_only=False,+ )if mode == AuthMode.SUBSCRIPTION:- return CompressionPolicy(live_zone_only=True, cache_aligner_enabled=False)+ return CompressionPolicy(+ live_zone_only=True,+ cache_aligner_enabled=False,+ volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION,+ max_lossy_ratio=_MAX_LOSSY_RATIO_SUBSCRIPTION,+ toin_read_only=True,+ )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).+ (default in F2.1 c1-c4; flipped 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 thediff --git a/tests/test_compression_policy.py b/tests/test_compression_policy.pyindex b2a1d15e3..c517b0868 100644--- a/tests/test_compression_policy.py+++ b/tests/test_compression_policy.py@@ -5,6 +5,11 @@ The Python module is a hand-mirror ofpin both halves: that the per-mode values are right, and that thePython and Rust sides agree on the field map. F2.2 will likely retirethe hand-mirror via PyO3 — until then, this file is the canary.++F2.2 extends the F2.1 surface with three tuning fields:+``volatile_token_threshold``, ``max_lossy_ratio``, ``toin_read_only``.+Per-mode value tests below mirror the Rust unit tests in+``crates/headroom-core/src/compression_policy.rs``."""from __future__ import annotations@@ -20,7 +25,7 @@ from headroom.transforms.compression_policy import (class TestCompressionPolicyForMode:- """Per-mode field assertions. Mirrors the three Rust unit tests in+ """Per-mode field assertions. Mirrors the Rust unit tests in`crates/headroom-core/src/compression_policy.rs`."""@@ -29,13 +34,31 @@ class TestCompressionPolicyForMode: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_payg_tuning_fields_aggressive(self):+ # F2.2: per-mode tuning fields. Values are the conservative+ # defaults pending bake telemetry (see PR body and module+ # docstring).+ p = policy_for_mode(AuthMode.PAYG)+ assert p.volatile_token_threshold == 128, (+ "PAYG volatile threshold is the relaxed default; F2.2-followup will tune"+ )+ assert p.max_lossy_ratio == pytest.approx(0.45), (+ "PAYG max_lossy_ratio caps lossy paths at 0.45; F2.2-followup will tune"+ )+ assert p.toin_read_only is False, (+ "PAYG keeps TOIN write-enabled — network effect feeds on PAYG traffic"+ )+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).+ # Canary: when F2.2-followup diverges OAuth from PAYG, this test+ # fails and forces a deliberate update on BOTH sides (Rust ++ # Python). Covers ALL fields (F2.1 + F2.2) so a future field-+ # level divergence trips the assertion just as loudly as a flag+ # flip.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. "+ "F2.1+F2.2 ship OAuth=PAYG; F2.2-followup 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 "@@ -49,6 +72,32 @@ class TestCompressionPolicyForMode:"Subscription MUST skip cache aligner — load-bearing for issues #327 / #388")+ def test_subscription_tuning_fields_conservative(self):+ # F2.2: per-mode tuning fields. Subscription is the conservative+ # end — tighter threshold, lower lossy cap, TOIN read-only — so+ # cache prefixes stay stable and the learning pool isn't+ # mutated from cache-stability-sensitive traffic.+ p = policy_for_mode(AuthMode.SUBSCRIPTION)+ assert p.volatile_token_threshold == 32, (+ "Subscription volatile threshold flags content earlier (cache stability)"+ )+ assert p.max_lossy_ratio == pytest.approx(0.25), (+ "Subscription max_lossy_ratio caps lossy paths at 0.25 (conservative)"+ )+ assert p.toin_read_only is True, (+ "Subscription MUST be TOIN read-only — load-bearing for keeping the "+ "learning pool consistent across cache-sensitive traffic"+ )++ def test_max_lossy_ratio_in_unit_interval(self):+ # Defensive: every per-mode `max_lossy_ratio` MUST be in+ # ``[0.0, 1.0]`` because it expresses a fraction. A tune that+ # drifts outside the unit interval is a bug — catch it cheaply+ # here rather than at the eventual consumer site.+ for mode in (AuthMode.PAYG, AuthMode.OAUTH, AuthMode.SUBSCRIPTION):+ r = policy_for_mode(mode).max_lossy_ratio+ assert 0.0 <= r <= 1.0, f"max_lossy_ratio for {mode!r} = {r} is outside [0.0, 1.0]"+class TestPolicyDefaultPayg:"""The constant used when the enforcement flag is disabled."""@@ -68,20 +117,38 @@ class TestImmutability:# CPython 3.10+). Catch both for compatibility.p.live_zone_only = True # type: ignore[misc]+ def test_f22_tuning_fields_also_frozen(self):+ # Each F2.2 field gets its own immutability assertion — a+ # future refactor that accidentally drops `frozen=True` on the+ # dataclass would silently allow per-request mutation. The+ # F2.1 test only covered ``live_zone_only``; explicit per-+ # field coverage prevents quiet regressions.+ p = policy_for_mode(AuthMode.PAYG)+ for attr_name in ("volatile_token_threshold", "max_lossy_ratio", "toin_read_only"):+ with pytest.raises((AttributeError, Exception)):+ setattr(p, attr_name, 0) # 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.+ field there for a future PR, 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"}+ # Python catches up. F2.2 added three: volatile_token_threshold,+ # max_lossy_ratio, toin_read_only.+ expected_fields = {+ "live_zone_only",+ "cache_aligner_enabled",+ "volatile_token_threshold",+ "max_lossy_ratio",+ "toin_read_only",+ }actual_fields = {f.name for f in CompressionPolicy.__dataclass_fields__.values()}assert actual_fields == expected_fields, (f"Python CompressionPolicy fields drifted from Rust. "