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(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.rs
index 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.py
index 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 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.
+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 dataclass
from 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 the
diff --git a/tests/test_compression_policy.py b/tests/test_compression_policy.py
index 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 of
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.
+
+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. "