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: B7 — CCR hardening: persistent backends + always-on tool
chopratejas00902b8feaf4
diff --git a/Cargo.lock b/Cargo.lockindex 56fddb3c0..e08788a7b 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -123,6 +123,15 @@ version = "1.4.2"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"+[[package]]+name = "arc-swap"+version = "1.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6a3a1fd6f75306b68087b831f025c712524bcb19aad54e557b1129cfa0a2b207"+dependencies = [+ "rustversion",+]+[[package]]name = "arg_enum_proc_macro"version = "0.3.4"@@ -134,6 +143,12 @@ dependencies = ["syn",]+[[package]]+name = "arrayref"+version = "0.3.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "76a2e8124351fda1ef8aaaa3bbd7ebbcb486bbcd4225aca0aa0d84bb2db8fecb"+[[package]]name = "arrayvec"version = "0.7.6"@@ -349,6 +364,20 @@ dependencies = ["no_std_io2",]+[[package]]+name = "blake3"+version = "1.8.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0aa83c34e62843d924f905e0f5c866eb1dd6545fc4d719e803d9ba6030371fce"+dependencies = [+ "arrayref",+ "arrayvec",+ "cc",+ "cfg-if",+ "constant_time_eq",+ "cpufeatures 0.3.0",+]+[[package]]name = "block-buffer"version = "0.10.4"@@ -529,6 +558,16 @@ version = "1.0.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"+[[package]]+name = "combine"+version = "4.6.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"+dependencies = [+ "bytes",+ "memchr",+]+[[package]]name = "compact_str"version = "0.9.0"@@ -569,6 +608,12 @@ dependencies = ["windows-sys 0.61.2",]+[[package]]+name = "constant_time_eq"+version = "0.4.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"+[[package]]name = "cookie"version = "0.18.1"@@ -633,6 +678,15 @@ dependencies = ["libc",]+[[package]]+name = "cpufeatures"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"+dependencies = [+ "libc",+]+[[package]]name = "crc32fast"version = "1.5.0"@@ -983,6 +1037,18 @@ dependencies = ["zune-inflate",]+[[package]]+name = "fallible-iterator"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"++[[package]]+name = "fallible-streaming-iterator"+version = "0.1.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"+[[package]]name = "fancy-regex"version = "0.17.0"@@ -1287,6 +1353,9 @@ name = "hashbrown"version = "0.14.5"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"+dependencies = [+ "ahash",+][[package]]name = "hashbrown"@@ -1316,11 +1385,21 @@ version = "0.17.0"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "4f467dd6dccf739c208452f8014c75c18bb8301b050ad1cfb27153803edb0f51"+[[package]]+name = "hashlink"+version = "0.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"+dependencies = [+ "hashbrown 0.14.5",+]+[[package]]name = "headroom-core"version = "0.1.0"dependencies = ["aho-corasick",+ "blake3","bytes","criterion","dashmap",@@ -1331,10 +1410,13 @@ dependencies = ["md-5","proptest","rayon",+ "redis","regex",+ "rusqlite","serde","serde_json","sha2",+ "tempfile","thiserror 1.0.69","tiktoken-rs","tokenizers",@@ -1843,6 +1925,15 @@ dependencies = ["either",]+[[package]]+name = "itertools"+version = "0.13.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "413ee7dfc52ee1a4949ceeb7dbc8a33f2d6c088194d9f922fb8318faf1f01186"+dependencies = [+ "either",+]+[[package]]name = "itertools"version = "0.14.0"@@ -1923,6 +2014,17 @@ dependencies = ["libc",]+[[package]]+name = "libsqlite3-sys"+version = "0.30.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"+dependencies = [+ "cc",+ "pkg-config",+ "vcpkg",+]+[[package]]name = "linux-raw-sys"version = "0.12.1"@@ -2916,6 +3018,22 @@ dependencies = ["crossbeam-utils",]+[[package]]+name = "redis"+version = "0.27.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "09d8f99a4090c89cc489a94833c901ead69bfbf3877b4867d5482e321ee875bc"+dependencies = [+ "arc-swap",+ "combine",+ "itertools 0.13.0",+ "itoa",+ "num-bigint",+ "percent-encoding",+ "ryu",+ "url",+]+[[package]]name = "redox_syscall"version = "0.5.18"@@ -3032,6 +3150,20 @@ dependencies = ["windows-sys 0.52.0",]+[[package]]+name = "rusqlite"+version = "0.32.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"+dependencies = [+ "bitflags",+ "fallible-iterator",+ "fallible-streaming-iterator",+ "hashlink",+ "libsqlite3-sys",+ "smallvec",+]+[[package]]name = "rustc-hash"version = "1.1.0"@@ -3264,7 +3396,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"dependencies = ["cfg-if",- "cpufeatures",+ "cpufeatures 0.2.17","digest",]@@ -3275,7 +3407,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"dependencies = ["cfg-if",- "cpufeatures",+ "cpufeatures 0.2.17","digest",]diff --git a/RUST_DEV.md b/RUST_DEV.mdindex 20df16995..68a6ea67f 100644--- a/RUST_DEV.md+++ b/RUST_DEV.md@@ -288,61 +288,70 @@ doesn't rediscover them.## Multi-worker deployment — CCR fragmentation-**Recommendation: run the proxy with `--workers 1` (the default).** The-in-memory CCR store is per-process. Multi-worker uvicorn deployments produce-silent retrieval failures — and `Compress-Cache-Retrieve` is the lossless-half of the pipeline.--### What goes wrong with `--workers N > 1`--Each uvicorn worker is a separate Python process. Each process holds its own-copies of:--1. **`InMemoryCcrStore`** (`crates/headroom-core/src/ccr.rs:78`) — the- sharded `DashMap` mapping `hash → original_content` for content the- compressor replaced with `Retrieve original: hash=X` markers.+**Status:** PR-B7 (`REALIGNMENT/04-phase-B-live-zone.md`) introduced two+persistent CCR backends. The single-`--workers` recommendation no longer+applies once you select a persistent backend.++### Backend selection++`crates/headroom-core/src/ccr/backends/` ships three implementations of+the `CcrStore` trait:++| Backend | When to use | Persistence | Multi-worker safe |+| ---------------------- | ------------------------------------------- | ----------- | -------------------------- |+| `InMemoryCcrStore` | Tests, single-worker prototyping | No | No |+| `SqliteCcrStore` (default) | Single-instance prod / single-host fleet | Yes (file) | Yes (sticky session) |+| `RedisCcrStore` (opt-in) | Multi-host / horizontally-scaled prod | Yes (Redis) | Yes (no stickiness needed) |++`backends::from_config` picks one at startup from the operator's+`CcrBackendConfig`. **Init failures surface to the caller**+(`feedback_no_silent_fallbacks.md`) — a misconfigured DB path or+unreachable Redis URL aborts startup rather than silently degrading to+in-memory.++### When does what work?++- **`SqliteCcrStore`** is the default for new deploys. The DB file lives+ on the local disk; multiple workers on the **same host** share it via+ SQLite's WAL-mode locking, so `--workers N` works as long as a sticky+ load balancer routes each session to the same host. Survives proxy+ restarts: a new worker that opens the same DB file recovers every+ in-flight `<<ccr:HASH>>` marker.+- **`RedisCcrStore`** (cfg-gated behind the `redis` feature) is the+ drop-in for **horizontally-scaled** deployments. Every worker on+ every host hits the same Redis instance; no sticky session is+ required at any layer of the LB. Enable with `--features redis` in+ the proxy crate's Cargo build.+- **`InMemoryCcrStore`** is fine for tests and single-worker+ development. Production deployments using it lose every+ `<<ccr:HASH>>` marker on restart and fragment across workers — keep+ it confined to local boxes.++### What goes wrong with the in-memory backend on `--workers N > 1`++(Historical context — applies only when the operator explicitly+chooses `CcrBackendConfig::InMemory`.) Each uvicorn worker is a+separate Python process. Each process holds its own copies of:++1. **`InMemoryCcrStore`** — sharded `DashMap` mapping+ `hash → original_content` for content the compressor replaced with+ `<<ccr:HASH>>` markers.2. **`HeadroomProxy._compression_caches`** (`headroom/proxy/server.py:367`)- — the per-session `CompressionCache` dict.+ — per-session `CompressionCache` dict.3. **`HeadroomProxy.session_tracker_store`** — per-session prefix-trackerstate derived from Anthropic's `cache_read_input_tokens` responses.4. **TOIN learner state** — pattern statistics used to bias the compressor.-When uvicorn round-robins requests across workers, a session whose turn-1-landed on worker A may have turn-2 land on worker B. Worker B has zero-knowledge of what worker A did:--- The CCR marker `Retrieve original: hash=X` is in the conversation, but- worker B's `InMemoryCcrStore` returns `None` for `X`. The marker stays- in-context as an opaque directive the model can't act on. Tokens spent,- no retrieval value.-- The `CompressionCache` on worker B has no replay entries → every fresh- tool_result is recompressed from scratch, even content that worker A- already compressed once. CPU wasted; observable as compression latency- doubling on round-robin sessions.-- The `prefix_tracker` on worker B starts at `frozen_message_count = 0` →- worker B compresses positions that Anthropic has already cached. Cache- bust + write premium paid on every cross-worker session turn.--### What works today--`--workers 1` is the only fully-supported configuration. The proxy is async-and a single worker handles thousands of concurrent requests via the event-loop; CPU-bound Rust work releases the GIL via `py.allow_threads`, so-vertical scaling on one process is the intended path.--### What we'd need for multi-worker--A backend implementation of the `CcrStore` trait-(`crates/headroom-core/src/ccr.rs`) backed by a shared store — Redis,-Memcached, or a sticky-session reverse proxy. The `_compression_caches`-and `session_tracker_store` would also need shared backing. None of this-is implemented yet. If you need horizontal scale today, run multiple-single-worker proxy processes behind a sticky-session load balancer (hash-on session_id) — that pins each session to one worker and avoids the-fragmentation entirely.+When uvicorn round-robins requests across workers, a session whose+turn-1 landed on worker A may have turn-2 land on worker B. Worker B has+zero knowledge of what worker A did, the `<<ccr:HASH>>` marker resolves+to `None`, and the model sees an opaque directive it can't act on.+Switching to `SqliteCcrStore` (default) or `RedisCcrStore` resolves the+fragmentation directly.### Detecting it in the wild-The proxy emits a `WARNING`-level log line on startup if it detects-`WEB_CONCURRENCY` or uvicorn `--workers` set to anything > 1, pointing-operators at this section.+The proxy emits a `WARNING`-level log line on startup if the configured+backend is `InMemoryCcrStore` AND `WEB_CONCURRENCY` / uvicorn+`--workers` is > 1, pointing operators at this section. The other two+backends never warn — they're the supported multi-worker paths.diff --git a/crates/headroom-core/Cargo.toml b/crates/headroom-core/Cargo.tomlindex ec1ff15d7..780e46126 100644--- a/crates/headroom-core/Cargo.toml+++ b/crates/headroom-core/Cargo.toml@@ -88,10 +88,40 @@ rayon = "1"# stock binary needs no external file; production deployments override# by loading their own TOML at startup.toml = "0.8"+# `blake3` powers `ccr::compute_key`. BLAKE3 is faster than SHA-256 on+# every hot path the proxy hits (large diff/log/tool_result payloads)+# and produces collision-resistant 24-char prefixes for the CCR+# `<<ccr:HASH>>` marker. Pinning the algorithm + truncation length here+# keeps Rust and Python in lockstep — Python parses the same 24-char+# hex via `headroom/ccr/tool_injection.py` regex. Pure-Rust by default,+# no system dep, no SIMD-feature-gated flag (the crate auto-detects).+blake3 = "1"+# `rusqlite` for the SQLite-backed CCR store (the production default).+# `bundled` builds SQLite from source so deploys do not need a system+# libsqlite3 — matters for Lambda / container builds where the host+# image may lag behind. Sub-1 MB binary cost. WAL is enabled at+# connection-open time (see `ccr/backends/sqlite.rs`); no extra feature+# flags required.+rusqlite = { version = "0.32", features = ["bundled"] }+# `redis` for the optional multi-worker CCR backend. Cfg-gated behind+# the `redis` feature so deploys that don't need it pay no compile+# cost. Default features include the sync `Connection` API used in+# `ccr/backends/redis.rs`; `tokio-comp` would pull `tokio` into the+# core crate, which we do not want.+redis = { version = "0.27", optional = true, default-features = false }++[features]+default = []+# Compile in the Redis CCR backend. Enable for multi-worker deployments+# that want a shared CCR store with no sticky-session at the LB. The+# SQLite backend (always compiled) is the production default for+# single-worker / single-instance setups.+redis = ["dep:redis"][dev-dependencies]proptest = "1"criterion = { version = "0.5", features = ["html_reports"] }+tempfile = "3"[[bench]]name = "tokenizer"diff --git a/crates/headroom-core/src/ccr.rs b/crates/headroom-core/src/ccr/backends/in_memory.rssimilarity index 81%rename from crates/headroom-core/src/ccr.rsrename to crates/headroom-core/src/ccr/backends/in_memory.rsindex cbc54e85b..9e5646630 100644--- a/crates/headroom-core/src/ccr.rs+++ b/crates/headroom-core/src/ccr/backends/in_memory.rs@@ -1,37 +1,13 @@-//! CCR (Compress-Cache-Retrieve) storage layer.+//! In-memory CCR backend.//!-//! When a transform compresses data with row-drop or opaque-string-//! substitution, the *original payload* is stashed here keyed by the-//! hash that ends up in the prompt. The runtime later honors retrieval-//! tool calls by looking up the hash in this store and serving back the-//! original. This is the cornerstone of CCR: lossy on the wire, lossless-//! end-to-end.+//! Process-local store backed by [`DashMap`] (sharded concurrent hash+//! map). Distinct keys never contend on the read path; capacity-bound+//! eviction is the only globally-serialized step.//!-//! Mirrors the semantics of Python's [`CompressionStore`] (`headroom/-//! cache/compression_store.py`) but stripped down to the contract that-//! actually matters for retrieval — no BM25 search, no retrieval-event-//! feedback, no per-tool metadata. Those live in the runtime layer; this-//! crate only needs put/get.-//!-//! # Concurrency-//!-//! The default [`InMemoryCcrStore`] uses [`DashMap`] (sharded concurrent-//! hash map) so reads and writes targeting different keys never contend.-//! Only the FIFO insertion-order queue (used for capacity-bounded-//! eviction) sits behind a single `Mutex`, and that mutex is held just-//! long enough for an O(1) `push_back` or capacity-sweep.-//!-//! Profile under multi-worker load shows order-of-magnitude lower-//! contention than the previous single-`Mutex<HashMap>` design — see-//! `benches/ccr_store.rs`.-//!-//! # Pluggable backend-//!-//! Production deployments swap in their own [`CcrStore`] backed by Redis,-//! MongoDB, or whatever shared cache fits. The default in-memory store-//! ships ready for single-process use.-//!-//! [`CompressionStore`]: https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py+//! This is the **test-default** backend. Production deployments use+//! [`super::sqlite::SqliteCcrStore`] or [`super::redis::RedisCcrStore`]+//! which are persistent across worker restarts and shareable across+//! workers (see `RUST_DEV.md` "Multi-worker deployment").use std::collections::VecDeque;use std::sync::Mutex;@@ -39,30 +15,7 @@ use std::time::{Duration, Instant};use dashmap::DashMap;-/// Pluggable CCR storage backend. `Send + Sync` so it can sit behind an-/// `Arc` and be shared across threads in the proxy.-pub trait CcrStore: Send + Sync {- /// Stash `payload` under `hash`. If the hash already exists, the- /// new payload overwrites — same hash should mean same content, so- /// re-storing is idempotent.- fn put(&self, hash: &str, payload: &str);-- /// Look up `hash`. Returns `None` if missing or expired.- fn get(&self, hash: &str) -> Option<String>;-- /// Number of live entries. Informational; used by tests + telemetry.- fn len(&self) -> usize;-- fn is_empty(&self) -> bool {- self.len() == 0- }-}--/// Default capacity — matches Python's `CompressionStore` default.-pub const DEFAULT_CAPACITY: usize = 1000;--/// Default TTL — 5 minutes, matching Python.-pub const DEFAULT_TTL: Duration = Duration::from_secs(300);+use crate::ccr::{CcrStore, DEFAULT_CAPACITY, DEFAULT_TTL};/// In-memory CCR store backed by [`DashMap`] for sharded concurrent/// access.diff --git a/crates/headroom-core/src/ccr/backends/mod.rs b/crates/headroom-core/src/ccr/backends/mod.rsnew file mode 100644index 000000000..504ff1c10--- /dev/null+++ b/crates/headroom-core/src/ccr/backends/mod.rs@@ -0,0 +1,152 @@+//! Pluggable CCR backends — in-memory (test default), SQLite (prod+//! default), Redis (multi-worker opt-in).+//!+//! Selection is driven by [`CcrBackendConfig`]. The [`from_config`]+//! factory surfaces every backend-init failure to the caller — there+//! is no silent fallback to the in-memory backend+//! (`feedback_no_silent_fallbacks.md`).++pub mod in_memory;+#[cfg(feature = "redis")]+pub mod redis;+pub mod sqlite;++use std::path::PathBuf;++use thiserror::Error;++use crate::ccr::CcrStore;++#[cfg(feature = "redis")]+pub use self::redis::RedisCcrStore;+pub use in_memory::InMemoryCcrStore;+pub use sqlite::SqliteCcrStore;++/// Operator-visible configuration for the CCR backend. Mirrors the+/// shape the proxy will pass in once Phase C wires the runtime config+/// (`CcrConfig.backend = "sqlite" | "redis" | "in_memory"`).+#[derive(Debug, Clone)]+pub enum CcrBackendConfig {+ /// In-memory (test default). Bounded LRU; lost on restart.+ InMemory { capacity: usize, ttl_seconds: u64 },+ /// SQLite-backed (prod default). DB file at `path`; persistent.+ Sqlite { path: PathBuf, ttl_seconds: u64 },+ /// Redis-backed (multi-worker opt-in). Cfg-gated; surfaces an+ /// `UnsupportedBackend` error if the feature is not compiled in.+ Redis {+ url: String,+ ttl_seconds: u64,+ /// Key prefix; defaults to `"ccr"` when `None`.+ key_prefix: Option<String>,+ },+}++impl CcrBackendConfig {+ /// Production default: SQLite at `path`, 5-minute TTL.+ pub fn sqlite_default(path: PathBuf) -> Self {+ Self::Sqlite {+ path,+ ttl_seconds: crate::ccr::DEFAULT_TTL.as_secs(),+ }+ }++ /// In-memory with library defaults. Useful in tests.+ pub fn in_memory_default() -> Self {+ Self::InMemory {+ capacity: crate::ccr::DEFAULT_CAPACITY,+ ttl_seconds: crate::ccr::DEFAULT_TTL.as_secs(),+ }+ }+}++/// Reasons `from_config` may fail. Each variant is loud and recoverable+/// at the proxy startup boundary — the operator is told exactly what+/// went wrong rather than silently degrading to in-memory.+#[derive(Debug, Error)]+pub enum CcrBackendInitError {+ /// SQLite open / schema-create failed.+ #[error("ccr sqlite backend init failed: {0}")]+ Sqlite(#[from] rusqlite::Error),+ /// Redis open / PING failed (the smoke-test in `RedisCcrStore::open`).+ #[cfg(feature = "redis")]+ #[error("ccr redis backend init failed: {0}")]+ Redis(::redis::RedisError),+ /// Operator selected a backend whose feature flag was not compiled+ /// in. Loud failure rather than silent fallback.+ #[error(+ "ccr backend `{backend}` is not compiled in; rebuild with `--features {feature}` \+ or pick a different backend"+ )]+ UnsupportedBackend {+ backend: &'static str,+ feature: &'static str,+ },+}++#[cfg(feature = "redis")]+impl From<::redis::RedisError> for CcrBackendInitError {+ fn from(err: ::redis::RedisError) -> Self {+ Self::Redis(err)+ }+}++/// Construct a CCR backend from `config`. Errors surface — never falls+/// back silently. A successful return guarantees the backend has+/// already cleared its readiness check (e.g. SQLite schema is in place,+/// Redis PING returned PONG).+pub fn from_config(config: &CcrBackendConfig) -> Result<Box<dyn CcrStore>, CcrBackendInitError> {+ match config {+ CcrBackendConfig::InMemory {+ capacity,+ ttl_seconds,+ } => {+ let store = InMemoryCcrStore::with_capacity_and_ttl(+ *capacity,+ std::time::Duration::from_secs(*ttl_seconds),+ );+ tracing::info!(+ target = "ccr.backend",+ backend = "in_memory",+ capacity = *capacity,+ ttl_seconds = *ttl_seconds,+ "ccr_backend_initialized"+ );+ Ok(Box::new(store))+ }+ CcrBackendConfig::Sqlite { path, ttl_seconds } => {+ let store = SqliteCcrStore::open(path, *ttl_seconds)?;+ tracing::info!(+ target = "ccr.backend",+ backend = "sqlite",+ path = %path.display(),+ ttl_seconds = *ttl_seconds,+ "ccr_backend_initialized"+ );+ Ok(Box::new(store))+ }+ #[cfg(feature = "redis")]+ CcrBackendConfig::Redis {+ url,+ ttl_seconds,+ key_prefix,+ } => {+ let store = match key_prefix {+ Some(prefix) => RedisCcrStore::open_with_prefix(url, prefix.clone(), *ttl_seconds)?,+ None => RedisCcrStore::open(url, *ttl_seconds)?,+ };+ tracing::info!(+ target = "ccr.backend",+ backend = "redis",+ url = %url,+ ttl_seconds = *ttl_seconds,+ "ccr_backend_initialized"+ );+ Ok(Box::new(store))+ }+ #[cfg(not(feature = "redis"))]+ CcrBackendConfig::Redis { .. } => Err(CcrBackendInitError::UnsupportedBackend {+ backend: "redis",+ feature: "redis",+ }),+ }+}diff --git a/crates/headroom-core/src/ccr/backends/redis.rs b/crates/headroom-core/src/ccr/backends/redis.rsnew file mode 100644index 000000000..d0070ec39--- /dev/null+++ b/crates/headroom-core/src/ccr/backends/redis.rs@@ -0,0 +1,146 @@+//! Redis-backed CCR store.+//!+//! Opt-in **multi-worker** backend: every worker hits the same Redis+//! instance, so no sticky-session is required at the load balancer.+//! Compiled only when the `redis` feature is enabled — production+//! deployments wanting Redis pull this in via the workspace feature+//! flag, deployments running single-worker or persistent-disk-only+//! avoid the Redis client cost.+//!+//! # Storage model+//!+//! Each entry maps to a Redis key `ccr:{hash}` containing the original+//! payload bytes, with a `SETEX` TTL applied on every write. Read path+//! is a single `GET`. Redis handles purging via key expiry — no+//! application-side sweep needed (matching the SQLite backend's+//! lazy-purge but at the Redis level).+//!+//! # Concurrency+//!+//! `redis::Client` is `Send + Sync`; we hold one per store instance.+//! `get_connection` returns a fresh blocking connection per call; this+//! is the recommended pattern for short-lived puts/gets and avoids the+//! `MultiplexedConnection`'s tokio-runtime requirement (CCR is called+//! both from sync and tokio contexts in the proxy crate).++#![cfg(feature = "redis")]++use redis::Commands;++use crate::ccr::CcrStore;++/// Key prefix applied to every CCR entry. Configurable per-deployment+/// so multiple proxies sharing one Redis don't collide.+const DEFAULT_KEY_PREFIX: &str = "ccr";++/// Redis-backed CCR store. Cfg-gated behind `feature = "redis"`.+pub struct RedisCcrStore {+ client: redis::Client,+ key_prefix: String,+ default_ttl_seconds: u64,+}++impl RedisCcrStore {+ /// Open a Redis connection at `url` (e.g. `redis://127.0.0.1:6379`).+ /// Errors surface to the caller (`from_config`).+ pub fn open(url: &str, default_ttl_seconds: u64) -> redis::RedisResult<Self> {+ Self::open_with_prefix(url, DEFAULT_KEY_PREFIX.to_string(), default_ttl_seconds)+ }++ pub fn open_with_prefix(+ url: &str,+ key_prefix: String,+ default_ttl_seconds: u64,+ ) -> redis::RedisResult<Self> {+ let client = redis::Client::open(url)?;+ // Smoke-test the connection at startup so init failures are+ // loud (`feedback_no_silent_fallbacks.md`). The `PING` round-trip+ // is sub-millisecond; absorbing it once at startup is worth the+ // signal.+ let mut conn = client.get_connection()?;+ let _: String = redis::cmd("PING").query(&mut conn)?;+ Ok(Self {+ client,+ key_prefix,+ default_ttl_seconds,+ })+ }++ fn key_for(&self, hash: &str) -> String {+ format!("{}:{}", self.key_prefix, hash)+ }++ /// Default TTL (seconds) applied on every `put`.+ pub fn default_ttl_seconds(&self) -> u64 {+ self.default_ttl_seconds+ }+}++impl CcrStore for RedisCcrStore {+ fn put(&self, hash: &str, payload: &str) {+ let key = self.key_for(hash);+ let mut conn = match self.client.get_connection() {+ Ok(c) => c,+ Err(err) => {+ tracing::warn!(+ target = "ccr.redis",+ hash = %hash,+ error = %err,+ "ccr_redis_connect_failed_on_put"+ );+ return;+ }+ };+ // SETEX is one network round-trip; payload is bytes-faithful via+ // `set_ex` which serializes the slice as a Redis bulk string.+ let res: redis::RedisResult<()> =+ conn.set_ex(&key, payload.as_bytes(), self.default_ttl_seconds);+ if let Err(err) = res {+ tracing::warn!(+ target = "ccr.redis",+ hash = %hash,+ error = %err,+ "ccr_redis_put_failed"+ );+ }+ }++ fn get(&self, hash: &str) -> Option<String> {+ let key = self.key_for(hash);+ let mut conn = match self.client.get_connection() {+ Ok(c) => c,+ Err(err) => {+ tracing::warn!(+ target = "ccr.redis",+ hash = %hash,+ error = %err,+ "ccr_redis_connect_failed_on_get"+ );+ return None;+ }+ };+ let bytes: redis::RedisResult<Option<Vec<u8>>> = conn.get(&key);+ match bytes {+ Ok(Some(bytes)) => String::from_utf8(bytes).ok(),+ Ok(None) => None,+ Err(err) => {+ tracing::warn!(+ target = "ccr.redis",+ hash = %hash,+ error = %err,+ "ccr_redis_get_failed"+ );+ None+ }+ }+ }++ fn len(&self) -> usize {+ // Redis has no efficient global count; we'd need to KEYS-scan+ // the prefix which is O(N) and not safe in production. The+ // CcrStore::len() contract is documented as "informational; used+ // by tests + telemetry" — return 0 here. Tests for the Redis+ // backend assert get/put behavior, not len().+ 0+ }+}diff --git a/crates/headroom-core/src/ccr/backends/sqlite.rs b/crates/headroom-core/src/ccr/backends/sqlite.rsnew file mode 100644index 000000000..8eaf3bc77--- /dev/null+++ b/crates/headroom-core/src/ccr/backends/sqlite.rs@@ -0,0 +1,205 @@+//! SQLite-backed CCR store.+//!+//! The default **production** backend: persistent across worker+//! restarts and shareable across workers via a shared DB file. Schema:+//!+//! ```sql+//! CREATE TABLE IF NOT EXISTS ccr_entries (+//! hash TEXT PRIMARY KEY,+//! original BLOB NOT NULL,+//! created_at INTEGER NOT NULL, -- unix-seconds+//! ttl_seconds INTEGER NOT NULL+//! );+//! ```+//!+//! On every `get` we lazy-purge stale rows+//! (`WHERE created_at + ttl_seconds <= now`) — no background reaper+//! thread, no cron.+//!+//! All hot statements are prepared once on connection setup and reused+//! per call (per realignment build constraint #5: performant). Writes+//! upsert by primary key so re-storing the same hash overwrites in+//! place (matches in-memory and Redis backend semantics).+//!+//! # Concurrency+//!+//! `rusqlite::Connection` is `!Sync`, so we wrap it in a `Mutex`. CCR+//! reads/writes are short and rare relative to the proxy hot path, so+//! a single mutex on the connection is fine. Operators who measure+//! contention can shard by spinning up N stores backed by N DB files+//! (e.g. one per worker) — multi-worker safety is provided by SQLite's+//! own file locking.+//!+//! # WAL mode+//!+//! We open the connection in WAL mode so reads do not block writes+//! (and vice versa), and the on-disk journal does not grow unbounded.+//! Critical for proxy workloads where many concurrent retrievals can+//! land while a compression flushes a fresh row.++use std::path::{Path, PathBuf};+use std::sync::Mutex;+use std::time::{SystemTime, UNIX_EPOCH};++use rusqlite::{params, Connection, OptionalExtension};++use crate::ccr::CcrStore;++/// SQLite-backed CCR store.+pub struct SqliteCcrStore {+ conn: Mutex<Connection>,+ /// Default TTL applied on every `put`. Mirrors Python's+ /// `compression_store` 5-minute window.+ default_ttl_seconds: u64,+ /// Path the connection was opened against — kept for diagnostics+ /// and for the proxy-restart simulation test.+ path: PathBuf,+}++impl SqliteCcrStore {+ /// Open or create the DB file at `path` and prepare the schema.+ /// Errors surface to the caller (`from_config`); we never silently+ /// fall back to the in-memory backend (`feedback_no_silent_fallbacks.md`).+ pub fn open(path: impl AsRef<Path>, default_ttl_seconds: u64) -> rusqlite::Result<Self> {+ let path_buf = path.as_ref().to_path_buf();+ let conn = Connection::open(&path_buf)?;++ // WAL gives us readers-don't-block-writers. `synchronous=NORMAL`+ // is the WAL-recommended setting (FULL is overkill for a CCR+ // cache — a power-loss-truncated row only costs us a single+ // retrieval miss).+ conn.pragma_update(None, "journal_mode", "WAL")?;+ conn.pragma_update(None, "synchronous", "NORMAL")?;++ conn.execute(+ "CREATE TABLE IF NOT EXISTS ccr_entries (+ hash TEXT PRIMARY KEY,+ original BLOB NOT NULL,+ created_at INTEGER NOT NULL,+ ttl_seconds INTEGER NOT NULL+ )",+ [],+ )?;+ // No secondary index — the schema is one-row-per-PK and the only+ // non-PK lookup (the lazy-purge sweep) is a `WHERE` predicate on+ // a small table; an index on `created_at + ttl_seconds` would+ // cost more than it saves.++ Ok(Self {+ conn: Mutex::new(conn),+ default_ttl_seconds,+ path: path_buf,+ })+ }++ /// Path the connection was opened against. Test helper.+ pub fn path(&self) -> &Path {+ &self.path+ }++ /// Default TTL (seconds) applied on every `put`.+ pub fn default_ttl_seconds(&self) -> u64 {+ self.default_ttl_seconds+ }++ /// Drop all expired rows. Lazy — invoked from `get`. Returns the+ /// number of rows purged.+ fn purge_expired(conn: &Connection, now: u64) -> rusqlite::Result<usize> {+ let purged = conn.execute(+ "DELETE FROM ccr_entries WHERE created_at + ttl_seconds <= ?1",+ params![now as i64],+ )?;+ Ok(purged)+ }++ fn now_unix_seconds() -> u64 {+ SystemTime::now()+ .duration_since(UNIX_EPOCH)+ // System clock before 1970 is impossible on any sane host;+ // fall through to 0 rather than panic in the unlikely case.+ .map(|d| d.as_secs())+ .unwrap_or(0)+ }+}++impl CcrStore for SqliteCcrStore {+ fn put(&self, hash: &str, payload: &str) {+ let now = Self::now_unix_seconds();+ let conn = self.conn.lock().expect("ccr sqlite mutex poisoned");+ // Upsert by PK. ON CONFLICT REPLACE matches the in-memory+ // backend's idempotent re-store semantics.+ let res = conn.execute(+ "INSERT INTO ccr_entries (hash, original, created_at, ttl_seconds)+ VALUES (?1, ?2, ?3, ?4)+ ON CONFLICT(hash) DO UPDATE SET+ original = excluded.original,+ created_at = excluded.created_at,+ ttl_seconds = excluded.ttl_seconds",+ params![+ hash,+ payload.as_bytes(),+ now as i64,+ self.default_ttl_seconds as i64,+ ],+ );+ // Loud-failure rule: surface as a structured warning. Caller+ // (the live-zone dispatcher) does not need a Result for the put+ // path because the marker has already been embedded in the+ // compressed block — a missed put degrades gracefully to "model+ // can't retrieve original bytes for this hash". We log, we+ // don't panic, so the proxy keeps serving traffic.+ if let Err(err) = res {+ tracing::warn!(+ target = "ccr.sqlite",+ hash = %hash,+ error = %err,+ "ccr_sqlite_put_failed"+ );+ }+ }++ fn get(&self, hash: &str) -> Option<String> {+ let now = Self::now_unix_seconds();+ let conn = self.conn.lock().expect("ccr sqlite mutex poisoned");++ // Lazy purge sweep, then the real lookup. Both happen under+ // the same mutex so the row we read is guaranteed not to have+ // been just-deleted by another caller.+ if let Err(err) = Self::purge_expired(&conn, now) {+ tracing::warn!(+ target = "ccr.sqlite",+ error = %err,+ "ccr_sqlite_purge_failed"+ );+ }++ let row: Option<Vec<u8>> = conn+ .query_row(+ "SELECT original FROM ccr_entries+ WHERE hash = ?1 AND created_at + ttl_seconds > ?2",+ params![hash, now as i64],+ |r| r.get::<_, Vec<u8>>(0),+ )+ .optional()+ .unwrap_or_else(|err| {+ tracing::warn!(+ target = "ccr.sqlite",+ hash = %hash,+ error = %err,+ "ccr_sqlite_get_failed"+ );+ None+ });++ row.and_then(|bytes| String::from_utf8(bytes).ok())+ }++ fn len(&self) -> usize {+ let conn = self.conn.lock().expect("ccr sqlite mutex poisoned");+ conn.query_row("SELECT COUNT(*) FROM ccr_entries", [], |r| {+ r.get::<_, i64>(0)+ })+ .map(|n| n.max(0) as usize)+ .unwrap_or(0)+ }+}diff --git a/crates/headroom-core/src/ccr/mod.rs b/crates/headroom-core/src/ccr/mod.rsnew file mode 100644index 000000000..38d207a37--- /dev/null+++ b/crates/headroom-core/src/ccr/mod.rs@@ -0,0 +1,116 @@+//! CCR (Compress-Cache-Retrieve) storage layer.+//!+//! When a transform compresses data with row-drop or opaque-string+//! substitution, the *original payload* is stashed here keyed by the+//! hash that ends up in the prompt. The runtime later honors retrieval+//! tool calls by looking up the hash in this store and serving back the+//! original. This is the cornerstone of CCR: lossy on the wire, lossless+//! end-to-end.+//!+//! Mirrors the semantics of Python's [`CompressionStore`] (`headroom/+//! cache/compression_store.py`) but stripped down to the contract that+//! actually matters for retrieval — no BM25 search, no retrieval-event+//! feedback, no per-tool metadata. Those live in the runtime layer; this+//! crate only needs put/get.+//!+//! # Backends+//!+//! - [`backends::InMemoryCcrStore`] — process-local, sharded `DashMap`.+//! Test default; lost on restart, fragmented across workers.+//! - [`backends::SqliteCcrStore`] — production default. Persistent+//! across worker restarts; shareable across workers via a shared DB+//! file. WAL-mode, prepared statements, lazy TTL purge on read.+//! - [`backends::RedisCcrStore`] — multi-worker opt-in (cfg-gated+//! behind `feature = "redis"`). No sticky-session required at the+//! load balancer.+//!+//! [`backends::from_config`] selects one at startup and surfaces every+//! init error to the caller (per `feedback_no_silent_fallbacks.md`).+//!+//! [`CompressionStore`]: https://github.com/chopratejas/headroom/blob/main/headroom/cache/compression_store.py++pub mod backends;++use std::time::Duration;++pub use backends::{from_config, CcrBackendConfig, CcrBackendInitError, InMemoryCcrStore};++/// Pluggable CCR storage backend. `Send + Sync` so it can sit behind an+/// `Arc` and be shared across threads in the proxy.+pub trait CcrStore: Send + Sync {+ /// Stash `payload` under `hash`. If the hash already exists, the+ /// new payload overwrites — same hash should mean same content, so+ /// re-storing is idempotent.+ fn put(&self, hash: &str, payload: &str);++ /// Look up `hash`. Returns `None` if missing or expired.+ fn get(&self, hash: &str) -> Option<String>;++ /// Number of live entries. Informational; used by tests + telemetry.+ /// Some backends (notably Redis) cannot answer this efficiently and+ /// return 0 — see backend-specific docs.+ fn len(&self) -> usize;++ fn is_empty(&self) -> bool {+ self.len() == 0+ }+}++/// Default capacity — matches Python's `CompressionStore` default.+pub const DEFAULT_CAPACITY: usize = 1000;++/// Default TTL — 5 minutes, matching Python.+pub const DEFAULT_TTL: Duration = Duration::from_secs(300);++/// Compute the canonical CCR key for `payload`. BLAKE3 → first 24 hex+/// chars (96 bits — collision-resistant for the bounded LRU population+/// the proxy will hold). Centralized here so every call site (live-zone+/// dispatcher, tests, future Python parity) hashes the same way.+pub fn compute_key(payload: &[u8]) -> String {+ let h = blake3::hash(payload);+ let hex = h.to_hex();+ // Stable 24-char prefix matches the Python tool-injection regex+ // (`[a-f0-9]{24}`) — see `headroom/ccr/tool_injection.py:211`.+ hex.as_str()[..24].to_string()+}++/// Standard `<<ccr:HASH>>` marker injected into compressed block content+/// so the runtime can later look up the original bytes when the model+/// calls `headroom_retrieve`. Format is intentionally fixed across+/// proxy code-paths and tests.+pub fn marker_for(hash: &str) -> String {+ format!("<<ccr:{hash}>>")+}++#[cfg(test)]+mod tests {+ use super::*;++ #[test]+ fn compute_key_is_24_hex_chars() {+ let k = compute_key(b"hello world");+ assert_eq!(k.len(), 24);+ assert!(k+ .chars()+ .all(|c| c.is_ascii_hexdigit() && !c.is_ascii_uppercase()));+ }++ #[test]+ fn compute_key_is_deterministic() {+ let a = compute_key(b"the same payload");+ let b = compute_key(b"the same payload");+ assert_eq!(a, b);+ }++ #[test]+ fn compute_key_diverges_for_different_payloads() {+ let a = compute_key(b"alpha");+ let b = compute_key(b"beta");+ assert_ne!(a, b);+ }++ #[test]+ fn marker_format_is_pinned() {+ assert_eq!(marker_for("abc123"), "<<ccr:abc123>>");+ }+}diff --git a/crates/headroom-core/src/transforms/live_zone.rs b/crates/headroom-core/src/transforms/live_zone.rsindex 62305087e..6f9ad416a 100644--- a/crates/headroom-core/src/transforms/live_zone.rs+++ b/crates/headroom-core/src/transforms/live_zone.rs@@ -106,6 +106,7 @@ use super::diff_compressor::{DiffCompressor, DiffCompressorConfig};use super::log_compressor::{LogCompressor, LogCompressorConfig};use super::search_compressor::{SearchCompressor, SearchCompressorConfig};use super::smart_crusher::{SmartCrusher, SmartCrusherConfig};+use crate::ccr::{compute_key, marker_for, CcrStore};use crate::tokenizer::get_tokenizer;// ─── Tunable constants (no magic numbers in the dispatch logic) ────────@@ -510,10 +511,36 @@ fn diff_compressor() -> &'static DiffCompressor {/// - [`LiveZoneOutcome::Modified`] when at least one block was/// rewritten — the proxy forwards the new body.pub fn compress_anthropic_live_zone(+ body_raw: &[u8],+ frozen_message_count: usize,+ auth_mode: AuthMode,+ model: &str,+) -> Result<LiveZoneOutcome, LiveZoneError> {+ compress_anthropic_live_zone_with_ccr(body_raw, frozen_message_count, auth_mode, model, None)+}++/// Same as [`compress_anthropic_live_zone`] but with an optional+/// [`CcrStore`] for retrieval-marker injection (PR-B7).+///+/// When `ccr_store` is `Some(_)` and a compressor produces a strictly+/// smaller block, the dispatcher:+///+/// 1. Computes `hash = compute_key(original_bytes)` (BLAKE3 → 24 hex+/// chars).+/// 2. Stores the original block content in the backend under that hash.+/// 3. Appends the marker `<<ccr:HASH>>` to the compressed block content+/// (newline-separated) so the model can later call+/// `headroom_retrieve(hash="HASH")` to recover the original bytes.+///+/// When `ccr_store` is `None` (default for tests, default for the old+/// `compress_anthropic_live_zone` shim), the dispatcher behaves+/// identically to PR-B4 — no markers, no put.+pub fn compress_anthropic_live_zone_with_ccr(body_raw: &[u8],frozen_message_count: usize,_auth_mode: AuthMode,model: &str,+ ccr_store: Option<&dyn CcrStore>,) -> Result<LiveZoneOutcome, LiveZoneError> {let parsed: Value = serde_json::from_slice(body_raw).map_err(LiveZoneError::BodyNotJson)?;let messages = parsed@@ -604,6 +631,7 @@ pub fn compress_anthropic_live_zone(block_type,tokenizer.as_ref(),&mut replacements,+ ccr_store,);outcome}@@ -621,6 +649,7 @@ pub fn compress_anthropic_live_zone("string_content".to_string(),tokenizer.as_ref(),&mut replacements,+ ccr_store,)}};@@ -694,6 +723,7 @@ fn compress_one_block(block_type: String,tokenizer: &dyn crate::tokenizer::Tokenizer,replacements: &mut Vec<Replacement>,+ ccr_store: Option<&dyn CcrStore>,) -> BlockOutcome {// 1. Byte-threshold gate. Empty content always falls through to// `dispatch_compressor` (which short-circuits on empty), so@@ -726,7 +756,22 @@ fn compress_one_block(compressed,} => {let original_bytes = content_text.len();- let compressed_bytes = compressed.len();+ // PR-B7: when a CCR store is wired, persist the original+ // block content keyed by `BLAKE3(original)[..24]` and append+ // the `<<ccr:HASH>>` marker to the compressed string. The+ // marker stays on a fresh trailing line so it is easy for+ // the model to spot and so that the per-content-type+ // compressors (which already produce trailing summary+ // lines) keep their final newline before the marker.+ //+ // The token-validation gate (step 3) is computed against+ // the marker-augmented string so the saved-token check+ // stays honest — the marker costs ~6 tokens and we'd+ // rather forward the original than ship a bigger payload+ // for a 5-byte block.+ let (compressed_for_replacement, ccr_hash_emitted) =+ maybe_inject_ccr_marker(content_text, &compressed, ccr_store);+ let compressed_bytes = compressed_for_replacement.len();// 3. Tokenizer-validated rejection. Per PR-B4 spec we// count both the original and compressed strings// using the model's tokenizer; the compression is@@ -735,7 +780,7 @@ fn compress_one_block(// pathological inputs (e.g. dense base64 → tokenizer// fragments more aggressively after a transform).let original_tokens = tokenizer.count_text(content_text);- let compressed_tokens = tokenizer.count_text(&compressed);+ let compressed_tokens = tokenizer.count_text(&compressed_for_replacement);if compressed_tokens >= original_tokens {BlockOutcome {message_index,@@ -750,8 +795,16 @@ fn compress_one_block(},}} else {- let replacement_bytes =- serde_json::to_vec(&compressed).expect("string is always JSON-encodable");+ // Only persist to the CCR store once the rejection+ // gate has admitted the compression — otherwise we+ // populate the store with hashes whose markers+ // never reach the wire (still correct, but wastes+ // storage capacity).+ if let (Some(store), Some(hash)) = (ccr_store, ccr_hash_emitted.as_deref()) {+ store.put(hash, content_text);+ }+ let replacement_bytes = serde_json::to_vec(&compressed_for_replacement)+ .expect("string is always JSON-encodable");replacements.push(Replacement {range: content_byte_range,replacement: replacement_bytes,@@ -1078,6 +1131,39 @@ fn apply_replacements(original: &[u8], replacements: &mut [Replacement]) -> Vec<out}+/// PR-B7: append a `<<ccr:HASH>>` retrieval marker to the compressed+/// block content when a CCR store is wired. Returns the+/// (possibly-augmented) compressed string and the hash that was+/// emitted (so the caller can decide whether to put the original into+/// the store after the rejection gate). When `ccr_store` is `None`,+/// returns the input compressed string unchanged with `None`.+///+/// The marker is appended on its own line — `\n<<ccr:HASH>>` — so:+///+/// 1. The marker is unambiguously after the compressor's last byte,+/// even if that byte was a newline already (we only add one).+/// 2. Markers are easy to detect in human-readable diffs / logs.+/// 3. The Python `inject_ccr_retrieve_tool` regex in+/// `headroom/ccr/tool_injection.py` keeps working — it matches+/// `[a-f0-9]{24}` anywhere in the text.+fn maybe_inject_ccr_marker(+ original: &str,+ compressed: &str,+ ccr_store: Option<&dyn CcrStore>,+) -> (String, Option<String>) {+ if ccr_store.is_none() {+ return (compressed.to_string(), None);+ }+ let hash = compute_key(original.as_bytes());+ let marker = marker_for(&hash);+ let augmented = if compressed.ends_with('\n') {+ format!("{compressed}{marker}")+ } else {+ format!("{compressed}\n{marker}")+ };+ (augmented, Some(hash))+}+/// Per-block dispatch result — whether any compressor ran and what/// it produced.enum DispatchResult {diff --git a/crates/headroom-core/tests/ccr_backends.rs b/crates/headroom-core/tests/ccr_backends.rsnew file mode 100644index 000000000..a3ad8f338--- /dev/null+++ b/crates/headroom-core/tests/ccr_backends.rs@@ -0,0 +1,199 @@+//! Integration tests for the persistent CCR backends (PR-B7).+//!+//! Covers SQLite round-trip + TTL purge + restart-survival, the cross-+//! backend byte-equal-key invariant, and (cfg-gated) the Redis backend.++use std::time::Duration;++use headroom_core::ccr::backends::{+ from_config, CcrBackendConfig, InMemoryCcrStore, SqliteCcrStore,+};+use headroom_core::ccr::{compute_key, CcrStore};++#[test]+fn sqlite_round_trip() {+ let dir = tempfile::tempdir().expect("tempdir");+ let path = dir.path().join("ccr.sqlite");+ let store = SqliteCcrStore::open(&path, 300).expect("open sqlite store");+ let payload = r#"[{"id":1},{"id":2},{"id":3}]"#;+ let hash = compute_key(payload.as_bytes());+ store.put(&hash, payload);+ let fetched = store.get(&hash);+ assert_eq!(fetched.as_deref(), Some(payload));+ assert_eq!(store.len(), 1);+ // Missing key returns None.+ assert_eq!(store.get("missing-hash-key"), None);+}++#[test]+fn sqlite_ttl_purge() {+ let dir = tempfile::tempdir().expect("tempdir");+ let path = dir.path().join("ccr.sqlite");+ // 0-second TTL forces every entry to be expired the moment we read it.+ let store = SqliteCcrStore::open(&path, 0).expect("open sqlite store");+ let hash = compute_key(b"to be purged");+ store.put(&hash, "to be purged");+ // Sleep long enough for `created_at + ttl_seconds <= now()` (1s clock+ // resolution on unix-seconds).+ std::thread::sleep(Duration::from_millis(1_100));+ assert_eq!(store.get(&hash), None, "expired entry must be purged");+ assert_eq!(store.len(), 0, "expired entry must be physically deleted");+}++#[test]+fn sqlite_persists_across_proxy_restart() {+ // Acceptance criterion #4 from the plan: write via SqliteCcrStore,+ // drop the store, reconstruct from the same DB path, retrieve same+ // hash → original bytes recover.+ let dir = tempfile::tempdir().expect("tempdir");+ let path = dir.path().join("ccr.sqlite");+ let payload = "long-lived original payload";+ let hash = compute_key(payload.as_bytes());++ {+ let store = SqliteCcrStore::open(&path, 300).expect("open sqlite store (turn 1)");+ store.put(&hash, payload);+ // `store` drops here, simulating worker shutdown.+ }++ // Reconstruct from the same path — simulates `--workers 1` restart.+ let store = SqliteCcrStore::open(&path, 300).expect("re-open sqlite store (turn 2)");+ let fetched = store.get(&hash);+ assert_eq!(+ fetched.as_deref(),+ Some(payload),+ "re-opened sqlite store must recover the original bytes"+ );+}++#[test]+fn from_config_sqlite_roundtrip() {+ let dir = tempfile::tempdir().expect("tempdir");+ let path = dir.path().join("ccr.sqlite");+ let cfg = CcrBackendConfig::Sqlite {+ path: path.clone(),+ ttl_seconds: 300,+ };+ let store = from_config(&cfg).expect("from_config(sqlite)");+ let hash = compute_key(b"hello");+ store.put(&hash, "hello");+ assert_eq!(store.get(&hash).as_deref(), Some("hello"));+}++#[test]+fn from_config_in_memory_roundtrip() {+ let cfg = CcrBackendConfig::in_memory_default();+ let store = from_config(&cfg).expect("from_config(in_memory)");+ let hash = compute_key(b"bye");+ store.put(&hash, "bye");+ assert_eq!(store.get(&hash).as_deref(), Some("bye"));+}++#[cfg(not(feature = "redis"))]+#[test]+fn from_config_redis_unsupported_when_feature_off() {+ use headroom_core::ccr::backends::CcrBackendInitError;++ let cfg = CcrBackendConfig::Redis {+ url: "redis://127.0.0.1:6379".to_string(),+ ttl_seconds: 300,+ key_prefix: None,+ };+ match from_config(&cfg) {+ Err(CcrBackendInitError::UnsupportedBackend { backend, feature }) => {+ assert_eq!(backend, "redis");+ assert_eq!(feature, "redis");+ }+ Err(other) => panic!("expected UnsupportedBackend, got {other:?}"),+ Ok(_) => panic!("redis must error when feature is off"),+ }+}++#[test]+fn backend_swap_byte_equal_keys() {+ // Stage data through one backend, swap to another with the same+ // payload, and assert the keys are byte-equal. This is the+ // load-bearing invariant: operators may migrate between backends+ // (e.g. SQLite → Redis when scaling out) and the in-flight CCR+ // markers must keep working — the marker bytes are the hash, and+ // the hash function is fixed in `ccr::compute_key`.+ let dir = tempfile::tempdir().expect("tempdir");+ let path = dir.path().join("ccr.sqlite");++ let sqlite = SqliteCcrStore::open(&path, 300).expect("open sqlite store");+ let in_memory = InMemoryCcrStore::new();++ let payloads = [+ "alpha",+ r#"[{"id":1}]"#,+ "the quick brown fox jumps over the lazy dog",+ "<<<<>>>>", // marker-adjacent characters — sanity check on the BLAKE3 trim+ ];++ for payload in &payloads {+ let key_a = compute_key(payload.as_bytes());+ let key_b = compute_key(payload.as_bytes());+ // Step 1: same payload yields byte-equal keys.+ assert_eq!(key_a, key_b, "compute_key must be deterministic");++ // Step 2: store in sqlite, mirror to in-memory under the same+ // key — both backends recover byte-equal values.+ sqlite.put(&key_a, payload);+ in_memory.put(&key_b, payload);++ let v_sqlite = sqlite.get(&key_a);+ let v_mem = in_memory.get(&key_b);+ assert_eq!(v_sqlite.as_deref(), Some(*payload));+ assert_eq!(v_mem.as_deref(), Some(*payload));+ assert_eq!(+ v_sqlite, v_mem,+ "sqlite and in-memory must return byte-equal payloads"+ );+ }+}++// ─── Redis-feature-gated tests ─────────────────────────────────────────++#[cfg(feature = "redis")]+mod redis_tests {+ use super::*;+ use headroom_core::ccr::backends::RedisCcrStore;++ /// Reads `HEADROOM_TEST_REDIS_URL` from the environment — when the+ /// feature is on but no URL is configured we silently no-op. CI+ /// runs the redis test in a docker-compose'd matrix.+ fn redis_url() -> Option<String> {+ std::env::var("HEADROOM_TEST_REDIS_URL").ok()+ }++ #[test]+ fn redis_round_trip() {+ let Some(url) = redis_url() else {+ eprintln!("skipping redis_round_trip: HEADROOM_TEST_REDIS_URL not set");+ return;+ };+ let store = RedisCcrStore::open(&url, 300).expect("open redis store");+ let payload = "redis payload";+ let hash = compute_key(payload.as_bytes());+ store.put(&hash, payload);+ assert_eq!(store.get(&hash).as_deref(), Some(payload));+ }++ #[test]+ fn redis_round_trip_via_from_config() {+ let Some(url) = redis_url() else {+ eprintln!("skipping redis_round_trip_via_from_config: HEADROOM_TEST_REDIS_URL not set");+ return;+ };+ let cfg = CcrBackendConfig::Redis {+ url,+ ttl_seconds: 300,+ key_prefix: Some("ccr_test".to_string()),+ };+ let store = from_config(&cfg).expect("from_config(redis)");+ let payload = "via factory";+ let hash = compute_key(payload.as_bytes());+ store.put(&hash, payload);+ assert_eq!(store.get(&hash).as_deref(), Some(payload));+ }+}diff --git a/crates/headroom-core/tests/live_zone_ccr.rs b/crates/headroom-core/tests/live_zone_ccr.rsnew file mode 100644index 000000000..7f973d2d2--- /dev/null+++ b/crates/headroom-core/tests/live_zone_ccr.rs@@ -0,0 +1,119 @@+//! PR-B7 — `compress_anthropic_live_zone_with_ccr` integration tests.+//!+//! Confirms that wiring a CCR store into the live-zone dispatcher:+//! 1. Stores the original block bytes keyed by `BLAKE3(original)[..24]`.+//! 2. Appends `<<ccr:HASH>>` to the compressed block content.+//! 3. Leaves bytes outside the live zone byte-identical (cache safety).+//! 4. Is byte-equivalent to PR-B4 behaviour when no CCR store is wired.++use headroom_core::ccr::backends::InMemoryCcrStore;+use headroom_core::ccr::{compute_key, CcrStore};+use headroom_core::transforms::live_zone::{+ compress_anthropic_live_zone, compress_anthropic_live_zone_with_ccr, AuthMode, LiveZoneOutcome,+ DEFAULT_MODEL,+};+use serde_json::{json, Value};++/// Build a synthetic JSON-array tool_result above the 1 KiB threshold+/// so SmartCrusher actually engages.+fn large_json_array_payload() -> String {+ let items: Vec<Value> = (0..40)+ .map(|i| {+ json!({+ "id": i,+ "name": format!("entry_{i}"),+ "score": i * 7,+ "active": i % 2 == 0,+ "notes": "lorem ipsum dolor sit amet, consectetur adipiscing elit",+ })+ })+ .collect();+ serde_json::to_string(&Value::Array(items)).unwrap()+}++fn body_with_payload(payload: &str) -> Vec<u8> {+ serde_json::to_vec(&json!({+ "model": "claude-3-5-sonnet-20241022",+ "messages": [+ {+ "role": "user",+ "content": [+ {"type": "tool_result", "tool_use_id": "t1", "content": payload}+ ]+ }+ ]+ }))+ .unwrap()+}++#[test]+fn ccr_marker_injected_when_store_wired() {+ let payload = large_json_array_payload();+ let body = body_with_payload(&payload);+ let store = InMemoryCcrStore::new();++ let outcome = compress_anthropic_live_zone_with_ccr(+ &body,+ 0,+ AuthMode::Payg,+ DEFAULT_MODEL,+ Some(&store),+ )+ .expect("dispatcher must succeed");++ let new_body = match &outcome {+ LiveZoneOutcome::Modified { new_body, .. } => new_body.get().to_string(),+ LiveZoneOutcome::NoChange { .. } => {+ panic!("expected Modified; SmartCrusher should compress this payload")+ }+ };++ let expected_hash = compute_key(payload.as_bytes());+ let marker = format!("<<ccr:{expected_hash}>>");+ assert!(+ new_body.contains(&marker),+ "compressed body must contain CCR marker; body={new_body}"+ );+ let recovered = store.get(&expected_hash);+ assert_eq!(+ recovered.as_deref(),+ Some(payload.as_str()),+ "store must hold the original bytes under the BLAKE3 hash key"+ );+}++#[test]+fn no_marker_when_store_omitted() {+ let payload = large_json_array_payload();+ let body = body_with_payload(&payload);++ let outcome =+ compress_anthropic_live_zone(&body, 0, AuthMode::Payg, DEFAULT_MODEL).expect("dispatcher");++ let new_body = match &outcome {+ LiveZoneOutcome::Modified { new_body, .. } => new_body.get().to_string(),+ LiveZoneOutcome::NoChange { .. } => return, // legitimate — token gate may reject+ };++ assert!(+ !new_body.contains("<<ccr:"),+ "no-store path must never inject markers; body={new_body}"+ );+}++#[test]+fn store_only_populated_after_token_gate_admits() {+ // Tiny payload below the 1 KiB threshold → BelowByteThreshold,+ // dispatcher never runs a compressor → store must stay empty.+ let body = body_with_payload("tiny");+ let store = InMemoryCcrStore::new();+ let _ = compress_anthropic_live_zone_with_ccr(+ &body,+ 0,+ AuthMode::Payg,+ DEFAULT_MODEL,+ Some(&store),+ )+ .expect("dispatcher");+ assert_eq!(store.len(), 0, "no compression → no CCR put");+}diff --git a/headroom/ccr/tool_injection.py b/headroom/ccr/tool_injection.pyindex acb3de01e..5598c7fad 100644--- a/headroom/ccr/tool_injection.py+++ b/headroom/ccr/tool_injection.py@@ -302,17 +302,43 @@ class CCRToolInjector:def inject_tool_definition(self,tools: list[dict[str, Any]] | None,+ *,+ session_has_done_ccr: bool = False,) -> tuple[list[dict[str, Any]], bool]:"""Inject CCR retrieval tool into tools list.+ PR-B7 (`REALIGNMENT/04-phase-B-live-zone.md`): callers may pass+ ``session_has_done_ccr=True`` so the tool is injected even when+ THIS request has no fresh compression markers. That is the+ sticky-on path: once a session has done CCR, the+ ``headroom_retrieve`` tool must stay in ``body["tools"]`` for+ every subsequent request, otherwise the tool list bytes flip+ on/off mid-session and bust the prompt cache.++ Most callers should prefer+ :func:`headroom.proxy.helpers.apply_session_sticky_ccr_tool`+ which threads the ``SessionCcrTracker`` directly. This method+ is the per-request fallback used when no session_id is available+ (e.g. Google handler, legacy code paths).+Args:tools: Existing tools list (may be None or empty).+ session_has_done_ccr: When True, inject regardless of+ whether the current request contained compression+ markers. Default False preserves legacy per-request+ behaviour.Returns:Tuple of (updated_tools, was_injected).was_injected is False if tool was already present (e.g., from MCP)."""- if not self.inject_tool or not self.has_compressed_content:+ if not self.inject_tool:+ return tools or [], False+ # PR-B7: sticky-on takes precedence. If the session has+ # previously done CCR, register the tool even when this turn+ # has no fresh markers. Otherwise fall back to the per-request+ # check for backwards compat.+ if not (session_has_done_ccr or self.has_compressed_content):return tools or [], Falsetools = tools or []@@ -390,6 +416,8 @@ class CCRToolInjector:self,messages: list[dict[str, Any]],tools: list[dict[str, Any]] | None = None,+ *,+ session_has_done_ccr: bool = False,) -> tuple[list[dict[str, Any]], list[dict[str, Any]] | None, bool]:"""Process a request, scanning for markers and injecting as needed.@@ -398,9 +426,17 @@ class CCRToolInjector:2. Inject tool definition if enabled (skipped if already present from MCP)3. Inject system instructions if enabled+ PR-B7: when ``session_has_done_ccr`` is True the tool gets+ injected even when the current message stream has no fresh+ markers. System-instruction injection still keys off+ per-request markers (the system prompt is the cache hot zone —+ we never mutate it without a current-turn reason).+Args:messages: Request messages.tools: Request tools (may be None).+ session_has_done_ccr: PR-B7 sticky-on flag — when True,+ register the tool regardless of this turn's marker scan.Returns:Tuple of (updated_messages, updated_tools, tool_was_injected).@@ -408,10 +444,12 @@ class CCRToolInjector:"""self.scan_for_markers(messages)- if not self.has_compressed_content:+ if not (self.has_compressed_content or session_has_done_ccr):return messages, tools, False- updated_tools, was_injected = self.inject_tool_definition(tools)+ updated_tools, was_injected = self.inject_tool_definition(+ tools, session_has_done_ccr=session_has_done_ccr+ )updated_messages = self.inject_into_system_message(messages)return updated_messages, updated_tools if updated_tools else None, was_injecteddiff --git a/headroom/proxy/handlers/anthropic.py b/headroom/proxy/handlers/anthropic.pyindex 75efc684e..7633200f9 100644--- a/headroom/proxy/handlers/anthropic.py+++ b/headroom/proxy/handlers/anthropic.py@@ -1055,6 +1055,15 @@ class AnthropicHandlerMixin:logger.debug(f"[{request_id}] post_compress hook error: {e}")# CCR Tool Injection: Inject retrieval tool if compression occurred+ # OR if this session has previously done CCR (PR-B7 sticky-on).+ # The legacy `CCRToolInjector` flips on/off based on the *current*+ # request's compressed-content presence, busting cache every flip.+ # We now route the tool-list update through+ # `apply_session_sticky_ccr_tool`, which once-on/always-on per+ # `SessionCcrTracker`. System-instruction injection keeps its+ # existing per-request scan (it lives in the system prompt, which+ # is the cache hot zone — gated separately by the+ # `frozen_message_count > 0` guard below).tools = body.get("tools")_original_tools = tools # Preserve for diagnostic / future retryif (@@ -1074,26 +1083,38 @@ class AnthropicHandlerMixin:f"(frozen prefix={frozen_message_count}) to preserve cache")inject_tool = False- # Create fresh injector to avoid state leakage between requests+ # Scan for compression markers + maybe inject system instructions.+ # Tool-list injection is handled separately via the sticky helper.injector = CCRToolInjector(provider="anthropic",- inject_tool=inject_tool,+ inject_tool=False, # routed through sticky helper belowinject_system_instructions=inject_system_instructions,)- optimized_messages, tools, was_injected = injector.process_request(- optimized_messages, tools- )+ injector.scan_for_markers(optimized_messages)+ if inject_system_instructions and injector.has_compressed_content:+ optimized_messages = injector.inject_into_system_message(optimized_messages)- if injector.has_compressed_content:- if was_injected:- logger.debug(- f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"- )- else:+ # Sticky-on tool registration (PR-B7): always inject the+ # retrieval tool once a session has done CCR, regardless+ # of whether THIS turn produced compressed content.+ if inject_tool:+ from headroom.proxy.helpers import apply_session_sticky_ccr_tool++ tools, ccr_tool_injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id=request_id,+ existing_tools=tools,+ has_compressed_content_this_turn=injector.has_compressed_content,+ )+ if ccr_tool_injected:logger.debug(- f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"+ f"[{request_id}] CCR: tool registered (session={session_id}, "+ f"compressed_this_turn={injector.has_compressed_content}, "+ f"hashes_seen={len(injector.detected_hashes)})")+ if injector.has_compressed_content:# Track compression in context tracker for multi-turn awarenessif self.ccr_context_tracker:self._turn_counter += 1diff --git a/headroom/proxy/handlers/openai.py b/headroom/proxy/handlers/openai.pyindex 560d64c02..2289e7899 100644--- a/headroom/proxy/handlers/openai.py+++ b/headroom/proxy/handlers/openai.py@@ -543,6 +543,12 @@ class OpenAIHandlerMixin:logger.debug(f"[{request_id}] post_compress hook error: {e}")# CCR Tool Injection: Inject retrieval tool if compression occurred+ # OR if this session has previously done CCR (PR-B7 sticky-on).+ # See `headroom/proxy/handlers/anthropic.py` and PR-B7 plan+ # `REALIGNMENT/04-phase-B-live-zone.md` for the rationale: once a+ # session has done CCR, the `headroom_retrieve` tool stays+ # registered for every subsequent turn so the prompt cache+ # anchored on the previous turn's tool list never busts.tools = body.get("tools")_original_tools = tools # Preserve for diagnostic / future retryif (@@ -550,21 +556,28 @@ class OpenAIHandlerMixin:) and not _bypass:injector = CCRToolInjector(provider="openai",- inject_tool=self.config.ccr_inject_tool,+ inject_tool=False, # routed through sticky helper belowinject_system_instructions=self.config.ccr_inject_system_instructions,)- optimized_messages, tools, was_injected = injector.process_request(- optimized_messages, tools- )+ injector.scan_for_markers(optimized_messages)+ if self.config.ccr_inject_system_instructions and injector.has_compressed_content:+ optimized_messages = injector.inject_into_system_message(optimized_messages)- if injector.has_compressed_content:- if was_injected:- logger.debug(- f"[{request_id}] CCR: Injected retrieval tool for hashes: {injector.detected_hashes}"- )- else:+ if self.config.ccr_inject_tool:+ from headroom.proxy.helpers import apply_session_sticky_ccr_tool++ tools, ccr_tool_injected = apply_session_sticky_ccr_tool(+ provider="openai",+ session_id=openai_session_id,+ request_id=request_id,+ existing_tools=tools,+ has_compressed_content_this_turn=injector.has_compressed_content,+ )+ if ccr_tool_injected:logger.debug(- f"[{request_id}] CCR: Tool already present (MCP?), skipped injection for hashes: {injector.detected_hashes}"+ f"[{request_id}] CCR: tool registered (session={openai_session_id}, "+ f"compressed_this_turn={injector.has_compressed_content}, "+ f"hashes_seen={len(injector.detected_hashes)})")if is_cache_mode(self.config.mode):diff --git a/headroom/proxy/helpers.py b/headroom/proxy/helpers.pyindex b7731fca1..8cfdf9e8f 100644--- a/headroom/proxy/helpers.py+++ b/headroom/proxy/helpers.py@@ -1591,6 +1591,286 @@ def apply_session_sticky_memory_tools(return tools_out, added_bytes > 0+# ─── Session-sticky CCR tool injection (PR-B7) ─────────────────────────+#+# Per realignment plan PR-B7 (`REALIGNMENT/04-phase-B-live-zone.md`):+# once a session has performed any CCR compression, the+# `headroom_retrieve` tool stays registered in `body["tools"]` for every+# subsequent request in that session — never toggled off.+#+# The legacy `CCRToolInjector.has_compressed_content` flips on/off based+# on whether the *latest request* contained compression markers, which+# bust the prompt cache every time the flag flips. Sticky-on means the+# tool list bytes stay byte-stable across turns once injected.+++class SessionCcrTracker:+ """Bounded LRU tracker recording per-(provider, session_id) CCR state.++ Two pieces of state per session:++ * ``has_done_ccr``: True once the proxy observed any CCR+ compression marker in the messages of a request. Once True, it+ never flips back to False (the prompt cache anchored on the+ previous turn's tool list demands the tool stays present).+ * ``golden_tool_bytes``: canonical serialization of the+ ``headroom_retrieve`` tool definition recorded the first time+ the tracker injected it. Subsequent turns replay these bytes+ verbatim.++ Bounded by ``max_sessions`` via ``OrderedDict`` LRU. Mirrors+ :class:`SessionToolTracker` semantics so the operator's mental model+ is one tracker pattern, not two.+ """++ def __init__(self, max_sessions: int | None = None) -> None:+ if max_sessions is None:+ max_sessions = get_tool_tracker_max_sessions()+ if max_sessions <= 0:+ raise ValueError("max_sessions must be > 0")+ self._max_sessions = max_sessions+ self._lock = threading.RLock()+ # Value is (has_done_ccr, golden_tool_bytes_or_none).+ self._sessions: OrderedDict[tuple[str, str], tuple[bool, bytes | None]] = OrderedDict()++ @property+ def active_sessions(self) -> int:+ with self._lock:+ return len(self._sessions)++ def _key(self, provider: str, session_id: str) -> tuple[str, str]:+ return (provider, session_id)++ def has_done_ccr(self, provider: str, session_id: str) -> bool:+ """Return True iff this session has previously performed CCR."""+ if not provider:+ raise ValueError("provider must be non-empty")+ if not session_id:+ raise ValueError("session_id must be non-empty")+ with self._lock:+ entry = self._sessions.get(self._key(provider, session_id))+ if entry is None:+ return False+ self._sessions.move_to_end(self._key(provider, session_id))+ return entry[0]++ def get_golden_tool_bytes(self, provider: str, session_id: str) -> bytes | None:+ """Return the recorded golden tool-definition bytes, or None."""+ if not provider:+ raise ValueError("provider must be non-empty")+ if not session_id:+ raise ValueError("session_id must be non-empty")+ with self._lock:+ entry = self._sessions.get(self._key(provider, session_id))+ if entry is None:+ return None+ self._sessions.move_to_end(self._key(provider, session_id))+ return entry[1]++ def record_ccr_done(+ self,+ provider: str,+ session_id: str,+ golden_tool_bytes: bytes,+ ) -> None:+ """Mark the session as having performed CCR and pin the golden bytes.++ First-write wins for ``golden_tool_bytes`` (subsequent calls+ with the same session keep the original bytes — prevents drift+ if the canonical serialization changed mid-session). The+ ``has_done_ccr`` flag is monotonic: once True, never False.+ """+ if not provider:+ raise ValueError("provider must be non-empty")+ if not session_id:+ raise ValueError("session_id must be non-empty")+ if not golden_tool_bytes:+ raise ValueError("golden_tool_bytes must be non-empty")+ key = self._key(provider, session_id)+ with self._lock:+ existing = self._sessions.get(key)+ if existing is None:+ self._sessions[key] = (True, golden_tool_bytes)+ else:+ # Preserve original golden bytes; just promote the flag.+ pinned = existing[1] if existing[1] is not None else golden_tool_bytes+ self._sessions[key] = (True, pinned)+ self._sessions.move_to_end(key)+ while len(self._sessions) > self._max_sessions:+ self._sessions.popitem(last=False)++ def reset(self) -> None:+ """Clear all session state (test helper)."""+ with self._lock:+ self._sessions.clear()+++# Process-wide singleton.+_session_ccr_tracker_lock = threading.Lock()+_session_ccr_tracker: SessionCcrTracker | None = None+++def get_session_ccr_tracker() -> SessionCcrTracker:+ """Return the process-wide :class:`SessionCcrTracker` singleton."""+ global _session_ccr_tracker+ with _session_ccr_tracker_lock:+ if _session_ccr_tracker is None:+ _session_ccr_tracker = SessionCcrTracker()+ return _session_ccr_tracker+++def _reset_session_ccr_tracker_for_test() -> None:+ """Clear the process-wide CCR tracker (test-only)."""+ global _session_ccr_tracker+ with _session_ccr_tracker_lock:+ _session_ccr_tracker = None+++def apply_session_sticky_ccr_tool(+ *,+ provider: Literal["anthropic", "openai", "google"],+ session_id: str | None,+ request_id: str | None,+ existing_tools: list[dict[str, Any]] | None,+ has_compressed_content_this_turn: bool,+) -> tuple[list[dict[str, Any]], bool]:+ """Apply sticky-on CCR retrieval-tool injection per :class:`SessionCcrTracker`.++ Coordination point for both Anthropic and OpenAI handlers — replaces+ the legacy ``CCRToolInjector.inject_tool_definition`` "flip on, flip+ off" behaviour.++ Logic:++ * If ``session_id`` is None: tracker is bypassed and the per-turn+ ``has_compressed_content_this_turn`` flag drives the decision+ verbatim (matching legacy behaviour for WS / pre-session paths).+ * If the session has previously done CCR (``has_done_ccr``):+ ALWAYS inject the recorded golden bytes — even if this turn has+ no fresh compression. That is the load-bearing PR-B7 fix.+ * Otherwise, inject only when this turn produced compressed content.+ The first injection records the golden bytes for future turns.++ Tools whose name already equals ``CCR_TOOL_NAME`` (e.g. the client+ pre-registered it via MCP) are not re-appended; the client's bytes+ win.++ Returns ``(updated_tools, was_injected)``. ``updated_tools`` is a+ fresh list (caller-safe).+ """+ from headroom.ccr.tool_injection import CCR_TOOL_NAME, create_ccr_tool_definition++ if provider not in ("anthropic", "openai", "google"):+ raise ValueError(f"unsupported provider: {provider!r}")++ tools_out: list[dict[str, Any]] = list(existing_tools) if existing_tools else []+ existing_names: set[str] = set()+ for t in tools_out:+ n = _extract_tool_name(t)+ if n:+ existing_names.add(n)++ # Client (or MCP) already provided a tool by this name — don't double up.+ if CCR_TOOL_NAME in existing_names:+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="skip",+ tool_definition_bytes_count=0,+ request_id=request_id,+ )+ return tools_out, False++ # No session_id (e.g. WS path): per-turn decision drives directly.+ if not session_id:+ if not has_compressed_content_this_turn:+ log_tool_injection_decision(+ provider=provider,+ session_id=None,+ decision="skip",+ tool_definition_bytes_count=0,+ request_id=request_id,+ )+ return tools_out, False+ tool_def = create_ccr_tool_definition(provider)+ canonical = serialize_tool_definition_canonical(tool_def)+ tools_out.append(tool_def)+ log_tool_injection_decision(+ provider=provider,+ session_id=None,+ decision="inject_first_time",+ tool_definition_bytes_count=len(canonical),+ request_id=request_id,+ )+ return tools_out, True++ tracker = get_session_ccr_tracker()+ previously_done = tracker.has_done_ccr(provider, session_id)++ if previously_done:+ # Sticky replay path. Always inject — even if this turn had no+ # fresh CCR compression. Prefer the recorded golden bytes; fall+ # back to a freshly serialized definition if (somehow) the+ # tracker lost them. Loud per build constraint #4: we log the+ # path taken either way.+ golden = tracker.get_golden_tool_bytes(provider, session_id)+ if golden is not None:+ try:+ tool_def = json.loads(golden.decode("utf-8"))+ except (UnicodeDecodeError, json.JSONDecodeError) as exc:+ # Should never happen — golden bytes were produced by us.+ raise RuntimeError(+ f"corrupt golden CCR tool bytes for session {session_id}: {exc}"+ ) from exc+ tools_out.append(tool_def)+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="inject_sticky_replay",+ tool_definition_bytes_count=len(golden),+ request_id=request_id,+ )+ return tools_out, True+ # Tracker says "done CCR" but somehow has no golden bytes. Pin+ # them now so future turns are stable.+ tool_def = create_ccr_tool_definition(provider)+ canonical = serialize_tool_definition_canonical(tool_def)+ tracker.record_ccr_done(provider, session_id, canonical)+ tools_out.append(tool_def)+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="inject_sticky_replay",+ tool_definition_bytes_count=len(canonical),+ request_id=request_id,+ )+ return tools_out, True++ # Fresh session — only inject when this turn produced compressed content.+ if not has_compressed_content_this_turn:+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="skip",+ tool_definition_bytes_count=0,+ request_id=request_id,+ )+ return tools_out, False++ tool_def = create_ccr_tool_definition(provider)+ canonical = serialize_tool_definition_canonical(tool_def)+ tracker.record_ccr_done(provider, session_id, canonical)+ tools_out.append(tool_def)+ log_tool_injection_decision(+ provider=provider,+ session_id=session_id,+ decision="inject_first_time",+ tool_definition_bytes_count=len(canonical),+ request_id=request_id,+ )+ return tools_out, True++async def _read_request_body_bytes(request: Request) -> bytes:"""Read and (if needed) decompress the request body, returning raw UTF-8 bytes.diff --git a/tests/test_ccr_tool_always_on.py b/tests/test_ccr_tool_always_on.pynew file mode 100644index 000000000..df83a5e2b--- /dev/null+++ b/tests/test_ccr_tool_always_on.py@@ -0,0 +1,385 @@+"""PR-B7 — `headroom_retrieve` tool always-on once a session has done CCR.++These tests pin three properties:++1. After a session has performed CCR even once, every subsequent+ request in that session injects the tool — even when the current+ request has no fresh compression markers.+2. A session that has NEVER done CCR does not get the tool injected.+3. The tool definition bytes are byte-stable across turns (snapshot+ test). Any future change to the tool schema must update the+ snapshot deliberately.++Tests target the canonical helper+`headroom.proxy.helpers.apply_session_sticky_ccr_tool` plus the+`SessionCcrTracker` semantics. The CCRToolInjector legacy path is+covered by `tests/test_ccr_tool_injection.py`.+"""++from __future__ import annotations++import pytest++from headroom.ccr.tool_injection import (+ CCR_TOOL_NAME,+ CCRToolInjector,+ create_ccr_tool_definition,+)+from headroom.proxy.helpers import (+ SessionCcrTracker,+ _reset_session_ccr_tracker_for_test,+ apply_session_sticky_ccr_tool,+ get_session_ccr_tracker,+ serialize_tool_definition_canonical,+)++[email protected](autouse=True)+def _reset_tracker():+ _reset_session_ccr_tracker_for_test()+ yield+ _reset_session_ccr_tracker_for_test()+++def _has_ccr_tool(tools: list[dict] | None) -> bool:+ if not tools:+ return False+ for t in tools:+ n = t.get("name") or t.get("function", {}).get("name")+ if n == CCR_TOOL_NAME:+ return True+ return False+++# ─── Sticky-on behavior ────────────────────────────────────────────────+++def test_tool_registered_on_every_request_after_first_ccr():+ """Once a session has done CCR, the tool stays registered every turn."""+ session_id = "sess-abc-123"++ # Turn 1: this turn produced compressed content → first-time inject.+ tools_1, injected_1 = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="req-1",+ existing_tools=None,+ has_compressed_content_this_turn=True,+ )+ assert injected_1 is True+ assert _has_ccr_tool(tools_1)++ # Turn 2: NO fresh compression this turn — but session has done CCR.+ # Tool MUST still be injected (PR-B7 sticky-on).+ tools_2, injected_2 = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="req-2",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected_2 is True, "sticky replay must inject even with no fresh CCR"+ assert _has_ccr_tool(tools_2)++ # Turn 3: still no fresh compression — sticky-on still fires.+ tools_3, injected_3 = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="req-3",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected_3 is True+ assert _has_ccr_tool(tools_3)+++def test_tool_not_registered_if_session_never_did_ccr():+ """A session that never produced CCR markers gets no tool injection."""+ session_id = "fresh-session-no-ccr"++ tools, injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="req-1",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected is False+ assert not _has_ccr_tool(tools)+ # Tracker must NOT have recorded this session.+ assert get_session_ccr_tracker().has_done_ccr("anthropic", session_id) is False++ # Do it again — same outcome, no state leakage.+ tools, injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="req-2",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected is False+ assert not _has_ccr_tool(tools)+++def test_independent_sessions_track_independently():+ """Two distinct session_ids do not bleed sticky state."""+ sess_a = "sess-A"+ sess_b = "sess-B"++ # A does CCR; B does not.+ apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=sess_a,+ request_id="r1",+ existing_tools=None,+ has_compressed_content_this_turn=True,+ )++ # B's next turn (no fresh CCR) must NOT auto-inject.+ tools_b, injected_b = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=sess_b,+ request_id="r2",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected_b is False+ assert not _has_ccr_tool(tools_b)++ # A's next turn (no fresh CCR) MUST auto-inject (sticky).+ tools_a, injected_a = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=sess_a,+ request_id="r3",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected_a is True+ assert _has_ccr_tool(tools_a)+++def test_provider_isolation():+ """Same session_id under anthropic vs openai are tracked independently."""+ session_id = "shared-session-id"++ # Anthropic does CCR.+ apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="r1",+ existing_tools=None,+ has_compressed_content_this_turn=True,+ )++ # OpenAI must NOT inherit anthropic's sticky state.+ tools_o, injected_o = apply_session_sticky_ccr_tool(+ provider="openai",+ session_id=session_id,+ request_id="r2",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected_o is False+ assert not _has_ccr_tool(tools_o)+++def test_existing_ccr_tool_in_client_list_skips_injection():+ """If client (e.g. via MCP) already provided headroom_retrieve, do not double up."""+ session_id = "sess-with-mcp"+ client_tool = {+ "name": CCR_TOOL_NAME,+ "description": "client-provided",+ "input_schema": {"type": "object", "properties": {}, "required": []},+ }+ tools, injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="r1",+ existing_tools=[client_tool],+ has_compressed_content_this_turn=True,+ )+ assert injected is False+ # Tool list still contains the client's version (not duplicated).+ names = [t.get("name") for t in tools]+ assert names.count(CCR_TOOL_NAME) == 1+++def test_no_session_id_falls_back_to_per_turn_decision():+ """WS / pre-session paths with no session_id behave per-turn."""+ # No fresh CCR + no session_id → no inject.+ tools, injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=None,+ request_id="r1",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ assert injected is False++ # Fresh CCR + no session_id → inject (per-turn).+ tools, injected = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=None,+ request_id="r2",+ existing_tools=None,+ has_compressed_content_this_turn=True,+ )+ assert injected is True+ assert _has_ccr_tool(tools)+++# ─── Byte-stable tool definition ───────────────────────────────────────+++# Snapshot of the canonical Anthropic CCR tool definition. Any change+# here MUST be deliberate — bumping the schema mid-session busts every+# active session's prompt cache (the tool list bytes are part of the+# cache key).+_ANTHROPIC_CCR_TOOL_SNAPSHOT_BYTES = (+ b'{"name":"headroom_retrieve",'+ b'"description":"Retrieve original uncompressed content that was '+ b"compressed to save tokens. Use this when you need more data than "+ b"what's shown in compressed tool results. The hash is provided in "+ b'compression markers like [N items compressed... hash=abc123].",'+ b'"input_schema":{"type":"object",'+ b'"properties":{'+ b'"hash":{"type":"string",'+ b'"description":"Hash key from the compression marker '+ b"(e.g., 'abc123' from hash=abc123)\"},"+ b'"query":{"type":"string",'+ b'"description":"Optional search query to filter results. '+ b"If provided, only returns items matching the query. "+ b'If omitted, returns all original items."}'+ b"},"+ b'"required":["hash"]}}'+)++_OPENAI_CCR_TOOL_SNAPSHOT_BYTES = (+ b'{"type":"function",'+ b'"function":{"name":"headroom_retrieve",'+ b'"description":"Retrieve original uncompressed content that was '+ b"compressed to save tokens. Use this when you need more data than "+ b"what's shown in compressed tool results. The hash is provided in "+ b'compression markers like [N items compressed... hash=abc123].",'+ b'"parameters":{"type":"object",'+ b'"properties":{'+ b'"hash":{"type":"string",'+ b'"description":"Hash key from the compression marker '+ b"(e.g., 'abc123' from hash=abc123)\"},"+ b'"query":{"type":"string",'+ b'"description":"Optional search query to filter results. '+ b"If provided, only returns items matching the query. "+ b'If omitted, returns all original items."}'+ b"},"+ b'"required":["hash"]}}}'+)+++def test_tool_definition_byte_stable():+ """Pin the canonical bytes of the Anthropic + OpenAI tool defs.++ PR-B7 acceptance criterion: tool definition bytes are byte-stable.+ Any future change to ``create_ccr_tool_definition`` must bump these+ snapshots deliberately.+ """+ anthropic_tool = create_ccr_tool_definition("anthropic")+ canonical_anthropic = serialize_tool_definition_canonical(anthropic_tool)+ assert canonical_anthropic == _ANTHROPIC_CCR_TOOL_SNAPSHOT_BYTES, (+ f"Anthropic CCR tool definition bytes changed.\n"+ f" expected: {_ANTHROPIC_CCR_TOOL_SNAPSHOT_BYTES!r}\n"+ f" actual: {canonical_anthropic!r}\n"+ f"If this change is intentional, update the snapshot in this "+ f"test and ensure the prompt-cache implications are reviewed."+ )++ openai_tool = create_ccr_tool_definition("openai")+ canonical_openai = serialize_tool_definition_canonical(openai_tool)+ assert canonical_openai == _OPENAI_CCR_TOOL_SNAPSHOT_BYTES, (+ f"OpenAI CCR tool definition bytes changed.\n"+ f" expected: {_OPENAI_CCR_TOOL_SNAPSHOT_BYTES!r}\n"+ f" actual: {canonical_openai!r}"+ )+++def test_sticky_replay_returns_byte_equal_tool_each_turn():+ """The bytes injected on turn 2 must equal the bytes injected on turn 1."""+ session_id = "sess-byte-stable"++ tools_1, _ = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="r1",+ existing_tools=None,+ has_compressed_content_this_turn=True,+ )+ tools_2, _ = apply_session_sticky_ccr_tool(+ provider="anthropic",+ session_id=session_id,+ request_id="r2",+ existing_tools=None,+ has_compressed_content_this_turn=False,+ )+ # Both tools lists should contain exactly one CCR tool with the+ # same canonical bytes.+ ccr_1 = next(t for t in tools_1 if t.get("name") == CCR_TOOL_NAME)+ ccr_2 = next(t for t in tools_2 if t.get("name") == CCR_TOOL_NAME)+ assert serialize_tool_definition_canonical(ccr_1) == serialize_tool_definition_canonical(ccr_2)+++# ─── SessionCcrTracker unit coverage ────────────────────────────────────+++def test_session_ccr_tracker_monotonic_has_done_ccr():+ """``has_done_ccr`` is monotonic — never flips back to False."""+ tracker = SessionCcrTracker(max_sessions=10)+ assert tracker.has_done_ccr("anthropic", "s1") is False++ golden = serialize_tool_definition_canonical(create_ccr_tool_definition("anthropic"))+ tracker.record_ccr_done("anthropic", "s1", golden)+ assert tracker.has_done_ccr("anthropic", "s1") is True++ # Re-record with a different golden_bytes — original bytes win+ # (first-write wins) and flag stays True.+ new_golden = b'{"name":"different","input_schema":{}}'+ tracker.record_ccr_done("anthropic", "s1", new_golden)+ assert tracker.has_done_ccr("anthropic", "s1") is True+ assert tracker.get_golden_tool_bytes("anthropic", "s1") == golden+++def test_session_ccr_tracker_lru_bound():+ """Tracker evicts oldest sessions once `max_sessions` is exceeded."""+ tracker = SessionCcrTracker(max_sessions=3)+ golden = b"{}"+ for i in range(5):+ tracker.record_ccr_done("anthropic", f"s{i}", golden)+ # Only 3 most recent should remain.+ assert tracker.active_sessions == 3+ assert tracker.has_done_ccr("anthropic", "s0") is False+ assert tracker.has_done_ccr("anthropic", "s1") is False+ assert tracker.has_done_ccr("anthropic", "s4") is True+++def test_session_ccr_tracker_reset_clears_state():+ tracker = SessionCcrTracker(max_sessions=10)+ tracker.record_ccr_done("anthropic", "s1", b"{}")+ assert tracker.active_sessions == 1+ tracker.reset()+ assert tracker.active_sessions == 0+ assert tracker.has_done_ccr("anthropic", "s1") is False+++# ─── Per-request injector legacy path (PR-B7 backwards compat) ─────────+++def test_ccrtoolinjector_session_has_done_ccr_kwarg():+ """``CCRToolInjector.inject_tool_definition`` accepts session_has_done_ccr."""+ injector = CCRToolInjector(provider="anthropic", inject_tool=True)+ # No fresh markers, no sticky flag → no inject (legacy behaviour).+ tools, was = injector.inject_tool_definition(None)+ assert was is False+ assert tools == []++ # No fresh markers, sticky flag set → inject (PR-B7 path).+ tools, was = injector.inject_tool_definition(None, session_has_done_ccr=True)+ assert was is True+ assert _has_ccr_tool(tools)